From 48a3f9ed6d63f20ce525e74965c0dfe27aff5969 Mon Sep 17 00:00:00 2001 From: pesse Date: Fri, 11 Oct 2019 17:03:21 +0200 Subject: [PATCH 1/5] Make "Version 2 to 3 comparison" an actual section in readme --- readme.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/readme.md b/readme.md index 315124db6..b0401647f 100644 --- a/readme.md +++ b/readme.md @@ -168,12 +168,25 @@ To sign up to the chat use [this link](http://utplsql-slack-invite.herokuapp.com ---------- [__Authors__](docs/about/authors.md) + +---------- +__Project Directories__ + +* .travis - contains files needed for travis-ci integration +* client_source - Sources to be used on the client-side. Developer workstation or CI platform to run the tests. +* development - Set of useful scripts and utilities for development and debugging of utPLSQL +* docs - Documentation of the project +* examples - Example source code and unit tests +* source - The installation code for utPLSQL +* tests - Tests for utPLSQL framework + ---------- -__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/). +# Version 2 to Version 3 Comparison + | Feature | Version 2 | Version 3 | | -------------------------------------- | ---------------------- | ---------------------- | | Easy to install | Yes | Yes | @@ -224,19 +237,6 @@ If you have a great feature in mind, that you would like to see in utPLSQL v3 pl 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__ - -* .travis - contains files needed for travis-ci integration -* client_source - Sources to be used on the client-side. Developer workstation or CI platform to run the tests. -* development - Set of useful scripts and utilities for development and debugging of utPLSQL -* docs - Documentation of the project -* examples - Example source code and unit tests -* source - The installation code for utPLSQL -* tests - Tests for utPLSQL framework - ------------ # Supporters The utPLSQL project is community-driven and is not commercially motivated. Nonetheless, donations and other contributions are always welcome, and are detailed below. From f8a3b87014aa5fd71b858dbd51ce7f60c9973aba Mon Sep 17 00:00:00 2001 From: pesse Date: Fri, 11 Oct 2019 17:14:07 +0200 Subject: [PATCH 2/5] Outsource the Version comparison to a separate file so it can be directly linked --- docs/compare_version2_to_3.md | 56 +++++++++++++++++++++++++++++++++++ docs/index.md | 1 + readme.md | 50 +------------------------------ 3 files changed, 58 insertions(+), 49 deletions(-) create mode 100644 docs/compare_version2_to_3.md diff --git a/docs/compare_version2_to_3.md b/docs/compare_version2_to_3.md new file mode 100644 index 000000000..624bf0df8 --- /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](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. diff --git a/docs/index.md b/docs/index.md index ebd934948..acc3c4861 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/readme.md b/readme.md index b0401647f..864e1041e 100644 --- a/readme.md +++ b/readme.md @@ -187,55 +187,7 @@ If you have a great feature in mind, that you would like to see in utPLSQL v3 pl # Version 2 to Version 3 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](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. +[Version 2 to Version 3 Comparison](docs/compare_version2_to_3.md) # Supporters From 40badacae3f13163a28db55c522e60e7b280f62d Mon Sep 17 00:00:00 2001 From: pesse Date: Fri, 11 Oct 2019 17:58:54 +0200 Subject: [PATCH 3/5] Describe the usage of tags in the "Running"-section Fixes #1003 --- docs/userguide/running-unit-tests.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/userguide/running-unit-tests.md b/docs/userguide/running-unit-tests.md index ce88c7889..3e6ce8547 100644 --- a/docs/userguide/running-unit-tests.md +++ b/docs/userguide/running-unit-tests.md @@ -282,6 +282,23 @@ 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. +Multiple tags are separated by comma. If multiple tags are set, all tests with __any__ of them specified are run. + +Example Procedure: +```sql +begin + ut.run('hr.test_apply_bonus', a_tags => 'test1,test2'); +end; +``` +Example Function: +```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. From 4cfb0cf8c552c6d087a250d1ba91664f508c3e49 Mon Sep 17 00:00:00 2001 From: pesse Date: Fri, 11 Oct 2019 18:01:34 +0200 Subject: [PATCH 4/5] Add link to Tag-annotation and tweak for consistency --- docs/userguide/running-unit-tests.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/userguide/running-unit-tests.md b/docs/userguide/running-unit-tests.md index 3e6ce8547..a1535bc73 100644 --- a/docs/userguide/running-unit-tests.md +++ b/docs/userguide/running-unit-tests.md @@ -284,16 +284,14 @@ select * from table(ut.run('hr.test_apply_bonus', a_random_test_order_seed => 30 # 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. +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. -Example Procedure: ```sql begin ut.run('hr.test_apply_bonus', a_tags => 'test1,test2'); end; ``` -Example Function: ```sql select * from table(ut.run('hr.test_apply_bonus', a_tags => 'suite1')) ``` From afca2482fbb59820709283373107d48c5df808a5 Mon Sep 17 00:00:00 2001 From: Jacek Gebal Date: Mon, 21 Oct 2019 00:31:45 +0100 Subject: [PATCH 5/5] Fixed broken doc link --- docs/compare_version2_to_3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/compare_version2_to_3.md b/docs/compare_version2_to_3.md index 624bf0df8..5f53e41d4 100644 --- a/docs/compare_version2_to_3.md +++ b/docs/compare_version2_to_3.md @@ -25,7 +25,7 @@ There is a [migration tool](https://github.com/utPLSQL/utPLSQL-v2-v3-migration) | 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)| +| 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 |