Update code.

lwasylow · lwasylow · commit 987d3911c703 · 2022-02-06T15:49:24.000Z
diff --git a/docs/userguide/annotations.md b/docs/userguide/annotations.md
@@ -140,7 +140,7 @@ end;
 | `--%beforetest([[<owner>.]<package>.]<procedure>[,...])` | Procedure | Denotes that mentioned procedure(s) should be executed before the annotated `%test` procedure. |
 | `--%aftertest([[<owner>.]<package>.]<procedure>[,...])` | Procedure | Denotes that mentioned procedure(s) should be executed after the annotated `%test` procedure. |
 | `--%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) |
-| `--%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. |
+| `--%disabled(<reason>)` | Package/procedure | Used to disable a suite, whole context or a test. Disabled suites/contexts/tests do not get executed, they are however marked and reported as disabled in a test run. The reason that will be displayed next to disabled tests is decided based on hierarchy suites -> context -> test |
 | `--%context(<description>)` | Package | Denotes start of a named context (sub-suite) in a suite package an optional description for context can be provided. |
 | `--%name(<name>)` | Package | Denotes name for a context. Must be placed after the context annotation and before start of nested context. |
 | `--%endcontext` | Package | Denotes end of a nested context (sub-suite) in a suite package |
@@ -343,12 +343,13 @@ Finished in .008815 seconds
 
 ### Disabled
 Marks annotated suite package or test procedure as disabled.
+You can provide the reason why the test is disabled that will be displayed in output.
 
 Disabling suite.
 ```sql
 create or replace package test_package as
   --%suite(Tests for a package)
-  --%disabled
+  --%disabled(Reason for disabling suite)
   
   --%test(Description of tested behavior)
   procedure some_test;
@@ -371,13 +372,58 @@ exec ut.run('test_package');
 ```
 ```
 Tests for a package
-  Description of tested behavior [0 sec] (DISABLED)
-  Description of another behavior [0 sec] (DISABLED)
+  Description of tested behavior [0 sec] (DISABLED - Reason for disabling suite)
+  Description of another behavior [0 sec] (DISABLED - Reason for disabling suite)
  
 Finished in .001441 seconds
 2 tests, 0 failed, 0 errored, 2 disabled, 0 warning(s)
 ```
 
+Disabling the context(s).
+```sql
+create or replace package test_package as
+  --%suite(Tests for a package)
+  
+  --%context(Context1)
+
+  --%test(Description of tested behavior)
+  procedure some_test;
+
+  --%endcontext
+
+  --%context(Context2)
+
+  --%disabled(Reason for disabling context2)
+
+  --%test(Description of another behavior)
+  procedure other_test;
+
+  --%endcontext
+end;
+/
+create or replace package body test_package as
+  
+  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
+  Context1
+    Description of tested behavior [.002 sec]
+  Context2
+    Description of another behavior [0 sec] (DISABLED - Reason for disabling context2)
+ 
+Finished in .005079 seconds
+2 tests, 0 failed, 0 errored, 1 disabled, 0 warning(s)
+```
+
 Disabling individual test(s).
 ```sql
 create or replace package test_package as
@@ -387,7 +433,7 @@ create or replace package test_package as
   procedure some_test;
 
   --%test(Description of another behavior)
-  --%disabled
+  --%disabled(Reason for disabling test)
   procedure other_test;
 end;
 /
@@ -406,7 +452,7 @@ exec ut.run('test_package');
 ```
 Tests for a package
   Description of tested behavior [.004 sec]
-  Description of another behavior [0 sec] (DISABLED)
+  Description of another behavior [0 sec] (DISABLED - Reason for disabling test)
  
 Finished in .005868 seconds
 2 tests, 0 failed, 0 errored, 1 disabled, 0 warning(s)
diff --git a/source/api/ut_suite_item_info.tpb b/source/api/ut_suite_item_info.tpb
@@ -17,7 +17,7 @@ create or replace type body ut_suite_item_info is
   */
   constructor function ut_suite_item_info(a_object_owner varchar2, a_object_name varchar2, a_item_name varchar2, 
     a_item_description varchar2, a_item_type varchar2, a_item_line_no integer, a_path varchar2, a_disabled_flag integer,
-    a_tags ut_varchar2_rows) return self as result is  
+    a_disabled_reason varchar2, a_tags ut_varchar2_rows) return self as result is  
   begin
     self.object_owner     := a_object_owner;
     self.object_name      := a_object_name;
@@ -27,6 +27,10 @@ create or replace type body ut_suite_item_info is
     self.item_line_no     := a_item_line_no;
     self.path             := a_path;
     self.disabled_flag    := a_disabled_flag;
+    self.disabled_reason  := case when 
+                               a_disabled_flag = 1 then a_disabled_reason
+                               else null
+                             end;
     self.tags             := case 
                                when a_tags is null then null 
                                when a_tags.count = 0 then null
diff --git a/source/api/ut_suite_item_info.tps b/source/api/ut_suite_item_info.tps
@@ -23,9 +23,10 @@ create or replace type ut_suite_item_info as object (
   item_line_no     integer,         -- line_number where annotation identifying the item exists
   path             varchar2( 4000 ),-- suitepath of the item
   disabled_flag    integer,          -- 0 (zero) if item is not disabled, 1 if item is disabled by --%disabled annotation
+  disabled_reason  varchar2(4000), -- if disable flag is set then you can pass reason
   tags             varchar2(4000),
   constructor function ut_suite_item_info(a_object_owner varchar2, a_object_name varchar2, a_item_name varchar2, 
     a_item_description varchar2, a_item_type varchar2, a_item_line_no integer, a_path varchar2, a_disabled_flag integer,
-    a_tags ut_varchar2_rows) return self as result
+    a_disabled_reason varchar2, a_tags ut_varchar2_rows) return self as result
 )
 /
diff --git a/source/core/types/ut_logical_suite.tpb b/source/core/types/ut_logical_suite.tpb
@@ -16,12 +16,12 @@ create or replace type body ut_logical_suite as
   limitations under the License.
   */
 
-  overriding member procedure mark_as_skipped(self in out nocopy ut_logical_suite) is
+  overriding member procedure mark_as_skipped(self in out nocopy ut_logical_suite, a_skip_reason in varchar2) is
   begin
     ut_event_manager.trigger_event(ut_event_manager.gc_before_suite, self);
     self.start_time := current_timestamp;
     for i in 1 .. self.items.count loop
-      self.items(i).mark_as_skipped();
+      self.items(i).mark_as_skipped(coalesce(a_skip_reason,self.disabled_reason));
     end loop;
     self.end_time := self.start_time;
     ut_event_manager.trigger_event(ut_event_manager.gc_after_suite, self);
diff --git a/source/core/types/ut_logical_suite.tps b/source/core/types/ut_logical_suite.tps
@@ -1,4 +1,4 @@
-create or replace type ut_logical_suite under ut_suite_item (
+create or replace type ut_logical_suite force under ut_suite_item (
   /*
   utPLSQL - Version 3
   Copyright 2016 - 2021 utPLSQL Project
@@ -21,7 +21,7 @@ create or replace type ut_logical_suite under ut_suite_item (
   */
   items        ut_suite_items,
 
-  overriding member procedure mark_as_skipped(self in out nocopy ut_logical_suite),
+  overriding member procedure mark_as_skipped(self in out nocopy ut_logical_suite, a_skip_reason in varchar2),
   overriding member procedure set_rollback_type(self in out nocopy ut_logical_suite, a_rollback_type integer, a_force boolean := false),
   overriding member function  do_execute(self in out nocopy ut_logical_suite) return boolean,
   overriding member procedure calc_execution_result(self in out nocopy ut_logical_suite),
diff --git a/source/core/types/ut_run.tpb b/source/core/types/ut_run.tpb
@@ -39,7 +39,7 @@ create or replace type body ut_run as
     return;
   end;
 
-  overriding member procedure mark_as_skipped(self in out nocopy ut_run) is
+  overriding member procedure mark_as_skipped(self in out nocopy ut_run,a_skip_reason in varchar2) is
   begin
     null;
   end;
diff --git a/source/core/types/ut_run.tps b/source/core/types/ut_run.tps
@@ -36,7 +36,7 @@ create or replace type ut_run under ut_suite_item (
     a_random_test_order_seed positive := null,
     a_run_tags               ut_varchar2_rows := null
   ) return self as result,
-  overriding member procedure mark_as_skipped(self in out nocopy ut_run),
+  overriding member procedure mark_as_skipped(self in out nocopy ut_run,a_skip_reason in varchar2),
   overriding member function  do_execute(self in out nocopy ut_run) return boolean,
   overriding member procedure set_rollback_type(self in out nocopy ut_run, a_rollback_type integer, a_force boolean := false),
   overriding member procedure calc_execution_result(self in out nocopy ut_run),
diff --git a/source/core/types/ut_suite.tpb b/source/core/types/ut_suite.tpb
@@ -44,7 +44,7 @@ create or replace type body ut_suite  as
     ut_utils.debug_log('ut_suite.execute');
 
     if self.get_disabled_flag() then
-      self.mark_as_skipped();
+      self.mark_as_skipped(a_skip_reason => self.disabled_reason);
     else
       self.start_time := current_timestamp;
       ut_event_manager.trigger_event(ut_event_manager.gc_before_suite, self);
diff --git a/source/core/types/ut_suite_cache_row.tps b/source/core/types/ut_suite_cache_row.tps
@@ -1,4 +1,4 @@
-create type ut_suite_cache_row as object (
+create or replace type ut_suite_cache_row as object (
   /*
   utPLSQL - Version 3
   Copyright 2016 - 2021 utPLSQL Project
@@ -26,6 +26,7 @@ create type ut_suite_cache_row as object (
   description          varchar2(4000 byte),
   rollback_type        number,
   disabled_flag        number,
+  disabled_reason      varchar2(4000 byte),
   warnings             ut_varchar2_rows,
   before_all_list      ut_executables,
   after_all_list       ut_executables,
diff --git a/source/core/types/ut_suite_item.tpb b/source/core/types/ut_suite_item.tpb
@@ -26,6 +26,7 @@ create or replace type body ut_suite_item as
     self.line_no       := a_line_no;
     self.transaction_invalidators := ut_varchar2_list();
     self.disabled_flag := ut_utils.boolean_to_int(false);
+    self.disabled_reason := null;
   end;
 
   member function get_disabled_flag return boolean is
diff --git a/source/core/types/ut_suite_item.tps b/source/core/types/ut_suite_item.tps
@@ -46,6 +46,10 @@ create or replace type ut_suite_item force under ut_event_item (
   */
   disabled_flag integer(1),
   /**
+  * Indicates reason whysa test is to be disabled by execution
+  */
+  disabled_reason varchar2(4000),
+  /**
   * Line no where annotation identifying this item is placed in package
   */
   line_no       integer,
@@ -66,7 +70,7 @@ create or replace type ut_suite_item force under ut_event_item (
   tags ut_varchar2_rows,
   member procedure init(self in out nocopy ut_suite_item, a_object_owner varchar2, a_object_name varchar2, a_name varchar2, a_line_no integer),
   member function get_disabled_flag return boolean,
-  not instantiable member procedure mark_as_skipped(self in out nocopy ut_suite_item),
+  not instantiable member procedure mark_as_skipped(self in out nocopy ut_suite_item, a_skip_reason in varchar2),
   member procedure set_rollback_type(self in out nocopy ut_suite_item, a_rollback_type integer, a_force boolean := false),
   member function get_rollback_type return integer,
   member function create_savepoint_if_needed return varchar2,
diff --git a/source/core/types/ut_test.tpb b/source/core/types/ut_test.tpb
@@ -35,11 +35,12 @@ create or replace type body ut_test as
     return;
   end;
 
-  overriding member procedure mark_as_skipped(self in out nocopy ut_test) is
+  overriding member procedure mark_as_skipped(self in out nocopy ut_test, a_skip_reason in varchar2) is
   begin
     ut_event_manager.trigger_event(ut_event_manager.gc_before_test, self);
     self.start_time := current_timestamp;
     self.result := ut_utils.gc_disabled;
+    self.disabled_reason := coalesce(a_skip_reason,self.disabled_reason);
     ut_utils.debug_log('ut_test.execute - disabled');
     self.results_count.set_counter_values(self.result);
     self.end_time := self.start_time;
@@ -54,7 +55,7 @@ create or replace type body ut_test as
     ut_utils.debug_log('ut_test.execute');
 
     if self.get_disabled_flag() then
-      mark_as_skipped();
+      mark_as_skipped(self.disabled_reason);
     else
       self.start_time := current_timestamp;
       ut_event_manager.trigger_event(ut_event_manager.gc_before_test, self);
diff --git a/source/core/types/ut_test.tps b/source/core/types/ut_test.tps
@@ -59,7 +59,7 @@ create or replace type ut_test force under ut_suite_item (
     self in out nocopy ut_test, a_object_owner varchar2 := null, a_object_name varchar2, a_name varchar2,
     a_line_no integer, a_expected_error_codes ut_varchar2_rows := null, a_tags ut_varchar2_rows := null
   ) return self as result,
-  overriding member procedure mark_as_skipped(self in out nocopy ut_test),
+  overriding member procedure mark_as_skipped(self in out nocopy ut_test, a_skip_reason in varchar2),
   overriding member function do_execute(self in out nocopy ut_test) return boolean,
   overriding member procedure calc_execution_result(self in out nocopy ut_test),
   overriding member procedure mark_as_errored(self in out nocopy ut_test, a_error_stack_trace varchar2),
diff --git a/source/core/ut_suite_builder.pkb b/source/core/ut_suite_builder.pkb
@@ -355,6 +355,7 @@ create or replace package body ut_suite_builder is
     l_annotation_texts tt_annotation_texts;
     l_proc_annotations tt_annotations_by_name :=  a_annotations.by_proc(a_procedure_name);
   begin
+
     if not l_proc_annotations.exists(gc_test) then
       return;
     end if;
@@ -412,6 +413,12 @@ create or replace package body ut_suite_builder is
     end if;
     l_test.disabled_flag := ut_utils.boolean_to_int( l_proc_annotations.exists( gc_disabled));
 
+    if l_proc_annotations.exists(gc_disabled) then
+      l_annotation_texts := l_proc_annotations( gc_disabled);
+      --take the last definition if more than one was provided    
+      l_test.disabled_reason := l_annotation_texts(l_annotation_texts.first);
+    end if;
+
     a_suite_items.extend;
     a_suite_items( a_suite_items.last ) := l_test;
 
@@ -560,8 +567,13 @@ create or replace package body ut_suite_builder is
     if a_annotations.by_name.exists(gc_tags) then
       add_tags_to_suite_item(a_suite, a_annotations.by_name(gc_tags),a_suite.tags);
     end if;
+    
     a_suite.disabled_flag := ut_utils.boolean_to_int(a_annotations.by_name.exists(gc_disabled));
-
+    if a_annotations.by_name.exists(gc_disabled) then
+      l_annotation_text := trim(a_annotations.by_name(gc_disabled)(a_annotations.by_name(gc_disabled).first));
+      a_suite.disabled_reason := l_annotation_text;
+    end if;
+    
     --process procedure annotations for suite
     get_annotated_procedures(a_annotations, a_suite, a_suite_items, l_before_each_list, l_after_each_list, l_before_all_list, l_after_all_list);
 
diff --git a/source/core/ut_suite_cache_manager.pkb b/source/core/ut_suite_cache_manager.pkb
@@ -67,7 +67,7 @@ create or replace package body ut_suite_cache_manager is
         select ut_suite_cache_row(
                  null,
                  s.self_type, s.path, s.object_owner, s.object_name,
-                 s.object_name, null, null, null, null, 0,
+                 s.object_name, null, null, null, null, 0,null,
                  ut_varchar2_rows(),
                  s.x, s.x, s.x, s.x, s.x, s.x,
                  s.y, null, s.z
@@ -325,7 +325,7 @@ create or replace package body ut_suite_cache_manager is
             (
                 id, self_type, path, object_owner, object_name, name,
                 line_no, parse_time, description,
-                rollback_type, disabled_flag, warnings,
+                rollback_type, disabled_flag,disabled_reason, warnings,
                 before_all_list, after_all_list,
                 before_each_list, after_each_list,
                 before_test_list, after_test_list,
@@ -339,7 +339,7 @@ create or replace package body ut_suite_cache_manager is
           select /*+ no_parallel */ ut_suite_cache_seq.nextval, s.i.self_type as self_type, s.i.path as path,
                  upper(s.i.object_owner) as object_owner, upper(s.i.object_name) as object_name, upper(s.i.name) as name,
                  s.i.line_no as line_no, s.i.parse_time as parse_time, s.i.description as description,
-                 s.i.rollback_type as rollback_type, s.i.disabled_flag as disabled_flag, s.i.warnings as warnings,
+                 s.i.rollback_type as rollback_type, s.i.disabled_flag as disabled_flag,s.i.disabled_reason as disabled_reason, s.i.warnings as warnings,
                  s.i.before_all_list as before_all_list, s.i.after_all_list as after_all_list,
                  null before_each_list, null after_each_list,
                  null before_test_list, null after_test_list,
@@ -351,7 +351,7 @@ create or replace package body ut_suite_cache_manager is
           (
             id, self_type, path, object_owner, object_name, name,
             line_no, parse_time, description,
-            rollback_type, disabled_flag, warnings,
+            rollback_type, disabled_flag,disabled_reason, warnings,
             before_all_list, after_all_list,
             before_each_list, after_each_list,
             before_test_list, after_test_list,
@@ -365,7 +365,7 @@ create or replace package body ut_suite_cache_manager is
         select /*+ no_parallel */ ut_suite_cache_seq.nextval, s.t.self_type as self_type, s.t.path as path,
                upper(s.t.object_owner) as object_owner, upper(s.t.object_name) as object_name, upper(s.t.name) as name,
                s.t.line_no as line_no, s.t.parse_time as parse_time, s.t.description as description,
-               s.t.rollback_type as rollback_type, s.t.disabled_flag as disabled_flag, s.t.warnings as warnings,
+               s.t.rollback_type as rollback_type, s.t.disabled_flag as disabled_flag, s.t.disabled_reason as disabled_reason, s.t.warnings as warnings,
                null before_all_list, null after_all_list,
                s.t.before_each_list as before_each_list, s.t.after_each_list as after_each_list,
                s.t.before_test_list as before_test_list, s.t.after_test_list as after_test_list,
@@ -408,7 +408,7 @@ create or replace package body ut_suite_cache_manager is
     select /*+ no_parallel */ ut_suite_item_info(
              c.object_owner, c.object_name, c.name,
              c.description, c.self_type, c.line_no,
-             c.path, c.disabled_flag, c.tags
+             c.path, c.disabled_flag, c.disabled_reason, c.tags
              )
       bulk collect into l_results
       from table(l_cache_rows) c;
diff --git a/source/core/ut_suite_manager.pkb b/source/core/ut_suite_manager.pkb
diff --git a/source/reporters/ut_documentation_reporter.tpb b/source/reporters/ut_documentation_reporter.tpb
diff --git a/test/install_ut3_tester_tests.sql b/test/install_ut3_tester_tests.sql
diff --git a/test/ut3_tester/core/annotations/test_annot_disabled_reason.pkb b/test/ut3_tester/core/annotations/test_annot_disabled_reason.pkb
diff --git a/test/ut3_tester/core/annotations/test_annot_disabled_reason.pks b/test/ut3_tester/core/annotations/test_annot_disabled_reason.pks
diff --git a/test/ut3_user/api/test_ut_runner.pkb b/test/ut3_user/api/test_ut_runner.pkb

Original file line number	Diff line number	Diff line change
`@@ -23,9 +23,10 @@ create or replace type ut_suite_item_info as object (`
`23`	`23`	`item_line_no integer, -- line_number where annotation identifying the item exists`
`24`	`24`	`path varchar2( 4000 ),-- suitepath of the item`
`25`	`25`	`disabled_flag integer, -- 0 (zero) if item is not disabled, 1 if item is disabled by --%disabled annotation`
	`26`	`+ disabled_reason varchar2(4000), -- if disable flag is set then you can pass reason`
`26`	`27`	`tags varchar2(4000),`
`27`	`28`	`constructor function ut_suite_item_info(a_object_owner varchar2, a_object_name varchar2, a_item_name varchar2,`
`28`	`29`	`a_item_description varchar2, a_item_type varchar2, a_item_line_no integer, a_path varchar2, a_disabled_flag integer,`
`29`		`- a_tags ut_varchar2_rows) return self as result`
	`30`	`+ a_disabled_reason varchar2, a_tags ut_varchar2_rows) return self as result`
`30`	`31`	`)`
`31`	`32`	`/`