[ Home | Getting Started | Build Test Packages | Examples | User Guide | Release Notes | Document Map ]

< Previous Section: User Guide | Next Section: utConfig Package >

utPLSQL Package

The utPLSQL package offers the following capabilities:

Run a Test or Test Suite

With utPLSQL, you can run all the unit tests contained in a single test package, or run the tests for a series of test packages defined in a test suite.

The utPLSQL package offers two procedures, test and testsuite, to make it easy for you to run "red light, green light" tests. Before you can use these programs, however, you must build your own test package.

To run a test for a single package, use the utPLSQL.test procedure:

PROCEDURE utPLSQL.test (
   package_in IN VARCHAR2,
   samepackage_in IN BOOLEAN := FALSE,
   prefix_in IN VARCHAR2 := NULL,
   recompile_in IN BOOLEAN := TRUE,
   dir_in IN VARCHAR2 := NULL,
   suite_in in VARCHAR2 := NULL,
   owner_in IN VARCHAR2 := NULL,
   reset_results_in IN BOOLEAN := TRUE ,
   from_suite_in         IN   BOOLEAN := FALSE,
   subprogram_in         IN   VARCHAR2 := '%',
   per_method_setup_in   IN   BOOLEAN := FALSE
);

where the parameters are defined as follows:

Here are some examples of using the utPLSQL.test procedure:

1. Run the unit test for the betwnstr function (by executing the ut_betwnstr test package, since the default prefix is used). Do not recompile the test package.

SQL> exec utPLSQL.test ('betwnstr', recompile_in => FALSE)

2. Run all of the unit tests for the te_employee package, stored in a test package called "test_te_employee" in the /tmp directory. Recompile the test package before execution.

SQL> exec utPLSQL.test ('te_employee', prefix_in => 'test_', dir_in => '/tmp')

3. Run all the unit tests for the corporate_polluters package, located in the same package as the source code.

SQL> exec utPLSQL.test ('te_employee', samepackage_in => TRUE)

Since utPLSQL follows the red light-green light approach on reporting results, each time you run utPLSQL.test, it will display the results. If successful, you will see output like this:

SUCCESS: "betwnstr"

If the test fails at some point, you will see output like this:

FAILURE: "betwnstr"
BETWNSTR: IS NULL: NULL start
BETWNSTR: End larger than string length; expected "cdeg", got "cdefg"

Running a Test the other way

The normal usage of the test procedure as described above assumes that for each package you want to test, say mypackage, has a package for testing this package having the same name but with an additional prefix: ut_mypackage. Instead of using this approach, you can use the procedure run. This procedure runs a test package directly without any further conditions on the name or other packages. The only condition that still applies is the naming conventions necessary to make it a valid test package.

PROCEDURE run (
    testpackage_in      IN VARCHAR2,
    prefix_in           IN VARCHAR2 := NULL,
    suite_in            IN VARCHAR2 := NULL,
    owner_in            IN VARCHAR2 := NULL,
    reset_results_in    IN BOOLEAN  := TRUE,
    from_suite_in       IN BOOLEAN  := FALSE,
    subprogram_in       IN VARCHAR2 := '%',
    per_method_setup_id IN BOOLEAN  := FALSE);

where the parameters are defined as follows:

Running a Test Suite

In addition to running a test for a single test package, you can set up a test suite that consists of one or more test packages. You can then run an entire suite of tests with a call to utPLSQL.testsuite:

PROCEDURE utPLSQL.testsuite (
   suite_in IN VARCHAR2,
   recompile_in IN BOOLEAN := TRUE,
   reset_results_in IN BOOLEAN := TRUE
   per_method_setup_in in BOOLEAN := FALSE
   );

where suite_in is the name of the suite and recompiled_in determines the auto compilation behavior.

Here is an example of the call I would make to run all my tests for the PL/Vision library:

SQL> exec utplsql.testsuite ('plvision');

The parameter list for utPLSQL.testSuite is much shorter than utPLSQL.test; rather than pass information like directory, owner name and same-package through a parameter list, you define these characteristics in the suite itself (stored in a series of utPLSQL tables).

Before you can test an entire suite, you must define the suite.

Running a Test Suite the other way

Similiar to the run procedure for single packages, there is the runsuite procedure to run testsuites. When you use this procedure there is no relationship assumed between the names of test packages specified in the test suite and the procedures to be tested.

PROCEDURE utPLSQL.runsuite (
   suite_in IN VARCHAR2,
   reset_results_in IN BOOLEAN := TRUE
   per_method_setup_in in BOOLEAN := FALSE
   );

The usage of the parameters is just as in testsuite.

Recording and Accessing Test Statistics

If you have defined test suites, and packages within those test suites, utPLSQL will update those definitions with the follow statistics after each test is run:

• Status of last run: success or failure?
• Start and end times of last run
• Total number of failures
• Total number of executions of the test

All of this is done for you automatically. You can then write queries and reports against the ut_package and ut_suite tables.

Return utPLSQL version

Run the utPLSQL.version function to return the version of utPLSQL you have installed:

FUNCTION utPLSQL.version RETURN VARCHAR2

utPLSQL Trace

These routines are very simple and take no arguments:

PROCEDURE trc;

PROCEDURE notrc;

FUNCTION tracing RETURN BOOLEAN;

The procedures trc and notrc are used to turn tracing on and off respectively. The function tracing returns TRUE if tracing is currently turned on and FALSE otherwise. This facility is useful when writing code in utPLSQL (the framework itself, not your test code). An example of the output generated is:

Initialized utPLSQL session...
Setpkg to Lottery
Package and program = ut_Lottery
Same package? N
Is package? Y
Prefix = ut_
Recompiling ut_Lottery in
Runprog of ut_SETUP
Package and program = ut_Lottery.ut_SETUP
Same package? N
Is package? Y
Prefix = ut_
Addtest
Package and program = Lottery.UT_DRAW
Same package? N
Override? Y
Prefix = ut_
Runprog of UT_DRAW
Package and program = ut_Lottery.UT_DRAW
Same package? N
Is package? Y
Prefix = ut_
.
>  FFFFFFF   AA     III  L      U     U RRRRR   EEEEEEE
>  F        A  A     I   L      U     U R    R  E
>  F       A    A    I   L      U     U R     R E
>  F      A      A   I   L      U     U R     R E
>  FFFF   A      A   I   L      U     U RRRRRR  EEEE
>  F      AAAAAAAA   I   L      U     U R   R   E
>  F      A      A   I   L      U     U R    R  E
>  F      A      A   I   L       U   U  R     R E
>  F      A      A  III  LLLLLLL  UUU   R     R EEEEEEE
.
FAILURE: "Lottery"
.
> Individual Test Case Results:
>
FAILURE - EQ "Test of DRAW" Expected "01 02 05 27 43 49" and got "02 04 27 28 31 33"
>
>
> Errors recorded in utPLSQL Error Log:
>
> NONE FOUND
Runprog of ut_TEARDOWN
Package and program = ut_Lottery.ut_TEARDOWN
Same package? N
Is package? Y
Prefix = ut_

PL/SQL procedure successfully completed.

Register a Unit Test

As of version 1.4.1, you no longer have to explicitly register a unit test! The default behavior of utPLSQL is now to extract from the data dictionary (via the ALL_ARGUMENTS data dictionary view) the names of all the unit test procedures you have defined, and then run them. utPLSQL identifies these programs by looking for all programs whose names start with the specified prefix.

If you decide that you want to explicitly register your unit tests, then you will need to turn on manual registration:

SQL> exec utConfig.registertest (TRUE)

This setting is immediately saved in the database for your schema. To turn off manual registration:

SQL> exec utConfig.registertest (FALSE)

So read no further unless you have turned on manual registration! You might do this, for example, if you have already built a number of test packages in a version of utPLSQL prior to 1.4.1 and do not want to make any changes to your test package code.

All aspects of manual registration of unit tests for a program or package actually occur within the Unit Test Package itself, in the setup procedure. No persistent unit test information is stored between runs of the unit test, unless you define that unit test within a test suite.

Use the utPLSQL.addtest procedure to register a unit test.

   PROCEDURE utPLSQL.addtest (
      NAME_IN IN VARCHAR2,
      utprefix_in IN VARCHAR2,
      iterations_in IN PLS_INTEGER := 1
   );
 
   PROCEDURE utPLSQL.addtest (
      package_in IN VARCHAR2,
      NAME_IN IN VARCHAR2,
      utprefix_in IN VARCHAR2,
      iterations_in IN PLS_INTEGER := 1
   );

where

name_in is the name of the program you are testing. Note that this is the name of the unit test procedure itself, including the unit test prefix..

utprefix_in is the prefix to be applied to name_in to construct the unit tst procedure. This is currently NOT IN USE; only the package prefix specified in your call to utPLSQL.test and utPLSQL.testsuite is used.

iterations_in is the number of times you wish to run the test (currently NOT IN USE).

package_in is the name of the package containing the unit test procedure. If you provide a package name when you call utPLSQL.addtest, you will override the package name set when you called utPLSQL.test -- but only for that one test. We recommend that you not change the package name.

Here is a setup procedure that sets up a series of tests for a query-only encapsulation of the employee table:

CREATE OR REPLACE PACKAGE BODY ut_te_employee
IS
   PROCEDURE ut_setup
   IS
   BEGIN
      utplsql.addtest ('UT_EMP_DEPT_LOOKUPROWCOUNT');
      utplsql.addtest ('UT_EMP_JOB_LOOKUPROWCOUNT');
      utplsql.addtest ('UT_EMP_MGR_LOOKUPROWCOUNT');
      utplsql.addtest ('UT_HIRE_DATE$VAL');
      utplsql.addtest ('UT_I_EMPLOYEE_NAME$ROW');
      utplsql.addtest ('UT_I_EMPLOYEE_NAME$VAL');
      utplsql.addtest ('UT_ONEROW');
      utplsql.addtest ('UT_PKYROWCOUNT');
      utplsql.addtest ('UT_ROWCOUNT');
      utplsql.addtest ('UT_SALARY$VAL');
   END;

Once you have placed your addtest programs into your test package's setup procedure, you are ready to build your own unit tests.

< Previous Section: User Guide | Next Section: utConfig Package >

Copyright © 2000-2005, 2014-2016 Steven Feuerstein, Chris Rimmer, Patrick Barel and the utPLSQL Project. All rights reserved