INFORMIX
DataBlade Developers Kit User's Guide
Chapter 8: Testing and Debugging DataBlade Modules on UNIX
Home Contents Index Master Index New Book

Testing DataBlade Modules

 When you generate functional tests, BladeSmith creates a set of files that include shell scripts and SQL scripts for testing opaque data types, user-defined routines, and casts. 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 Test Data" for information about entering test data.

Testing a DataBlade module is usually an iterative process, repeated several 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 (if necessary).

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

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

    See the INFORMIX-Universal Server Administrator's Guide for more information.

    1. Create a test database.

    See the DB-Access User Manual for more information.

    1. Register the DataBlade module, using BladeManager (if necessary).

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

    1. Execute the functional tests.

    1. Edit the source code (if necessary).

    1. Regenerate the tests in BladeSmith (if necessary).

    1. Repeat the procedure, as necessary.

Functional Test Overview

 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:

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

Contents of the Functional Test Directory

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

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 that is being tested:
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.

rtree.sql

equal.sql

overlap.sql

contains.sql

within.sql

union.sql

size.sql

inter.sql

R-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 only generated when the support routines it tests are defined.

Adding Custom Test Files

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.

Executing Functional Tests

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.

Using the Functional Test Scripts

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

main.sh build

Runs user.sh with a "build" target.

Runs the setup.sql script.

main.sh clean

Deletes .log files.

Runs user.sh with a "clean" target.

Executes clean.sql in the database.

main.sh run

Uses DB-Access to run each SQL script generated by BladeSmith, saving the output in a .log file.

If a .req file exists, calls diff to determine the test result. It prints a message telling whether the test passed or failed.

After all BladeSmith-generated tests are run, executes user.sh with a "run" target.

main.sh save

Copies all .log files to .req files, overwriting existing .req files.

main.sh all

Performs the "build," "run," and "clean" actions. Use this shortcut after the .req files have been saved.

Initializing Reference Files

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

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:

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.



DataBlade Developers Kit User's Guide, version 3.6
Copyright © 1998, Informix Software, Inc. All rights reserved.