< Previous Section: utPLSQL Package | Next Section: utResult Package >

utConfig Package

To make it as easy as possible for you to run your tests, utPLSQL stores various pieces of configuration data in the ut_config table. This data is stored by schema name and is automatically loaded into utPLSQL the first time you use this utility in your session. This configuration information is also automatically updated whenever you call utPLSQL.test -- or any of the utPLSQL programs specifically designed to change the configuration settings.

You can at any time view the utPLSQL configuration for the currently-connected schema or for another schema (there is not at this point any schema-level security; all utPLSQL users can view the configurations of all other users).

The data that is currently maintained for a utPLSQL user are:

Test package directory - the location of the test package code you want to run. You must specify a directory in order to allow utPLSQL to automatically compile your test packages before each test run.

Unit test prefix - the prefix used for test package names and the program names within the package. If you do not specify a prefix, the default of "ut_" is automatically applied.

Unit test registration mode - This setting determines whether utPLSQL will automatically identify the unit tests to be run (strongly recommended) or if you have chosen to manually register your unit tests in the test package setup procedure.

Auto-compilation of test packages - By default, utPLSQL will recompile your test package before execution. You can turn off this feature and manually recompile only when you desire (a fine idea if your test package has gotten very large!).

Return whose configuration is being used

By default, the configuration stored for the currently-connected user will be used. However, it is possible to use configurations stored against other usernames. To show whose configuration is currently being used the following function is used:

FUNCTION utConfig.tester RETURN VARCHAR2;

Set whose configuration is being used

This returns the configuration that will be used whenever a username is not specified. To set this, the following procedure is used:

PROCEDURE utConfig.settester (username_in IN VARCHAR2 := USER);

View a schema's configuration

Call the utconfig.showconfig procedure to view the configuration for a specified schema. The header is:

PROCEDURE utConfig.showconfig (username_in IN VARCHAR2 := NULL);

If you do not specify a schema, then the currently used configuration is returned. Here is an example of output from this procedure:

SQL> exec utconfig.showconfig
=============================================================
utPLSQL Configuration for SCOTT
   Directory: /apps/utplsql/code
   Autcompile? Y
   Manual test registration? N
   Prefix = test_
=============================================================

And here is an example of calling showConfig for a different schema:

SQL> exec utconfig.showconfig ('COMP')
=============================================================
utPLSQL Configuration for COMP
   Directory: M:\shared_apps\utplsql\comp
   Autcompile? N
   Manual test registration? N
   Prefix = ut_
=============================================================

You might want to put a call to showConfig in your SQL*Plus login file so that you are reminded on startup as to what the current settings are. Here is such a script (to be found in Examples\login_sample.sql):

exec utconfig.setdir ('e:\openoracle\utplsql\utinstall\examples')
SET SERVEROUTPUT ON SIZE 1000000 FORMAT WRAPPED
exec utconfig.showconfig

Set the directory containing the test package code

If you want utPLSQL to compile your test package, you must tell it the directory in which your code is found. You can do this either when you define your test suite and packages within the suite, or you can call the utConfig.setdir procedure to set the directory for your current session.

Note: as of v1.5.1, the value you pass in any of these programs is saved in the configuration table and will be used in the future -- until you change it by passing a different value.

The header for this procedure is:

PROCEDURE utConfig.setdir (dir_in IN VARCHAR2, username_in IN VARCHAR2 := NULL);

where dir_in is the directory and username_in is the name of the schema to which this directory applies (NULL means the currently used configuration is set), as in:

SQL> exec utconfig.setdir ('e:\demo\utplsql');

or, with the specification of a non-current schema:

SQL> exec utconfig.setdir ('e:\demo\utplsql', 'ANALYSIS');

Note that this directory must be accessible through UTL_FILE.

You might consider putting the the call to utConfig.setdir into your login.sql so that it is run automatically, each time your start up SQL*Plus -- if you are always working from the same directory.

Return the directory containing the test package code

You can obtain the current directory with a call to utConfig.dir:

FUNCTION utConfig.dir (username_in IN VARCHAR2 := NULL)
      RETURN VARCHAR2;

Set the default unit test prefix for your code.

The unit test prefix is very important in utPLSQL; the utility uses the prefix to associate source code to be tested with the test package. The prefix also allows utPLSQL to automatically identify the programs within a test package that are to be executed as unit tests.

The default prefix in utPLSQL is "ut_", but you can override this when you call utPLSQL.test or by calling the utConfig.setprefix procedure:

PROCEDURE utConfig.setPrefix (
   prefix_in IN VARCHAR2, username_in IN VARCHAR2 := NULL)

where prefix_in is the prefix and username_in is the name of the schema to which this prefix applies (NULL means the currently used configuration is set), as in:

SQL> exec utconfig.setPrefix ('tst#');

or, with the specification of a non-current schema:

SQL> exec utconfig.setPrefix ('t_', 'ANALYSIS');

Return the default unit test prefix for your code.

You can obtain the current prefix with a call to utConfig.prefix:

FUNCTION utConfig.prefix (username_in IN VARCHAR2 := NULL)
      RETURN VARCHAR2;

uPLSQL currently does not support the use of a suffix, or combination of suffix and prefix, to identify test packages and unit test procedures.

Set the registration mode (manual or automatic).

As of utPLSQL v1.5.1, you no longer have to register your unit test procedures in the setup procedure of your test package. Instead, utPLSQL will scan the data dictionary (via theALL_ARGUMENTS view) for 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 so choose, you can request that utPLSQL turn off automatic detection of unit test procedures and only run those programs listed in the setup procedure. To do this, you call the utConfig.registerTest procedure:

PROCEDURE utConfig.registerTest (
      onoff_in IN BOOLEAN,
      username_in IN VARCHAR2 := NULL
   );

as in:

SQL> exec utConfig.registerTest (TRUE)

Note: if you are using automatic unit test detection, any calls to utPLSQL.addtest in the setup procedure will be ignored.

You can return the current registration mode using the following function:

FUNCTION registeringtest (username_in IN VARCHAR2 := NULL)
   RETURN BOOLEAN;

This returns TRUE if the registration mode has been set to manual and FALSE otherwise.

Set autocompile feature

The default settings for utPLSQL is to re-compile your base package before each unit test. This guarantees that any recent changes will be tested. It also saves you the step of doing an explicit compile. In order to perform automatic compilation:

directly

In general (and the default), you should allow your test package to be recompiled with each execution. You might want to avoid recompilation if:

You have made a copy of the package body with some temporary changes and already compiled that. If you recompile automatically, you will wipe out those changes. You have not set up UTL_FILE and you don't want to deal with it. You are running the tests on a server to which you have no access other than via a database connection.

Turning off Auto-compile

If you are working with products like SQL*Navigator, you may be always editing from code stored in the database. In this case, you will never want to have utPLSQL recompile your code for you – it will already be compiled and you do not need to hassle with UTL_FILE. You can avoid auto-recompilation in two ways: 1. Pass a value of FALSE for the recompile_in argument to utPLSQL.test or utPLSQL.testsuite. Here is an example:

BEGIN
   -- Define a test suite for PL/Vision
   utsuite.add ('PLVision');
  
   -- Add two packages for testing
   utsuite.addpkg (
      'PLVision', 'PLVstr', dir_in => 'e:\utplsql');
   utsuite.addpkg (
      'PLVision', 'PLVdate', dir_in => 'e:\utplsql');
  
   -- Run the test suite
   utplsql.testsuite (
      'PLVision', recompile_in => FALSE);
END;
/

If you know that you will never want to recompilation, however, you can set the default behavior at the schema level by calling the autocompile procedure

   PROCEDURE utConfig.autocompile (
      onoff_in IN BOOLEAN,
      username_in IN VARCHAR2 := NULL
   );

So I can make the following call to turn off autocompilation for the SCOTT schema:

SQL> exec utconfig.autocompile (FALSE, 'SCOTT')

This program updates the ut_config table with your information and then commits the setting.

You can determine the current setting for auto-compilation at any time by calling the following function:

   FUNCTION utConfig.autocompiling (username_in IN VARCHAR2 := NULL)
      RETURN BOOLEAN;

Note: When you set the schema-level recompilation value to FALSE, that will override anything you pass in a call to utPLSQL.test or utPLSQL.testsuite.

V2 Delimiter

You can set the delimiter to be used in V2 procedure names using the following procedure:

PROCEDURE setdelimiter (
  delimiter_in IN VARCHAR2, 
  username_in IN VARCHAR2 := NULL
);

while the current delimiter can be obtained by the function:

FUNCTION delimiter (username_in IN VARCHAR2 := NULL)
  RETURN VARCHAR2;

Turn off the display of successful test results

By default, the results of all the tests are shown. This includes both successful and unsuccessful results. The following procedure allows you to limit the tests shown to only those that have failed:

PROCEDURE showfailuresonly (
     onoff_in      IN   BOOLEAN,
     username_in   IN   VARCHAR2 := NULL
   );

the current setting can be obtained by the function:

FUNCTION showingfailuresonly (username_in IN VARCHAR2 := NULL)
      RETURN BOOLEAN;

Set and Get the default output reporter

By default, all results are sent to the screen via DBMS_OUTPUT. However, it is possible to use other output reporters as described in more detail on this page. The following procedure allows you to set which output reporter should be used by default:

PROCEDURE setreporter (
      reporter_in   IN   VARCHAR2
     ,username_in   IN   VARCHAR2 := NULL
   );

as usual, the current setting can be obtain by the following function:

FUNCTION getreporter (username_in IN VARCHAR2 := NULL)
      RETURN VARCHAR2;

< Previous Section: utPLSQL Package | Next Section: utResult Package >

utConfig.tester	Return whose configuration is used
utConfig.settester	Set whose configuration is used
utConfig.showconfig	View a schema's configuration
utConfig.setdir	Set the directory containing the test package code
utConfig.dir	Return the directory containing the test package code
utConfig.setprefix	Set the default unit test prefix for your code
utConfig.prefix	Return the default unit test prefix for your code
utConfig.registertest	Set the registration mode (manual or automatic)
utConfig.registering	Return the registration mode
utConfig.autocompile	Set autocompile feature
utConfig.autocompiling	Return the autocompile flag
utConfig.setdelimiter	Set the V2 delimiter
utConfig.delimiter	Return the V2 delimiter
utConfig.showfailuresonly	Turn off the display of successful tests
utConfig.showingfailuresonly	Return whether successful test results are shown or not
utConfig.setreporter	Sets the default Output Reporter to use
utConfig.getreporter	Gets the name of the default Output Reporter to use
utConfig.setfiledir	Set the directory for file output
utConfig.filedir	Return which directory is used for file output
utConfig.setuserprefix	Set the user prefix for output file names
utConfig.userprefix	Return the user prefix for output file names
utConfig.setincludeprogname	Set whether to include the name of the program being tested in output file names
utConfig.includeprogname	Return whether to include the name of the program being tested in output file names
utConfig.setdateformat	Set the date format for the date portion of output file names
utConfig.dateformat	Return the date format used to construct output file names
utConfig.setfileextension	Set the file extension for output file names
utConfig.fileextension	Return the file extension used for output file names
utConfig.setfileinfo	Set all of the above file output related items
utConfig.fileinfo	Return all of the above file output related items