-
Notifications
You must be signed in to change notification settings - Fork 7
Expand file tree
/
Copy pathreporter.html
More file actions
274 lines (219 loc) · 10.3 KB
/
Copy pathreporter.html
File metadata and controls
274 lines (219 loc) · 10.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<!-- WARNING! This file is generated. -->
<!-- To alter documentation, edit files in src directory -->
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Custom Reporter Packages</title>
<link rel="stylesheet" href="utplsql.css" type="text/css" />
<meta name="keywords" content="utPLSQL, PL\SQL, Unit Testing, Framework, Oracle" />
<meta name="description" content="Unit Testing PL\SQL" />
<meta name="title" content="Custom Reporter Packages" />
<meta name="author" content="Steven Feuerstein, Chris Rimmer, Patrick Barel and the utPLSQL Project" />
<meta name="copyright" content="(C) 2000-2005, 2014-2016 Steven Feuerstein, Chris Rimmer, Patrick Barel and the utPLSQL Project" />
</head>
<body>
<div class="purple_bar"><a href="index.html"><img src="utplsql.jpg" alt="utPLSQL logo" /></a></div>
<p>[ <a href="index.html">Home</a>
| <a href="started.html">Getting Started</a>
| <a href="buildpack.html">Build Test Packages</a>
| <a href="examples.html">Examples</a>
| <a href="userguide.html">User Guide</a>
| <a href="release.html">Release Notes</a>
| <a href="map.html">Document Map</a> ]</p>
<p><a href="defsuite.html">< Previous Section: Defining Test Suites</a> | <a href="fileout.html">Next Section: Configuring the File Reporter ></a></p>
<!-- Begin utPLSQL Body -->
<!-- $Id$ -->
<h1>Custom Reporter Packages</h1>
<p>
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:
</p>
<ul>
<li><a href="#outputreporter">Output Reporter</a></li>
<li><a href="#filereporter">File Reporter</a></li>
<li><a href="#htmlreporter">HTML Reporter</a></li>
</ul>
<p>
The naming convention is that reporter packages are called
UT<i><b><NAME></b></i>REPORTER. To set which reporter is used, you will
need to call <a href="utconfig.html#setgetreporter">utConfig.Setreporter</a>, passing the name of the reporter.
To use the HTML reporter for example, you should issue the following command:
</p>
<pre>
BEGIN
utConfig.setreporter('HTML');
END;
</pre>
<p>
For more details of how to develop your own custom
reporter package, see <a href="#custom">below</a>.
</p>
<h2><a name="outputreporter"></a>Output Reporter</h2>
<p>
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.
</p>
<h2><a name="filereporter"></a>File Reporter</h2>
<p>
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 <a href="fileout.html">here</a>. This functionality was
available before version 2.2 of utPLSQL, but has now been moved into its own
package.
</p>
<h2><a name="htmlreporter"></a>HTML Reporter</h2>
<p>
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.
</p>
<h2><a name="custom"></a>Writing your own Reporter</h2>
<p>
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.
</p>
<pre>
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;
/
</pre>
<p>
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. <b>Note</b> 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.
</p>
<h3>open</h3>
<p>
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.
</p>
<h3>pl</h3>
<p>
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 <code>utoutputreporter.pl</code> to send this to DBMS_OUTPUT instead.
</p>
<h3>before_results</h3>
<p>
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 <code>utresult.success (run_id)</code> to determine if the run was a success or not and display a large banner.
</p>
<h3>show_failure</h3>
<p>
This is called when a failure is reported and we are only showing failures (i.e. <a href="utconfig.html#showfailuresonly">utconfig.showfailuresonly</a> has been set).
To get details of the failure, you will need to examine the package level record <code>utreport.outcome</code>.
</p>
<h3>show_result</h3>
<p>
This is called whenever a result is reported and we are showing all
results. To get details, you will need to examine
<code>utreport.outcome</code>. See below for details.
</p>
<h3>after_results</h3>
<p>This is called after all the results have been sent for output.</p>
<h3>before_errors</h3>
<p>This is called before any errors are sent for output.</p>
<h3>show_error</h3>
<p>
This is called for each error to output. To get details, you will need
to examine the package level record <code>utreport.error</code>.
See below for details.
</p>
<h3>after_errors</h3>
<p>This is called after any errors have been sent for output.</p>
<h3>before_suite_results</h3>
<p>
This is called only when a suite is executed. It displays the overall
banner and suite execution statistics.
</p>
<h2><a name="reportrecords"></a>Outcome and Error records</h2>
<p>
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.
</p>
<pre>
outcome utr_outcome%ROWTYPE;
error utr_error%ROWTYPE;
</pre>
<p>The important fields in the outcome record are:</p>
<ul>
<li>status - This is a string which is either "SUCCESS" or "FAILURE" depending on the outcome of this test.</li>
<li>description - The text describing the success or failure.</li>
</ul>
<p>The important fields in the error record are:</p>
<ul>
<li>errlevel - The Error Level</li>
<li>errcode - The Error Code</li>
<li>errtext - The Description of the error that occurred</li>
</ul>
<h2>Using Your Custom Reporter</h2>
<p>
To use your custom reporter, you simply call <a href="utconfig.html#setgetreporter">utConfig.Setreporter</a> with the name of your reporter. So if
you have defined your reporter in the utMyRssReporter package, you need to call:
</p>
<pre>
BEGIN
utConfig.setreporter('MyRss');
END;
</pre>
<p>
Then you just run your tests as usual and hopefully your reporter will
format the results as you expect.
</p>
<h3>Sending output to the current reporter</h3>
<p>
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:
</p>
<pre>
BEGIN
utReport.pl('Logging Message');
END;
</pre>
<p>will be equivalent to </p>
<pre>
BEGIN
utMyRssReporter.pl('Logging Message');
END;
</pre>
<!-- End utPLSQL Body -->
<p><a href="defsuite.html">< Previous Section: Defining Test Suites</a> | <a href="fileout.html">Next Section: Configuring the File Reporter ></a></p>
<div class="purple_bar"><a href="index.html"><img src="utplsql.jpg" alt="utPLSQL logo" /></a></div>
<p>
<a href="http://validator.w3.org/check?uri=referer">
<img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0 Strict" height="31" width="88" />
</a>
</p>
<p class="copyright">Copyright © 2000-2005, 2014-2016 <a href="mailto:steven@stevenfeuerstein.com">Steven Feuerstein</a>, <a href="mailto:c@24.org.uk">Chris Rimmer</a>, <a href="mailto:pbarel@vda.nl">Patrick Barel</a> and the utPLSQL Project. All rights reserved</p>
</body>
</html>