< Previous Section: Defining Test Suites | Next Section: Configuring the File Reporter >

Custom Reporter Packages

Generally, the default output provided by utPLSQL is sufficient. This just writes to the screen using DBMS_OUTPUT. If you are running it interactively while doing some development, you just need to know if the tests are passing and details of the failing tests. However, there are cases where you'd like the results to be reported in a different format, especially when the tests are being run in batch mode. To support this, utPLSQL has the concept of Reporter Packages. utPLSQL is distributed with the following reporter packages as standard:

Output Reporter
File Reporter
HTML Reporter

The naming convention is that reporter packages are called UT<NAME>REPORTER. To set which reporter is used, you will need to call utConfig.Setreporter, passing the name of the reporter. To use the HTML reporter for example, you should issue the following command:

BEGIN
   utConfig.setreporter('HTML');
END;

For more details of how to develop your own custom reporter package, see below.

Output Reporter

Contained in the UTOUTPUTREPORTER package, this simply encapsulates the standard behaviour, whereby the output is written out to DBMS_OUTPUT. When a problem occurs with another reporter, utPLSQL will automatically fall back on this mechanism to report problems. This means it is wise to have DBMS_OUTPUT enabled even if you are using another output method.

File Reporter

This reporter, contained in the UTFILEREPORTER package, writes test results out to a file. For details on how to configure this process, see the details which can be found here. This functionality was available before version 2.2 of utPLSQL, but has now been moved into its own package.

HTML Reporter

The package UTHTMLREPORTER is really just an example package to be used as a basis for your own custom reporters. It builds on the filereporter described above to send results to a file. The difference is that the results are presented in a (rather crude) HTML table.

Writing your own Reporter

To define your own reporter package you need it conform to a particular API. The various procedures are then registered as 'callbacks' for utPLSQL to use. An example package spec is given below.

CREATE OR REPLACE PACKAGE utMyRssReporter
IS

   PROCEDURE open;
   PROCEDURE pl (str IN VARCHAR2);
   
   PROCEDURE before_results(run_id IN utr_outcome.run_id%TYPE);
   PROCEDURE show_failure;
   PROCEDURE show_result;
   PROCEDURE after_results(run_id IN utr_outcome.run_id%TYPE);
   
   PROCEDURE before_errors(run_id IN utr_error.run_id%TYPE);
   PROCEDURE show_error;
   PROCEDURE after_errors(run_id IN utr_error.run_id%TYPE);   
   
   PROCEDURE close;
   
   PROCEDURE before_suite_results(suite_id IN ut_suite.id%TYPE);

END utMyRssReporter;
/

Your reporter package can define other functions and procedures, for example to allow configuration, but all the procedures shown above should be defined. The usage of these procedures follows. Note If you want to keep the format of the output the same as for the Output Reporter, but wish to send it elsewhere, you can define open, close and pl, but simply call the equivalent procedure in utOutputReporter for the others. For an example of this, see the File Reporter.

open

This is called at the very start of the process and is the ideal place to do initialization, such as opening any files that you will be writing to.

pl

This is a general routine to simply write out the given string for purposes of logging etc. If you don't want this to show up in your output, you can simply call utoutputreporter.pl to send this to DBMS_OUTPUT instead.

before_results

As the name suggests, this is called before the results are output. Note that the tests have already completed at this point, so it is possible to call utresult.success (run_id) to determine if the run was a success or not and display a large banner.

show_failure

This is called when a failure is reported and we are only showing failures (i.e. utconfig.showfailuresonly has been set). To get details of the failure, you will need to examine the package level record utreport.outcome.

show_result

This is called whenever a result is reported and we are showing all results. To get details, you will need to examine utreport.outcome. See below for details.

after_results

This is called after all the results have been sent for output.

before_errors

This is called before any errors are sent for output.

show_error

This is called for each error to output. To get details, you will need to examine the package level record utreport.error. See below for details.

after_errors

This is called after any errors have been sent for output.

before_suite_results

This is called only when a suite is executed. It displays the overall banner and suite execution statistics.

Outcome and Error records

In order to keep the API as simple as possible, many of the procedures defined above take no parameters. In particular, details of the outcome or error which triggered the callback are not passed through to your procedure. These are stored as package level records in the utReport package as shown below.

outcome utr_outcome%ROWTYPE;
error utr_error%ROWTYPE;

The important fields in the outcome record are:

status - This is a string which is either "SUCCESS" or "FAILURE" depending on the outcome of this test.
description - The text describing the success or failure.

The important fields in the error record are:

errlevel - The Error Level
errcode - The Error Code
errtext - The Description of the error that occurred

Using Your Custom Reporter

To use your custom reporter, you simply call utConfig.Setreporter with the name of your reporter. So if you have defined your reporter in the utMyRssReporter package, you need to call:

BEGIN
   utConfig.setreporter('MyRss');
END;

Then you just run your tests as usual and hopefully your reporter will format the results as you expect.

Sending output to the current reporter

If you wish to send output to the current reporter, for example, for logging purposes, you should call utReport.pl. This is part of the utReport package, which acts as a facade and passes any calls through to the current reporter package. So if you have set up a custom reporter package 'utMyRssReporter' as shown above and called utConfig.setreporter('MyRss'), any calls such as the following:

BEGIN
  utReport.pl('Logging Message');
END;

will be equivalent to

BEGIN
  utMyRssReporter.pl('Logging Message');
END;

< Previous Section: Defining Test Suites | Next Section: Configuring the File Reporter >