17-8. Reconfiguring utPLSQL Parameters
Problem
You would like to change some of the configurations for your utPLSQL install. For instance, you would like to change the prefix for all of your unit test packages so that, instead of beginning with ut_, they all start with test_.
Solution
Use the utConfig package to alter the configurations for utPLSQL. For this solution, you will see how utConfig can be used to change the prefix that is used for all of your test packages. For example, here's how to change the prefix for your test packages from ut_ to test_ using the utConfig package for the current schema.
SQL> exec utConfig.setPrefix('test_'),
PL/SQL procedure successfully completed.
After executing the statement in the example, the utPLSQL unit test framework will look for test packages beginning with the test_ prefix rather than ut_ within the current schema, until the prefix is changed again using the utConfig package.
How It Works
The utPLSQL test framework can be configured to operate differently from its default manner by changing options using the utConfig package. Changes can be made for the current schema only, or for all schemas within the database. In the solution to this recipe, you have seen that the prefix for test packages is configurable. To change the prefix, pass the desired prefix in string format to utConfig.setPrefix(). The setPrefix() procedure also accepts an additional schema name that will specify the schema to which the configuration option will be applied. If you do not pass a schema name, the changes will occur within the current schema. The actual format for executing the utConfig.setPrefix procedure is as follows:
exec utConfig.setPrefix(desired_prefix, [schema]);
There are many configurable options that can be changed using the utConfig package. Table 17-2 shows the complete list of options.
Table 17-2. utConfig Configuration Options
| Option | Description |
utConfig.autocompile |
Configure autocompile feature |
utConfig.registertest |
Configure the registration mode (manual or automatic) |
utConfig.setdateformat |
Configure the date format for the date portion of output file names |
utConfig.setdelimiter |
Configure the V2 delimiter |
utConfig.setdir |
Configure the directory containing the test package code |
utConfig.setfiledir |
Configure the directory for file output |
utConfig.setfileextension |
Configure the file extension for output file names |
utConfig.setfileinfo |
Configure all of the above file output related items |
utConfig.setincludeprogname |
Configure whether to include the name of the program being tested within output file names |
utConfig.setprefix |
Configure the default unit test prefix |
utConfig.setreporter |
Configure the default Output Reporter |
utConfig.settester |
Configure whose configuration is used |
utConfig.setuserprefix |
Configure the user prefix for output file names |
utConfig.showfailuresonly |
Switch off the display for successful tests |
You can set of the options shown here using a syntax similar to that shown for the setPrefix() procedure that was demonstrated in the solution to this recipe. For more information on using the configurations listed in Table 17-2, please see the online documentation that can be found at: http://utplsql.oracledeveloper.nl/. Along with configurable options, the utConfig package includes some functions that can be called to retrieve information regarding the unit test configuration for the database or for a particular schema. Table 17-3 contains a listing of the options that utConfig makes available for obtaining information.
Table 17-3. utConfig Informational Options
| Option Name | Description |
utConfig.autocompiling |
Returns autocompile flag value |
utConfig.dateformat |
Returns date format used to construct output file names |
utConfig.delimiter |
Returns V2 delimiter |
utConfig.dir |
Returns directory containing the test package code |
utConfig.filedir |
Returns file output directory |
utConfig.fileextension |
Returns output file name extension |
utConfig.fileinfo |
Returns all file output—related items |
utConfig.getreporter |
Obtains name of the default Output Reporter to use |
utConfig.includeprogname |
Returns whether to include the name of the program being tested within file names |
utConfig.prefix |
Returns default unit test prefix for your code |
utConfig.registering |
Returns registration mode |
utConfig.showconfig |
Displays a schema configuration |
utConfig.showingfailuresonly |
Returns whether successful test results are displayed |
utConfig.tester |
Returns the schema whose configuration is used |
utConfig.userprefix |
Returns the user prefix for output files |
The functions can be called just as if they were standard functions within your schema. Some, such as the utConfig.showconfig procedure, require you to set serveroutput on in order to display the output. The following excerpt from a SQL*Plus session shows a call to utConfig.showconfig.
SQL> set serveroutput on
SQL> exec utconfig.showconfig
=============================================================
utPLSQL Configuration for USERNAME
Directory:
Autcompile?
Manual test registration?
Prefix =
Default reporter =
----- File Output settings:
Output directory:
User prefix =
Include progname?
Date format =
File extension =
----- End File Output settings
=============================================================
PL/SQL procedure successfully completed.
The utConfig package contains a variety of configurable options that will allow you to adjust unit testing according to your specific needs. Out of the box, the utPLSQL testing framework contains default values for each of these options, so you may never need to touch utConfig, but the option is available if you need it. Another nice feature is that you can set configurable options for a specific schema. Doing so will allow different schemas in the database to act differently when performing unit testing.