utPLSQL · Pazus · Mar 21, 2017 · Mar 12, 2017 · Mar 12, 2017 · Mar 12, 2017
diff --git a/CONTRIBUTING.md → docs/about/CONTRIBUTING.md b/CONTRIBUTING.md → docs/about/CONTRIBUTING.md
diff --git a/authors.md → docs/about/authors.md b/authors.md → docs/about/authors.md
diff --git a/docs/about/project-details.md b/docs/about/project-details.md
@@ -8,8 +8,7 @@
 
 utPLSQL is hosted on [hosted on GitHub](https://github.com/utPLSQL/utPLSQL) and open source project.
 
-Community help on this project is always appreciated, if your interested in helping please read our [guide to contributing](https://github.com/utPLSQL/utPLSQL/blob/master/CONTRIBUTING.md)
+Community help on this project is always appreciated, if your interested in helping please read our [guide to contributing](CONTRIBUTING.md)
 
 
 
-
diff --git a/docs/images/3_steps_to_run_utPLSQL.gif b/docs/images/3_steps_to_run_utPLSQL.gif
diff --git a/...serguide/images/coverage_html_details.png → docs/images/coverage_html_details.png b/...serguide/images/coverage_html_details.png → docs/images/coverage_html_details.png
diff --git a/...serguide/images/coverage_html_summary.png → docs/images/coverage_html_summary.png b/...serguide/images/coverage_html_summary.png → docs/images/coverage_html_summary.png
diff --git a/docs/images/documentation_reporter.png b/docs/images/documentation_reporter.png
diff --git a/docs/images/documentation_reporter_color.png b/docs/images/documentation_reporter_color.png
diff --git a/docs/images/running_from_command_line.gif b/docs/images/running_from_command_line.gif
diff --git a/docs/images/running_with_coverage_line.gif b/docs/images/running_with_coverage_line.gif
diff --git a/docs/images/teamcity_report_example.png b/docs/images/teamcity_report_example.png
diff --git a/docs/images/teamcity_report_example_errors.png b/docs/images/teamcity_report_example_errors.png
diff --git a/docs/images/xunit_reporter_jenkins.png b/docs/images/xunit_reporter_jenkins.png
diff --git a/docs/images/xunit_reporter_jenkins_errors.png b/docs/images/xunit_reporter_jenkins_errors.png
diff --git a/docs/index.md b/docs/index.md
@@ -1,11 +1,56 @@
 # Introduction to utPLSQL
 
- utPLSQL is a powerful unit testing library for Oracle PL/SQL.
+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/)
 
- TODO: Sales pitch of utPLSQL with links to documentation areas that support discussed features.
+  - 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)
 
- TODO: Table of Contents / Index of the docs
 
+#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 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.  
+
+
+# Command line 
+The `ut_run.sql` script is a powerful thing - it can provide output from the tests on the fly.
+You can also use it to have coloured output from the test, and if you try to test code that was dropper, all of unit tests related to that code will fail.
+
+![colors_and_failures](images/running_from_command_line.gif)
+
+Look into [ut_run.sql script options](userguide/ut_run-script.md) to see more.
+
+# Coverage
+If you want to have code coverage gathered on your code , it's best to use `ut_run.sql` to execute your tests with multiple reporters and have both test execution report as well as coverage report saved to a file.
+Check out the [coverage documentation](userguide/coverage.md) for options of coverage reporting
+
+![coverage](images/running_with_coverage_line.gif)
 
 
 

diff --git a/docs/userguide/coverage.md b/docs/userguide/coverage.md
@@ -44,11 +44,11 @@ The `ut_coverage_html_reporter` will produce a interactive HTML report. You may
 
 The report provides a summary information with list of source code that was expected to be covered.
 
-![Coverage Summary page](images/coverage_html_summary.png)
+![Coverage Summary page](../images/coverage_html_summary.png)
 
 The report allow to navigate to every source and inspect line by line coverage.
 
-![Coverage Details page](images/coverage_html_details.png)
+![Coverage Details page](../images/coverage_html_details.png)
 
 
 ##Coverage reporting options

diff --git a/docs/userguide/expectations.md b/docs/userguide/expectations.md
@@ -1,4 +1,4 @@
-# Concept of expectation and matcher 
+# Concepts 
 
 Validation of the code under test (the tested logic of procedure/function etc.) is performed by comparing the actual data against the expected data.
 To do that we use concept of expectation and a matcher to perform the check on the data.
@@ -12,68 +12,237 @@ 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} );
+```
 
-# List of currently build-in matchers
-- `match`
-- `equal`
-- `be_true`
-- `be_null`
-- `be_not_null`
-- `be_like`
-- `be_less_than`
-- `be_less_or_equal`
-- `be_greater_than`
-- `be_greater_or_equal`
-- `be_false`
+
+# Matchers
+utPLSQL provides following matchers to perform checks on the expected and actual values.  
 - `be_between`
 - `be_empty`
+- `be_false`
+- `be_greater_than`
+- `be_greater_or_equal`
+- `be_less_or_equal`
+- `be_less_than`
+- `be_like`
+- `be_not_null`
+- `be_null`
+- `be_true`
+- `equal`
+- `match`
 
-## match
-Allows regexp_like validations to be executed against the following datatypes:
-- `clob`
-- `varchar2`
+## be_between
+Validates that the actual value is between the lower and upper bound.
+
+Example:
+```sql
+  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 data-set is empty.
+
+Usage:
+```sql
+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.
+
+## be_false
+Unary matcher that validates if the provided value is false.
+
+Usage:
+```sql
+  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
+  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
+  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
+  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 ).to_( match( a_pattern in varchar2, a_modifiers in varchar2 := null) )
+  exec ut.expect( 3 ).to_( be_less_than( 2 ) );
 ```
 
-Parameters `a_pattern` and `a_modifiers` represent a valid regexp pattern accepted by [Oracle regexp_like function](http://docs.oracle.com/database/121/SQLRF/conditions007.htm#SQLRF00501)
+
+## be_like
+Validates that the actual value is like the expected expression.
+
+Usage:
+```sql
+  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)
+
+
+## be_not_null
+Unary matcher that validates if the actual value is not null.
+
+Usage:
+```sql
+  exec ut.expect( to_clob('ABC') ).to_( be_not_null() );
+```
+
+## be_null
+Unary matcher that validates if the actual value is null.
+
+Usage:
+```sql
+  exec ut.expect( cast(null as varchar2(100)) ).to_( be_null() );
+```
+
+## be_true
+Unary matcher that validates if the provided value is false.
+- `boolean`
+
+Usage:
+```sql
+  exec ut.expect( ( 1 = 1 ) ).to_( be_true() );
+```
 
 ## equal
 
-The equal matcher is a very restrictive matcher.
-It only returns true, if compared data-types.
+The equal matcher is a very restrictive matcher. It only returns true, if compared data-types.
 That means, that comparing varchar2 to a number will fail even if the varchar2 contains the same number.
 This matcher is designed to capture changes of data-type, so that if you expect your variable to be number and is now something else,
  the test will fail and give you early indication of potential problem.
 
 Usage:
 ```sql
-  ut.expect( a_actual ).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!**)
 
+The `anydata` data type is used to compare user defined object and collections.
+
+Example usage of anydata to compare user defined types.
+```sql
+create type department as object(name varchar2(30));
+/
+create or replace package demo_dept as 
+  -- %suite(demo)
 
-The equal matcher accepts a_expected of following data-types.
-- `anydata`
-- `blob`
-- `boolean`
-- `clob`
-- `date`
-- `number`
-- `sys_refcursor`
-- `timestamp_unconstrained`
-- `timestamp_tz_unconstrained`
-- `timestamp_ltz_unconstrained`
-- `varchar2`
-- `yminterval_unconstrained`
-- `dsinterval_unconstrained`
+  --%test(demo_dept)
+  procedure test_department; 
+end;
+/
+
+create or replace package body demo_dept as 
+  procedure test_department is
+    v_expected department;
+    v_actual   department;
+  begin
+    v_expected := department('HR');
+    ut.expect( anydata.convertObject(v_expected) ).to_( equal( anydata.convertObject(v_actual) ) );
+  end;
+end;
+/
+```
+
+This test will fail as the `v_acutal` is not equal `v_expected`. 
+
+## match
+Validates that the actual value is matching the expected regular expression.
+
+Usage:
+```sql
+  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)
+
+
+
+# Supported data types
+
+Below matrix illustrates the data types supported by different matchers.
+
+|                               | be_between | be_empty | be_false | be_greater_than | be_greater_or_equal | be_less_or_equal | be_less_than | be_like | be_not_null | be_null | be_true | equal | match |
+|:------------------------------|:----------:|:--------:|:--------:|:---------------:|:-------------------:|:----------------:|:------------:|:-------:|:-----------:|:-------:|:-------:|:-----:|:-----:|
+| anydata                       |            |    X     |          |                 |                     |                  |              |         |     X       |   X     |         |   X   |       |
+| blob                          |            |          |          |                 |                     |                  |              |         |     X       |   X     |         |   X   |       |
+| boolean                       |            |          |    X     |                 |                     |                  |              |         |     X       |   X     |    X    |   X   |       |
+| clob                          |            |          |          |                 |                     |                  |              |   X     |     X       |   X     |         |   X   |   X   |
+| date                          |    X       |          |          |       X         |         X           |      X           |     X        |         |     X       |   X     |         |   X   |       |
+| number                        |    X       |          |          |       X         |         X           |      X           |     X        |         |     X       |   X     |         |   X   |       |
+| refcursor                     |            |    X     |          |                 |                     |                  |              |         |     X       |   X     |         |   X   |       |
+| timestamp                     |    X       |          |          |       X         |         X           |      X           |     X        |         |     X       |   X     |         |   X   |       |
+| timestamp with timezone       |    X       |          |          |       X         |         X           |      X           |     X        |         |     X       |   X     |         |   X   |       |
+| timestamp with local timezone |    X       |          |          |       X         |         X           |      X           |     X        |         |     X       |   X     |         |   X   |       |
+| varchar2                      |    X       |          |          |                 |                     |                  |              |   X     |     X       |   X     |         |   X   |   X   |
+| interval year to month        |    X       |          |          |       X         |         X           |      X           |     X        |         |     X       |   X     |         |   X   |       |
+| interval day to second        |    X       |          |          |       X         |         X           |      X           |     X        |         |     X       |   X     |         |   X   |       |
 
-The second parameter decides on the behavior of `null=null` comparison (**this comparison by default is true!**)
-
 
-  A test procedure will contain one or more checks to verify the the test performed as expected.   These checks are called assertion.   utPLSQL provides a robust and extensible assertion library. 
+
+# Negating the matcher
+Expectations provide a very convenient way to check for a negative of the expectation.
+
+Syntax of check for matcher evaluating to true:
+```sql
+  exec ut.expect( a_actual {data-type} ).to_( {matcher} );
+```
+
+Syntax of check for matcher evaluating to false:
+```sql
+  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. 
 
 
-TODO: Finish Expectations concepts 
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
Original file line number	Diff line number	Diff line change
Expand Up		@@ -8,8 +8,7 @@

		utPLSQL is hosted on [hosted on GitHub](https://github.com/utPLSQL/utPLSQL) and open source project.

		Community help on this project is always appreciated, if your interested in helping please read our [guide to contributing](https://github.com/utPLSQL/utPLSQL/blob/master/CONTRIBUTING.md)
		Community help on this project is always appreciated, if your interested in helping please read our [guide to contributing](CONTRIBUTING.md)