koffice/kexi/tests/altertable/README

===================================================
 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.