Updates to documentation.

Added additional warnings.
utPLSQL · jgebal · Apr 25, 2018 · Mar 4, 2018 · Mar 14, 2018 · Mar 15, 2018
commit b1ff0fc57edd96675efbe2e70475745c5ec70458
diff --git a/docs/userguide/annotations.md b/docs/userguide/annotations.md
@@ -136,10 +136,7 @@ create or replace package test_package as
 end;
 /
 create or replace package body test_package as
-  procedure some_test is
-  begin
-    null;
-  end;
+  procedure some_test is begin null; end;
 end;
 /
 ```
@@ -164,10 +161,7 @@ create or replace package test_package as
 end;
 /
 create or replace package body test_package as
-  procedure some_test is
-  begin
-    null;
-  end;
+  procedure some_test is begin null; end;
 end;
 /
 ```
@@ -194,10 +188,7 @@ create or replace package test_package as
 end;
 /
 create or replace package body test_package as
-  procedure some_test is
-  begin
-    null;
-  end;
+  procedure some_test is begin null; end;
 end;
 /
 ```
@@ -237,14 +228,10 @@ create or replace package test_package as
 end;
 /
 create or replace package body test_package as
-  procedure some_test is
-  begin
-    null;
-  end;
-  procedure other_test is
-  begin
-    null;
-  end;
+
+  procedure some_test is begin null; end;
+
+  procedure other_test is begin null; end;
 end;
 /
 ```
@@ -275,14 +262,10 @@ create or replace package test_package as
 end;
 /
 create or replace package body test_package as
-  procedure some_test is
-  begin
-    null;
-  end;
-  procedure other_test is
-  begin
-    null;
-  end;
+
+  procedure some_test is begin null; end;
+
+  procedure other_test is begin null; end;
 end;
 /
 ```
@@ -324,14 +307,10 @@ create or replace package body test_package as
   begin
     dbms_output.put_line('--- SETUP_STUFF invoked ---');
   end;
-  procedure some_test is
-  begin
-    null;
-  end;
-  procedure other_test is
-  begin
-    null;
-  end;
+
+  procedure some_test is begin null; end;
+
+  procedure other_test is begin null; end;
 end;
 /
 ```
@@ -351,7 +330,8 @@ Finished in .012292 seconds
 
 
 When you define multiple beforeall procedures, all of them will get executed before invoking any test in package.
-Order of execution for beforeall procedures is defined by the position of the `--%beforeall` annotation in the package specification. 
+Order of execution for beforeall procedures is defined by the position of the `--%beforeall` annotation in the package specification.
+Note that procedure `another_setup` is also invoked before any test, though it's located at the end of package specification.  
  ```sql
  create or replace package test_package as
    --%suite(Tests for a package)
@@ -375,18 +355,62 @@ Order of execution for beforeall procedures is defined by the position of the `-
    begin
      dbms_output.put_line('--- ANOTHER_SETUP invoked ---');
    end;
+
    procedure initial_setup is
    begin
      dbms_output.put_line('--- INITIAL_SETUP invoked ---');
    end;
-   procedure some_test is
-   begin
-     null;
-   end;
-   procedure other_test is
+
+   procedure some_test is begin null; end;
+
+   procedure other_test is begin null; end;
+ end;
+ /
+```
+
+ ```sql
+ exec ut.run('test_package');
+ ```
+ ```
+Tests for a package
+  --- INITIAL_SETUP invoked ---
+  --- ANOTHER_SETUP invoked ---
+  Description of tesed behavior [.004 sec]
+  Description of another behavior [.004 sec]
+
+Finished in .016672 seconds
+2 tests, 0 failed, 0 errored, 0 disabled, 0 warning(s)
+ ```
+
+When multiple `--%beforeall` annotations are specified for a procedure, the first annotation will be used and a warning message will appear indicating duplicate annotation.  
+When procedure is annotated as both `--%beforeall` and `--%test`, the procedure will become a test and a warning message will appear indicating invalid annotation combination.    
+```sql
+ create or replace package test_package as
+   --%suite(Tests for a package)
+
+   --%beforeall
+   --%beforeall
+   procedure initial_setup;
+
+   --%test(Description of tesed behavior)
+   --%beforeall
+   procedure some_test;
+
+   --%test(Description of another behavior)
+   procedure other_test;
+
+ end;
+ /
+ create or replace package body test_package as
+
+   procedure initial_setup is
    begin
-     null;
+     dbms_output.put_line('--- INITIAL_SETUP invoked ---');
    end;
+
+   procedure some_test is begin null; end;
+
+   procedure other_test is begin null; end;
  end;
  /
 ```

diff --git a/source/core/ut_suite_builder.pkb b/source/core/ut_suite_builder.pkb
@@ -289,9 +289,6 @@ create or replace package body ut_suite_builder is
   begin
     l_test := ut_test(a_suite.object_owner, a_suite.object_name, a_procedure_name);
 
-    warning_on_duplicate_annot(a_suite, a_procedure_name, a_annotations, 'test');
---     warning_on_duplicate_annot(a_suite, a_procedure_name, a_annotations, 'displayname');
---     warning_on_duplicate_annot(a_suite, a_procedure_name, a_annotations, 'rollback');
     if a_annotations.exists('displayname') then
       l_annotation_texts := a_annotations('displayname');
       --take the last definition if more than one was provided
@@ -360,6 +357,13 @@ create or replace package body ut_suite_builder is
     a_after_each_list  in out nocopy ut_executables
   ) is
   begin
+    warning_on_duplicate_annot(a_suite, a_procedure_name, a_proc_annotations, 'test');
+    --     warning_on_duplicate_annot(a_suite, a_procedure_name, a_proc_annotations, 'displayname');
+    --     warning_on_duplicate_annot(a_suite, a_procedure_name, a_proc_annotations, 'rollback');
+    warning_on_duplicate_annot(a_suite, a_procedure_name, a_proc_annotations, 'beforeall');
+    warning_on_duplicate_annot(a_suite, a_procedure_name, a_proc_annotations, 'beforeeach');
+    warning_on_duplicate_annot(a_suite, a_procedure_name, a_proc_annotations, 'afterall');
+    warning_on_duplicate_annot(a_suite, a_procedure_name, a_proc_annotations, 'aftereach');
     if a_proc_annotations.exists('test') then
       add_test( a_suite, a_procedure_name, a_proc_annotations);
 

diff --git a/test/core/test_suite_builder.pkb b/test/core/test_suite_builder.pkb
@@ -168,6 +168,78 @@ create or replace package body test_suite_builder is
     );
   end;
 
+  procedure beforeall_annot_duplicated is
+    l_actual      clob;
+    l_annotations ut3.ut_annotations;
+  begin
+      --Arrange
+    l_annotations := ut3.ut_annotations(
+        ut3.ut_annotation(2, 'suite','Cool', null),
+        ut3.ut_annotation(8, 'beforeall', null, 'test_procedure'),
+        ut3.ut_annotation(9, 'beforeall', null, 'test_procedure')
+    );
+    --Act
+    l_actual := invoke_builder_for_annotations(l_annotations, 'SOME_PACKAGE');
+    --Assert
+    ut.expect(l_actual).to_be_like(
+        '%<DESCRIPTION>Cool</DESCRIPTION>%<WARNINGS>%&quot;--%beforeall&quot;%UT3_TESTER.SOME_PACKAGE.TEST_PROCEDURE%line 9%</WARNINGS>%'
+    );
+  end;
+
+  procedure beforeeach_annot_duplicated is
+    l_actual      clob;
+    l_annotations ut3.ut_annotations;
+  begin
+      --Arrange
+    l_annotations := ut3.ut_annotations(
+        ut3.ut_annotation(2, 'suite','Cool', null),
+        ut3.ut_annotation(8, 'beforeeach', null, 'test_procedure'),
+        ut3.ut_annotation(9, 'beforeeach', null, 'test_procedure')
+    );
+    --Act
+    l_actual := invoke_builder_for_annotations(l_annotations, 'SOME_PACKAGE');
+    --Assert
+    ut.expect(l_actual).to_be_like(
+        '%<DESCRIPTION>Cool</DESCRIPTION>%<WARNINGS>%&quot;--%beforeeach&quot;%UT3_TESTER.SOME_PACKAGE.TEST_PROCEDURE%line 9%</WARNINGS>%'
+    );
+  end;
+
+  procedure afterall_annot_duplicated is
+    l_actual      clob;
+    l_annotations ut3.ut_annotations;
+  begin
+      --Arrange
+    l_annotations := ut3.ut_annotations(
+        ut3.ut_annotation(2, 'suite','Cool', null),
+        ut3.ut_annotation(8, 'afterall', null, 'test_procedure'),
+        ut3.ut_annotation(9, 'afterall', null, 'test_procedure')
+    );
+    --Act
+    l_actual := invoke_builder_for_annotations(l_annotations, 'SOME_PACKAGE');
+    --Assert
+    ut.expect(l_actual).to_be_like(
+        '%<DESCRIPTION>Cool</DESCRIPTION>%<WARNINGS>%&quot;--%afterall&quot;%UT3_TESTER.SOME_PACKAGE.TEST_PROCEDURE%line 9%</WARNINGS>%'
+    );
+  end;
+
+  procedure aftereach_annot_duplicated is
+    l_actual      clob;
+    l_annotations ut3.ut_annotations;
+  begin
+    --Arrange
+    l_annotations := ut3.ut_annotations(
+        ut3.ut_annotation(2, 'suite','Cool', null),
+        ut3.ut_annotation(8, 'aftereach', null, 'test_procedure'),
+        ut3.ut_annotation(9, 'aftereach', null, 'test_procedure')
+    );
+    --Act
+    l_actual := invoke_builder_for_annotations(l_annotations, 'SOME_PACKAGE');
+    --Assert
+    ut.expect(l_actual).to_be_like(
+        '%<DESCRIPTION>Cool</DESCRIPTION>%<WARNINGS>%&quot;--%aftereach&quot;%UT3_TESTER.SOME_PACKAGE.TEST_PROCEDURE%line 9%</WARNINGS>%'
+    );
+  end;
+
   procedure suitepath_annot_duplicated is
     l_actual      clob;
     l_annotations ut3.ut_annotations;

diff --git a/test/core/test_suite_builder.pks b/test/core/test_suite_builder.pks
@@ -26,6 +26,18 @@ create or replace package test_suite_builder is
   --%test(Gives warning if more than one --%test annotation used)
   procedure test_annot_duplicated;
 
+  --%test(Gives warning if more than one --%beforeall annotation used)
+  procedure beforeall_annot_duplicated;
+
+  --%test(Gives warning if more than one --%beforeeach annotation used)
+  procedure beforeeach_annot_duplicated;
+
+  --%test(Gives warning if more than one --%afterall annotation used)
+  procedure afterall_annot_duplicated;
+
+  --%test(Gives warning if more than one --%aftereach annotation used)
+  procedure aftereach_annot_duplicated;
+
   --%test(Gives warning if more than one --%suitepath annotation used)
   procedure suitepath_annot_duplicated;