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

Skip to content

Commit 71e940c

Browse files
jgebaljgebal
authored
Merge pull request #689 from utPLSQL/feature/enable_throw_variable
Feature/enable throw variable
2 parents c5bc73e + 9847364 commit 71e940c

7 files changed

Lines changed: 565 additions & 71 deletions

File tree

‎docs/userguide/annotations.md‎

Lines changed: 127 additions & 33 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,21 +1179,43 @@ 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 exceptions as one of:
1183+
- number literals - example `--%throws(-20134)`
1184+
- variables of type exception defined in a package specification - example `--%throws(exc_pkg.c_exception_No_variable)`
1185+
- variables of type number defined in a package specification - example `--%throws(exc_pkg.c_some_exception)`
1186+
- [predefined oracle exceptions](https://docs.oracle.com/cd/E11882_01/timesten.112/e21639/exceptions.htm#CIHFIGFE) - example `--%throws(no_data_found)`
11831187

1184-
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.
1188+
The annotation is ignored, when no valid arguments are provided. Examples of invalid annotations `--%throws()`,`--%throws`, `--%throws(abe, 723pf)`.
11851189

1186-
The framework ignores bad arguments. `--%throws(7894562, operaqk, -=1, -20496, pow74d, posdfk3)` will be interpreted as `--%throws(-20496)`.
1187-
The annotation is ignored, when no valid arguments are provided `--%throws()`,`--%throws`, `--%throws(abe, 723pf)`.
1190+
If `--%throws` annotation is specified with arguments and no exception is raised, the test is marked as failed.
11881191

1192+
If `--%throws` annotation is specified with arguments and exception raised is not on the list of provided exceptions, the test is marked as failed.
1193+
1194+
The framework will raise a warning, when `--%throws` annotation has invalid arguments or when no arguments were provided.
1195+
1196+
Annotation `--%throws(7894562, operaqk, -=1, -20496, pow74d, posdfk3)` will be interpreted as `--%throws(-20496)`.
1197+
1198+
Please note that `NO_DATA_FOUND` exception is a special case in Oracle. To capture it use `NO_DATA_FOUND` named exception or `-1403` exception No.
1199+
11891200
Example:
11901201
```sql
1202+
create or replace package exc_pkg is
1203+
c_e_option1 constant number := -20200;
1204+
c_e_option2 constant varchar2(10) := '-20201';
1205+
c_e_option3 number := -20202;
1206+
1207+
e_option4 exception;
1208+
pragma exception_init(e_option4, -20203);
1209+
1210+
end;
1211+
/
1212+
11911213
create or replace package example_pgk as
11921214

11931215
--%suite(Example Throws Annotation)
11941216

11951217
--%test(Throws one of the listed exceptions)
1196-
--%throws(-20145,-20146, -20189 ,-20563)
1218+
--%throws(-20145,bad,-20146, -20189 ,-20563)
11971219
procedure raised_one_listed_exception;
11981220

11991221
--%test(Throws different exception than expected)
@@ -1207,6 +1229,30 @@ create or replace package example_pgk as
12071229
--%test(Gives failure when an exception is expected and nothing is thrown)
12081230
--%throws(-20459, -20136, -20145)
12091231
procedure nothing_thrown;
1232+
1233+
--%test(Throws package exception option1)
1234+
--%throws(exc_pkg.c_e_option1)
1235+
procedure raised_option1_exception;
1236+
1237+
--%test(Throws package exception option2)
1238+
--%throws(exc_pkg.c_e_option2)
1239+
procedure raised_option2_exception;
1240+
1241+
--%test(Throws package exception option3)
1242+
--%throws(exc_pkg.c_e_option3)
1243+
procedure raised_option3_exception;
1244+
1245+
--%test(Throws package exception option4)
1246+
--%throws(exc_pkg.e_option4)
1247+
procedure raised_option4_exception;
1248+
1249+
--%test(Raise name exception)
1250+
--%throws(DUP_VAL_ON_INDEX)
1251+
procedure raise_named_exc;
1252+
1253+
--%test(Invalid throws annotation)
1254+
--%throws
1255+
procedure bad_throws_annotation;
12101256

12111257
end;
12121258
/
@@ -1230,39 +1276,87 @@ create or replace package body example_pgk is
12301276
begin
12311277
ut.expect(1).to_equal(1);
12321278
end;
1279+
1280+
procedure raised_option1_exception is
1281+
begin
1282+
raise_application_error(exc_pkg.c_e_option1, 'Test error');
1283+
end;
1284+
1285+
procedure raised_option2_exception is
1286+
begin
1287+
raise_application_error(exc_pkg.c_e_option2, 'Test error');
1288+
end;
1289+
1290+
procedure raised_option3_exception is
1291+
begin
1292+
raise_application_error(exc_pkg.c_e_option3, 'Test error');
1293+
end;
1294+
1295+
procedure raised_option4_exception is
1296+
begin
1297+
raise exc_pkg.e_option4;
1298+
end;
1299+
1300+
procedure raise_named_exc is
1301+
begin
1302+
raise DUP_VAL_ON_INDEX;
1303+
end;
1304+
1305+
procedure bad_throws_annotation is
1306+
begin
1307+
null;
1308+
end;
12331309
end;
12341310
/
1235-
1236-
exec ut.run('example_pgk');
1311+
1312+
exec ut3.ut.run('example_pgk');
12371313
```
12381314

12391315
Running the test will give report:
12401316
```
12411317
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)
1318+
Throws one of the listed exceptions [.002 sec]
1319+
Throws different exception than expected [.002 sec] (FAILED - 1)
1320+
Throws different exception than listed [.003 sec] (FAILED - 2)
12451321
Gives failure when an exception is expected and nothing is thrown [.002 sec] (FAILED - 3)
1322+
Throws package exception option1 [.003 sec]
1323+
Throws package exception option2 [.002 sec]
1324+
Throws package exception option3 [.002 sec]
1325+
Throws package exception option4 [.002 sec]
1326+
Raise name exception [.002 sec]
1327+
Invalid throws annotation [.002 sec]
12461328
12471329
Failures:
12481330
12491331
1) raised_different_exception
12501332
Actual: -20143 was expected to equal: -20144
12511333
ORA-20143: Test error
12521334
ORA-06512: at "UT3.EXAMPLE_PGK", line 9
1335+
ORA-06512: at "UT3.EXAMPLE_PGK", line 9
12531336
ORA-06512: at line 6
12541337
12551338
2) raised_unlisted_exception
12561339
Actual: -20143 was expected to be one of: (-20144, -1, -20145)
12571340
ORA-20143: Test error
12581341
ORA-06512: at "UT3.EXAMPLE_PGK", line 14
1342+
ORA-06512: at "UT3.EXAMPLE_PGK", line 14
12591343
ORA-06512: at line 6
12601344
12611345
3) nothing_thrown
12621346
Expected one of exceptions (-20459, -20136, -20145) but nothing was raised.
12631347
1264-
Finished in .038692 seconds
1265-
4 tests, 3 failed, 0 errored, 0 disabled, 0 warning(s)
1348+
1349+
Warnings:
1350+
1351+
1) example_pgk
1352+
Invalid parameter value "bad" for "--%throws" annotation. Parameter ignored.
1353+
at "UT3.EXAMPLE_PGK.RAISED_ONE_LISTED_EXCEPTION", line 6
1354+
2) example_pgk
1355+
"--%throws" annotation requires a parameter. Annotation ignored.
1356+
at "UT3.EXAMPLE_PGK.BAD_THROWS_ANNOTATION", line 42
1357+
1358+
Finished in .025784 seconds
1359+
10 tests, 3 failed, 0 errored, 0 disabled, 2 warning(s)
12661360
```
12671361

12681362
## Order of execution
@@ -1335,7 +1429,7 @@ end test_employee_pkg;
13351429
```
13361430

13371431
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-
1432+
13391433
```
13401434
create a savepoint 'before-suite'
13411435
execute setup_employees (--%beforeall)

0 commit comments

Comments
 (0)