utPLSQL · jgebal · Apr 28, 2023 · Mar 28, 2023 · Mar 28, 2023 · Mar 29, 2023
diff --git a/docs/userguide/annotations.md b/docs/userguide/annotations.md
@@ -1616,11 +1616,8 @@ or
 
 Tags are defined as a comma separated list within the `--%tags` annotation. 
 
-When executing a test run with tag filter applied, the framework will find all tests associated with the given tags and execute them. 
-The framework applies `OR` logic to all specified tags so any test / suite that matches at least one tag will be included in the test run. 
-
-When a suite/context is tagged, all of its children will automatically inherit the tag and get executed along with the parent. Parent suite tests are not executed, but a suitepath hierarchy is kept.
-
+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.
 
 Sample test suite package with tags.
 ```sql linenums="1"
@@ -1660,51 +1657,23 @@ create or replace package body ut_sample_test is
 end ut_sample_test;
 /
 ```
-
-Execution of the test is done by using the parameter `a_tags`
-
-```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'));
-```
-The above call will execute only the `ut_sample_test.ut_refcursors1` test, as only the test `ut_refcursors1` is tagged with `complex`
-
-```sql linenums="1"
-select * from table(ut.run(a_tags => 'fast'));
-```
-The above call will execute both `ut_sample_test.ut_refcursors1` and `ut_sample_test.ut_test` tests, as both tests are tagged with `fast`
-
 #### Tag naming convention
 
 Tags must follow the below naming convention:
 
 - tag is case sensitive
-- tag can contain special characters like `$#/\?-!` etc.
-- tag cannot be an empty string
+- tag must not contain any of the following reserved characters:
+  - comma (,)
+  - left or right parenthesis ((, ))
+  - ampersand (&)
+  - vertical bar (|)
+  - exclamation point (!)
+- tag cannot be null or blank
 - tag cannot start with a dash, e.g. `-some-stuff` is **not** a valid tag
 - tag cannot contain spaces, e.g. `test of batch`. To create a multi-word tag use underscores or dashes, e.g. `test_of_batch`, `test-of-batch`
 - leading and trailing spaces are ignored in tag name, e.g. `--%tags(  tag1  ,   tag2  )` becomes `tag1` and `tag2` tag names
 
 
-#### Excluding tests/suites by tags
-
-It is possible to exclude parts of test suites with tags.
-In order to do so, prefix the tag name to exclude with a `-` (dash) sign when invoking the test run.
-
-Examples (based on above sample test suite)
-
-```sql linenums="1"
-select * from table(ut.run(a_tags => 'api,fast,-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`.  
-Given the above example package `ut_sample_test`, only `ut_sample_test.ut_test` will be executed.  
-
-
-
 ### Suitepath
 
 It is very likely that the application for which you are going to introduce tests consists of many different packages, procedures and functions.

diff --git a/docs/userguide/running-unit-tests.md b/docs/userguide/running-unit-tests.md
@@ -319,23 +319,85 @@ select * from table(ut.run('hr.test_apply_bonus', a_random_test_order_seed => 30
 
 In addition to the path, you can filter the tests to be run by specifying tags. Tags are defined in the test / context / suite with the `--%tags`-annotation ([Read more](annotations.md#tags)).  
 Multiple tags are separated by comma. 
-The framework applies `OR` logic to all specified tags so any test / suite that matches at least one tag will be included in the test run.
+
+
+### Tag Expressions
+
+Tag expressions are boolean expressions with the operators !, & and |. In addition, ( and ) can be used to adjust for operator precedence.
+
+| Operator | Meaning |
+| -------- | --------|
+| !        | not     |
+| &        | and     |
+| \|        | or      |
+
+If you are tagging your tests across multiple dimensions, tag expressions help you to select which tests to execute. When tagging by test type (e.g., micro, integration, end-to-end) and feature (e.g., product, catalog, shipping), the following tag expressions can be useful.
+
+
+| Tag Expression | Selection |
+| -------- | --------|
+| 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 |
+| (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
+
 
 ```sql linenums="1"
-begin
-  ut.run('hr.test_apply_bonus', a_tags => 'test1,test2');
-end;
+select * from table(ut.run(a_tags => 'fast|!complex'));
+```
+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'));
 ```
+The above call will execute only the `ut_sample_test.ut_refcursors1` test, as only the test `ut_refcursors1` is tagged with `complex`
+
 ```sql linenums="1"
-select * from table(ut.run('hr.test_apply_bonus', a_tags => 'suite1'))
+select * from table(ut.run(a_tags => 'fast'));
 ```
+The above call will execute both `ut_sample_test.ut_refcursors1` and `ut_sample_test.ut_test` tests, as both tests are tagged with `fast`
+
+### Excluding tests/suites by tags
 
-You can also exclude specific tags by adding a `-` (dash) in front of the tag
+It is possible to exclude parts of test suites with tags.
+In order to do so, prefix the tag name to exclude with a `!` (exclamation) sign when invoking the test run which is equivalent of `-` (dash) in legacy notation.
+Examples (based on above sample test suite)
 
 ```sql linenums="1"
-select * from table(ut.run('hr.test_apply_bonus', a_tags => '-suite1'))
+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'));
+```
+
+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`.  
+Given the above example package `ut_sample_test`, only `ut_sample_test.ut_test` will be executed.  
+
+
 ## Keeping uncommitted data after test-run
 
 utPLSQL by default runs tests in autonomous transaction and performs automatic rollback to assure that tests do not impact one-another and do not have impact on the current session in your IDE.

diff --git a/source/api/ut_runner.pkb b/source/api/ut_runner.pkb
@@ -78,8 +78,7 @@ create or replace package body ut_runner is
     l_run                     ut_run;
     l_coverage_schema_names   ut_varchar2_rows;
     l_paths                   ut_varchar2_list;
-    l_random_test_order_seed  positive;
-    l_tags                    ut_varchar2_rows := ut_varchar2_rows();
+    l_random_test_order_seed  positive;    
   begin
     ut_event_manager.initialize();
     if a_reporters is not empty then
@@ -118,12 +117,6 @@ create or replace package body ut_runner is
         l_coverage_schema_names := ut_suite_manager.get_schema_names(l_paths);
       end if;
 
-
-      if a_tags is not null then
-        l_tags := l_tags multiset union distinct ut_utils.convert_collection(
-          ut_utils.trim_list_elements(ut_utils.filter_list(ut_utils.string_to_table(a_tags,','),ut_utils.gc_word_no_space))
-        );
-      end if;
       l_run := ut_run(
         a_run_paths => l_paths,
         a_coverage_options => ut_coverage_options(
@@ -140,10 +133,10 @@ create or replace package body ut_runner is
         a_test_file_mappings => set(a_test_file_mappings),
         a_client_character_set => a_client_character_set,
         a_random_test_order_seed => l_random_test_order_seed,
-        a_run_tags => l_tags
+        a_run_tags => a_tags
       );
 
-      ut_suite_manager.configure_execution_by_path(l_paths, l_run.items, l_random_test_order_seed, l_tags);
+      ut_suite_manager.configure_execution_by_path(l_paths, l_run.items, l_random_test_order_seed, a_tags);
       if a_force_manual_rollback then
         l_run.set_rollback_type( a_rollback_type => ut_utils.gc_rollback_manual, a_force => true );
       end if;

diff --git a/source/core/types/ut_run.tpb b/source/core/types/ut_run.tpb
@@ -24,7 +24,7 @@ create or replace type body ut_run as
     a_test_file_mappings     ut_file_mappings := null,
     a_client_character_set   varchar2 := null,
     a_random_test_order_seed positive := null,
-    a_run_tags               ut_varchar2_rows := null
+    a_run_tags               varchar2 := null
   ) return self as result is
   begin
     self.run_paths := a_run_paths;

diff --git a/source/core/types/ut_run.tps b/source/core/types/ut_run.tps
@@ -21,7 +21,7 @@ create or replace type ut_run under ut_suite_item (
   project_name                   varchar2(4000),
   items                          ut_suite_items,
   run_paths                      ut_varchar2_list,
-  run_tags                       ut_varchar2_rows,
+  run_tags                       varchar2(4000),
   coverage_options               ut_coverage_options,
   test_file_mappings             ut_file_mappings,
   client_character_set           varchar2(100),
@@ -34,7 +34,7 @@ create or replace type ut_run under ut_suite_item (
     a_test_file_mappings     ut_file_mappings := null,
     a_client_character_set   varchar2 := null,
     a_random_test_order_seed positive := null,
-    a_run_tags               ut_varchar2_rows := null
+    a_run_tags               varchar2 := null
   ) return self as result,
   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,

diff --git a/source/core/types/ut_stack.tpb b/source/core/types/ut_stack.tpb
@@ -0,0 +1,58 @@
+create or replace type body ut_stack as
+ /*
+  utPLSQL - Version 3
+  Copyright 2016 - 2023 utPLSQL Project
+
+  Licensed under the Apache License, Version 2.0 (the "License"):
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+  */
+
+  constructor function ut_stack( self in out nocopy ut_stack) return self as result is
+  begin
+    self.tokens := ut_varchar2_list();
+    self.top := 0;
+    return;
+  end ut_stack;
+
+  member function peek(self in out nocopy ut_stack) return varchar2 is
+    l_token varchar2(32767);
+  begin
+    if self.tokens.count =0 or self.tokens is null then
+      l_token := null;
+    else
+      l_token := self.tokens(self.tokens.last);
+    end if;
+    return l_token;
+  end;
+
+  member procedure push(self in out nocopy ut_stack, a_token varchar2) is
+  begin
+    self.tokens.extend;
+    self.tokens(self.tokens.last) := a_token;
+    self.top := self.tokens.count;
+  end push;
+
+  member procedure pop(self in out nocopy ut_stack,a_cnt in integer default 1) is
+  begin
+    self.tokens.trim(a_cnt);
+    self.top := self.tokens.count;
+  end pop;
+
+  member function pop(self in out nocopy ut_stack) return varchar2 is
+    l_token varchar2(32767) := self.tokens(self.tokens.last);
+  begin
+    self.pop();
+    return l_token;
+  end;
+end;  
+/
+
diff --git a/source/core/types/ut_stack.tps b/source/core/types/ut_stack.tps
@@ -0,0 +1,26 @@
+create or replace type ut_stack as object (
+  top integer,
+  tokens ut_varchar2_list,
+  /*
+  utPLSQL - Version 3
+  Copyright 2016 - 2023 utPLSQL Project
+
+  Licensed under the Apache License, Version 2.0 (the "License"):
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+  */
+  constructor function ut_stack( self in out nocopy ut_stack) return self as result,
+  member function peek(self in out nocopy ut_stack) return varchar2,
+  member procedure push(self in out nocopy ut_stack, a_token varchar2),
+  member procedure pop(self in out nocopy ut_stack,a_cnt in integer default 1),
+  member function pop(self in out nocopy ut_stack) return varchar2
+)
+/