Update code.

utPLSQL · lwasylow · Feb 8, 2022 · Feb 6, 2022 · Feb 6, 2022 · Feb 6, 2022
commit 987d3911c703ce9da8334b6a4cc3a8c9d0d4c49f
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;