Addressed review comments.

jgebal · jgebal · commit a171f5ffb3b3 · 2017-03-20T23:09:43.000Z
diff --git a/docs/index.md b/docs/index.md
@@ -3,18 +3,39 @@
 utPLSQL is a Unit Testing framework for Oracle PL/SQL.
 The framework follows industry standards and best patterns of modern Unit Testing frameworks like [JUnit](http://junit.org/junit4/) and [RSpec](http://rspec.info/)
 
+  - User Guide
+       - [Installation](userguide/install.md)
+       - [Getting Started](userguide/getting-started.md)
+       - [Annotations](userguide/annotations.md)
+       - [Expectations](userguide/expectations.md)
+       - [Running unit tests](userguide/running-unit-tests.md)
+       - [Using the ut_run script](userguide/ut_run-script.md)
+       - [Testing best pracitces](userguide/best-practices.md)
+       - [Upgrade utPLSQL](userguide/upgrade.md)
+  - Reporting
+       - [Using reporters](userguide/reporters.md)
+       - [Reporting errors](userguide/exception-reporting.md)
+       - [Code coverage](userguide/coverage.md)
+  - About
+       - [Project Details](about/project-details.md)
+       - [License](about/license.md)
+       - [Support](about/support.md)
+       - [Authors](about/authors.md)
+       - [Contributing](about/CONTRIBUTING.md)
+
+
 #Three steps
 With just three simple steps you can define and run your unit tests for PLSQL code.
  
 1. Install the utPLSQL framework 
-2. Create Unit Tests to cover the code
+2. Create Unit Tests to for the code
 3. Run the tests
 
 Here is how you can simply create tested code, unit tests and execute the tests using SQL Developer
 
 ![3_steps](images/3_steps_to_run_utPLSQL.gif)
 
-Check out the sections on [annotations](userguide/annotations.md) and [expectations](userguide/expectations.md) to see how to define your tests  
+Check out the sections on [annotations](userguide/annotations.md) and [expectations](userguide/expectations.md) to see how to define your tests.  
 
 
 # Command line 
diff --git a/docs/userguide/expectations.md b/docs/userguide/expectations.md
@@ -12,7 +12,13 @@ end;
 
 Expectation is a set of the expected value(s), actual values(s) and the matcher(s) to run on those values.
 
-Matcher is defining the comparison operation to be performed on expected and actual values. 
+Matcher is defining the comparison operation to be performed on expected and actual values.
+Pseudo-code:
+```sql
+  ut.expect( a_actual {data-type} ).to_( {matcher} );
+  ut.expect( a_actual {data-type} ).not_to( {matcher} );
+```
+
 
 # Matchers
 utPLSQL provides following matchers to perform checks on the expected and actual values.  
@@ -33,17 +39,23 @@ utPLSQL provides following matchers to perform checks on the expected and actual
 ## be_between
 Validates that the actual value is between the lower and upper bound.
 
-Usage:
+Example:
 ```sql
-  ut.expect( a_actual {mulitple data-types} ).to_( be_between( a_lower_bound {mulitple data-types}, a_upper_bound {mulitple data-types}) );
+  exec ut.expect( a_actual => 3 ).to_( be_between( a_lower_bound => 1, a_upper_bound => 3 ) );
+  exec ut.expect( 3 ).to_( be_between( 1, 3 ) );
 ```
 
 ## be_empty
-Unary matcher that validates if the provided dataset is empty.
+Unary matcher that validates if the provided data-set is empty.
 
 Usage:
 ```sql
-  ut.expect( a_actual {mulitple data-types} ).to_( be_empty() );
+declare
+  l_cursor sys_refcursor;
+begin
+  open l_cursor for select * from dual where 1 = 0;
+  ut.expect( l_cursor ).to_( be_empty() );
+end;
 ```
 
 When used with anydata, it is only valid for collection data types.
@@ -53,39 +65,39 @@ Unary matcher that validates if the provided value is false.
 
 Usage:
 ```sql
-  ut.expect( a_actual buulean ).to_( be_false() );
+  exec ut.expect( ( 1 = 0 ) ).to_( be_false() );
 ```
 
 ## be_greater_or_equal
 Allows to check if the actual value is greater or equal than the expected.
 
 Usage:
 ```sql
-  ut.expect( a_actual {mulitple data-types} ).to_( be_greater_or_equal( a_expected {mulitple data-types}) );
+  exec ut.expect( sysdate ).to_( be_greater_or_equal( sysdate - 1 ) );
 ```
 
 ## be_greater_than
 Allows to check if the actual value is greater than the expected.
 
 Usage:
 ```sql
-  ut.expect( a_actual {mulitple data-types} ).to_( be_greater_than( a_expected {mulitple data-types}) );
+  exec ut.expect( 2 ).to_( be_greater_than( 1 ) );
 ```
 
 ## be_less_or_equal
 Allows to check if the actual value is less or equal than the expected.
 
 Usage:
 ```sql
-  ut.expect( a_actual {mulitple data-types} ).to_( be_less_or_equal( a_expected {mulitple data-types}) );
+  exec ut.expect( 3 ).to_( be_less_or_equal( 3 ) );
 ```
 
 ## be_less_than
 Allows to check if the actual value is less than the expected.
 
 Usage:
 ```sql
-  ut.expect( a_actual {mulitple data-types} ).to_( be_less_than( a_expected {mulitple data-types}) );
+  exec ut.expect( 3 ).to_( be_less_than( 2 ) );
 ```
 
 
@@ -94,7 +106,8 @@ Validates that the actual value is like the expected expression.
 
 Usage:
 ```sql
-  ut.expect( a_actual {mulitple data-types} ).to_( be_like( a_mask in varchar2, a_escape_char in varchar2 := null) );
+  exec ut.expect( 'Lorem_impsum' ).to_( be_like( a_mask => '%rem\_%', a_escape_char => '\' ) );
+  exec ut.expect( 'Lorem_impsum' ).to_( be_like( '%rem\_%', '\' ) );
 ```
 
 Parameters `a_mask` and `a_escape_char` represent a valid parameters of the [Oracle like function](https://docs.oracle.com/database/121/SQLRF/conditions007.htm#SQLRF52142)
@@ -105,15 +118,15 @@ Unary matcher that validates if the actual value is not null.
 
 Usage:
 ```sql
-  ut.expect( a_actual {mulitple data-types} ).to_( be_not_null() );
+  exec ut.expect( to_clob('ABC') ).to_( be_not_null() );
 ```
 
 ## be_null
 Unary matcher that validates if the actual value is null.
 
 Usage:
 ```sql
-  ut.expect( a_actual {mulitple data-types} ).to_( be_null() );
+  exec ut.expect( cast(null as varchar2(100)) ).to_( be_null() );
 ```
 
 ## be_true
@@ -122,7 +135,7 @@ Unary matcher that validates if the provided value is false.
 
 Usage:
 ```sql
-  ut.expect( a_actual buulean ).to_( be_false() );
+  exec ut.expect( ( 1 = 1 ) ).to_( be_true() );
 ```
 
 ## equal
@@ -134,7 +147,13 @@ This matcher is designed to capture changes of data-type, so that if you expect
 
 Usage:
 ```sql
-  ut.expect( a_actual {mulitple data-types} ).to_( equal( a_expected {mulitple data-types}, a_nulls_are_equal boolean := null) );
+declare
+  x ref_cursor;
+  y ref_cursor;
+begin
+  ut.expect( 'a dog' ).to_( equal( 'a dog' ) );
+  ut.expect( a_actual => y ).to_( equal( a_expected => x, a_nulls_are_equal => true ) );
+end;
 ```
 The `a_nulls_are_equal` parameter decides on the behavior of `null=null` comparison (**this comparison by default is true!**)
 
@@ -148,7 +167,7 @@ create or replace package demo_dept as
   -- %suite(demo)
 
   --%test(demo_dept)
-  procedure test_department 
+  procedure test_department; 
 end;
 /
 
@@ -171,7 +190,8 @@ Validates that the actual value is matching the expected regular expression.
 
 Usage:
 ```sql
-  ut.expect( a_actual {mulitple data-types} ).to_( match( a_pattern in varchar2, a_modifiers in varchar2 := null) );
+  exec ut.expect( a_actual => '123-456-ABcd' ).to_( match( a_pattern => '\d{3}-\d{3}-[a-z]', a_modifiers => 'i' ) );
+  exec ut.expect( 'some value' ).to_( match( '^some.*' ) );
 ```
 
 Parameters `a_pattern` and `a_modifiers` represent a valid regexp pattern accepted by [Oracle regexp_like function](https://docs.oracle.com/database/121/SQLRF/conditions007.htm#SQLRF00501)
@@ -205,20 +225,22 @@ Expectations provide a very convenient way to check for a negative of the expect
 
 Syntax of check for matcher evaluating to true:
 ```sql
-  ut.expect( a_actual {mulitple data-types} ).to_( {matcher} );
+  exec ut.expect( a_actual {data-type} ).to_( {matcher} );
 ```
 
 Syntax of check for matcher evaluating to false:
 ```sql
-  ut.expect( a_actual {mulitple data-types} ).not_to( {matcher} );
+  exec ut.expect( a_actual {data-type} ).not_to( {matcher} );
 ```
 
 If a matcher evaluated to NULL, then both `to_` and `not_to` will cause the expectation to report failure.
 
 Example:
 ```sql
+begin
   ut.expect( null ).to_( be_true() );
   ut.expect( null ).not_to( be_true() );
+end;
 ```
 
 Since NULL is neither true not it is not true, both expectations will report failure. 
diff --git a/docs/userguide/install.md b/docs/userguide/install.md
@@ -25,7 +25,12 @@ The installation user/schema must have the following Oracle system permissions d
   
 In addition it must be granted execute to the following system packages.
 
-  - DBMS_LOCK  
+  - DBMS_LOCK
+    
+The utPLSQL is using Oracle [DBMS_PROFILER tables](https://docs.oracle.com/cd/E18283_01/appdev.112/e16760/d_profil.htm#i999476). The tables will be created in the installation schema if they do not exist.
+The uninstall process however will not drop those tables, as they can potentially be shared and reused for profiling PLSQL code.
+It is up to DBA to maintain the storage of the profiler tables.
+
   
 # Installation Procedure
 
diff --git a/docs/userguide/reporters.md b/docs/userguide/reporters.md
@@ -71,8 +71,8 @@ Example of failure report details
 
 #Teamcity reporter
 
-[Teamcity](https://www.jetbrains.com/teamcity/) is a CI server by Jetbrains. The CI has it's own format of reporting that allows tracking of progress of a CI step/task as it executes.
-The format developed by Jetbrains is supported by utPLSQL with `ut_teamcity_reporter`.
+[Teamcity](https://www.jetbrains.com/teamcity/) is a CI server by Jetbrains. It supports XUnit reporting and additionally has it's own format of reporting that allows tracking of progress of a CI step/task as it executes.
+The TeamCity format developed by Jetbrains is supported by utPLSQL with `ut_teamcity_reporter`.
 
 Invocation of tests with Teamcity reporter.  
 
diff --git a/docs/userguide/running-unit-tests.md b/docs/userguide/running-unit-tests.md
@@ -10,7 +10,7 @@ The `run` API is designed to be called directly by developer, when using IDE/SQL
 The main benefit of using this API is it's simplicity.
 One-line call is enough to execute a set of tests form one or multiple schemes.
 
-The **procedures** execute specified tests and produces outputs to DBMS_OUTPUT suing specified reporter
+The **procedures** execute specified tests and produces outputs to DBMS_OUTPUT using specified reporter
 The **functions** can only be used in SELECT statements. They execute specified tests and produce outputs as a pipelined data stream to be consumed by select satement.
 
 ## ut.run procedures
@@ -24,43 +24,49 @@ end;
 ```
 Execute all tests in current schema (_HR_).
 
+
 ```sql
 begin
   ut.run('HR');
 end;
 ```
 Execute all tests in specified schema (_HR_).
 
+
+```sql
+begin
+  ut.run('hr:com.my_org.my_project');
+end;
+```
+
+Execute all tests from all packages that are on the _COM.MY_ORG.MY_PROJECT_ suitepath.
+Check the [annotations documentation](annotations.md) to find out about suitepaths and how they can be used to group test packages.
+
+
 ```sql
 begin
   ut.run('hr.test_apply_bonus');
 end;
 ```
 Execute all tests from package _HR.TEST_APPLY_BONUS_. 
 
+
 ```sql
 begin
   ut.run('hr.test_apply_bonus.bonus_cannot_be_negative');
 end;
 ```
 Execute single test procedure _HR.TEST_APPLY_BONUS.BONUS_CANNOT_BE_NEGATIVE_.
 
+
 ```sql
 begin
   ut.run(ut_varcahr2_list('hr.test_apply_bonus','cust'));
 end;
 ```
 Execute all tests from package _HR.TEST_APPLY_BONUS_ and all tests from schema _CUST_.
-Using a list of things to execute allows you to execute a fine-grained set of tests.
-
-```sql
-begin
-  ut.run('hr:com.my_org.my_project');
-end;
-```
+Using a list of items to execute allows you to execute a fine-grained set of tests.
 
-Execute all tests from all packages that are on the _COM.MY_ORG.MY_PROJECT_ suitepath.
-Check the [annotations documentation](annotations.md) to find out about suitepaths and how they can be used to group test packages.
 
 **Note:**
 `ut_documentation_reporter` is default reporter for all API's defined for running unit tests.
@@ -75,6 +81,7 @@ end;
 ```
 Execute all tests from package _HR.TEST_APPLY_BONUS_ and provide outputs to DBMS_OUTPUT using the XUnit reporter. 
 
+
 For details on build-in reporters look at [reporters documentation](reporters.md).
 
 ## ut.run functions
@@ -91,15 +98,15 @@ select * from table(ut.run('hr.test_apply_bonus', ut_xunit_reporter()));
 
 The `ut_runner` provides API for integrating utPLSQL with other products. Maven, Jenkins, SQL Develper, PL/SQL Developer, TOAD and others can leverage this API to call utPLSQL.
 
-The main difference as compared to `ut.run` API is that the `ut_runner.run` does not provide outputs.
+The main difference as compared to `ut.run` API is that the `ut_runner.run` does not print outputs to the screen.
 
 `ut_runner.run` accepts multiple reporters. Each reporter produces outputs into a separate output (uniquely identified by output_id).
 Outputs of multiple reporters can be consumed in parallel. This allows for live reporting of test execution progress with threads and several database sessions.
 
 The concept is pretty simple.
 
-- in main thread (session), define the reporters to be used. Each reporter has it's output_id and so you need to extract and store those output_id's.
+- in the main thread (session), define the reporters to be used. Each reporter has it's output_id and so you need to extract and store those output_id's.
 - as a separate thread, start the `ut_runner.run` and pass reporters with previously defined output_id's
 - for each reporter start a separate thread and read outputs from `ut_output_buffer.get_lines` table function by providing the output_id defined in the main thread.
 
-
+`ut_runner.run` is internally used by the [`ut_run.sql` script](ut_run-script.md) which is a utility for running tests with multiple reporters and provides parameters to save reporters results into individual files on the local file system.  
