You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
201 lines
8.8 KiB
201 lines
8.8 KiB
===================================================
|
|
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.
|