dbd::informix::testharness(3)
NAME
DBD::Informix::TestHarness - Test Harness for
DBD::Informix
SYNOPSIS
use DBD::Informix::TestHarness;
DESCRIPTION
This document describes DBD::Informix::TestHarness for
DBD::Informix version 1.00 and later. This is pure Perl
code which exploits DBI and DBD::Informix to make it eas
ier to write tests. Most notably, it provides a simple
mechanism to connect to the user's chosen test database
and a uniform set of reporting mechanisms.
Loading DBD::Informix::TestHarness
- To use the DBD::Informix::TestHarness software, you need
to load the DBI software and then install the Informix
driver: - use DBD::Informix::TestHarness;
- Connecting to test database
$dbh = &connect_to_test_database({ AutoCommit => 0 });- This gives you a reference to the database connection han
dle, aka the database handle. If the load fails, your
program stops immediately. The functionality available
from this handle is documented in the DBD::Informix manual
page. This function does not report success when it suc
ceeds because the test scripts for blobs, for example,
need to know whether they are working with an OnLine sys
tem before reporting how many tests will be run. - This code exploits 3 environment variables:
DBD_INFORMIX_DATABASE
DBD_INFORMIX_USERNAME
DBD_INFORMIX_PASSWORD- The database variable can be simply the name of the
database, or it can be 'database@server', or it can be one
of the SE notations such as '/opt/dbase' or '//host
name/dbase'. If INFORMIXSERVER is not set, then you had
better be on a 5.0x system as otherwise the connection
will fail. With 6.00 and above, you can optionally spec
ify a user name and password in the environment. This is
horribly insecure -- do not use it for production work.
The test scripts do not print the password. - Using connect_noisily
- The method connect_noisily is identical to con
nect_to_test_database.
$dbh = &connect_noisily({ AutoCommit => 0 });- Using connect_quietly
- The method connect_quietly does not echo the connection
information whereas both connect_noisily and con
nect_to_test_database do. It is used in a very few spe
cial cases where the connection information is of limited
interest -- primarily during '"InformixTechSupport -w"' or
'"ItWorks"'.
$dbh = &connect_quietly({ AutoCommit => 0 });- All three connection methods internally use the nonexported connect_controllably method.
- Using cleanup_database
- If the test needs a clean database to work with, the
cleanup_database method removes any tables, views, syn
onyms (or IUS types) created by the DBD::Informix test
suite. These are all identified by the 'dbd_ix_' prefix.
&cleanup_database($dbh);- This is not used in all tests by any stretch of the imagi
nation. In fact, the only test to use it routinely is
t/t99clean.t. Whereever possible, tests should use tempo
rary tables. - Using test_for_ius
- If the test explicitly requires Informix Universal Server
(IUS) or IDS/UDO (Informix Dynamic Server with Universal
Data Option -- essentially the product as IUS, but with a
longer, more recent, name), then the mechanism to use is:
my ($dbh) = &test_for_ius();- If this returns, then the ESQL/C is capable of handling
IUS data types, the database connection worked, and the
database server is capable of handling IUS data types. - Using is_shared_memory_connection
- You cannot have multiple simultaneous connections if both
connections use shared memory connectivity. The multiple
connection tests try to determine whether both test
databases have shared memory connections. This Unix-cen
tric test provides such a test and allows the tests to
report that 'skipping test on this platform'.
if (&is_shared_memory_connection($dbase1)) { ... }- Using stmt_test
- Once you have a database connection, you can execute sim
ple statements (those which do not return any data) using
&stmt_test():
&stmt_test($dbh, $stmt, $flag, $tag);- The first argument is the database handle. The second is
a string containing the statement to be executed. The
third is optional and is a boolean. If it is 0, then the
statement must execute without causing an error or the
test will terminate. If it is set to 1, then the
statement may fail and the error will be reported but the
test will continue. The fourth argument is an optional
string which will be used as a tag before the statement
when it is printed. If omitted, it defaults to "Test". - Using stmt_retest
- The &stmt_retest() function takes three arguments, which
have the same meaning as the first three arguments of
&stmt_test():
&stmt_retest($dbh, $stmt, $flag);- It calls:
&stmt_test($dbh, $stmt, 0, "Retest");- Using print_sqlca
- The &print_sqlca() function takes a single argument which
can be either a statement handle or a database handle and
prints out the current values of the SQLCA record.
&print_sqlca($dbh);
&print_sqlca($sth);- Using print_dbinfo
- The &print_dbinfo() function takes a single argument which
should be a database handle and prints out salient infor
mation about the database.
&print_dbinfo($dbh);- Using all_ok
- The &all_ok() function can be used at the end of a test
script to report that everything was OK. It exits with
status 0.
&all_ok();- Using stmt_ok
- This routine adds 'ok N' to the end of a line. The N
increments automatically each time &stmt_ok() or
&stmt_fail() is called. If called with a non-false argu ment, it prints the contents of DBI::errstr as a warning
message too. This routine is used internally by
stmt_test() but is also available for your use.
&stmt_ok(0);- Using stmt_fail
- This routine adds 'not ok N' to the end of a line, then
reports the error message in DBI::errstr, and then dies.
The N is incremented automatically, as with &stmt_ok(). This routine is used internally by stmt_test() but is also available for your use. It takes an optional string as an
argument, which is printed as well.
&stmt_fail();
&stmt_fail("Reason why test failed");- Using stmt_err
- This routines prints a caption (defaulting to 'Error Mes
sage') and the contents of DBI::errstr, ensuring that each
line is prefixed by "# ". This routine is used internally
by the DBD::Informix::TestHarness module, but is also
available for your use.
&stmt_err('Warning Message');- Using stmt_note
- This routine writes a string (without any newline unless
you include it). This routine is used internally by
stmt_test() but is also available for your use.
&stmt_note("Some string or other");- Using select_some_data
- This routine takes three arguments:
&select_some_data($dbh, $nrows, $stmt);- The first argument is the database handle. The second is
the number of rows that should be returned. The third is
a string containing the SELECT statement to be executed.
It prints all the data returned with a '#' preceding the
first field and two colons separating the fields. It
reports OK if the select succeeds and the correct number
of rows are returned; it fails otherwise. - Using select_zero_data
- This routine takes a database handle and a SELECT state
ment and invokes &select_some_data with 0 rows expected.
&select_zero_data($dbh, $stmt);- Using memory_leak_test
- This routine takes a reference to a subroutine, and
optionally a nap time in seconds (default 5) and a "ps"
command string (default "ps -lp", suitable for Solaris 2.x
and Solaris 7). - Normally, your test script will simply call this routine
and exit. The remaining code in the test file will imple
ment a test which shows the memory leak. You should not
connect to the test database before invoking mem
ory_leak_test.
use strict;
use DBD::Informix::TestHarness;
&memory_leak_test(test_subroutine);
exit;- When it is called, memory_leak_test forks, and the parent
process runs the given subroutine with no arguments. The
subroutine will do the sequence of database operations
which show that there is a memory leak, or that the memory
leak is fixed. The child process checks that the parent
is still alive, and runs the "ps" command to determine the
size of the process. The output of "ps" is not parsed, so
you have to run the test in a verbose mode to see whether
there is a memory leak or not.
&memory_leak_test(test_subroutine);
&memory_leak_test(test_subroutine, 10, "ps -l- grep");
- The "ps" command string has a process number appended to
the end after a space, and should report the size of the
given process. Note that the last example is not as reli
able as requesting the process status of a specific pro
cess number; it will probably show the grep command and
the child Perl process, and maybe random other processes. - Using primary_connection
- The primary_connection function returns three values, the
database name, the username and the password for the pri
mary test connection. This is used internally by the con
nect_controllably function, and hence by the con
nect_to_test_database function.
my ($dbase, $user, $pass) = &primary_connection();
my ($dbh) = DBI->connect("dbi:Informix:$dbase", $user,- $pass)
or die "$DBI::errstr0;
- In looking for the three values, it examines the environ
ment variables DBD_INFORMIX_DATABASE, DBD_INFORMIX_USER
NAME and DBD_INFORMIX_PASSWORD. If the database is not
determined, it looks at the DBI_DBNAME environment vari
able (which is essentially obsolete as far as DBI is con
cerned, but which is documented by the esqltest code -- an
alternative was to remove support for DBI_DBNAME from
esqltest.ec). If DBI_DBNAME is not set, then the default
database name is 'stores' with no version suffix. If the
username and password are not set, then empty strings are
returned. - Using secondary_connection
- The secondary_connection function also returns three val
ues, the database name, the username and the password for
the secondary test connection. This is used in the multi
ple connection tests.
my ($dbase, $user, $pass) = &secondary_connection();
my ($dbh) = DBI->connect("dbi:Informix:$dbase", $user,- $pass)
or die "$DBI::errstr0;
- In looking for the three values, it examines the environ
ment variables DBD_INFORMIX_DATABASE2, DBD_INFORMIX_USER
NAME2 and DBD_INFORMIX_PASSWORD2. If the database is not
determined, it uses the primary_connection method above to
specify the values. - Note
- All these routines can also be used without parentheses or
the &, so that the following is also valid:
select_zero_data $dbh, $stmt;
AUTHOR
At various times:
· Jonathan Leffler (johnl@informix.com) # obsolete email
address
· Jonathan Leffler (j.leffler@acm.org)
· Jonathan Leffler (jleffler@informix.com)
SEE ALSO
- perl(1), DBD::Informix