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

Skip to content

Commit 93dff9b

Browse files
PazusPazus
authored
Merge pull request #399 from jgebal/feature/documentation_cleanup
Feature/documentation cleanup
2 parents 7cefa0a + 6d56548 commit 93dff9b

4 files changed

Lines changed: 105 additions & 309 deletions

File tree

‎docs/userguide/upgrade.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
1-
# How to upgrade from prior versions
1+
# Upgrading from version 2
2+
3+
utPLSQL v3 is a total rewrite of the framework.
4+
To make utPLSQL v2 packages run on v3 framework you need to install and execute migration utility.
5+
See the [utPLSQL-v2-v3-migration](https://github.com/utPLSQL/utPLSQL-v2-v3-migration) project for details on how to install and execute the migration.
26

3-
utPLSQL v3 is a total rewrite of the previous version. There is no automated way to migrate tests from version 2.x to version 3.
4-
There are plans to build a mapping/bridging solution that would allow running v2 tests using v3 framework.
57

‎readme.md‎

Lines changed: 100 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
# utPLSQL v3<sub><sup> | Powerful PL/SQL Unit Testing Framework </sup></sub>
22

33
[![latest-release](https://img.shields.io/github/release/utPLSQL/utPLSQL.svg)](https://github.com/utPLSQL/utPLSQL/releases)
4-
[![license](http://img.shields.io/badge/license-apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
4+
[![license](https://img.shields.io/github/license/utPLSQL/utPLSQL.svg)](https://www.apache.org/licenses/LICENSE-2.0)
55
[![chat](http://img.shields.io/badge/slack-team--chat-blue.svg)](http://utplsql-slack-invite.herokuapp.com/)
66
[![twitter](https://img.shields.io/twitter/follow/utPLSQL.svg?style=social&label=Follow)](https://twitter.com/utPLSQL)
77

88
[![build](https://img.shields.io/travis/utPLSQL/utPLSQL/master.svg?label=master%20branch)](https://travis-ci.org/utPLSQL/utPLSQL)
99
[![build](https://img.shields.io/travis/utPLSQL/utPLSQL/develop.svg?label=develop%20branch)](https://travis-ci.org/utPLSQL/utPLSQL)
10-
[![sonar](https://sonarqube.com/api/badges/gate?key=utPLSQL%3AutPLSQL%3Adevelop)](https://sonarqube.com/dashboard/index?id=utPLSQL%3AutPLSQL%3Adevelop)
10+
[![sonar](https://sonarcloud.io/api/badges/gate?key=utPLSQL%3AutPLSQL%3Adevelop)](https://sonarcloud.io/dashboard/index?id=utPLSQL%3AutPLSQL%3Adevelop)
1111
[![Coveralls coverage](https://coveralls.io/repos/github/utPLSQL/utPLSQL/badge.svg?branch=develop)](https://coveralls.io/github/utPLSQL/utPLSQL?branch=develop)
1212

1313
----------
@@ -47,87 +47,48 @@ Full documentation of the project is automatically published on [utPLSQL github
4747

4848
[Cheat-sheet](https://www.cheatography.com/jgebal/cheat-sheets/utplsql-v3/#downloads)
4949

50-
# Contributing to the project
51-
52-
We welcome new developers to join our community and contribute to the utPLSQL project.
53-
If you are interested in helping please read our [guide to contributing](docs/about/CONTRIBUTING.md)
54-
The best place to start is to read the documentation and get familiar with the existing code base.
55-
A [slack chat](https://utplsql.slack.com/) is the place to go if you want to talk with team members.
56-
To sign up to the chat use [this link](http://utplsql-slack-invite.herokuapp.com/)
57-
50+
# Installation
5851

59-
[__Authors__](docs/about/authors.md)
52+
To install the utPLSQL into a new database schema and grant it to public, execute the script `install_headless.sql`.
53+
This will create a new user `UT3`, grant all required privileges to that user and create PUBLIC synonyms needed.
6054

61-
__Version 2 to Version 3 Comparison__
55+
For detailed instructions on other install options see the [Install Guide](docs/userguide/install.md)
6256

63-
If you have a great feature in mind, that you would like to see in utPLSQL v3 please create an [issue on GitHub](https://github.com/utPLSQL/utPLSQL/issues) or discuss it with us in the [Slack chat rooms](http://utplsql-slack-invite.herokuapp.com/).
6457

58+
# Running tests
6559

66-
| Feature | Version 2 | Version 3 |
67-
| -------------------------------------- | ---------------------- | ---------------------- |
68-
| Easy to install | Yes | Yes |
69-
| Documentation | Yes | Yes |
70-
| License | GPL v2 | Apache 2.0 |
71-
| **Tests Creation** | | |
72-
| Declarative test configuration | No | Yes - Annotations<sup>1</sup>|
73-
| Tests as Packages | Yes | Yes |
74-
| Multiple Tests in a single Package | Yes | Yes |
75-
| Optional Setup/Teardown | No | Yes |
76-
| Different Setup/Teardown <br/> For Each Test in a Single Package| No | Yes - Annotations<sup>1</sup> |
77-
| Suite Definition Storage | Tables | Package - Annotations<sup>1</sup> |
78-
| Multiple Suites | Yes | Yes |
79-
| Suites can contain Suites | No | Yes |
80-
| Automatic Test detection | No | Yes - Annotations<sup>1</sup>|
81-
| Unconstrained naming of Test packages | No - prefixes | Yes - name not relevant|
82-
| Require Prefix on Test procedures | No - prefixes | Yes - name not relevant|
83-
| Auto Compilation of Tests | Yes | No (Let us know if you use this) |
84-
| Assertion Library | 30 assertions<sup>2</sup> | 26 matchers (13 + 13 negated) |
85-
| Extendable assertions | No | Yes - custom matchers |
86-
| PLSQL Record Assertions | generated code through **utRecEq** Package | [possible on Oracle 12c](https://oracle-base.com/articles/12c/using-the-table-operator-with-locally-defined-types-in-plsql-12cr1) using [cursor matchers](docs/userguide/expectations.md#comparing-cursors)|
87-
| Test Skeleton Generation | Yes | On Roadmap |
88-
| **Test Execution<sup>3</sup>** | | |
89-
| Single Test Package Execution | Yes | Yes |
90-
| Single Test Procedure Execution | No | Yes |
91-
| Test Suite Execution | Yes | Yes |
92-
| Subset of Suite Execution | No | Yes |
93-
| Multiple Suite Execution | No | Yes |
94-
| Organizing Suites into hierarchies | No | Yes |
95-
| **Code Coverage Reporting** | No | Yes |
96-
| Html Coverage Report | No | Yes |
97-
| Sonar XML Coverage Report | No | Yes |
98-
| Coveralls Json Coverage Report | No | Yes |
99-
| Framework Transaction Control | No | Yes - Annotations<sup>1</sup> |
100-
| **Test Output** | | |
101-
| Real-time test execution progress reporting | No | Yes |
102-
| Multiple Output Reporters can be used during test execution | No| Yes |
103-
| DBMS_OUTPUT | Yes | Yes (clean formatting) |
104-
| File | Yes (to db server only)| Yes (on client side) |
105-
| Stored in Table | Yes | No (can be added as custom reporter)
106-
| XUnit format support | No | Yes |
107-
| HTML Format | Yes | No |
108-
| Custom Output reporter | Yes-needs configuration| Yes - no config needed |
60+
To execute using development IDE (TOAD/SQLDeveloper/PLSQLDeveloper/other) use one of following commands.
61+
```sql
62+
begin
63+
ut.run();
64+
end;
65+
/
66+
```
67+
```sql
68+
exec ut.run();
69+
```
70+
```sql
71+
select * from table(ut.run());
72+
```
10973

110-
<sup>1</sup> Annotations are specially formatted comments in your package specification. This enables *declarative* test configuration that is coupled with the source code. See Documentation for more details.
74+
The above commands will run all the suites in the current schema and provide report to dbms_output or as a select statement.
11175

112-
<sup>2</sup> **utAssert2** package - Contains 59 Assertions - 2 Not implemented = 57, 28 are duplicated only change on outcome_in parameter 57-28 = 29, **utPipe** package - Contains 1 Assertion 29 + 1 = 30
76+
# Command lien clients
11377

114-
<sup>3</sup> Test execution comparison is in a single call so the results are combined. We know it was always possible to group in any way with multiple calls. But that may not be desired under a CI system where you want a single JUnit XML Output.
78+
To have more control over how the tests are invoked, use one of the utPLSQL command line clients: [utPLSQL-sql-cli](https://github.com/utPLSQL/utPLSQL-sql-cli) or [utPLSQL-cli](https://github.com/utPLSQL/utPLSQL-cli).
11579

116-
# Installation
80+
To use `utPLSQL-sql-cli` you will need to have SQLPlus installed. `utPLSQL-cli` is Java project, so no additional software is needed.
11781

118-
To simply install the utPLSQL into a new database schema and grant it to public, execute the script `install_headless.sql`.
82+
Amongst many benefits they provide ability to:
83+
* see the progress of test execution for long-running tests - real-time reporting
84+
* use many reporting formats simultaneously and save reports to files (publish)
85+
* map your project source files and test files into database objects
11986

120-
This will create a new user `UT3` with password `UT3`, grant all required privileges to that user and create PUBLIC synonyms needed to use the utPLSQL framework.
12187

122-
Example invocation of the script from command line:
123-
```bash
124-
cd source
125-
sqlplus admin/admins_password@xe @@install_headless.sql
126-
```
88+
# Example unit test packages
12789

128-
For detailed instructions on other install options see the [Install Guide](docs/userguide/install.md)
90+
**For examples of using Continuous Integration Server & SonarCloud with utPLSQL see the [utPLSQL demo project](https://github.com/utPLSQL/utPLSQL-demo-project/).**
12991

130-
# Example unit test packages
13192

13293
The below test package is a fully-functional Unit Test package for testing a [`betwnstr` function](examples/between_string/betwnstr.sql).
13394
The package specification is [annotated](docs/userguide/annotations.md) with special comments.
@@ -179,25 +140,7 @@ end;
179140
/
180141
```
181142

182-
Have a look at the [utPLSQL demo project](https://github.com/utPLSQL/utPLSQL-demo-project/).
183-
The project is installing few example packages from the [source directory](https://github.com/utPLSQL/utPLSQL-demo-project/tree/develop/source),
184-
installing the test packages from [test directory](https://github.com/utPLSQL/utPLSQL-demo-project/tree/develop/test)
185-
and finally executing all the tests using [Travis CI](https://travis-ci.org/utPLSQL/utPLSQL-demo-project).
186-
The [test results](https://sonarqube.com/component_measures/metric/tests/list?id=utPLSQL%3AutPLSQL-demo-project)
187-
together with [code coverage](https://sonarqube.com/component_measures/metric/coverage/list?id=utPLSQL%3AutPLSQL-demo-project)
188-
are published to the [projects Sonar page](https://sonarqube.com/dashboard?id=utPLSQL%3AutPLSQL-demo-project) after every successful build.
189-
190-
# Running tests
191-
192-
To execute using development IDE (TOAD/SQLDeveloper/PLSQLDeveloper/other) just run the following.
193-
```sql
194-
begin
195-
ut.run();
196-
end;
197-
/
198-
```
199-
Will run all the suites in the current schema and provide documentation report using dbms_output
200-
143+
Outputs from running the above tests
201144
```
202145
Between string function
203146
Returns substring from start position to end position
@@ -209,12 +152,77 @@ Finished in .036027 seconds
209152
4 tests, 0 failures
210153
```
211154

212-
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)
213155

214-
You may benefit from using the [ut_run](https://github.com/utPLSQL/utPLSQL-sql-cli) script to execute your tests if you want to achieve one of the following:
215-
* see the progress of test execution for long-running tests
216-
* have output to screen with one output format (text) and at the same time have output to file in other format (xunit)
156+
# Contributing to the project
157+
158+
We welcome new developers to join our community and contribute to the utPLSQL project.
159+
If you are interested in helping please read our [guide to contributing](docs/about/CONTRIBUTING.md)
160+
The best place to start is to read the documentation and get familiar with the existing code base.
161+
A [slack chat](https://utplsql.slack.com/) is the place to go if you want to talk with team members.
162+
To sign up to the chat use [this link](http://utplsql-slack-invite.herokuapp.com/)
163+
164+
165+
----------
166+
[__Authors__](docs/about/authors.md)
167+
168+
----------
169+
__Version 2 to Version 3 Comparison__
170+
171+
If you have a great feature in mind, that you would like to see in utPLSQL v3 please create an [issue on GitHub](https://github.com/utPLSQL/utPLSQL/issues) or discuss it with us in the [Slack chat rooms](http://utplsql-slack-invite.herokuapp.com/).
172+
217173

174+
| Feature | Version 2 | Version 3 |
175+
| -------------------------------------- | ---------------------- | ---------------------- |
176+
| Easy to install | Yes | Yes |
177+
| Documentation | Yes | Yes |
178+
| License | GPL v2 | Apache 2.0 |
179+
| **Tests Creation** | | |
180+
| Declarative test configuration | No | Yes - Annotations<sup>1</sup>|
181+
| Tests as Packages | Yes | Yes |
182+
| Multiple Tests in a single Package | Yes | Yes |
183+
| Optional Setup/Teardown | No | Yes |
184+
| Different Setup/Teardown <br/> For Each Test in a Single Package| No | Yes - Annotations<sup>1</sup> |
185+
| Suite Definition Storage | Tables | Package - Annotations<sup>1</sup> |
186+
| Multiple Suites | Yes | Yes |
187+
| Suites can contain Suites | No | Yes |
188+
| Automatic Test detection | No | Yes - Annotations<sup>1</sup>|
189+
| Unconstrained naming of Test packages | No - prefixes | Yes - name not relevant|
190+
| Require Prefix on Test procedures | No - prefixes | Yes - name not relevant|
191+
| Auto Compilation of Tests | Yes | No (Let us know if you use this) |
192+
| Assertion Library | 30 assertions<sup>2</sup> | 26 matchers (13 + 13 negated) |
193+
| Extendable assertions | No | Yes - custom matchers |
194+
| PLSQL Record Assertions | generated code through **utRecEq** Package | [possible on Oracle 12c](https://oracle-base.com/articles/12c/using-the-table-operator-with-locally-defined-types-in-plsql-12cr1) using [cursor matchers](docs/userguide/expectations.md#comparing-cursors)|
195+
| Test Skeleton Generation | Yes | No (Let us know if you use this) |
196+
| **Test Execution<sup>3</sup>** | | |
197+
| Single Test Package Execution | Yes | Yes |
198+
| Single Test Procedure Execution | No | Yes |
199+
| Test Suite Execution | Yes | Yes |
200+
| Subset of Suite Execution | No | Yes |
201+
| Multiple Suite Execution | No | Yes |
202+
| Organizing Suites into hierarchies | No | Yes |
203+
| **Code Coverage Reporting** | No | Yes |
204+
| Html Coverage Report | No | Yes |
205+
| Sonar XML Coverage Report | No | Yes |
206+
| Coveralls Json Coverage Report | No | Yes |
207+
| Framework Transaction Control | No | Yes - Annotations<sup>1</sup> |
208+
| **Test Output** | | |
209+
| Real-time test execution progress reporting | No | Yes |
210+
| Multiple Output Reporters can be used during test execution | No| Yes |
211+
| DBMS_OUTPUT | Yes | Yes (clean formatting) |
212+
| File | Yes (to db server only)| Yes (on client side) |
213+
| Stored in Table | Yes | No (can be added as custom reporter) |
214+
| XUnit format support | No | Yes |
215+
| HTML Format | Yes | No |
216+
| Custom Output reporter | Yes-needs configuration| Yes - no config needed |
217+
218+
<sup>1</sup> Annotations are specially formatted comments in your package specification. This enables *declarative* test configuration that is coupled with the source code. See Documentation for more details.
219+
220+
<sup>2</sup> **utAssert2** package - Contains 59 Assertions - 2 Not implemented = 57, 28 are duplicated only change on outcome_in parameter 57-28 = 29, **utPipe** package - Contains 1 Assertion 29 + 1 = 30
221+
222+
<sup>3</sup> Test execution comparison is in a single call so the results are combined. We know it was always possible to group in any way with multiple calls. But that may not be desired under a CI system where you want a single JUnit XML Output.
223+
224+
225+
----------
218226
__Project Directories__
219227

220228
* .travis - contains files needed for travis-ci integration

0 commit comments

Comments
 (0)