Skip to content

Commit dac1780

Browse files
jgebaljgebal
committed
Updated documentation.
1 parent 8366919 commit dac1780

File tree

6 files changed

+197
-91
lines changed

6 files changed

+197
-91
lines changed

‎docs/userguide/annotations.md‎

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,15 @@ The annotation list is based on moder testing framework such as jUnit 5, RSpec.
55

66
Annotations allow to configure test infrastructure in a declarative way without anything stored in tables or config files. The framework runner scans the schema for all the suitable annotated packages, automatically configures suites, forms hierarchy from then and executes them.
77

8-
# Example of annotated package
9-
```
8+
Annotations are case-insensitive. But it is recommended to use the lower-case standard as described in the documentation.
9+
10+
Annotation on procedure level must be placed directly before the procedure name.
11+
12+
Annotation `-- %suite` should be placed at the beginning of package specification. It is not required but highly recommended as a practice.
13+
14+
# Example of annotated test package
15+
16+
```sql
1017
create or replace package test_pkg is
1118

1219
-- %suite(Name of suite)
@@ -51,19 +58,19 @@ create or replace package test_pkg is
5158
end test_pkg;
5259
```
5360

54-
#Annotations meaning
61+
#Annotations description
5562

56-
| Annotation |Level| Describtion |
63+
| Annotation |Level| Description |
5764
| --- | --- | --- |
5865
| `%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. |
59-
| `%suitepath(<path>)` | Package | Similar to java package. The annotation allows logical grouping of suites into hierarcies. |
60-
| `%displayname(<description>)` | Package/procedure | Human-familiar describtion of the suite/test. Syntax is based on jUnit annotation: `%displayname(Name of the suite/test)` |
61-
| `%test(<description>)` | Procedure | Denotes that a method is a test method. Optional test discription can by provided, similar to `%displayname` annotation. |
66+
| `%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. |
6269
| `%beforeall` | Procedure | Denotes that the annotated procedure should be executed once before all elements of the current suite. |
6370
| `%afterall` | Procedure | Denotes that the annotated procedure should be executed once after all elements of the current suite. |
6471
| `%beforeeach` | Procedure | Denotes that the annotated procedure should be executed before each `%test` method in the current suite. |
6572
| `%aftereach` | Procedure | Denotes that the annotated procedure should be executed after each `%test` method in the current suite. |
6673
| `%beforetest(<procedure_name>)` | Procedure | Denotes that mentioned procedure should be executed before the annotated `%test` procedure. |
6774
| `%aftertest(<procedure_name>)` | Procedure | Denotes that mentioned procedure should be executed after the annotated `%test` procedure. |
6875
| `%rollback(<type>)` | Package/procedure | Configure transaction control behaviour (type). Supported values: `auto`(default) - rollback to savepoint (before the test/suite setup) is issued after each test/suite teardown; `manual` - rollback is never issued automatically. Property can be overridden for child element (test in suite) |
69-
| `%disable` | Package/procedure | Used to disable a suite or a test |
76+
| `%disable` | Package/procedure | Used to disable a suite or a test |

‎docs/userguide/assertions.md‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎docs/userguide/expectations.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Concept of expectation and matcher
2+
3+
Validation of the code under test (the tested logic of procedure/function etc.) is performed by comparing the actual data against the expected data.
4+
To do that we use concept of expectation and a matcher to perform the check on the data.
5+
6+
It's best to give an example to get an idea what is what
7+
```sql
8+
begin
9+
ut.expect( 'the tested value' ).to_( equal('the expected value') );
10+
end;
11+
```
12+
13+
Expectation is a set of the expected value(s), actual values(s) and the matcher(s) to run on those values.
14+
15+
Matcher is defining the comparison operation to be performed on expected and actual values.
16+
17+
# List of currently build-in matchers
18+
- `match`
19+
- `equal`
20+
- `be_true`
21+
- `be_null`
22+
- `be_not_null`
23+
- `be_like`
24+
- `be_less_than`
25+
- `be_less_or_equal`
26+
- `be_greater_than`
27+
- `be_greater_or_equal`
28+
- `be_false`
29+
- `be_between`
30+
31+
## match
32+
Allows regexp_like validations to be executed against the following datatypes:
33+
- `clob`
34+
- `varchar2`
35+
36+
Usage:
37+
```sql
38+
ut.expect( a_actual ).to_( match( a_pattern in varchar2, a_modifiers in varchar2 := null) )
39+
```
40+
41+
Parameters `a_pattern` and `a_modifiers` represent a valid regexp pattern accepted by [Oracle regexp_like function](https://docs.oracle.com/cd/E11882_01/server.112/e41084/conditions007.htm#SQLRF00501)
42+
43+
## equal
44+
45+
The equal matcher is a very restrictive matcher.
46+
It only returns true, if compared data-types.
47+
That means, that comparing varchar2 to a number will fail even if the varchar2 contains the same number.
48+
This matcher is designed to capture changes of data-type, so that if you expect your variable to be number and is now something else,
49+
the test will fail and give you early indication of potential problem.
50+
51+
Usage:
52+
```sql
53+
ut.expect( a_actual ).to_( equal( a_expected {mulitple data-types}, a_nulls_are_equal boolean := null) )
54+
```
55+
56+
57+
The equal matcher accepts a_expected of following data-types.
58+
- `anydata`
59+
- `blob`
60+
- `boolean`
61+
- `clob`
62+
- `date`
63+
- `number`
64+
- `sys_refcursor`
65+
- `timestamp_unconstrained`
66+
- `timestamp_tz_unconstrained`
67+
- `timestamp_ltz_unconstrained`
68+
- `varchar2`
69+
- `yminterval_unconstrained`
70+
- `dsinterval_unconstrained`
71+
72+
The second parameter decides on the behavior of `null=null` comparison (**this comparison by default is true!**)
73+
74+
75+
A test procedure will contain one or more checks to verify the the test performed as expected. These checks are called assertion. utPLSQL provides a robust and extensible assertion library.
76+
77+
78+
TODO: Finish Expectations concepts

‎examples/between_string/test_betwnstr.pkg‎

Lines changed: 6 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,32 @@
11
create or replace package test_betwnstr as
22

3-
-- %suite
4-
-- %displayname(Between string function)
3+
-- %suite(Between string function)
54

6-
-- %test
7-
-- %displayname(Returns substring from start position to end position)
5+
-- %test(Returns substring from start position to end position)
86
procedure normal_case;
97

10-
-- %test
11-
-- %displayname(Returns substring when start position is zero)
8+
-- %test(Returns substring when start position is zero)
129
procedure zero_start_position;
1310

14-
-- %test
15-
-- %displayname(Returns string until end if end position is greated than string length)
11+
-- %test(Returns string until end if end position is greater than string length)
1612
procedure big_end_position;
1713

18-
-- %test
19-
-- %displayname(Returns null for null inlut srting value)
14+
-- %test(Returns null for null input string value)
2015
procedure null_string;
2116
end;
2217
/
2318
create or replace package body test_betwnstr as
2419

2520
procedure normal_case is
2621
begin
27-
ut.expect( betwnstr( '1234567', 2, 5 ) ).to_( equal('2345') );
22+
ut.expect( betwnstr( '1234567', 2, 5 ) ).to_equal('2345');
2823
end;
2924

3025
procedure zero_start_position is
3126
begin
3227
ut.expect( betwnstr( '1234567', 0, 5 ) ).to_( equal('12345') );
3328
end;
3429

35-
3630
procedure big_end_position is
3731
begin
3832
ut.expect( betwnstr( '1234567', 0, 500 ) ).to_( equal('1234567') );

‎mkdocs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ pages:
1414
- Installation: userguide/install.md
1515
- Getting Started: userguide/getting-started.md
1616
- Annotations: userguide/annotations.md
17-
- Assertions: userguide/assertions.md
17+
- Expectations: userguide/expectations.md
1818
- Testing Best Pracitces: userguide/best-practices.md
1919
- Upgrade utPLSQL : userguide/upgrade.md
2020
- About:

‎readme.md‎

Lines changed: 97 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,31 @@
66
[![twitter](https://img.shields.io/twitter/follow/utPLSQL.svg?style=social&label=Follow)](https://twitter.com/utPLSQL)
77

88
----------
9-
Version 3 is a complete rewrite of utPLSQL from scratch. Version 2 still supports older versions of Oracle that are no longer available. This has lead to difficult to maintain code. Yet many developers wanted to take it to the next level. The community that had developed on GitHub, decided that a new internal architecture was needed, from that version 3 was born. Currently version 3 is not complete and is not ready for a production environment as the API is not stable and changing. However it is quickly taking shape. We welcome new developers to join our community and help utPLSQL grow.
10-
11-
Primary Goals:
12-
- Easier to maintain
13-
- Only supports versions of Oracle under [Extend Support](http://www.oracle.com/us/support/library/lifetime-support-technology-069183.pdf) (Currently 11.2, and 12.1)
14-
- API is documented in the code where possible.
15-
- Robust and vibrant assertion library.
16-
- Support for Code Coverage
17-
- Extensible API
18-
- Published upgrade/conversion path from version 2.
19-
- Easily called from current PL/SQL development tools
20-
- More permissive License to allow vendors easier ability to integrate utPLSQL.
9+
utPLSQL version 3 is a complete rewrite of utPLSQL v2 from scratch.
10+
Version 2 still supports older versions of Oracle that are no longer available.
11+
The community that had developed on GitHub, decided that a new internal architecture was needed, from that version 3 was born.
12+
13+
We welcome new developers to join our community and contribute to the utPLSQL project.
14+
15+
Primary features:
16+
- Support for all basic scalar data-types
17+
- Support for User Defined Object Types and Collections
18+
- Support for native cursors both strong and weak
19+
- Data-type aware testing
20+
- [Annotations](docs/userguide/annotations.md) based test definitions
21+
- Extensible [matchers](docs/userguide/expectations.md)
22+
- Extensible reporting formats
23+
- Extensible output providers
24+
- Support for multi-reporting
25+
- Code coverage reporting (with different formats)
26+
- Runtime reporting of test execution progress
27+
- Well-defined API
28+
- Easy to call from current PL/SQL development tools
29+
- More permissive License to allow vendors to integrate utPLSQL without violation of license
30+
- Published upgrade/conversion path from version 2 ( TODO )
31+
32+
Requirements:
33+
- Version of Oracle under [Extend Support](http://www.oracle.com/us/support/library/lifetime-support-technology-069183.pdf) (Currently 11.2 and above)
2134

2235
__Version 2 to Version 3 Comparison__
2336

@@ -81,84 +94,103 @@ sqlplus admin/admins_password@xe @@install_headless.sql
8194

8295
For detailed instructions on other install options see the [Install Guide](docs/userguide/install.md)
8396

84-
# Annotations
97+
# Example test package
8598

86-
Annotations provide a way to configure tests and suites in a declarative way similar to modern OOP languages.
87-
The annotation list is based on moder testing framework such as jUnit 5, RSpec.
99+
The below test package is a fully-functional Unit Test package for testing a function `betwnstr`.
100+
Package specification is annotated with special comments ([annotations](docs/userguide/annotations.md)).
101+
Annotations define that a package is a unit test suite, they also allow defining a description for the suite as well as the test itself.
102+
Package body consists of procedures containing unit test code. To validate [an expectation](docs/userguide/expectations.md) in test, use `ut.expect( actual_data ).to_( ... )` syntax.
88103

89-
Annotations allow to configure test infrastructure in a declarative way without anything stored in tables or config files. The framework runner scans the schema for all the suitable annotated packages, automatically configures suites, forms hierarchy from then and executes them.
90104

91-
# Example of annotated package
92-
```
93-
create or replace package test_pkg is
105+
```sql
106+
create or replace package test_between_string as
107+
108+
-- %suite(Between string function)
94109

95-
-- %suite(Name of suite)
96-
-- %suitepath(all.globaltests)
110+
-- %test(Returns substring from start position to end position)
111+
procedure normal_case;
97112

98-
-- %beforeall
99-
procedure globalsetup;
113+
-- %test(Returns substring when start position is zero)
114+
procedure zero_start_position;
100115

101-
-- %afterall
102-
procedure global_teardown;
116+
-- %test(Returns string until end if end position is greater than string length)
117+
procedure big_end_position;
103118

104-
/* Such comments are allowed */
119+
-- %test(Returns null for null input string value)
120+
procedure null_string;
121+
end;
122+
/
105123

106-
-- %test
107-
-- %displayname(Name of test1)
108-
procedure test1;
124+
create or replace package body test_between_string as
109125

110-
-- %test(Name of test2)
111-
-- %beforetest(setup_test1)
112-
-- %aftertest(teardown_test1)
113-
procedure test2;
126+
procedure normal_case is
127+
begin
128+
ut.expect( betwnstr( '1234567', 2, 5 ) ).to_equal('2345') );
129+
end;
114130

115-
-- %test
116-
-- %displayname(Name of test3)
117-
-- %disable
118-
procedure test3;
119-
120-
-- %test(Name of test4)
121-
-- %rollback(manual)
122-
procedure test4;
131+
procedure zero_start_position is
132+
begin
133+
ut.expect( betwnstr( '1234567', 0, 5 ) ).to_( equal('12345') );
134+
end;
123135

124-
procedure setup_test1;
136+
procedure big_end_position is
137+
begin
138+
ut.expect( betwnstr( '1234567', 0, 500 ) ).to_( equal('1234567') );
139+
end;
125140

126-
procedure teardown_test1;
141+
procedure null_string is
142+
begin
143+
ut.expect( betwnstr( null, 2, 5 ) ).to_( be_null );
144+
end;
127145

128-
-- %beforeeach
129-
procedure setup;
146+
end;
147+
/
148+
```
130149

131-
-- %aftereach
132-
procedure teardown;
133150

134-
end test_pkg;
151+
# Running tests
152+
153+
To execute using IDE ()TOAD/SQLDeveloper/PLSQLDeveloper/other) just run the following.
154+
```sql
155+
begin
156+
ut_runner.run();
157+
end;
158+
/
135159
```
160+
Will run all the suites in the current schema and provide documentation report using dbms_output
136161

137-
#Annotations meaning
162+
```
163+
Between string function
164+
Returns substring from start position to end position
165+
Returns substring when start position is zero
166+
Returns string until end if end position is greater than string length
167+
Returns null for null input string value
168+
169+
Finished in .036027 seconds
170+
4 tests, 0 failures
171+
```
172+
173+
To execute your tests from command line, you will need a oracle sql client like SQLPlus or [SQLcl](http://www.oracle.com/technetwork/developer-tools/sqlcl/overview/index.html)
174+
You may benefit from using the [ut_run.sql](client_source/sqlplus/ut_run.sql) to execute your tests if you want to achieve one of the following:
175+
* see the progress of test execution for long-running tests
176+
* have output to screen with one output format (text) and at the same time have output to file in other format (xunit)
138177

139-
| Annotation |Level| Describtion |
140-
| --- | --- | --- |
141-
| `%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. |
142-
| `%suitepath(<path>)` | Package | Similar to java package. The annotation allows logical grouping of suites into hierarcies. |
143-
| `%displayname(<description>)` | Package/procedure | Human-familiar describtion of the suite/test. Syntax is based on jUnit annotation: `%displayname(Name of the suite/test)` |
144-
| `%test(<description>)` | Procedure | Denotes that a method is a test method. Optional test discription can by provided, similar to `%displayname` annotation. |
145-
| `%beforeall` | Procedure | Denotes that the annotated procedure should be executed once before all elements of the current suite. |
146-
| `%afterall` | Procedure | Denotes that the annotated procedure should be executed once after all elements of the current suite. |
147-
| `%beforeeach` | Procedure | Denotes that the annotated procedure should be executed before each `%test` method in the current suite. |
148-
| `%aftereach` | Procedure | Denotes that the annotated procedure should be executed after each `%test` method in the current suite. |
149-
| `%beforetest(<procedure_name>)` | Procedure | Denotes that mentioned procedure should be executed before the annotated `%test` procedure. |
150-
| `%aftertest(<procedure_name>)` | Procedure | Denotes that mentioned procedure should be executed after the annotated `%test` procedure. |
151-
| `%rollback(<type>)` | Package/procedure | Configure transaction control behaviour (type). Supported values: `auto`(default) - rollback to savepoint (before the test/suite setup) is issued after each test/suite teardown; `manual` - rollback is never issued automatically. Property can be overridden for child element (test in suite) |
152-
| `%disable` | Package/procedure | Used to disable a suite or a test |
178+
Example:
179+
```
180+
c:\my_work\>sqlplus /nolog @ut_run hr/hr@xe
181+
```
182+
Will run all the suites in the current schema (hr) and provide documentation report into screen.
183+
Invoking this script will show the progress after each test.
153184

154185

155186
__Primary Directories__
156187

157188
* .travis - contains files needed for travis-ci integration
189+
* client_source - Sources to be used on the client-side. Developer workstation or CI platform to run the tests.
190+
* development - Set of useful scripts and utilities for development and debugging of utPLSQL
158191
* docs - Markdown version of the documentation
159192
* examples - contains example unit tests.
160-
* source - contains the code utPLSQL
161-
* lib - 3rd party libraries that are required for source.
193+
* source - contains the installation code for utPLSQL
162194
* tests - contains the tests written to test utPLSQL
163195

164196

0 commit comments

Comments
 (0)