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

Skip to content

Commit 1b5ea60

Browse files
PazusPazus
authored
Merge pull request #164 from jgebal/feature/update_readme
Updated documentation.
2 parents 81c6ada + 0aaace4 commit 1b5ea60

6 files changed

Lines changed: 197 additions & 91 deletions

File tree

‎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](http://docs.oracle.com/database/121/SQLRF/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
@@ -9,18 +9,31 @@
99
[![twitter](https://img.shields.io/twitter/follow/utPLSQL.svg?style=social&label=Follow)](https://twitter.com/utPLSQL)
1010

1111
----------
12-
Version 3 is a complete rewrite of utPLSQL from scratch. [Version 2](https://github.com/utPLSQL/utPLSQL/tree/version2) 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.
13-
14-
Primary Goals:
15-
- Easier to maintain
16-
- 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)
17-
- API is documented in the code where possible.
18-
- Robust and vibrant assertion library.
19-
- Support for Code Coverage
20-
- Extensible API
21-
- Published upgrade/conversion path from version 2.
22-
- Easily called from current PL/SQL development tools
23-
- More permissive License to allow vendors easier ability to integrate utPLSQL.
12+
utPLSQL version 3 is a complete rewrite of utPLSQL v2 from scratch.
13+
Version 2 still supports older versions of Oracle that are no longer available.
14+
The community that had developed on GitHub, decided that a new internal architecture was needed, from that version 3 was born.
15+
16+
We welcome new developers to join our community and contribute to the utPLSQL project.
17+
18+
Primary features:
19+
- Support for all basic scalar data-types
20+
- Support for User Defined Object Types and Collections
21+
- Support for native cursors both strong and weak
22+
- Data-type aware testing
23+
- [Annotations](docs/userguide/annotations.md) based test definitions
24+
- Extensible [matchers](docs/userguide/expectations.md)
25+
- Extensible reporting formats
26+
- Extensible output providers
27+
- Support for multi-reporting
28+
- Code coverage reporting (with different formats)
29+
- Runtime reporting of test execution progress
30+
- Well-defined API
31+
- Easy to call from current PL/SQL development tools
32+
- More permissive License to allow vendors to integrate utPLSQL without violation of license
33+
- Published upgrade/conversion path from version 2 ( TODO )
34+
35+
Requirements:
36+
- Version of Oracle under [Extend Support](http://www.oracle.com/us/support/library/lifetime-support-technology-069183.pdf) (Currently 11.2 and above)
2437

2538
__Download__
2639

@@ -89,84 +102,103 @@ sqlplus admin/admins_password@xe @@install_headless.sql
89102

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

92-
# Annotations
105+
# Example test package
93106

94-
Annotations provide a way to configure tests and suites in a declarative way similar to modern OOP languages.
95-
The annotation list is based on moder testing framework such as jUnit 5, RSpec.
107+
The below test package is a fully-functional Unit Test package for testing a function `betwnstr`.
108+
Package specification is annotated with special comments ([annotations](docs/userguide/annotations.md)).
109+
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.
110+
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.
96111

97-
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.
98112

99-
# Example of annotated package
100-
```
101-
create or replace package test_pkg is
113+
```sql
114+
create or replace package test_between_string as
115+
116+
-- %suite(Between string function)
102117

103-
-- %suite(Name of suite)
104-
-- %suitepath(all.globaltests)
118+
-- %test(Returns substring from start position to end position)
119+
procedure normal_case;
105120

106-
-- %beforeall
107-
procedure globalsetup;
121+
-- %test(Returns substring when start position is zero)
122+
procedure zero_start_position;
108123

109-
-- %afterall
110-
procedure global_teardown;
124+
-- %test(Returns string until end if end position is greater than string length)
125+
procedure big_end_position;
111126

112-
/* Such comments are allowed */
127+
-- %test(Returns null for null input string value)
128+
procedure null_string;
129+
end;
130+
/
113131

114-
-- %test
115-
-- %displayname(Name of test1)
116-
procedure test1;
132+
create or replace package body test_between_string as
117133

118-
-- %test(Name of test2)
119-
-- %beforetest(setup_test1)
120-
-- %aftertest(teardown_test1)
121-
procedure test2;
134+
procedure normal_case is
135+
begin
136+
ut.expect( betwnstr( '1234567', 2, 5 ) ).to_equal('2345') );
137+
end;
122138

123-
-- %test
124-
-- %displayname(Name of test3)
125-
-- %disable
126-
procedure test3;
127-
128-
-- %test(Name of test4)
129-
-- %rollback(manual)
130-
procedure test4;
139+
procedure zero_start_position is
140+
begin
141+
ut.expect( betwnstr( '1234567', 0, 5 ) ).to_( equal('12345') );
142+
end;
131143

132-
procedure setup_test1;
144+
procedure big_end_position is
145+
begin
146+
ut.expect( betwnstr( '1234567', 0, 500 ) ).to_( equal('1234567') );
147+
end;
133148

134-
procedure teardown_test1;
149+
procedure null_string is
150+
begin
151+
ut.expect( betwnstr( null, 2, 5 ) ).to_( be_null );
152+
end;
135153

136-
-- %beforeeach
137-
procedure setup;
154+
end;
155+
/
156+
```
138157

139-
-- %aftereach
140-
procedure teardown;
141158

142-
end test_pkg;
159+
# Running tests
160+
161+
To execute using IDE ()TOAD/SQLDeveloper/PLSQLDeveloper/other) just run the following.
162+
```sql
163+
begin
164+
ut_runner.run();
165+
end;
166+
/
143167
```
168+
Will run all the suites in the current schema and provide documentation report using dbms_output
144169

145-
#Annotations meaning
170+
```
171+
Between string function
172+
Returns substring from start position to end position
173+
Returns substring when start position is zero
174+
Returns string until end if end position is greater than string length
175+
Returns null for null input string value
176+
177+
Finished in .036027 seconds
178+
4 tests, 0 failures
179+
```
180+
181+
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)
182+
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:
183+
* see the progress of test execution for long-running tests
184+
* have output to screen with one output format (text) and at the same time have output to file in other format (xunit)
146185

147-
| Annotation |Level| Describtion |
148-
| --- | --- | --- |
149-
| `%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. |
150-
| `%suitepath(<path>)` | Package | Similar to java package. The annotation allows logical grouping of suites into hierarcies. |
151-
| `%displayname(<description>)` | Package/procedure | Human-familiar describtion of the suite/test. Syntax is based on jUnit annotation: `%displayname(Name of the suite/test)` |
152-
| `%test(<description>)` | Procedure | Denotes that a method is a test method. Optional test discription can by provided, similar to `%displayname` annotation. |
153-
| `%beforeall` | Procedure | Denotes that the annotated procedure should be executed once before all elements of the current suite. |
154-
| `%afterall` | Procedure | Denotes that the annotated procedure should be executed once after all elements of the current suite. |
155-
| `%beforeeach` | Procedure | Denotes that the annotated procedure should be executed before each `%test` method in the current suite. |
156-
| `%aftereach` | Procedure | Denotes that the annotated procedure should be executed after each `%test` method in the current suite. |
157-
| `%beforetest(<procedure_name>)` | Procedure | Denotes that mentioned procedure should be executed before the annotated `%test` procedure. |
158-
| `%aftertest(<procedure_name>)` | Procedure | Denotes that mentioned procedure should be executed after the annotated `%test` procedure. |
159-
| `%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) |
160-
| `%disable` | Package/procedure | Used to disable a suite or a test |
186+
Example:
187+
```
188+
c:\my_work\>sqlplus /nolog @ut_run hr/hr@xe
189+
```
190+
Will run all the suites in the current schema (hr) and provide documentation report into screen.
191+
Invoking this script will show the progress after each test.
161192

162193

163194
__Primary Directories__
164195

165196
* .travis - contains files needed for travis-ci integration
197+
* client_source - Sources to be used on the client-side. Developer workstation or CI platform to run the tests.
198+
* development - Set of useful scripts and utilities for development and debugging of utPLSQL
166199
* docs - Markdown version of the documentation
167200
* examples - contains example unit tests.
168-
* source - contains the code utPLSQL
169-
* lib - 3rd party libraries that are required for source.
201+
* source - contains the installation code for utPLSQL
170202
* tests - contains the tests written to test utPLSQL
171203

172204

0 commit comments

Comments
 (0)