utPLSQL · lwasylow · Feb 8, 2022 · Feb 6, 2022 · Feb 6, 2022 · Feb 6, 2022
diff --git a/.github/scripts/xsd/junit_windy.xsd b/.github/scripts/xsd/junit_windy.xsd
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
-
-<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+<xs:schema
+	xmlns:xs="http://www.w3.org/2001/XMLSchema"
 	 elementFormDefault="qualified"
 	 attributeFormDefault="unqualified">
 	<xs:annotation>
@@ -71,10 +71,11 @@ Permission to waive conditions of this license may be requested from Windy Road
 			<xs:element name="testcase" minOccurs="0" maxOccurs="unbounded">
 				<xs:complexType>
 					<xs:choice minOccurs="0">
-						<xs:element name="error">
-			<xs:annotation>
-				<xs:documentation xml:lang="en">Indicates that the test errored.  An errored test is one that had an unanticipated problem. e.g., an unchecked throwable; or a problem with the implementation of the test. Contains as a text node relevant data for the error, e.g., a stack trace</xs:documentation>
-			</xs:annotation>
+						<xs:element name="skipped" />
+						<xs:element name="error" minOccurs="0" maxOccurs="1">
+							<xs:annotation>
+								<xs:documentation xml:lang="en">Indicates that the test errored.  An errored test is one that had an unanticipated problem. e.g., an unchecked throwable; or a problem with the implementation of the test. Contains as a text node relevant data for the error, e.g., a stack trace</xs:documentation>
+							</xs:annotation>
 							<xs:complexType>
 								<xs:simpleContent>
 									<xs:extension base="pre-string">
@@ -93,9 +94,9 @@ Permission to waive conditions of this license may be requested from Windy Road
 							</xs:complexType>
 						</xs:element>
 						<xs:element name="failure">
-			<xs:annotation>
-				<xs:documentation xml:lang="en">Indicates that the test failed. A failure is a test which the code has explicitly failed by using the mechanisms for that purpose. e.g., via an assertEquals. Contains as a text node relevant data for the failure, e.g., a stack trace</xs:documentation>
-			</xs:annotation>
+							<xs:annotation>
+								<xs:documentation xml:lang="en">Indicates that the test failed. A failure is a test which the code has explicitly failed by using the mechanisms for that purpose. e.g., via an assertEquals. Contains as a text node relevant data for the failure, e.g., a stack trace</xs:documentation>
+							</xs:annotation>
 							<xs:complexType>
 								<xs:simpleContent>
 									<xs:extension base="pre-string">
@@ -192,6 +193,11 @@ Permission to waive conditions of this license may be requested from Windy Road
 				<xs:documentation xml:lang="en">The total number of tests in the suite that errored. An errored test is one that had an unanticipated problem. e.g., an unchecked throwable; or a problem with the implementation of the test.</xs:documentation>
 			</xs:annotation>
 		</xs:attribute>
+		<xs:attribute name="skipped" type="xs:int" use="optional">
+			<xs:annotation>
+				<xs:documentation xml:lang="en">The total number of ignored or skipped tests in the suite.</xs:documentation>
+			</xs:annotation>
+		</xs:attribute>
 		<xs:attribute name="time" type="xs:decimal" use="required">
 			<xs:annotation>
 				<xs:documentation xml:lang="en">Time taken (in seconds) to execute the tests in the suite</xs:documentation>
@@ -203,4 +209,4 @@ Permission to waive conditions of this license may be requested from Windy Road
 			<xs:whiteSpace value="preserve"/>
 		</xs:restriction>
 	</xs:simpleType>
-</xs:schema>
+</xs:schema>
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,12 @@ 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
+      a_suite.disabled_reason := a_annotations.by_name(gc_disabled)(a_annotations.by_name(gc_disabled).first);
+    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);
-Original file line number
+Diff line change
@@ Expand Up / @@ -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;
@@ Expand Down @@