Update docs

lwasylow · lwasylow · commit dbbf197914e3 · 2019-04-24T20:32:21.000+01:00
diff --git a/docs/userguide/annotations.md b/docs/userguide/annotations.md
@@ -38,6 +38,7 @@ We strongly recommend putting package level annotations at the very top of packa
 | `--%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. |
 | `--%context(<name>)` | Package | Denotes start of a named context (sub-suite) in a suite package |
 | `--%endcontext` | Package | Denotes end of a nested context (sub-suite) in a suite package |
+| `--%tags` | Package/procedure | Used to label a test or a suite for purpose of identification |
 
 ### Suite
 
@@ -823,7 +824,7 @@ See [beforeall](#Beforeall) for more examples.
 Indicates specific setup procedure(s) to be executed for a test. The procedure(s) can be located either:
 - within current package (package name is optional)
 - within another package 
- 
+
 The annotation need to be placed alongside `--%test` annotation.
 
 The `--%beforetest` procedures are executed after invoking all `--%beforeeach` for a test.
@@ -911,7 +912,7 @@ Finished in .015185 seconds
 Indicates specific cleanup procedure(s) to be executed for a test. The procedure(s) can be located either:
 - within current package (package name is optional)
 - within another package 
- 
+
 The annotation need to be placed alongside `--%test` annotation.
 
 If a test is marked as disabled the `--%aftertest` procedures are not invoked for that test.
@@ -1221,6 +1222,74 @@ Finished in .035261 seconds
 ```
 
 
+
+### Tags
+
+Tag is a label attached to the test or a suite path. It is used for identification and execution a group of tests / suites that share same tag.  
+
+It allows us to group a tests / suites using a various categorization and place a test / suite in multiple buckets. Same tests can be group with other tests based on the functionality , frequency, type of output etc.
+
+e.q. 
+
+```sql
+--%tags(batch,daily,csv)
+```
+
+or
+
+```sql
+--%tags(api,online,json)
+```
+
+
+
+Tags are defined as a coma separated list. When executing a tests filtering by tag utPLSQL will find all tests associated with a given tag and execute it. It will apply `OR` logic when resolving a tags so any tests / suites that got matching at least one tag will get executed. 
+
+When a suite gets tagged all of its children will automatically inherit a tag and get executed along the parent.
+
+```sql
+create or replace PACKAGE ut_sample_test IS
+
+   --%suite(Sample Test Suite)
+   --%tag(suite1)
+
+   --%test(Compare Ref Cursors)
+   --%tag(test1,sample)
+   PROCEDURE ut_refcursors1;
+
+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;
+
+END ut_sample_test;
+/
+```
+
+Execution of the test is done by using a new parameter `a_tags`
+
+```sql
+select * from table(ut.run(a_path => 'ut_sample_test',a_tags => 'suite1'));
+select * from table(ut.run(a_tags => 'suite1'));
+
+begin
+  ut.run(a_path => 'ut_sample_test',a_tags => 'suite1');
+end;
+/
+```
+
+
+
 ### Suitepath
 
 It is very likely that the application for which you are going to introduce tests consists of many different packages, procedures and functions.
@@ -1346,9 +1415,9 @@ If `--%throws` annotation is specified with arguments and exception raised is no
 The framework will raise a warning, when `--%throws` annotation has invalid arguments or when no arguments were provided.
 
 Annotation `--%throws(7894562, operaqk, -=1, -20496, pow74d, posdfk3)` will be interpreted as `--%throws(-20496)`.
- 
+
 Please note that `NO_DATA_FOUND` exception is a special case in Oracle. To capture it use `NO_DATA_FOUND` named exception or `-1403` exception No.
-                                                                                                        
+​                                                                                                        
 Example:
 ```sql
 create or replace package exc_pkg is
