diff options
Diffstat (limited to 'kexi/tests/altertable/README')
| -rw-r--r-- | kexi/tests/altertable/README | 200 |
1 files changed, 200 insertions, 0 deletions
diff --git a/kexi/tests/altertable/README b/kexi/tests/altertable/README new file mode 100644 index 00000000..1278a54d --- /dev/null +++ b/kexi/tests/altertable/README @@ -0,0 +1,200 @@ +=================================================== + README for the "altertable" test + Copyright (C) 2006 Jaroslaw Staniek <js@iidea.pl> +=================================================== + + +Invoking +-------- +"altertable" test requires <db_name>, <driver_name> and <alterscript> arguments + +The purpose of .altertable files +-------------------------------- +.altertable files are provoded to test a given use case of table altering. +It contains a set of commands mapped to a sequence of ALTER TABLE and other +SQL statements. The commands are mapped to AlterTableHandler::***Action objects, +what is equat to actions performed by the user during the table designing. + +Second purpose of the test is testing the Table Designer's GUI itself. +Whenever there is a bug in a the GUI, e.g. in the property editor, +the resulting schema can differ from expected, or there can be even a crash. +The suite already helped to find a few bugs in the GUI code. + + +How the test is performed, .alterscript file contents +----------------------------------------------------- + +The file can be consisted of many sections described below. The test can be built by: +a. requesting a table design to be opened in the Table designer, +b. specifying commands affecting the design, +c. then checking the actions sequence genrated by the "alter table machinery" + (it's a method that allocates AlterTableHandler::***Action objects and add them + using AlterTableHandler::addAction() to the alte table machinery. + The result is the same as user's actions); +d. then saving the design, +e. and finally checking the table data with the expected table contents. +Every comparison is performed line by line: obtained result is compared with expected one. + +2. Expected result of altering the table. + It's a full human-redable dump of table schema and its contents. + +Each section has a strictly defined format, so the test suite can combine commands into more complex sets. + + +Available commands of the test suite +------------------------------------ + +1. Top-level commands + +* openDatabase <filename> + Opens kexi database for tests. In fact the file is copied to a temporary file (with .tmp suffix) + and we're dealing with the copy, so the original could not be broken. Thus, tests can be reproduced. +#TODO: support server databases + Example use: openDatabase 1.kexi + +* designTable <tablename> \n <block> \n endDesign + Opens table in design mode. <block> contains one or more schema altering + commands described in 2. + +2. Commands for altering table fields (during the design mode, within "designTable" command): + +* insertField <rownumber(int)> <fieldname(string)> + Inserts a new table field with default properties (text type) and 'fieldname' name. + Note that the inserted field can *replace* an existing field. To avoid this, use + insertEmptyRow command before insertField to add an empty row. + Example use: insertField 2 abc + +* insertEmptyRow <rownumber(int)> + Inserts empty row before 'rownumber'. Rows below are moved down. + Example use: insertEmptyRow 2 + +* removeField <rownumber(int)> + Removes a table field at a specified row. + Example use: removeField 1 + +* changeFieldProperty <rownumber(int)> <propertyname(string)> <valuetype(string)> <value(string)> + Changes property of table field at a specified row. + 'valuetype' can be int, string, bool, double/float, bool/boolean, data, dateTime, time, + bytearray, longlong. + <value(string)> should be a string representation of the value. Special cases are: + byteArray: hexadecimal string like 'fd1a5c', dateTime: yyyy-mm-ddThh:mm:ss string + like '2005-11-05T12:34:56'. + Null values should be specified as <null> string. Empty string values should be specified as "". + 'type' property means a field datatype, where value can be any of the names + in KexiDB::Field::Type enum, written as string, e.g. "integer","text", "date", etc. + Example use: changeFieldProperty 1 type string date + +* i++ + Increases "i" variable by 1. This integer variable is initialized to 1 before test is executed. + Can be used as an argument for <rownumber(int)> for above field-related commands. + +* i=<number(int)> + Sets "i" variable to <number(int)>. + Example use: shows that using the variable instead of constants allows to insert + a command without a need for managing subsequent arguments. + i=3 + removeField i + insertField i textField + changeFieldProperty i type string text + i++ #i is now 4 + insertField i longTextField + changeFieldProperty i type string longText + +3. Commands related to altered (not saved) table schema: + +* showSchema [clipboard] + Shows schema dump as returned by KexiTableDesignerInterface::debugStringForCurrentTableSchema(). + Useful for creating "checkSchema" checks: Just paste the output to the test file. + You can use "clipboard" word to copy prepare the schema dump to clipboard. + +* checkSchema \n <block> \n endSchema + Checks validity of the not yet saved schema altered in the Table Designer using the + actions listed in p. 1. The <block> should end with "endSchema" line. + Between these lines there should be pasted a <block> - exact textual schema dump as returned + by KexiTableDesignerInterface::debugStringForCurrentTableSchema(). + The check compares lines returned from the Designer with the lines you provided, line by line. + You can use "showSchema" command to display the expected schema to the stderr and copy the text. + Every line contains up to three main sections <fieldname> <type> [<constraints>]. + The lines can be indented - trailing and leading whitespaces are ignored in comparison. + Example use: + checkSchema + textfield Text(200) + owner UNSIGNED Integer + booleanfield Boolean NOTNULL + endSchema + +4. Commands related to simplified list of Alter Table actions (simulated, before real saving): + +* showActions [clipboard] + Shows the list of simplified Alter Table actions that are result of commands related to table fields, + mentioned in 1. + You can use "clipboard" word to copy prepare the expected actions dump to clipboard. + +* checkActions \n <block> \n endActions + Checks validity of the list of simplified Alter Table actions. + The <block> should end with "endActions" line. + The check compares lines returned from the Designer with the lines you provided as <block>, line by line. + Textual dump of actions is obtained from KexiTableDesignerInterface::simulateAlterTableExecution(). + Every line contains section(s): <actionname> [(<fielddebugstring>)]. + Example use: + checkActions + Insert table field "textfield" at position 1 (textfield Text(200)) + Remove table field "model" + Insert table field "longtextfield" at position 3 (longtextfield Text(200)) + endActions + +5. Commands related to physical schema saving (altering) and checking its result + +* saveTableDesign + Executes the final Alter Table function. Table design will be altered and data should + be preserved. After this command it is usable to run "checkTableData" test to see + whether the data looks as expected. + +* showTableData [clipboard] + Shows current table contents in tab-separated CSV format (one row per record) + on the stderr; text is encoded in utf-8. The data is printed to the stderr. + If optional "clipboard" word is present, the data is copied to clipboard instead. + Table dumps can be sometimes large and hard to prepare by hand, so you can use + "clipboard" word to prepare the expected table dump by pasting the text to + a .altertable file. + For details about the output format in the description "checkTableData". + +* checkTableData \n <block> \n endTableData + Compares the current contents of table with expected contents, line by line. + The data has to be in tab-separated CSV format (one row per record); + text has to be encoded in utf-8 and enclosed in " quotes. + Column names should be included as a first row. + You can use showTableData command first and then copy the results to your test file for later. + Example use: + checkTableData + ID Name Surname + 1 John Wayne + 2 Al Pacino + endTableData + +6. Other commands. + +* closeWindow + Closes the currently opened table designer window without asking for saving changes. + +* stop + Stops processing immediately. For example, this can be inserted temporarily to stop testing + (with success result). This command is available in any place. + +* quit + Executes "closeWindow" command and quits the application (with success result). + +6. Comments + +Comments can be inserted by adding # on the left hand as in bash shell +or using /* and */ for multiple rows. Empty rows are ignored. + + +The result of executing the "altertable" test +--------------------------------------------- + +On errors, kexialtertabletest program will show an appropriate error message with line number +where the error encountered and stop executing the tests. + +A given "checkSchema" command should result in "Schema check for table 'foo': OK" message. +Entire test from a give .altertable file 'foo' should end with "Tests from file 'foo': OK" message. |