1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
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.
|
