You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
External code used in the development of this project, but is not required for use.
7
7
@@ -10,4 +10,6 @@ External code used in the development of this project, but is not required for u
10
10
|[Travis-Oracle](https://github.com/cbandy/travis-oracle)|[ISC](https://github.com/cbandy/travis-oracle/blob/master/LICENSE)| Install Oracle for Travis Builds |
11
11
|[mkDocs](http://www.mkdocs.org/)|[BSD](http://www.mkdocs.org/about/license/)| Produce HTML version of documentation |
12
12
13
-
**Note:** Version 1 & 2 of utPLSQL were licensed under GPL, version 3 was a complete rewrite from scratch which a allowed us to change the license to a more permissive license.
13
+
**Note:**
14
+
15
+
Version 1 & 2 of utPLSQL were licensed under GPL, version 3 was a complete rewrite from scratch which a allowed us to change the license to be more permissive.
Copy file name to clipboardExpand all lines: docs/index.md
+6-5Lines changed: 6 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,18 +39,19 @@ Check out the sections on [annotations](userguide/annotations.md) and [expectati
39
39
40
40
41
41
# Command line
42
-
The `ut_run.sql` script is a powerful thing - it can provide output from the tests on the fly.
43
-
You can also use it to have coloured output from the test, and if you try to test code that was dropper, all of unit tests related to that code will fail.
42
+
The `ut_run` (for linux/unix) and `ut_run.bat` (for windows) are simple yet powerful.
43
+
They can provide output from the tests on the fly.
Look into [ut_run.sql script options](userguide/ut_run-script.md) to see more.
48
48
49
49
# Coverage
50
-
If you want to have code coverage gathered on your code , it's best to use `ut_run.sql` to execute your tests with multiple reporters and have both test execution report as well as coverage report saved to a file.
50
+
If you want to have code coverage gathered on your code , it's best to use `ut_run` to execute your tests with multiple reporters and have both test execution report as well as coverage report saved to a file.
51
+
51
52
Check out the [coverage documentation](userguide/coverage.md) for options of coverage reporting
Copy file name to clipboardExpand all lines: docs/userguide/annotations.md
+90-44Lines changed: 90 additions & 44 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,17 +1,25 @@
1
1
# Annotations
2
2
3
-
Annotations provide a way to configure tests and suites in a declarative way similar to modern OOP languages. This way th behavior of tests stored along with the test logic, versioned using VCS with the code under test. No configuration files or tables are needed. The annotation list is based on popular testing frameworks such as jUnit 5 and RSpec.
4
-
The framework runner searches for all the suitable annotated packages, automatically configures suites, forms suites hierarchy, executes it and reports results in differet formats.
3
+
Annotations are used to configure tests and suites in a declarative way similar to modern OOP languages. This way, test configuration is stored along with the test logic inside the test package.
4
+
No configuration files or tables are needed. The annotations names are based on popular testing frameworks such as jUnit.
5
+
The framework runner searches for all the suitable annotated packages, automatically configures suites, forms suites hierarchy, executes it and reports results in specified formats.
5
6
6
-
Annotations are case-insensitive. But it is recommended to use the lower-case standard as described in the documentation.
7
+
Annotations are interpreted only in package specification and are case-insensitive. It is recommended however, to use the lower-case annotations as described in documentation.
7
8
8
-
There are two places where annotations may appear: at the beginning of the package specification (`%suite`, `%suitepath` etc) and right before a procedure (`%test`, `%beforeall`, `%beforeeach` etc). Package level annotations are separated by at least one empty line from the following procedure annotations. Procedure annotetions are defined right before the procedure they reference, no empty lines allowed.
9
+
There are two places where annotations may appear:
9
10
10
-
If a package conatins `%suite` annotation in its specification part it is treated as a test package and processed by the framework.
11
+
- at the beginning of the package specification (`%suite`, `%suitepath` etc)
12
+
- right before a procedure (`%test`, `%beforeall`, `%beforeeach` etc).
11
13
12
-
Some annotations accept parameters like `%suite`, `%test``%displayname`, then the values are provided without any quatation marks, parameters are separated by commas.
14
+
Package level annotations need to be separated by at least one empty line from the underlying procedure annotations.
13
15
14
-
# Example of annotated test package
16
+
Procedure annotations are defined right before the procedure they reference, no empty lines are allowed.
17
+
18
+
If a package specification contains `%suite` annotation, it is treated as a test package and processed by the framework.
19
+
20
+
Some annotations accept parameters like `%suite`, `%test``%displayname`. The parameters for annotations need to be placed in brackets. Values for parameters should be provided without any quotation marks.
21
+
22
+
# <aname="example"></a>Example of annotated test package
15
23
16
24
```sql
17
25
create or replace package test_pkg is
@@ -20,73 +28,63 @@ create or replace package test_pkg is
20
28
-- %suitepath(all.globaltests)
21
29
22
30
-- %beforeall
23
-
procedure globalsetup;
31
+
procedure global_setup;
24
32
25
33
-- %afterall
26
-
procedure global_teardown;
34
+
procedure global_cleanup;
27
35
28
36
/* Such comments are allowed */
29
37
30
38
-- %test
31
-
-- %displayname(Name of test1)
32
-
procedure test1;
39
+
-- %displayname(Name of a test)
40
+
procedure some_test;
33
41
34
-
-- %test(Name of test2)
35
-
-- %beforetest(setup_test1)
36
-
-- %aftertest(teardown_test1)
37
-
procedure test2;
42
+
-- %test(Name of another test)
43
+
-- %beforetest(setup_another_test)
44
+
-- %aftertest(cleanup_another_test)
45
+
procedure another_test;
38
46
39
47
-- %test
40
-
-- %displayname(Name of test3)
48
+
-- %displayname(Name of test)
41
49
-- %disabled
42
-
procedure test3;
50
+
procedure disabled_test;
43
51
44
-
-- %test(Name of test4)
52
+
-- %test(Name of test)
45
53
-- %rollback(manual)
46
-
procedure test4;
54
+
procedure no_transaction_control_test;
47
55
48
-
procedure setup_test1;
56
+
procedure setup_another_test;
49
57
50
-
procedure teardown_test1;
58
+
procedure cleanup_another_test;
51
59
52
60
-- %beforeeach
53
-
procedure setup;
61
+
procedure test_setup;
54
62
55
63
-- %aftereach
56
-
procedure teardown;
64
+
procedure test_cleanup;
57
65
58
66
end test_pkg;
59
67
```
60
68
61
-
# Annotations description
69
+
# Supported annotations
62
70
63
71
| Annotation |Level| Description |
64
72
| --- | --- | --- |
65
-
|`%suite(<description>)`| Package | Marks package to be a suite of tests This way all testing packages might be found in a schema. Optional schema discription can by provided, similar to `%displayname` annotation. |
73
+
|`%suite(<description>)`| Package |Mandatory. Marks package as a test suite. Optional suite description can be provided (see `displayname`). |
66
74
|`%suitepath(<path>)`| Package | Similar to java package. The annotation allows logical grouping of suites into hierarchies. |
67
-
|`%displayname(<description>)`| Package/procedure | Human-familiar description of the suite/test. Syntax is based on jUnit annotation: `%displayname(Name of the suite/test)`|
68
-
|`%test(<description>)`| Procedure | Denotes that a method is a test method. Optional test description can by provided, similar to `%displayname` annotation. |
69
-
|`%beforeall`| Procedure | Denotes that the annotated procedure should be executed once before all elements of the current suite. |
70
-
|`%afterall`| Procedure | Denotes that the annotated procedure should be executed once after all elements of the current suite. |
71
-
|`%beforeeach`| Procedure | Denotes that the annotated procedure should be executed before each `%test`method in the current suite. |
72
-
|`%aftereach`| Procedure | Denotes that the annotated procedure should be executed after each `%test`method in the current suite. |
75
+
|`%displayname(<description>)`| Package/procedure | Human-readable and meaningful description of a suite/test. `%displayname(Name of the suite/test)`. The annotation is provided for flexibility and convenience only. It has exactly the same meaning as `<descriotion>` in `test` and `suite` annotations. If description is provided using both `suite`/`test` and `displayname`, then the one defined as last takes precedence.|
76
+
|`%test(<description>)`| Procedure | Denotes that the annotated procedure is a unit test procedure. Optional test description can by provided (see `displayname`). |
77
+
|`%beforeall`| Procedure | Denotes that the annotated procedure should be executed once before all elements of the suite. |
78
+
|`%afterall`| Procedure | Denotes that the annotated procedure should be executed once after all elements of the suite. |
79
+
|`%beforeeach`| Procedure | Denotes that the annotated procedure should be executed before each `%test`procedure in the suite. |
80
+
|`%aftereach`| Procedure | Denotes that the annotated procedure should be executed after each `%test`procedure in the suite. |
73
81
|`%beforetest(<procedure_name>)`| Procedure | Denotes that mentioned procedure should be executed before the annotated `%test` procedure. |
74
82
|`%aftertest(<procedure_name>)`| Procedure | Denotes that mentioned procedure should be executed after the annotated `%test` procedure. |
75
-
|`%rollback(<type>)`| Package/procedure | Configure transaction control behaviour (type). 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) |
76
-
|`%disabled`| Package/procedure | Used to disable a suite or a test |
77
-
78
-
# Using automatic rollbacks in tests
79
-
By default, every test is isolated from other tests using savepoint.
80
-
This solution is suitable for use-cases, where the code that is getting tested as well as the unit tests themselves do not use transaction control commands (commit/rollback).
81
-
In general, your unit tests should not use transaction control as long as the core you are testing is not using it too.
82
-
Keeping the transactions uncommitted allows your changes to be isolated and the execution of tests is not impacting others that might be using a shared (integration) development database.
83
-
84
-
If however you're in situation, where the code you are testing, is using transaction control (like ETL code is usually doing), then your tests should not use the default rollback(auto)
85
-
You should make sure that thr entire suitepath all the way to the root is using manual transaction control in that case.
86
-
87
-
In some cases it is needed to perform DDL in setup/teardown. It is recommended to move such DDL statements to a procedure with pragma autonomous_transaction to eliminate implicit commit of the main session.
83
+
|`%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) |
84
+
|`%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. |
88
85
89
86
# Suitepath concept
87
+
90
88
It is very likely that the application for which you are going to introduce tests consists of many different packages or procedures/functions. Usually procedures can be logically grouped inside a package, there also might be several logical groups of procedure in a single package or even packages themselves might relate to a common module.
91
89
92
90
Lets say you have a complex insurance application the operates with policies, claims and payments. The payment module contains several packages for payment recognition, charging, planning etc. The payment recognition module among others contains a complex `recognize_payment` procedure that associates received money to the policies.
@@ -160,3 +158,51 @@ A `%suitepath` can be provided in tree ways:
160
158
*[schema]:suite1[.suite2][.suite3]...[.procedure] - execute all tests in all suites from suite1[.suite2][.suite3]...[.procedure] path. If schema is not provided, then current schema is used. Example: `:all.rooms_tests`.
161
159
*[schema.]package[.procedure] - execute all tests in the test package provided. The whole hierarchy of suites in the schema is build before, all before/after hooks of partn suites for th provided suite package are executed as well. Example: `tests.test_contact.test_last_name_validator` or simply `test_contact.test_last_name_validator` if `tests` is the current schema.
162
160
161
+
# Using automatic rollbacks in tests
162
+
163
+
By default, every test is isolated using savepoint.
164
+
This solution is suitable for use-cases, where the code that is getting tested as well as the unit tests themselves do not use transaction control (commit/rollback) or DDL commands.
165
+
In general, your unit tests should not use transaction control as long as the code you are testing is not using it too.
166
+
Keeping the transactions uncommitted allows your changes to be isolated and the execution of tests is not impacting others that might be using a shared development database.
167
+
168
+
If you are in situation, where the code you are testing, is using transaction control (common case with ETL code), then your tests probably should not use the default automatic transaction control.
169
+
In that case use the annotation `-- %rollback(manual)` on the suite level to disable automatic transaction control for entire suite.
170
+
If you are using nested suites, you need to make sure that thr entire suite all the way to the root is using manual transaction control.
171
+
172
+
In some cases it is needed to perform DDL as part of setup or cleanup for the tests.
173
+
It is recommended to move such DDL statements to a procedure with `pragma autonomous_transaction` to eliminate implicit commit of the main session.
174
+
Doing so, allows your test to use automatic transaction control of the framework and release you from the burden of manual cleanup of data that was created or modified by test execution.
175
+
176
+
177
+
# Order of execution
178
+
179
+
When processing the test suite `test_pkg` defined in [Example of annotated test package](#example), the execution will be done in the following order.
0 commit comments