Warning, /office/kexi/src/tests/altertable/README is written in an unsupported language. File is not indexed.

 ===================================================
  README for the "altertable" test
  Copyright (C) 2006 Jarosław Staniek <staniek@kde.org>
 ===================================================
 
 
 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.