Skip to content

Commit e897268

Browse files
jgebaljgebal
authored
Merge pull request #906 from utPLSQL/feature/tags
Feature/tags
2 parents 8c7a008 + effb420 commit e897268

31 files changed

Lines changed: 1346 additions & 213 deletions

‎docs/userguide/annotations.md‎

Lines changed: 97 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ We strongly recommend putting package level annotations at the very top of packa
3838
| `--%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. |
3939
| `--%context(<name>)` | Package | Denotes start of a named context (sub-suite) in a suite package |
4040
| `--%endcontext` | Package | Denotes end of a nested context (sub-suite) in a suite package |
41+
| `--%tags` | Package/procedure | Used to label a test or a suite for purpose of identification |
4142

4243
### Suite
4344

@@ -823,7 +824,7 @@ See [beforeall](#Beforeall) for more examples.
823824
Indicates specific setup procedure(s) to be executed for a test. The procedure(s) can be located either:
824825
- within current package (package name is optional)
825826
- within another package
826-
827+
827828
The annotation need to be placed alongside `--%test` annotation.
828829

829830
The `--%beforetest` procedures are executed after invoking all `--%beforeeach` for a test.
@@ -911,7 +912,7 @@ Finished in .015185 seconds
911912
Indicates specific cleanup procedure(s) to be executed for a test. The procedure(s) can be located either:
912913
- within current package (package name is optional)
913914
- within another package
914-
915+
915916
The annotation need to be placed alongside `--%test` annotation.
916917

917918
If a test is marked as disabled the `--%aftertest` procedures are not invoked for that test.
@@ -1221,6 +1222,98 @@ Finished in .035261 seconds
12211222
```
12221223

12231224

1225+
1226+
### Tags
1227+
1228+
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.
1229+
1230+
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.
1231+
1232+
e.q.
1233+
1234+
```sql
1235+
--%tags(batch,daily,csv)
1236+
```
1237+
1238+
or
1239+
1240+
```sql
1241+
--%tags(api,online,json)
1242+
```
1243+
1244+
1245+
1246+
Tags are defined as a coma separated list. When executing a test run with tag filter applied, framework will find all tests associated with given tags and execute them. Framework applies `OR` logic when resolving a tags so any tests / suites that match at least one tag will be included in the test run.
1247+
1248+
When a suite gets tagged all of its children will automatically inherit a tag and get executed along the parent. Parent suit tests are not executed. but a suitepath hierarchy is kept.
1249+
1250+
Sample tag package.
1251+
1252+
```sql
1253+
create or replace package ut_sample_test IS
1254+
1255+
--%suite(Sample Test Suite)
1256+
--%tag(suite1)
1257+
1258+
--%test(Compare Ref Cursors)
1259+
--%tag(test1,sample)
1260+
procedure ut_refcursors1;
1261+
1262+
--%test(Run equality test)
1263+
--%tag(test2,sample)
1264+
procedure ut_test;
1265+
1266+
end ut_sample_test;
1267+
/
1268+
1269+
create or replace package body ut_sample_test is
1270+
1271+
procedure ut_refcursors1 is
1272+
v_actual sys_refcursor;
1273+
v_expected sys_refcursor;
1274+
begin
1275+
open v_expected for select 1 as test from dual;
1276+
open v_actual for select 2 as test from dual;
1277+
1278+
ut.expect(v_actual).to_equal(v_expected);
1279+
end;
1280+
1281+
procedure ut_test is
1282+
begin
1283+
ut.expect(1).to_equal(0);
1284+
end;
1285+
1286+
end ut_sample_test;
1287+
/
1288+
```
1289+
1290+
Execution of the test is done by using a parameter `a_tags`
1291+
1292+
```sql
1293+
select * from table(ut.run(a_path => 'ut_sample_test',a_tags => 'suite1'));
1294+
select * from table(ut.run(a_tags => 'test1,test2'));
1295+
select * from table(ut.run(a_tags => 'sample'));
1296+
1297+
begin
1298+
ut.run(a_path => 'ut_sample_test',a_tags => 'suite1');
1299+
end;
1300+
/
1301+
1302+
exec ut.run('ut_sample_test', a_tags => 'sample');
1303+
```
1304+
1305+
1306+
1307+
Tags should adhere to following rules:
1308+
1309+
- tags are case sensitive
1310+
- tags cannot be an empty string
1311+
- tags cannot contain spaces e.g. to create a multi-word `tag` please use underscores,dashes, dots etc. e.g. `test_of_batch`
1312+
- tags with empty spaces will be ignored during execution
1313+
- tags can contain special characters
1314+
1315+
1316+
12241317
### Suitepath
12251318

12261319
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 +1439,9 @@ If `--%throws` annotation is specified with arguments and exception raised is no
13461439
The framework will raise a warning, when `--%throws` annotation has invalid arguments or when no arguments were provided.
13471440

13481441
Annotation `--%throws(7894562, operaqk, -=1, -20496, pow74d, posdfk3)` will be interpreted as `--%throws(-20496)`.
1349-
1442+
13501443
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.
1351-
1444+
​
13521445
Example:
13531446
```sql
13541447
create or replace package exc_pkg is

‎docs/userguide/querying_suites.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,21 +22,22 @@ Querying the data from function provides the follwing details:
2222
- `item_line_no` - line_number where annotation identifying the item exists
2323
- `path` - suitepath of the item
2424
- `disabled_flag` - (0/1) indicator if item is disabled by --%disabled annotation
25-
25+
- `tags` - tags associated with suites
26+
2627
To get list of all test suites in current schema
2728
```sql
2829
select * from table(ut_runner.get_suites_info()) where item_type = 'UT_SUITE';
29-
```
30+
```
3031

3132
To get list of all tests for test suite `TEST_STUFF` in current user schema
3233
```sql
3334
select * from table(ut_runner.get_suites_info(USER, 'TEST_STUFF')) where item_type = 'UT_TEST';
34-
```
35+
```
3536

3637
To get a full information about suite `TEST_STUFF` including suite description, all contexts and tests in a suite
3738
```sql
3839
select * from table(ut_runner.get_suites_info(USER, 'TEST_STUFF')) where item_type = 'UT_TEST';
39-
```
40+
```
4041

4142
## Checking if schema contains tests
4243

0 commit comments

Comments
 (0)