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

Skip to content

Commit 9f7ad6e

Browse files
jgebaljgebal
authored
Merge pull request #704 from utPLSQL/feature/parameters_for_before_after_annotations
Feature/parameters for before after annotations
2 parents f0c90dd + 2825cbf commit 9f7ad6e

5 files changed

Lines changed: 1052 additions & 613 deletions

File tree

‎docs/userguide/annotations.md‎

Lines changed: 184 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -23,11 +23,15 @@ We strongly recommend putting package level annotations at the very top of packa
2323
| `--%test(<description>)` | Procedure | Denotes that the annotated procedure is a unit test procedure. Optional test description can by provided (see `displayname`). |
2424
| `--%throws(<exception_number>[,<exception_number>[,...]])`| Procedure | Denotes that the annotated procedure must throw one of the exception numbers provided. If no valid numbers were provided as annotation parameters the annotation is ignored. Applicable to test procedures only. |
2525
| `--%beforeall` | Procedure | Denotes that the annotated procedure should be executed once before all elements of the suite. |
26+
| `--%beforeall([[<owner>.]<package>.]<procedure>[,...])` | Package | Denotes that the mentioned procedure(s) should be executed once before all elements of the suite. |
2627
| `--%afterall` | Procedure | Denotes that the annotated procedure should be executed once after all elements of the suite. |
28+
| `--%afterall([[<owner>.]<package>.]<procedure>[,...])` | Package | Denotes that the mentioned procedure(s) should be executed once after all elements of the suite. |
2729
| `--%beforeeach` | Procedure | Denotes that the annotated procedure should be executed before each `%test` procedure in the suite. |
30+
| `--%beforeeach([[<owner>.]<package>.]<procedure>[,...])` | Package | Denotes that the mentioned procedure(s) should be executed before each `%test` procedure in the suite. |
2831
| `--%aftereach` | Procedure | Denotes that the annotated procedure should be executed after each `%test` procedure in the suite. |
29-
| `--%beforetest(<[owner.[package.]]procedure_name>[,...])` | Procedure | Denotes that mentioned procedure(s) should be executed before the annotated `%test` procedure. |
30-
| `--%aftertest(<[owner.[package.]]procedure_name>[,...]>)` | Procedure | Denotes that mentioned procedure(s) should be executed after the annotated `%test` procedure. |
32+
| `--%aftereach([[<owner>.]<package>.]<procedure>[,...])` | Package | Denotes that the mentioned procedure(s) should be executed after each `%test` procedure in the suite. |
33+
| `--%beforetest([[<owner>.]<package>.]<procedure>[,...])` | Procedure | Denotes that mentioned procedure(s) should be executed before the annotated `%test` procedure. |
34+
| `--%aftertest([[<owner>.]<package>.]<procedure>[,...])` | Procedure | Denotes that mentioned procedure(s) should be executed after the annotated `%test` procedure. |
3135
| `--%rollback(<type>)` | Package/procedure | Defines transaction control. Supported values: `auto`(default) - a savepoint is created before invocation of each "before block" is and a rollback to specific savepoint is issued after each "after" block; `manual` - rollback is never issued automatically. Property can be overridden for child element (test in suite) |
3236
| `--%disabled` | Package/procedure | Used to disable a suite or a test. Disabled suites/tests do not get executed, they are however marked and reported as disabled in a test run. |
3337
| `--%context(<name>)` | Package | Denotes start of a named context (sub-suite) in a suite package |
@@ -301,8 +305,35 @@ Finished in .005868 seconds
301305

302306
### Beforeall
303307

308+
There are two possible ways to use the `--%beforeall` annotation.
309+
310+
As a procedure level annotation:
311+
```sql
312+
--%suite(Some test suite)
313+
314+
--%beforeall
315+
procedure to_be_executed_before_all;
316+
317+
--%test
318+
procedure some_test;
319+
```
304320
Marks annotated procedure to be executed before all test procedures in a suite.
305321

322+
As a package level annotation (not associated with any procedure).
323+
```sql
324+
--%suite(Some test suite)
325+
326+
--%beforeall(to_be_executed_before_all, other_package.some_setup)
327+
328+
--%test
329+
procedure some_test;
330+
331+
procedure to_be_executed_before_all;
332+
333+
```
334+
Indicates that the procedure(s) mentioned as the annotation parameter are to be executed before all test procedures in a suite.
335+
336+
306337
If `--%beforeall` raises an exception, suite content cannot be safely executed as the setup was not executed successfully for the suite.
307338

308339
If `--%beforeall` raises an exception the following will happen:
@@ -357,42 +388,58 @@ Finished in .012292 seconds
357388
2 tests, 0 failed, 0 errored, 0 disabled, 0 warning(s)
358389
```
359390

360-
In the below example, procedure `another_setup` is invoked after `initial_setup`.
361-
The `another_setup` still gets invoked before any test from that suite package is executed.
391+
In the below example a combination pacakge and procedure level `--%beforeall` annotations is used.
392+
The order of execution of the beforeall procedures is determined by the annotation position in package.
393+
All of the `--%beforeall` procedures get invoked before any test is executed in a suite.
362394
```sql
363-
create or replace package test_package as
364-
--%suite(Tests for a package)
365-
366-
--%beforeall
367-
procedure initial_setup;
368-
369-
--%test(Description of tested behavior)
370-
procedure some_test;
371-
372-
--%test(Description of another behavior)
373-
procedure other_test;
395+
create or replace package test_package as
396+
--%suite(Tests for a package)
397+
398+
--%beforeall(initial_setup,test_package.another_setup)
399+
400+
--%test(Description of tested behavior)
401+
procedure some_test;
402+
403+
--%test(Description of another behavior)
404+
procedure other_test;
405+
406+
--%beforeall
407+
procedure next_setup;
408+
409+
--%beforeall(one_more_setup)
410+
411+
procedure another_setup;
412+
procedure one_more_setup;
413+
procedure initial_setup;
374414

375-
--%beforeall
376-
procedure another_setup;
377-
378-
end;
379-
/
380-
create or replace package body test_package as
381-
procedure another_setup is
382-
begin
383-
dbms_output.put_line('--- ANOTHER_SETUP invoked ---');
384-
end;
385-
386-
procedure initial_setup is
387-
begin
388-
dbms_output.put_line('--- INITIAL_SETUP invoked ---');
389-
end;
390-
391-
procedure some_test is begin null; end;
392-
393-
procedure other_test is begin null; end;
394-
end;
395-
/
415+
end;
416+
/
417+
create or replace package body test_package as
418+
procedure one_more_setup is
419+
begin
420+
dbms_output.put_line('--- ONE_MORE_SETUP invoked ---');
421+
end;
422+
423+
procedure next_setup is
424+
begin
425+
dbms_output.put_line('--- NEXT_SETUP invoked ---');
426+
end;
427+
428+
procedure another_setup is
429+
begin
430+
dbms_output.put_line('--- ANOTHER_SETUP invoked ---');
431+
end;
432+
433+
procedure initial_setup is
434+
begin
435+
dbms_output.put_line('--- INITIAL_SETUP invoked ---');
436+
end;
437+
438+
procedure some_test is begin null; end;
439+
440+
procedure other_test is begin null; end;
441+
end;
442+
/
396443
```
397444

398445
```sql
@@ -402,10 +449,12 @@ The `another_setup` still gets invoked before any test from that suite package i
402449
Tests for a package
403450
--- INITIAL_SETUP invoked ---
404451
--- ANOTHER_SETUP invoked ---
405-
Description of tested behavior [.004 sec]
406-
Description of another behavior [.004 sec]
452+
--- NEXT_SETUP invoked ---
453+
--- ONE_MORE_SETUP invoked ---
454+
Description of tested behavior [.003 sec]
455+
Description of another behavior [.002 sec]
407456
408-
Finished in .016672 seconds
457+
Finished in .018944 seconds
409458
2 tests, 0 failed, 0 errored, 0 disabled, 0 warning(s)
410459
```
411460

@@ -468,8 +517,34 @@ Finished in .012158 seconds
468517

469518
### Afterall
470519

520+
There are two possible ways to use the `--%afterall` annotation.
521+
522+
As a procedure level annotation:
523+
```sql
524+
--%suite(Some test suite)
525+
526+
--%afterall
527+
procedure to_be_executed_after_all;
528+
529+
--%test
530+
procedure some_test;
531+
```
471532
Marks annotated procedure to be executed after all test procedures in a suite.
472533

534+
As a package level annotation (not associated with any procedure).
535+
```sql
536+
--%suite(Some test suite)
537+
538+
--%afterall(to_be_executed_after_all, other_package.some_cleanup)
539+
540+
--%test
541+
procedure some_test;
542+
543+
procedure to_be_executed_after_all;
544+
545+
```
546+
Indicates that the procedure(s) mentioned as the annotation parameter are to be executed after all test procedures in a suite.
547+
473548
If `--%afterall` raises an exception the following will happen:
474549
- a warning will be raised, indicating that `--%afterall` procedure has failed
475550
- execution will continue uninterrupted for rest of the suite
@@ -526,11 +601,38 @@ Finished in .014161 seconds
526601

527602
### Beforeeach
528603

529-
Marks annotated procedure to be executed before each test procedure in a suite.
530-
531604
The procedure annotated as `--%beforeeach` is getting executed before each test in a suite.
532605
That means that the procedure will be executed as many times as there are test in suite package.
533606

607+
There are two possible ways to use the `--%beforeeach` annotation.
608+
609+
As a procedure level annotation:
610+
```sql
611+
--%suite(Some test suite)
612+
613+
--%beforeeach
614+
procedure to_be_executed_before_each;
615+
616+
--%test
617+
procedure some_test;
618+
```
619+
Marks annotated procedure to be executed before each test procedures in a suite.
620+
621+
As a package level annotation (not associated with any procedure).
622+
```sql
623+
--%suite(Some test suite)
624+
625+
--%beforeeach(to_be_executed_before_each, other_package.some_setup)
626+
627+
--%test
628+
procedure some_test;
629+
630+
procedure to_be_executed_before_each;
631+
632+
```
633+
Indicates that the procedure(s) mentioned as the annotation parameter are to be executed before each test procedure in a suite.
634+
635+
534636
If a test is marked as disabled the `--%beforeeach` procedure is not invoked for that test.
535637

536638
If `--%beforeeach` raises an unhandled exception the following will happen:
@@ -604,6 +706,7 @@ Finished in .014683 seconds
604706
2 tests, 0 failed, 0 errored, 0 disabled, 0 warning(s)
605707
```
606708

709+
See [beforeall](#Beforeall) for more examples.
607710

608711
### Aftereach
609712

@@ -612,6 +715,34 @@ Marks annotated procedure to be executed after each test procedure in a suite.
612715
The procedure annotated as `--%aftereach` is getting executed after each test in a suite.
613716
That means that the procedure will be executed as many times as there are test in suite package.
614717

718+
There are two possible ways to use the `--%aftereach` annotation.
719+
720+
As a procedure level annotation:
721+
```sql
722+
--%suite(Some test suite)
723+
724+
--%aftereach
725+
procedure to_be_executed_after_each;
726+
727+
--%test
728+
procedure some_test;
729+
```
730+
Marks annotated procedure to be executed after each test procedures in a suite.
731+
732+
As a package level annotation (not associated with any procedure).
733+
```sql
734+
--%suite(Some test suite)
735+
736+
--%aftereach(to_be_executed_after_each, other_package.some_setup)
737+
738+
--%test
739+
procedure some_test;
740+
741+
procedure to_be_executed_after_each;
742+
743+
```
744+
Indicates that the procedure(s) mentioned as the annotation parameter are to be executed after each test procedure in a suite.
745+
615746
If a test is marked as disabled the `--%aftereach` procedure is not invoked for that test.
616747

617748
If `--%aftereach` raises an unhandled exception the following will happen:
@@ -683,6 +814,8 @@ Finished in .018115 seconds
683814
2 tests, 0 failed, 0 errored, 0 disabled, 0 warning(s)
684815
```
685816

817+
See [beforeall](#Beforeall) for more examples.
818+
686819
### Beforetest
687820

688821
Indicates specific setup procedure(s) to be executed for a test. The procedure(s) can be located either:
@@ -711,29 +844,16 @@ The order of execution for `--%beforetest` procedures is defined by:
711844
As a rule, the `--%beforetest` execution gets aborted if preceding `--%beforeeach` or `--%beforetest` failed.
712845

713846
```sql
714-
create or replace package shared_package as
715-
procedure do_some_stuff;
716-
end;
717-
/
718-
719-
create or replace package body shared_package as
720-
procedure do_some_stuff is
721-
begin
722-
dbms_output.put_line('---DO_SOME_STUFF invoked ---');
723-
end;
724-
end;
725-
/
726-
727847
create or replace package test_package as
728848
--%suite(Tests for a package)
729849

730850
--%test(Description of tested behavior)
731-
--%beforetest(setup_for_a_test, shared_package.do_some_stuff)
851+
--%beforetest(test_package.setup_for_a_test)
732852
--%beforetest(another_setup_for_a_test)
733853
procedure some_test;
734854

735855
--%test(Description of another behavior)
736-
--%beforetest(setup_for_a_test)
856+
--%beforetest(test_package.setup_for_a_test, another_setup_for_a_test)
737857
procedure other_test;
738858

739859
procedure another_setup_for_a_test;
@@ -770,16 +890,16 @@ exec ut.run('test_package');
770890
```
771891
```
772892
Tests for a package
773-
Description of tested behavior [.011 sec]
893+
Description of tested behavior [.008 sec]
774894
---SETUP_FOR_A_TEST invoked ---
775-
---DO_SOME_STUFF invoked ---
776895
---ANOTHER_SETUP_FOR_A_TEST invoked ---
777896
---SOME_TEST invoked ---
778897
Description of another behavior [.005 sec]
779898
---SETUP_FOR_A_TEST invoked ---
899+
---ANOTHER_SETUP_FOR_A_TEST invoked ---
780900
---OTHER_TEST invoked ---
781901
782-
Finished in .018446 seconds
902+
Finished in .015185 seconds
783903
2 tests, 0 failed, 0 errored, 0 disabled, 0 warning(s)
784904
```
785905

@@ -809,29 +929,16 @@ The order of execution for `--%aftertest` procedures is defined by:
809929
As a rule, the `--%aftertest` gets executed even if the associated `--%beforeeach`, `--%beforetest`, `--%test` or other `--%aftertest` procedures have raised unhandled exceptions.
810930

811931
```sql
812-
create or replace package shared_package as
813-
procedure do_some_stuff;
814-
end;
815-
/
816-
817-
create or replace package body shared_package as
818-
procedure do_some_stuff is
819-
begin
820-
dbms_output.put_line('---DO_SOME_STUFF invoked ---');
821-
end;
822-
end;
823-
/
824-
825932
create or replace package test_package as
826933
--%suite(Tests for a package)
827934

828935
--%test(Description of tested behavior)
829-
--%aftertest(cleanup_for_a_test, shared_package.do_some_stuff)
936+
--%aftertest(test_package.cleanup_for_a_test)
830937
--%aftertest(another_cleanup_for_a_test)
831938
procedure some_test;
832939

833940
--%test(Description of another behavior)
834-
--%aftertest(cleanup_for_a_test)
941+
--%aftertest(test_package.cleanup_for_a_test, another_cleanup_for_a_test)
835942
procedure other_test;
836943

837944
procedure another_cleanup_for_a_test;
@@ -868,16 +975,16 @@ exec ut.run('test_package');
868975
```
869976
```
870977
Tests for a package
871-
Description of tested behavior [.01 sec]
978+
Description of tested behavior [.008 sec]
872979
---SOME_TEST invoked ---
873980
---CLEANUP_FOR_A_TEST invoked ---
874-
---DO_SOME_STUFF invoked ---
875981
---ANOTHER_CLEANUP_FOR_A_TEST invoked ---
876982
Description of another behavior [.006 sec]
877983
---OTHER_TEST invoked ---
878984
---CLEANUP_FOR_A_TEST invoked ---
985+
---ANOTHER_CLEANUP_FOR_A_TEST invoked ---
879986
880-
Finished in .018691 seconds
987+
Finished in .016873 seconds
881988
2 tests, 0 failed, 0 errored, 0 disabled, 0 warning(s)
882989
```
883990

0 commit comments

Comments
 (0)