Skip to content

Feature/docs improvement #1004

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Oct 21, 2019
Merged

Feature/docs improvement #1004

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
48a3f9e
Make "Version 2 to 3 comparison" an actual section in readme
pesse Oct 11, 2019
f8a3b87
Outsource the Version comparison to a separate file so it can be
pesse Oct 11, 2019
40badac
Describe the usage of tags in the "Running"-section
pesse Oct 11, 2019
4cfb0cf
Add link to Tag-annotation and tweak for consistency
pesse Oct 11, 2019
a0ba9ad
Merge remote-tracking branch 'origin/develop' into feature/docs_impro…
jgebal Oct 20, 2019
afca248
Fixed broken doc link
jgebal Oct 20, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions docs/compare_version2_to_3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
For version 3 has been a complete rewrite of the framework, the way it can be used is different to
the previous versions, but also more in line with other modern unit-testing frameworks like JUnit and RSpec.

There is a [migration tool](https://github.com/utPLSQL/utPLSQL-v2-v3-migration) that can help you to migrate your existing utPLSQL v2 tests to the v3 capabilities.

# Feature comparison

| Feature | Version 2 | Version 3 |
| -------------------------------------- | ---------------------- | ---------------------- |
| Easy to install | Yes | Yes |
| Documentation | Yes | Yes |
| License | GPL v2 | Apache 2.0 |
| **Tests Creation** | | |
| Declarative test configuration | No | Yes - Annotations<sup>1</sup>|
| Tests as Packages | Yes | Yes |
| Multiple Tests in a single Package | Yes | Yes |
| Optional Setup/Teardown | No | Yes |
| Different Setup/Teardown <br/> For Each Test in a Single Package| No | Yes - Annotations<sup>1</sup> |
| Suite Definition Storage | Tables | Package - Annotations<sup>1</sup> |
| Multiple Suites | Yes | Yes |
| Suites can contain Suites | No | Yes |
| Automatic Test detection | No | Yes - Annotations<sup>1</sup>|
| Unconstrained naming of Test packages | No - prefixes | Yes - name not relevant|
| Require Prefix on Test procedures | No - prefixes | Yes - name not relevant|
| Auto Compilation of Tests | Yes | No (Let us know if you use this) |
| Assertion Library | 30 assertions<sup>2</sup> | 26 matchers (13 + 13 negated) |
| Extendable assertions | No | Yes - custom matchers |
| 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](userguide/expectations.md#comparing-cursors)|
| Test Skeleton Generation | Yes | No (Let us know if you use this) |
| **Test Execution<sup>3</sup>** | | |
| Single Test Package Execution | Yes | Yes |
| Single Test Procedure Execution | No | Yes |
| Test Suite Execution | Yes | Yes |
| Subset of Suite Execution | No | Yes |
| Multiple Suite Execution | No | Yes |
| Organizing Suites into hierarchies | No | Yes |
| **Code Coverage Reporting** | No | Yes |
| Html Coverage Report | No | Yes |
| Sonar XML Coverage Report | No | Yes |
| Coveralls Json Coverage Report | No | Yes |
| Framework Transaction Control | No | Yes - Annotations<sup>1</sup> |
| **Test Output** | | |
| Real-time test execution progress reporting | No | Yes |
| Multiple Output Reporters can be used during test execution | No| Yes |
| DBMS_OUTPUT | Yes | Yes (clean formatting) |
| File | Yes (to db server only)| Yes (on client side) |
| Stored in Table | Yes | No (can be added as custom reporter) |
| XUnit format support | No | Yes |
| HTML Format | Yes | No |
| Custom Output reporter | Yes-needs configuration| Yes - no config needed |

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

<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

<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.
1 change: 1 addition & 0 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ The framework follows industry standards and best patterns of modern Unit Testin
- [License](about/license.md)
- [Support](about/support.md)
- [Authors](about/authors.md)
- [Version 2 to Version 3 Comparison](compare_version2_to_3.md)

# Demo project

Expand Down
15 changes: 15 additions & 0 deletions docs/userguide/running-unit-tests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -282,6 +282,21 @@ select * from table(ut.run('hr.test_apply_bonus', a_random_test_order_seed => 30
**Note**
>Random order seed must be a positive number within range of 1 .. 1 000 000 000.

# Run by Tags

In addition to the path, you can filter the tests to be run by specifying tags. Tags are defined in the test with the `--%tags`-annotation ([Read more](annotations.md#tags)).
Multiple tags are separated by comma. If multiple tags are set, all tests with __any__ of them specified are run.

```sql
begin
ut.run('hr.test_apply_bonus', a_tags => 'test1,test2');
end;
```
```sql
select * from table(ut.run('hr.test_apply_bonus', a_tags => 'suite1'))
```


# Keeping uncommitted data after test-run

utPLSQL by default runs tests in autonomous transaction and performs automatic rollback to assure that tests do not impact one-another and do not have impact on the current session in your IDE.
Expand Down
66 changes: 9 additions & 57 deletions readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,62 +168,6 @@ To sign up to the chat use [this link](http://utplsql-slack-invite.herokuapp.com
----------
[__Authors__](docs/about/authors.md)

----------
__Version 2 to Version 3 Comparison__

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/).


| Feature | Version 2 | Version 3 |
| -------------------------------------- | ---------------------- | ---------------------- |
| Easy to install | Yes | Yes |
| Documentation | Yes | Yes |
| License | GPL v2 | Apache 2.0 |
| **Tests Creation** | | |
| Declarative test configuration | No | Yes - Annotations<sup>1</sup>|
| Tests as Packages | Yes | Yes |
| Multiple Tests in a single Package | Yes | Yes |
| Optional Setup/Teardown | No | Yes |
| Different Setup/Teardown <br/> For Each Test in a Single Package| No | Yes - Annotations<sup>1</sup> |
| Suite Definition Storage | Tables | Package - Annotations<sup>1</sup> |
| Multiple Suites | Yes | Yes |
| Suites can contain Suites | No | Yes |
| Automatic Test detection | No | Yes - Annotations<sup>1</sup>|
| Unconstrained naming of Test packages | No - prefixes | Yes - name not relevant|
| Require Prefix on Test procedures | No - prefixes | Yes - name not relevant|
| Auto Compilation of Tests | Yes | No (Let us know if you use this) |
| Assertion Library | 30 assertions<sup>2</sup> | 26 matchers (13 + 13 negated) |
| Extendable assertions | No | Yes - custom matchers |
| 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)|
| Test Skeleton Generation | Yes | No (Let us know if you use this) |
| **Test Execution<sup>3</sup>** | | |
| Single Test Package Execution | Yes | Yes |
| Single Test Procedure Execution | No | Yes |
| Test Suite Execution | Yes | Yes |
| Subset of Suite Execution | No | Yes |
| Multiple Suite Execution | No | Yes |
| Organizing Suites into hierarchies | No | Yes |
| **Code Coverage Reporting** | No | Yes |
| Html Coverage Report | No | Yes |
| Sonar XML Coverage Report | No | Yes |
| Coveralls Json Coverage Report | No | Yes |
| Framework Transaction Control | No | Yes - Annotations<sup>1</sup> |
| **Test Output** | | |
| Real-time test execution progress reporting | No | Yes |
| Multiple Output Reporters can be used during test execution | No| Yes |
| DBMS_OUTPUT | Yes | Yes (clean formatting) |
| File | Yes (to db server only)| Yes (on client side) |
| Stored in Table | Yes | No (can be added as custom reporter) |
| XUnit format support | No | Yes |
| HTML Format | Yes | No |
| Custom Output reporter | Yes-needs configuration| Yes - no config needed |

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

<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

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


----------
__Project Directories__
Expand All @@ -236,7 +180,15 @@ __Project Directories__
* source - The installation code for utPLSQL
* tests - Tests for utPLSQL framework

-----------
----------

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/).


# Version 2 to Version 3 Comparison

[Version 2 to Version 3 Comparison](docs/compare_version2_to_3.md)

# Supporters

The utPLSQL project is community-driven and is not commercially motivated. Nonetheless, donations and other contributions are always welcome, and are detailed below.
Expand Down