DataBlade Developers Kit User's Guide Debugging and Testing DataBlade Modules on UNIX

When you generate functional tests, BladeSmith creates a set of files that include shell scripts and SQL scripts for testing opaque data type support routines, user-defined routines, and cast support functions. By default, these files are created in the functest subdirectory of the directory containing the BladeSmith project file.

Functional tests are generated only for the DataBlade module objects for which you enter test data in your BladeSmith project. See Adding Functional Test Data for information about entering test data.

Functional testing is typically an iterative process, repeated many times until the code passes all the tests. The testing process has the following general steps:

1. Build the shared object file while logged on as user informix.

See Compiling on UNIX for instructions.

2. Install the DataBlade module shared object, SQL scripts, and test scripts in the $INFORMIXDIR/extend/project directory.

See Installing a DataBlade Module for more information.

3. Log on as the informix user and start your database server with the oninit command.

See the Administrator's Guide for Informix Dynamic Server 2000 for more information.

4. Create a test database.

See the DB-Access User's Manual for more information.

5. Register the DataBlade module, using BladeManager.

See Registering a DataBlade Module for more information.

6. If you are replacing an existing shared object, shut down and restart the database server with the onmode -k and oninit commands.

See Replacing a Shared Object File for more information.

7. Execute the functional tests.

See Executing Functional Tests for instructions.

8. Edit the source code (if necessary).
9. Regenerate the tests in BladeSmith (if necessary).
10. Repeat the procedure, as necessary.

Functional tests include SQL scripts and shell scripts that execute the SQL scripts and determine the results. The shell scripts build test tables in a database, run the SQL test scripts, and then drop the test tables from the database.

You can create custom shell scripts to run additional tests or initialization scripts. The generated scripts include calls to your custom scripts.

Shell scripts execute SQL scripts using DB-Access. The results from the SQL statements are saved in .log files. When you first run functional tests, you must inspect the .log files and, if the results are correct, use the shell scripts to copy them to .req files.

When you execute functional tests after saving .req files, the shell script uses the UNIX diff command to compare the .log files to the .req files. The script prints the following messages:

• "test passed" message if the .log and .req files match
• "test failed" message if the files do not match
• "status unknown" message when a .req file does not yet exist

Important: There are minor formatting differences between the UNIX and Windows NT versions of DB-Access that can cause tests to indicate failure incorrectly.

The functional test directory, functest, includes the following subdirectories:

• data. Contains .dat files for each opaque type, user-defined routine, and cast for which you entered test data. The name of the data file is objectname.dat, where objectname is either the name of the opaque type or the name of the C routine associated with a user-defined routine or cast.
• opaque. Contains a subdirectory for each opaque type for which you entered test data. The subdirectory contains functional tests for the support routines defined for the opaque type.
• udr. Contains a subdirectory containing functional tests for each user-defined routine for which you entered test data.
• cast. Contains a subdirectory containing functional tests for each cast for which you entered test data.

The functest directory contains a master shell script, main.sh, for executing all of the functional tests generated for the DataBlade module. Each subdirectory in the udr, opaque, and cast directories also contains a main.sh script to execute only the functional tests in that subdirectory.

The subdirectories in the udr, opaque, and cast directories contain various SQL scripts. Each subdirectory has a setup.sql script and a cleanup.sql script. The setup.sql script creates test tables and initializes them with test data. The cleanup.sql script drops all of the test tables from the database.

BladeSmith creates the following SQL test scripts for the object being tested:

• call_pos.sql, for user-defined routines
• call_neg.sql, for negative tests of user-defined routines
• cast.sql, for casts
• Additional scripts for opaque types to test the support routines defined for the type, as described in the following table

Script Names	Support Routines Tested
textio_pos.sql	Text input/output functions for an opaque type; uses only valid test data.
textio_neg.sql	Text input/output functions for an opaque type; uses test data with invalid input data.
binio.sql	Binary file input/output functions; uses the valid input data for the opaque type.
textexp.sql	Text file import/export functions for opaque types; uses the UNLOAD and LOAD SQL statements.
binexp.sql	Binary file import/export functions for an opaque type; uses nested calls to the binary file import/export functions. The result of the nested calls should be equivalent to the text input format for the type.
notify.sql	The Assign/Destroy routines; inserts and deletes values in a new test table.
compare.sql	The Compare function for an opaque type.
equal.sql	The Equal function for an opaque type.
notequal.sql	The NotEqual function for an opaque type.
btree.sql lessthan.sql lessthanorequal.sql greaterthan.sql greaterthanorequal.sql	B-tree support functions for an opaque type.
plus.sql minus.sql times.sql divide.sql	Standard math operators for an opaque type.
positive.sql negative.sql	The Positive and Negate functions for an opaque type.
concat.sql	The concatenation operator; calls the Concat function for an opaque data type with two instances of the type.
hash.sql	The Hash support function with a SELECT...GROUP BY SQL query.

A script is generated only when the support routines it tests are defined.

You can add other tests or initialization scripts to your test suite by adding your own scripts in the subdirectories of the functest directory and editing the sample user.sh shell script that BladeSmith generates. For example, you can add SQL scripts to create a test database, create special test tables in it, and execute custom tests against those tables.

To execute functional scripts, use the main.sh script. Execute a command in all test directories by executing the main.sh command in the top-level test directory. You can execute tests for a specific DataBlade module object by executing main.sh in that object's test directory.

The first time you execute the tests, initialize the reference files. See Initializing Reference Files for instructions.

The TESTDB environment variable must be set to the name of the test database.

The main.sh script is a Bourne shell script that accepts one of five possible command line parameters, as described in the following table.

The first time you run tests, execute the "build" and "run" targets, as follows:

main.sh build
main.sh run

These two steps prepare the database, run the test scripts, and generate .log files. The results of all tests are unknown (no reference file).

Check the results in each .log file to determine if the test returned the correct result. The expected result (which was entered with the test data in BladeSmith) is shown in a comment.

If the results are incorrect, you might need to fix the DataBlade module C code. In other cases, the test data can be incorrect.

When the tests return correct results, create reference files by executing the "save" target, as follows:

main.sh save

After reference files have been saved, use the "all" shortcut target to build and run the tests and clean up the database and test directory.