Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit f4b1692

Browse files
lwasylowlwasylow
committed
Update docs
1 parent 02af1cc commit f4b1692

1 file changed

Lines changed: 98 additions & 29 deletions

File tree

‎docs/userguide/annotations.md‎

Lines changed: 98 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ test_package
6565
6666
Finished in .002415 seconds
6767
0 tests, 0 failed, 0 errored, 0 disabled, 0 warning(s)
68-
```
68+
```
6969

7070
Suite package with description.
7171
```sql
@@ -82,7 +82,7 @@ Tests for a package
8282
8383
Finished in .001646 seconds
8484
0 tests, 0 failed, 0 errored, 0 disabled, 0 warning(s)
85-
```
85+
```
8686

8787
When multiple `--%suite` annotations are specified in package, the first annotation will be used and a warning message will appear indicating duplicate annotation.
8888
```sql
@@ -107,7 +107,7 @@ Warnings:
107107
108108
Finished in .003318 seconds
109109
0 tests, 0 failed, 0 errored, 0 disabled, 1 warning(s)
110-
```
110+
```
111111

112112
When `--%suite` annotation is bound to procedure, it is ignored and results in package not getting recognized as test suite.
113113
```sql
@@ -127,7 +127,7 @@ ORA-06512: at "UT3.UT", line 115
127127
ORA-06512: at "UT3.UT", line 306
128128
ORA-06512: at "UT3.UT", line 364
129129
ORA-06512: at line 1
130-
```
130+
```
131131

132132

133133
### Test
@@ -166,7 +166,7 @@ Tests for a package
166166
167167
Finished in .004109 seconds
168168
1 tests, 0 failed, 0 errored, 0 disabled, 0 warning(s)
169-
```
169+
```
170170

171171
Test procedure with description.
172172
```sql
@@ -192,7 +192,7 @@ Tests for a package
192192
193193
Finished in .006828 seconds
194194
1 tests, 0 failed, 0 errored, 0 disabled, 0 warning(s)
195-
```
195+
```
196196

197197
When multiple `--%test` annotations are specified for a procedure, the first annotation will be used and a warning message will appear indicating duplicate annotation.
198198
```sql
@@ -226,7 +226,7 @@ Warnings:
226226
227227
Finished in .008815 seconds
228228
1 tests, 0 failed, 0 errored, 0 disabled, 1 warning(s)
229-
```
229+
```
230230

231231
### Disabled
232232
Marks annotated suite package or test procedure as disabled.
@@ -263,7 +263,7 @@ Tests for a package
263263
264264
Finished in .001441 seconds
265265
2 tests, 0 failed, 0 errored, 2 disabled, 0 warning(s)
266-
```
266+
```
267267

268268
Disabling individual test(s).
269269
```sql
@@ -393,8 +393,8 @@ The `another_setup` still gets invoked before any test from that suite package i
393393
procedure other_test is begin null; end;
394394
end;
395395
/
396-
```
397-
396+
```
397+
398398
```sql
399399
exec ut.run('test_package');
400400
```
@@ -441,7 +441,7 @@ When procedure is annotated as both `--%beforeall` and `--%test`, the procedure
441441
end;
442442
/
443443
```
444-
444+
445445
```sql
446446
exec ut.run('test_package');
447447
```
@@ -463,8 +463,8 @@ Warnings:
463463
464464
Finished in .012158 seconds
465465
2 tests, 0 failed, 0 errored, 0 disabled, 2 warning(s)
466-
```
467-
466+
```
467+
468468

469469
### Afterall
470470

@@ -532,7 +532,7 @@ The procedure annotated as `--%beforeeach` is getting executed before each test
532532
That means that the procedure will be executed as many times as there are test in suite package.
533533

534534
If a test is marked as disabled the `--%beforeeach` procedure is not invoked for that test.
535-
535+
536536
If `--%beforeeach` raises an unhandled exception the following will happen:
537537
- the following `--%beforeeach` as well as all `--%beforetest` for that test **will not be executed**
538538
- the test will be marked as errored and exception stack trace will be captured and reported
@@ -613,7 +613,7 @@ The procedure annotated as `--%aftereach` is getting executed after each test in
613613
That means that the procedure will be executed as many times as there are test in suite package.
614614

615615
If a test is marked as disabled the `--%aftereach` procedure is not invoked for that test.
616-
616+
617617
If `--%aftereach` raises an unhandled exception the following will happen:
618618
- the test will be marked as errored and exception stack trace will be captured and reported
619619
- the `--%aftertest`, `--%aftereach` procedures **will be executed** for the errored test
@@ -691,7 +691,7 @@ Used alongside `--%test` annotation. Indicates procedure name to be executed bef
691691
The `--%beforetest` procedures are executed after invoking all `--%beforeeach` for a test.
692692

693693
If a test is marked as disabled the `--%beforetest` procedure is not invoked for that test.
694-
694+
695695
If `--%beforetest` raises an unhandled exception the following will happen:
696696
- the following `--%beforetest` for that test **will not be executed**
697697
- the test will be marked as errored and exception stack trace will be captured and reported
@@ -773,7 +773,7 @@ Used alongside `--%test` annotation. Indicates procedure name to be executed aft
773773
The `--%aftertest` procedures are executed before invoking any `--%aftereach` for a test.
774774

775775
If a test is marked as disabled the `--%aftertest` procedure is not invoked for that test.
776-
776+
777777
If `--%aftertest` raises an unhandled exception the following will happen:
778778
- the test will be marked as errored and exception stack trace will be captured and reported
779779
- the following `--%aftertest` and all `--%aftereach` procedures **will be executed** for the errored test
@@ -858,7 +858,7 @@ With this comes a challenge. How to group tests, related to one tested procedure
858858
This is where utPLSQL contexts come handy.
859859

860860
Contexts allow for creating sub-suites within a suite package and they allow for grouping of tests that are somehow related.
861-
861+
862862
In essence, context behaves like a suite within a suite.
863863

864864
Context have following characteristics:
@@ -869,10 +869,10 @@ Context have following characteristics:
869869
- `--%beforeall`, `--%beforeeach`, `--%afterall` and `--%aftereach` procedures defined at suite level, propagate to context
870870
- test suite package can have multiple contexts in it
871871
- contexts cannot be nested
872-
872+
873873

874874
The below example illustrates usage of `--%context` for separating tests for individual procedures of package.
875-
875+
876876
Tested tables and code
877877
```sql
878878
create table rooms (
@@ -1179,15 +1179,30 @@ Keep in mind that when your test runs as autonomous transaction it will not see
11791179

11801180
### Throws
11811181

1182-
The `--%throws` annotation allows you to specify a list of exception numbers that can be expected from a test.
1182+
The `--%throws` annotation allows you to specify a list of exception either by numbers or by exception type that can be expected from a test.
11831183

11841184
If `--%throws(-20001,-20002)` is specified and no exception is raised or the exception raised is not on the list of provided exception numbers, the test is marked as failed.
11851185

11861186
The framework ignores bad arguments. `--%throws(7894562, operaqk, -=1, -20496, pow74d, posdfk3)` will be interpreted as `--%throws(-20496)`.
11871187
The annotation is ignored, when no valid arguments are provided `--%throws()`,`--%throws`, `--%throws(abe, 723pf)`.
11881188

1189+
The framework allows to pass exception defined in variables for example constants in other packages or as exceptions `--%throws(exc_pkg.c_exc_variable)`
1190+
1191+
Please note that NO_DATA_FOUND is a special case and it will be translated into -1403.
1192+
11891193
Example:
11901194
```sql
1195+
create or replace package exc_pkg is
1196+
c_e_option1 constant number := -20200;
1197+
c_e_option2 constant varchar2(10) := '-20201';
1198+
c_e_option3 number := -20202;
1199+
1200+
e_option4 exception;
1201+
pragma exception_init(e_option4, -20203);
1202+
1203+
end;
1204+
/
1205+
11911206
create or replace package example_pgk as
11921207

11931208
--%suite(Example Throws Annotation)
@@ -1207,6 +1222,26 @@ create or replace package example_pgk as
12071222
--%test(Gives failure when an exception is expected and nothing is thrown)
12081223
--%throws(-20459, -20136, -20145)
12091224
procedure nothing_thrown;
1225+
1226+
--%test(Throws package exception option1)
1227+
--%throws(exc_pkg.c_e_option1)
1228+
procedure raised_option1_exception;
1229+
1230+
--%test(Throws package exception option2)
1231+
--%throws(exc_pkg.c_e_option2)
1232+
procedure raised_option2_exception;
1233+
1234+
--%test(Throws package exception option3)
1235+
--%throws(exc_pkg.c_e_option3)
1236+
procedure raised_option3_exception;
1237+
1238+
--%test(Throws package exception option4)
1239+
--%throws(exc_pkg.e_option4)
1240+
procedure raised_option4_exception;
1241+
1242+
--%test(Raise name exception)
1243+
--%throws(DUP_VAL_ON_INDEX)
1244+
procedure raise_named_exc;
12101245

12111246
end;
12121247
/
@@ -1230,39 +1265,73 @@ create or replace package body example_pgk is
12301265
begin
12311266
ut.expect(1).to_equal(1);
12321267
end;
1268+
1269+
procedure raised_option1_exception is
1270+
begin
1271+
raise_application_error(exc_pkg.c_e_option1, 'Test error');
1272+
end;
1273+
1274+
procedure raised_option2_exception is
1275+
begin
1276+
raise_application_error(exc_pkg.c_e_option2, 'Test error');
1277+
end;
1278+
1279+
procedure raised_option3_exception is
1280+
begin
1281+
raise_application_error(exc_pkg.c_e_option3, 'Test error');
1282+
end;
1283+
1284+
procedure raised_option4_exception is
1285+
begin
1286+
raise exc_pkg.e_option4;
1287+
end;
1288+
1289+
procedure raise_named_exc is
1290+
begin
1291+
raise DUP_VAL_ON_INDEX;
1292+
end;
1293+
12331294
end;
12341295
/
1235-
1296+
12361297
exec ut.run('example_pgk');
12371298
```
12381299

12391300
Running the test will give report:
12401301
```
12411302
Example Throws Annotation
1242-
Throws one of the listed exceptions [.018 sec]
1243-
Throws different exception than expected [.008 sec] (FAILED - 1)
1244-
Throws different exception than listed [.007 sec] (FAILED - 2)
1245-
Gives failure when an exception is expected and nothing is thrown [.002 sec] (FAILED - 3)
1303+
Throws one of the listed exceptions [.003 sec]
1304+
Throws different exception than expected [.003 sec] (FAILED - 1)
1305+
Throws different exception than listed [.004 sec] (FAILED - 2)
1306+
Gives failure when an exception is expected and nothing is thrown [.004 sec] (FAILED - 3)
1307+
Throws package exception option1 [.003 sec]
1308+
Throws package exception option2 [.003 sec]
1309+
Throws package exception option3 [.003 sec]
1310+
Throws package exception option4 [.003 sec]
1311+
Raise name exception [.003 sec]
12461312
12471313
Failures:
12481314
12491315
1) raised_different_exception
12501316
Actual: -20143 was expected to equal: -20144
12511317
ORA-20143: Test error
12521318
ORA-06512: at "UT3.EXAMPLE_PGK", line 9
1319+
ORA-06512: at "UT3.EXAMPLE_PGK", line 9
12531320
ORA-06512: at line 6
12541321
12551322
2) raised_unlisted_exception
12561323
Actual: -20143 was expected to be one of: (-20144, -1, -20145)
12571324
ORA-20143: Test error
12581325
ORA-06512: at "UT3.EXAMPLE_PGK", line 14
1326+
ORA-06512: at "UT3.EXAMPLE_PGK", line 14
12591327
ORA-06512: at line 6
12601328
12611329
3) nothing_thrown
12621330
Expected one of exceptions (-20459, -20136, -20145) but nothing was raised.
12631331
1264-
Finished in .038692 seconds
1265-
4 tests, 3 failed, 0 errored, 0 disabled, 0 warning(s)
1332+
Finished in .033843 seconds
1333+
9 tests, 3 failed, 0 errored, 0 disabled, 0 warning(s)
1334+
12661335
```
12671336

12681337
## Order of execution
@@ -1335,7 +1404,7 @@ end test_employee_pkg;
13351404
```
13361405

13371406
When processing the test suite `test_employee_pkg` defined in [Example of annotated test package](#example), the order of execution will be as follows.
1338-
1407+
13391408
```
13401409
create a savepoint 'before-suite'
13411410
execute setup_employees (--%beforeall)

0 commit comments

Comments
 (0)