diff --git a/docs/compare_version2_to_3.md b/docs/compare_version2_to_3.md new file mode 100644 index 000000000..5f53e41d4 --- /dev/null +++ b/docs/compare_version2_to_3.md @@ -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 - Annotations1| +| Tests as Packages | Yes | Yes | +| Multiple Tests in a single Package | Yes | Yes | +| Optional Setup/Teardown | No | Yes | +| Different Setup/Teardown
For Each Test in a Single Package| No | Yes - Annotations1 | +| Suite Definition Storage | Tables | Package - Annotations1 | +| Multiple Suites | Yes | Yes | +| Suites can contain Suites | No | Yes | +| Automatic Test detection | No | Yes - Annotations1| +| 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 assertions2 | 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 Execution3** | | | +| 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 - Annotations1 | +| **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 | + +1 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. + +2 **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 + +3 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. diff --git a/docs/index.md b/docs/index.md index ec919ecf0..cc3e79595 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 diff --git a/docs/userguide/running-unit-tests.md b/docs/userguide/running-unit-tests.md index 280778636..628ff38a5 100644 --- a/docs/userguide/running-unit-tests.md +++ b/docs/userguide/running-unit-tests.md @@ -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. diff --git a/readme.md b/readme.md index 315124db6..864e1041e 100644 --- a/readme.md +++ b/readme.md @@ -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 - Annotations1| -| Tests as Packages | Yes | Yes | -| Multiple Tests in a single Package | Yes | Yes | -| Optional Setup/Teardown | No | Yes | -| Different Setup/Teardown
For Each Test in a Single Package| No | Yes - Annotations1 | -| Suite Definition Storage | Tables | Package - Annotations1 | -| Multiple Suites | Yes | Yes | -| Suites can contain Suites | No | Yes | -| Automatic Test detection | No | Yes - Annotations1| -| 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 assertions2 | 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 Execution3** | | | -| 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 - Annotations1 | -| **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 | - -1 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. - -2 **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 - -3 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__ @@ -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.