Addressing changes via PR review.

utPLSQL · jgebal · Apr 28, 2023 · Mar 28, 2023 · Mar 28, 2023 · Mar 29, 2023
commit dc0b4a60dfa799b360245bc7c39480e11861f564
diff --git a/docs/userguide/annotations.md b/docs/userguide/annotations.md
@@ -1617,46 +1617,8 @@ or
 Tags are defined as a comma separated list within the `--%tags` annotation. 

 When a suite/context is tagged, all of its children will automatically inherit the tag and get executed along with the parent, unless they are excluded explicitly at runtime with a negated tag expression.
-Parent suite tests are not executed, but a suitepath hierarchy is kept.
+See [running unit tests](running-unit-tests.md) for more information on using tags to filter test suites that are to be executed.

-Sample test suite package with tags.
-```sql linenums="1"
-create or replace package ut_sample_test is
-
-   --%suite(Sample Test Suite)
-   --%tags(api)
-
-   --%test(Compare Ref Cursors)
-   --%tags(complex,fast)
-   procedure ut_refcursors1;
-
-   --%test(Run equality test)
-   --%tags(simple,fast)
-   procedure ut_test;
-
-end ut_sample_test;
-/
-
-create or replace package body ut_sample_test is
-
-   procedure ut_refcursors1 is
-      v_actual   sys_refcursor;
-      v_expected sys_refcursor;
-   begin
-    open v_expected for select 1 as test from dual;
-    open v_actual   for select 2 as test from dual;
-
-      ut.expect(v_actual).to_equal(v_expected);
-   end;
-
-   procedure ut_test is
-   begin
-       ut.expect(1).to_equal(0);
-   end;
-
-end ut_sample_test;
-/
-```
 #### Tag naming convention

 Tags must follow the below naming convention:

diff --git a/docs/userguide/running-unit-tests.md b/docs/userguide/running-unit-tests.md
@@ -323,7 +323,7 @@ Multiple tags are separated by comma.

 ### Tag Expressions

-Tag expressions are boolean expressions with the operators !, & and |. In addition, ( and ) can be used to adjust for operator precedence.
+Tag expressions are boolean expressions created by combining tags with the `!`, `&`, `|` operators. Tag expressions can be grouped using `(` and `)` braces. Grouping tag expressions affects operator precedence.

 | Operator | Meaning |
 | -------- | --------|
@@ -338,28 +338,86 @@ If you are tagging your tests across multiple dimensions, tag expressions help y
 | -------- | --------|
 | product        | all tests for product     |
 | catalog \| shipping        | all tests for catalog plus all tests for shipping     |
-| catalog & shipping       | all tests for the intersection between catalog and shipping     |
-| product & !end-to-end | all tests for product, but not the end-to-end tests |
+| catalog & shipping       | all tests that are tagged with both `catalog` and `shipping` tags      |
+| product & !end-to-end | all tests tagged `product`, except the tests tagged `end-to-end` |
 | (micro \| integration) & (product \| shipping) | all micro or integration tests for product or shipping |


-Execution of the test is done by using the parameter `a_tags` with tag expressions
+Taking the last expression above `(micro | integration) & (product | shipping)`

+| --%tags	|included in run |
+| -------- | --------|
+| micro	| no |
+| integration |	no |
+| micro	| no | 
+| product	| no |
+| shipping	| no |
+| micro	| no |
+| micro, integration | no |
+| product, shipping	| no |
+| micro, product	| yes |
+| micro, shipping	| yes |
+| integration, product |	yes |
+| integration, shipping |	yes |
+| integration, micro, shipping |	yes |
+| integration, micro, product |	yes |
+| integration, shipping ,product |	yes |
+| micro, shipping ,product |	yes |
+| integration, micro, shipping ,product |	yes |
+
+
+### Sample execution of test with tags.
+
+Execution of the test with tag expressions is done using the parameter `a_tags`.
+Given a test package `ut_sample_test` defined below 

 ```sql linenums="1"
-select * from table(ut.run(a_tags => 'fast|!complex'));
+create or replace package ut_sample_test is
+
+   --%suite(Sample Test Suite)
+   --%tags(api)
+
+   --%test(Compare Ref Cursors)
+   --%tags(complex,fast)
+   procedure ut_refcursors1;
+
+   --%test(Run equality test)
+   --%tags(simple,fast)
+   procedure ut_test;
+
+end ut_sample_test;
+/
+
+create or replace package body ut_sample_test is
+
+   procedure ut_refcursors1 is
+      v_actual   sys_refcursor;
+      v_expected sys_refcursor;
+   begin
+    open v_expected for select 1 as test from dual;
+    open v_actual   for select 2 as test from dual;
+
+      ut.expect(v_actual).to_equal(v_expected);
+   end;
+
+   procedure ut_test is
+   begin
+       ut.expect(1).to_equal(0);
+   end;
+
+end ut_sample_test;
+/
 ```
-The above call will execute all tests from `ut_sample_test` package as the whole suite is tagged with `api` because a suite meet expression condition.

 ```sql linenums="1"
 select * from table(ut.run(a_path => 'ut_sample_test',a_tags => 'api'));
 ```
 The above call will execute all tests from `ut_sample_test` package as the whole suite is tagged with `api`

 ```sql linenums="1"
-select * from table(ut.run(a_tags => 'complex'));
+select * from table(ut.run(a_tags => 'fast&complex'));
 ```
-The above call will execute only the `ut_sample_test.ut_refcursors1` test, as only the test `ut_refcursors1` is tagged with `complex`
+The above call will execute only the `ut_sample_test.ut_refcursors1` test, as only the test `ut_refcursors1` is tagged with `complex` and `fast`

 ```sql linenums="1"
 select * from table(ut.run(a_tags => 'fast'));
@@ -376,25 +434,13 @@ Examples (based on above sample test suite)
 select * from table(ut.run(a_tags => '(api|fast)&!complex'));
 ```

-which is equivalent of legacy calling:
-
-```sql linenums="1"
-select * from table(ut.run(a_tags => 'api,fast,-complex'));
-```
-
 or 

 ```sql linenums="1"
-select * from table(ut.run(a_tags => '(api|fast)&(!complex&!test1)'));
-```
-
-which is equivalent of legacy calling:
-
-```sql linenums="1"
-select * from table(ut.run(a_tags => 'api,fast,-complex,-test1'));
+select * from table(ut.run(a_tags => '(api|fast)&!complex&!test1'));
 ```

-The above call will execute all suites/contexts/tests that are marked with any of tags `api` or `fast` except those suites/contexts/tests that are marked as `complex`.  
+The above call will execute all suites/contexts/tests that are marked with any of tags `api` or `fast` except those suites/contexts/tests that are marked as `complex` and except those suites/contexts/tests that are marked as `test1`. 
 Given the above example package `ut_sample_test`, only `ut_sample_test.ut_test` will be executed.  



diff --git a/source/core/ut_suite_cache_manager.pkb b/source/core/ut_suite_cache_manager.pkb
@@ -285,18 +285,6 @@ create or replace package body ut_suite_cache_manager is
    return l_results;
  end;

-  function get_cached_suites(
-    a_schema_paths     ut_path_items,
-    a_random_seed      positive := null 
-  ) return ut_suite_cache_rows is
-    l_suite_items     ut_suite_cache_rows := ut_suite_cache_rows();
-    l_schema_paths    ut_path_items;  
-  begin
-    l_schema_paths := a_schema_paths;
-    l_suite_items := get_suite_items(a_schema_paths);
-    return l_suite_items;
-  end;
-
  function get_schema_parse_time(a_schema_name varchar2) return timestamp result_cache is
    l_cache_parse_time timestamp;
  begin
@@ -443,7 +431,7 @@ create or replace package body ut_suite_cache_manager is
    a_schema_paths     ut_path_items
  ) return ut_suite_cache_rows is
  begin
-    return get_cached_suite_rows(get_cached_suites( a_schema_paths ));
+    return get_cached_suite_rows(get_suite_items(a_schema_paths));
  end;

  function get_suite_items_info(

diff --git a/source/core/ut_suite_cache_manager.pks b/source/core/ut_suite_cache_manager.pks
@@ -58,11 +58,6 @@ create or replace package ut_suite_cache_manager authid definer is
    a_suites_filtered ut_suite_cache_rows 
  ) return ut_suite_cache_rows;

-  function get_cached_suites(
-    a_schema_paths     ut_path_items,
-    a_random_seed      positive := null
-  ) return ut_suite_cache_rows;
-
  function get_schema_paths(a_paths in ut_varchar2_list) return ut_path_items;

  /*
@@ -77,6 +72,10 @@ create or replace package ut_suite_cache_manager authid definer is
  function get_suite_items_info(
    a_suite_cache_items ut_suite_cache_rows
  ) return ut_suite_items_info;
+
+  function get_suite_items (
+    a_schema_paths ut_path_items
+  ) return ut_suite_cache_rows;

  /*
  * Retrieves list of cached suite packages.

diff --git a/source/core/ut_suite_manager.pkb b/source/core/ut_suite_manager.pkb
@@ -360,10 +360,7 @@ create or replace package body ut_suite_manager is
    l_filtered_rows      ut_suite_cache_rows;
    l_result             t_cached_suites_cursor;
  begin
-    l_unfiltered_rows := ut_suite_cache_manager.get_cached_suites(
-      a_schema_paths,
-      a_random_seed
-    );
+    l_unfiltered_rows := ut_suite_cache_manager.get_suite_items(a_schema_paths);

    l_tag_filter_applied := ut_suite_tag_filter.apply(l_unfiltered_rows,a_tags);
    l_filtered_rows := get_filtered_cursor(ut_suite_cache_manager.get_cached_suite_rows(l_tag_filter_applied),a_skip_all_objects);