Merge pull request #524 from john-otoole/documentation-fixes-part3

jgebal · web-flow · commit e43b15659f04 · 2017-11-27T23:33:50.000Z
Documentation fixes part3
diff --git a/docs/userguide/annotations.md b/docs/userguide/annotations.md
@@ -1,21 +1,21 @@
 # Annotations
 
 Annotations are used to configure tests and suites in a declarative way similar to modern OOP languages. This way, test configuration is stored along with the test logic inside the test package.
-No configuration files or tables are needed. The annotations names are based on popular testing frameworks such as jUnit.
-The framework runner searches for all the suitable annotated packages, automatically configures suites, forms suites hierarchy, executes it and reports results in specified formats.
+No configuration files or tables are needed. The annotation names are based on popular testing frameworks such as jUnit.
+The framework runner searches for all the suitable annotated packages, automatically configures suites, forms the suite hierarchy, executes it and reports results in specified formats.
 
-Annotations are interpreted only in package specification and are case-insensitive. It is recommended however, to use the lower-case annotations as described in documentation.
+Annotations are interpreted only in the package specification and are case-insensitive. It is recommended however, to use  lower-case annotations as described in this documentation.
 
-There are two places where annotations may appear: 
+There are two places where annotations may appear:
 
-- at the beginning of the package specification (`%suite`, `%suitepath` etc)
-- right before a procedure (`%test`, `%beforeall`, `%beforeeach` etc). 
+- at the beginning of the package specification (`%suite`, `%suitepath` etc.)
+- right before a procedure (`%test`, `%beforeall`, `%beforeeach` etc.)
 
-Package level annotations need to be separated by at least one empty line from the underlying procedure annotations. 
+Package level annotations need to be separated by at least one empty line from the underlying procedure annotations.
 
 Procedure annotations are defined right before the procedure they reference, no empty lines are allowed.
 
-If a package specification contains `%suite` annotation, it is treated as a test package and processed by the framework.
+If a package specification contains the `%suite` annotation, it is treated as a test package and is processed by the framework.
 
 Some annotations accept parameters like `%suite`, `%test` and `%displayname`. The parameters for annotations need to be placed in brackets. Values for parameters should be provided without any quotation marks.
 
@@ -48,7 +48,7 @@ create or replace package test_pkg is
   -- %displayname(Name of test)
   -- %disabled
   procedure disabled_test;
-  
+
   -- %test(Name of test)
   -- %rollback(manual)
   procedure no_transaction_control_test;
@@ -72,15 +72,15 @@ end test_pkg;
 | --- | --- | --- |
 | `%suite(<description>)` | Package | Mandatory. Marks package as a test suite. Optional suite description can be provided (see `displayname`). |
 | `%suitepath(<path>)` | Package | Similar to java package. The annotation allows logical grouping of suites into hierarchies. |
-| `%displayname(<description>)` | Package/procedure | Human-readable and meaningful description of a suite/test. `%displayname(Name of the suite/test)`. The annotation is provided for flexibility and convenience only. It has exactly the same meaning as `<descriotion>` in `test` and `suite` annotations. If description is provided using both `suite`/`test` and `displayname`, then the one defined as last takes precedence. |
+| `%displayname(<description>)` | Package/procedure | Human-readable and meaningful description of a suite/test. `%displayname(Name of the suite/test)`. The annotation is provided for flexibility and convenience only. It has exactly the same meaning as `<description>` in `test` and `suite` annotations. If description is provided using both `suite`/`test` and `displayname`, then the one defined as last takes precedence. |
 | `%test(<description>)` | Procedure | Denotes that the annotated procedure is a unit test procedure.  Optional test description can by provided (see `displayname`). |
 | `%beforeall` | Procedure | Denotes that the annotated procedure should be executed once before all elements of the suite. |
 | `%afterall` | Procedure | Denotes that the annotated procedure should be executed once after all elements of the suite. |
 | `%beforeeach` | Procedure | Denotes that the annotated procedure should be executed before each `%test` procedure in the suite. |
 | `%aftereach` | Procedure | Denotes that the annotated procedure should be executed after each `%test` procedure in the suite. |
 | `%beforetest(<procedure_name>)` | Procedure | Denotes that mentioned procedure should be executed before the annotated `%test` procedure. |
 | `%aftertest(<procedure_name>)` | Procedure | Denotes that mentioned procedure should be executed after the annotated `%test` procedure. |
-| `%rollback(<type>)` | Package/procedure | Defines transaction control. Supported values: `auto`(default) - A savepoint is created before invocation of each "before block" is and a rollback to specific savepoint is issued after each "after" block; `manual` - rollback is never issued automatically. Property can be overridden for child element (test in suite) |
+| `%rollback(<type>)` | Package/procedure | Defines transaction control. Supported values: `auto`(default) - a savepoint is created before invocation of each "before block" is and a rollback to specific savepoint is issued after each "after" block; `manual` - rollback is never issued automatically. Property can be overridden for child element (test in suite) |
 | `%disabled` | Package/procedure | Used to disable a suite or a test. Disabled suites/tests do not get executed, they are however marked and reported as disabled in a test run. |
 
 # Suitepath concept
@@ -94,10 +94,10 @@ If you want to create tests for your application it is recommended to structure
   *   Policy tests
   *   Claim tests
   *   Payment tests
-    * Payments recognition 
+    * Payments recognition
     * Payments set off
-    * Payouts 
-    
+    * Payouts
+
 The `%suitepath` annotation is used for such grouping. Even though test packages are defined in a flat structure the `%suitepath` is used by the framework to form them into a hierarchical structure. Your payments recognition test package might look like:
 
 ```sql
@@ -137,7 +137,7 @@ end test_payment_set_off;
 ```
 
 When you execute tests for your application, the framework constructs a test suite for each test package. Then it combines suites into grouping suites by the `%suitepath` annotation value so that the fully qualified path to the `recognize_by_num` procedure is `USER:payments.test_payment_recognition.test_recognize_by_num`. If any of its expectations fails then the test is marked as failed, also the `test_payment_recognition` suite, the parent suite `payments` and the whole run is marked as failed.
-The test report indicates which expectation has failed on the payments module. The payments recognition submodule is causing the failure as `recognize_by_num` has not met the expectations of the test. Grouping tests into modules and submodules using the `%suitepath` annotation allows you to logically organize your project's flat structure of packages into functional groups. 
+The test report indicates which expectation has failed on the payments module. The payments recognition submodule is causing the failure as `recognize_by_num` has not met the expectations of the test. Grouping tests into modules and submodules using the `%suitepath` annotation allows you to logically organize your project's flat structure of packages into functional groups.
 
 An additional advantage of such grouping is the fact that every element level of the grouping can be an actual unit test package containing a common module level setup for all of the submodules. So in addition to the packages mentioned above you could have the following package.
 ```sql
@@ -158,10 +158,10 @@ A `%suitepath` can be provided in three ways:
 * [schema]:suite1[.suite2][.suite3]...[.procedure] - execute all tests in all suites from suite1[.suite2][.suite3]...[.procedure] path. If schema is not provided, then the current schema is used. Example: `:all.rooms_tests`
 * [schema.]package[.procedure] - execute all tests in the specified test package. The whole hierarchy of suites in the schema is built before all before/after hooks or part suites for the provided suite package are executed as well. Example: `tests.test_contact.test_last_name_validator` or simply `test_contact.test_last_name_validator` if `tests` is the current schema.
 
-# Using automatic rollbacks in tests
+# Using automatic rollback in tests
 
 By default, changes performed by every setup, cleanup and test procedure are isolated by savepoints.
-This solution is suitable for use-cases where the code that is getting tested as well as the unit tests themselves do not use transaction control (commit/rollback) or DDL commands.
+This solution is suitable for use-cases where the code that is being tested as well as the unit tests themselves do not use transaction control (commit/rollback) or DDL commands.
 
 In general, your unit tests should not use transaction control as long as the code you are testing is not using it too.
 Keeping the transactions uncommitted allows your changes to be isolated and the execution of tests does not impact others who might be using a shared development database.
@@ -175,12 +175,12 @@ It is strongly recommended not to have mixed transaction control in a suite.
 Mixed transaction control settings will not work properly when your suites are using shared setup/cleanup with beforeall, afterall, beforeeach or aftereach annotations.
 Your suite will most likely fail with error or warning on execution. Some of the automatic rollbacks will probably fail to execute depending on the configuration you have.
 
-In some cases it is necessary to perform DDL as part of setup or cleanup for the tests. 
+In some cases it is necessary to perform DDL as part of setup or cleanup for the tests.
 It is recommended to move such DDL statements to a procedure with `pragma autonomous_transaction` to eliminate implicit commits in the main session that is executing all your tests.
 Doing so allows your tests to use the framework's automatic transaction control and releases you from the burden of manual cleanup of data that was created or modified by test execution.
 
 When you are testing code that performs explicit or implicit commits, you may set the test procedure to run as an autonomous transaction with `pragma autonomous_transaction`.
-Keep in mind that when your tests runs in autonomous transaction it will not see the data prepared in setup procedure unless the setup procedure committed the changes. 
+Keep in mind that when your test runs as autonomous transaction it will not see the data prepared in a setup procedure unless the setup procedure committed the changes.
 
 # Order of execution
 
@@ -189,23 +189,23 @@ When processing the test suite `test_pkg` defined in [Example of annotated test
 ```
   create a savepoint 'beforeall'
     execute global_setup
-    
+
     create savepoint 'beforeeach'
       execute test_setup
       execute some_test
       execute test_cleanup
     rollback to savepoint 'beforeeach'
-    
+
     create savepoint 'beforeeach'
       execute test_setup
       execute setup_another_test
       execute another_test
       execute cleanup_another_test
       execute test_cleanup
     rollback to savepoint 'beforeeach'
-    
+
     mark disabled_test as disabled
-    
+
     execute test_setup
     execute no_transaction_control_test
     execute test_cleanup    
@@ -217,23 +217,21 @@ When processing the test suite `test_pkg` defined in [Example of annotated test
 
 # Annotation cache
 
-utPLSQL needs to scan sources of package specifications to identify and parse annotations.
-To improve framework startup time, specially when dealing with database users owning large amount of packages the framework has build-in persistent cache for annotations.
+utPLSQL needs to scan the source of package specifications to identify and parse annotations.
+To improve framework startup time, especially when dealing with database users owning large amounts of packages, the framework has a built-in persistent cache for annotations.
 
-Cache is checked for staleness and refreshed automatically on every run.
-The initial startup of utPLSQL for a schema will take longer than consecutive executions.
+The annotation cache is checked for staleness and refreshed automatically on every run. The initial startup of utPLSQL for a schema will take longer than consecutive executions.
 
-If you're in situation, where your database is controlled via CI/CD server and gets refreshed/wiped before each run of your tests, 
-consider building upfront and creating the snapshot of our database after the cache was refreshed.
-
-To build annotation cache without actually invoking any tests, call `ut_runner.rebuild_annotation_cache(a_object_owner, a_object_type)` sql block for every unit test owner that you want to have annotations cache prebuilt.
+If you are in a situation where your database is controlled via CI/CD server and is refreshed/wiped before each run of your tests, consider building the annotation cache upfront and taking a snapshot of the database after the cache has been refreshed.
 
+To build the annotation cache without actually invoking any tests, call `ut_runner.rebuild_annotation_cache(a_object_owner, a_object_type)` for every unit test owner for which you want to have the annotation cache prebuilt.
 Example:
 ```sql
 exec ut_runner.rebuild_annotation_cache('HR', 'PACKAGE');
 ```
 
-To purge annotations cache call: 
+To purge the annotation cache call `ut_runner.purge_cache(a_object_owner, a_object_type)`.
+Example:
 ```sql
 exec ut_runner.purge_cache('HR', 'PACKAGE');
 ```
diff --git a/docs/userguide/install.md b/docs/userguide/install.md
@@ -61,7 +61,7 @@ The script accepts three optional parameters that define:
 Example invocation of the script from command line:
 ```bash
 cd source
-sqlplus sys/sys_pass@db as sysdba @@install_headless.sql  
+sqlplus sys/sys_pass@db as sysdba @install_headless.sql  
 ```
 
 Invoking script with parameters:
@@ -98,7 +98,7 @@ It is up to DBA to maintain the storage of the profiler tables.
 # Manual installation procedure
 
 ### Creating schema for utPLSQL
-To create the utPLSQL schema and grant all the needed privileges execute script `create_utplsql_owner.sql` from the `source` directory with parameters:
+To create the utPLSQL schema and grant all the required privileges execute script `create_utplsql_owner.sql` from the `source` directory with parameters:
 
   - `user name` - the name of the user that will own of utPLSQL object
   - `password`  - the password to be set for that user
@@ -121,8 +121,8 @@ cd source
 sqlplus admin/admins_password@database @install.sql ut3  
 ```
 
-### Allowing other users to access utPLSQL framework
-In order to allow other users to access utPLSQL, synonyms must be created and grants need to be added.
+### Allowing other users to access the utPLSQL framework
+In order to allow other users to access utPLSQL, synonyms must be created and privileges granted.
 You have two options:
 
   - use grants and synonyms to public, to allow all users to access the framework
@@ -135,7 +135,7 @@ Example invocation:
 cd source
 sqlplus admin/admins_password@database @create_synonyms_and_grants_for_public.sql ut3  
 ```
-To grant utPLSQL to individual user execute script `source/create_synonyms_and_grants_for_user.sql`, provide `schema_name` where utPLSQL is installed and `user_name` to grant access for.
+To grant utPLSQL to an individual user, execute script `source/create_synonyms_and_grants_for_user.sql`, provide `schema_name` where utPLSQL is installed and `user_name` to grant access for.
 
 Example invocation:
 ```bash
@@ -151,31 +151,39 @@ The following tools that support the SQL*Plus commands can be used to run the in
  
 # Additional requirements
 
-In order to use Code Coverage functionality of utPLSQL, users executing the tests must have the CREATE privilege on the PLSQL code that the coverage is gathered on.
+In order to use the Code Coverage functionality of utPLSQL, users executing the tests must have the CREATE privilege on the PLSQL code that the coverage is gathered on.
 This is a requirement of [DBMS_PROFILER package](https://docs.oracle.com/cd/E18283_01/appdev.112/e16760/d_profil.htm#i999476).
 
 In practice, user running tests for PLSQL code that he does not own, needs to have CREATE ANY PROCEDURE/CREATE ANY TRIGGER privileges.
 Running code coverage on objects that the user does not own will **not produce any coverage information** without those privileges.
 
 # Uninstalling utPLSQL
 
-To uninstall run `/source/uninstall.sql` and provide `schema_name` where utPLSQL is installed.
+To uninstall run `uninstall.sql` and provide `schema_name` where utPLSQL is installed.
+
+Example invocation:
+```bash
+cd source
+sqlplus admin/admins_password@database @uninstall.sql ut3
+```
 
 The uninstall script will remove all the objects installed by the install script.
-Additionally, all the public and private synonyms pointing to the objects in utPLSQL schema will be removed.
+Additionally, all the public and private synonyms pointing to the objects in the utPLSQL schema will be removed.
+
+If you have extended any utPLSQL types such as a custom reporter, these will need to be dropped before the uninstall, otherwise the uninstall script might fail.
 
-If you have you have extended any utPLSQL types such as a custom reporter, these will need to be dropped before the uninstall, otherwise the uninstall script might fail.
+The uninstall script does not drop the schema.
 
-In order for the uninstall to be successful, you need to use the uninstall script, that was provided whit the exact version that was installed on your database.
-The uninstall script provided with version 3.0.1 will probably not work, if you want to remove version 3.0.0 from your database.
+In order for the uninstall to be successful, you need to use the uninstall script that was provided with the exact utPLSQL version installed on your database.
+i.e. the uninstall script provided with version 3.0.1 will probably not work if you want to remove version 3.0.0 from your database.
 
 # Version upgrade
 
-Currently, the only way to upgrade version of utPLSQL v3.0.0 and above is to remove the previous version and install new version
+Currently, the only way to upgrade version of utPLSQL v3.0.0 and above is to remove the previous version and install the new version.
 
 # Working with utPLSQL v2
 
 If you are using utPLSQL v2, you can still install utPLSQL v3.
-The only requirement is that utPLSQL v3 needs to be installed in different schema than utPLSQL v2.
+The only requirement is that utPLSQL v3 needs to be installed in a different schema than utPLSQL v2.
 
 utPLSQL v3 and utPLSQL v2 do not collide on public synonym names. 
