Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 51ba943

Browse files
jgebaljgebal
committed
Updated documentation with new and changed annotations.
1 parent 8617613 commit 51ba943

1 file changed

Lines changed: 137 additions & 72 deletions

File tree

‎docs/userguide/annotations.md‎

Lines changed: 137 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,17 @@
11
# Annotations
22

33
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 annotation names are based on popular testing frameworks such as jUnit.
4+
No configuration files or tables are needed. The annotation names are based on popular testing frameworks such as JUnit.
55
The framework runner searches for all the suitable annotated packages, automatically configures suites, forms the suite hierarchy, executes it and reports results in specified formats.
66

77
Annotations are interpreted only in the package specification and are case-insensitive. We strongly recommend using lower-case annotations as described in this documentation.
88

9-
There are two locations where annotations can be placed:
10-
- Package level annotations can be placed at the very top of the package specification (`--%suite`, `--%suitepath` etc.)
11-
- Procedure level annotations can be placed right before a procedure (`--%test`, `--%beforeall`, `--%beforeeach` etc.)
9+
There are two distinct types of annotations, identified by their location in package:
10+
- Procedure level annotations - placed directly before a procedure (`--%test`, `--%beforeall`, `--%beforeeach` etc.).
11+
- Package level annotations - placed at any place in package except directly before procedure (`--%suite`, `--%suitepath` etc.).
12+
13+
We strongly recommend putting package level annotations at the very top of package except for the `--%context` annotations (described below)
14+
1215

1316
If procedure level annotation is not placed right before procedure, it is not considered an annotation for procedure.
1417

@@ -35,10 +38,10 @@ create or replace package test_pkg is
3538
procedure yet_another_test;
3639
end test_pkg;
3740
```
38-
Procedure annotations are defined right before the procedure they reference, no empty lines are allowed, no comment lines can exist between annotation and the procedure.
41+
Procedure level annotations must be defined right before the procedure they reference, no empty lines are allowed, no comment lines can exist between annotation and the procedure.
3942

4043

41-
Package level annotations need to be separated by at least one empty line from the underlying procedure annotations.
44+
Package level annotations need to be separated by at least one empty line from a procedure procedure or procedure annotation.
4245

4346
Example of invalid package level annotation.
4447
```sql
@@ -48,42 +51,57 @@ create or replace package test_pkg is
4851
procedure first_test;
4952
end test_pkg;
5053
```
54+
In the above example, the `--%suite` annotation is ignored, as it is in fact associated with `procedure first_test`. Association with procedure takes precedence over association with package.
5155

52-
If a package specification contains the `--%suite` annotation, it is treated as a test package and is processed by the framework.
53-
54-
Some annotations accept parameters like `--%suite`, `--%test` and `--%displayname`. The parameters for annotations need to be placed in brackets.
55-
Values for parameters should be provided without any quotation marks.
56-
If the parameters are placed without brackets or with incomplete brackets, they will be ignored.
57-
Example: `--%suite(The name of suite without closing bracket`
58-
59-
# <a name="example"></a>Example of an annotated test package
56+
## Order of execution
6057

6158
```sql
62-
create or replace package test_pkg is
59+
create or replace package test_employee_pkg is
6360

64-
--%suite(Name of suite)
65-
--%suitepath(all.globaltests)
61+
--%suite(Employee management)
62+
--%suitepath(com.my_company.hr)
63+
--%rollback(auto)
64+
65+
--%beforeall
66+
procedure setup_employees;
6667

6768
--%beforeall
68-
procedure global_setup;
69+
procedure setup_departments;
6970

7071
--%afterall
71-
procedure global_cleanup;
72+
procedure cleanup_log_table;
7273

73-
/* Such comments are allowed */
74+
--%context(add_employee)
7475

75-
--%test
76-
--%displayname(Name of a test)
77-
--%throws(-20145,-20146,-20189,-20563)
78-
procedure some_test;
76+
--%beforeeach
77+
procedure setup_for_add_employees;
7978

80-
--%test(Name of another test)
79+
--%test(Raises exception when employee already exists)
80+
--%throws(-20145)
81+
procedure add_existing_employee;
82+
83+
--%test(Inserts employee to emp table)
84+
procedure add_employee;
85+
86+
--%endcontext
87+
88+
89+
--%context(remove_employee)
90+
91+
--%beforeall
92+
procedure setup_for_remove_employee;
93+
94+
--%test(Removed employee from emp table)
95+
procedure del_employee;
96+
97+
--%endcontext
98+
99+
--%test(Test without context)
81100
--%beforetest(setup_another_test)
82101
--%aftertest(cleanup_another_test)
83-
procedure another_test;
102+
procedure some_test;
84103

85-
--%test
86-
--%displayname(Name of test)
104+
--%test(Name of test)
87105
--%disabled
88106
procedure disabled_test;
89107

@@ -96,15 +114,76 @@ create or replace package test_pkg is
96114
procedure cleanup_another_test;
97115

98116
--%beforeeach
99-
procedure test_setup;
117+
procedure set_session_context;
100118

101119
--%aftereach
102-
procedure test_cleanup;
120+
procedure cleanup_session_context;
103121

104-
end test_pkg;
122+
end test_employee_pkg;
105123
```
106124

107-
# Supported annotations
125+
When processing the test suite `test_employee_pkg` defined in [Example of annotated test package](#example), the order of execution will be as follows.
126+
127+
```
128+
create a savepoint 'before-suite'
129+
execute setup_employees (--%beforeall)
130+
execute setup_departments (--%beforeall)
131+
132+
create a savepoint 'before-context'
133+
create savepoint 'before-test'
134+
execute test_setup (--%beforeeach)
135+
execute setup_for_add_employees (--%beforeeach from context)
136+
execute add_existing_employee (--%test)
137+
execute test_cleanup (--%aftereach)
138+
rollback to savepoint 'before-test'
139+
create savepoint 'before-test' (--%suite)
140+
execute test_setup (--%beforeeach)
141+
execute setup_for_add_employees (--%beforeeach from context)
142+
execute add_employee (--%test)
143+
execute test_cleanup (--%aftereach)
144+
rollback to savepoint 'before-test'
145+
rollback to savepoint 'before-context'
146+
147+
create a savepoint 'before-context'
148+
execute setup_for_remove_employee (--%beforeall from context)
149+
create savepoint 'before-test'
150+
execute test_setup (--%beforeeach)
151+
execute add_existing_employee (--%test)
152+
execute test_cleanup (--%aftereach)
153+
rollback to savepoint 'before-test'
154+
rollback to savepoint 'before-context'
155+
156+
create savepoint 'before-test'
157+
execute test_setup (--%beforeeach)
158+
execute some_test (--%test)
159+
execute test_cleanup (--%aftereach)
160+
rollback to savepoint 'before-test'
161+
162+
create savepoint 'before-test'
163+
execute test_setup (--%beforeeach)
164+
execute setup_another_test (--%beforetest)
165+
execute another_test (--%test)
166+
execute cleanup_another_test (--%aftertest)
167+
execute test_cleanup (--%beforeeach)
168+
rollback to savepoint 'before-test'
169+
170+
mark disabled_test as disabled (--%test --%disabled)
171+
172+
execute test_setup (--%beforeeach)
173+
execute no_transaction_control_test (--%test)
174+
execute test_cleanup (--%aftertest)
175+
176+
execute global_cleanup (--%afterall)
177+
rollback to savepoint 'before-suite'
178+
```
179+
180+
**Note**
181+
>utPLSQL does not guarantee ordering of tests in suite. On contrary utPLSQL might give random order of tests/contexts in suite.
182+
>
183+
>Order of execution within multiple occurrences of `before`/`after` procedures is determined by the order of annotations in specific block (context/suite) of package specification.
184+
185+
186+
## Supported annotations
108187

109188
| Annotation |Level| Description |
110189
| --- | --- | --- |
@@ -121,10 +200,25 @@ end test_pkg;
121200
| `--%aftertest(<procedure_name>)` | Procedure | Denotes that mentioned procedure should be executed after the annotated `%test` procedure. |
122201
| `--%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) |
123202
| `--%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. |
203+
| `--%context(<description>)` | Package | Denotes start of a nested context (sub-suite) in a suite package |
204+
| `--%endcontext` | Package | Denotes end of a nested context (sub-suite) in a suite package |
205+
206+
207+
**Note**
208+
>Package is considered a test-suite only when package specification contains the `--%suite` annotation at the package level.
209+
>
210+
>Some annotations like `--%suite`, `--%test` and `--%displayname` accept parameters. The parameters for annotations need to be placed in brackets.
211+
Values for parameters should be provided without any quotation marks.
212+
If the parameters are placed without brackets or with incomplete brackets, they will be ignored.
213+
>
214+
>Example: `--%suite(The name of suite without closing bracket`
124215
125216
# Suitepath concept
126217

127-
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.
218+
It is very likely that the application for which you are going to introduce tests consists of many different packages, procedures and functions.
219+
Usually procedures can be logically grouped inside a package, there also might be several logical groups of procedures in a single package and packages might be grouped into modules and modules into subject areas.
220+
221+
As your project grows, the codebase will grow to. utPLSQL allows you to group packages into modules and modules into
128222

129223
Let's say you have a complex insurance application that deals 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.
130224

@@ -135,7 +229,6 @@ If you want to create tests for your application it is recommended to structure
135229
* Payment tests
136230
* Payments recognition
137231
* Payments set off
138-
* Payouts
139232

140233
The `%suitepath` annotation is used for such grouping. Even though test packages are defined in a flat structure the `%suitepath` is used by the framework to form them into a hierarchical structure. Your payments recognition test package might look like:
141234

@@ -148,8 +241,7 @@ create or replace package test_payment_recognition as
148241
--%test(Recognize payment by policy number)
149242
procedure test_recognize_by_num;
150243

151-
--%test
152-
--%displayname(Recognize payment by payment purpose)
244+
--%test(Recognize payment by payment purpose)
153245
procedure test_recognize_by_purpose;
154246

155247
--%test(Recognize payment by customer)
@@ -165,12 +257,11 @@ create or replace package test_payment_set_off as
165257
--%suite(Payment set off tests)
166258
--%suitepath(payments)
167259

168-
--%test(Set off creation test)
260+
--%test(Creates set off)
169261
procedure test_create_set_off;
170262

171-
--%test
172-
--%displayname(Set off annulation test)
173-
procedure test_annulate_set_off;
263+
--%test(Cancels set off)
264+
procedure test_cancel_set_off;
174265

175266
end test_payment_set_off;
176267
```
@@ -221,38 +312,12 @@ Doing so allows your tests to use the framework's automatic transaction control
221312
When you are testing code that performs explicit or implicit commits, you may set the test procedure to run as an autonomous transaction with `pragma autonomous_transaction`.
222313
Keep in mind that when your test runs as autonomous transaction it will not see the data prepared in a setup procedure unless the setup procedure committed the changes.
223314

224-
# Order of execution
225-
226-
When processing the test suite `test_pkg` defined in [Example of annotated test package](#example), the order of execution will be as follows.
227-
228-
```
229-
create a savepoint 'beforeall'
230-
execute global_setup
231-
232-
create savepoint 'beforeeach'
233-
execute test_setup
234-
execute some_test
235-
execute test_cleanup
236-
rollback to savepoint 'beforeeach'
237-
238-
create savepoint 'beforeeach'
239-
execute test_setup
240-
execute setup_another_test
241-
execute another_test
242-
execute cleanup_another_test
243-
execute test_cleanup
244-
rollback to savepoint 'beforeeach'
245-
246-
mark disabled_test as disabled
247-
248-
execute test_setup
249-
execute no_transaction_control_test
250-
execute test_cleanup
251-
252-
execute global_cleanup
253-
rollback to savepoint 'beforeall'
254-
255-
```
315+
**Note**
316+
> The `--%suitepath` annotation, when used, must be provided with a value of path.
317+
> The path in suitepath cannot contain spaces. Dot (.) identifies individual elements of the path.
318+
>
319+
> Example: `--%suitepath(org.utplsql.core.utils)`
320+
>
256321
257322
# Annotation cache
258323

0 commit comments

Comments
 (0)