Merge branch 'develop' into feature/color_reporter

Pazus · web-flow · commit f227f1769f7f · 2017-01-20T08:23:27.000+03:00
diff --git a/.travis/create_release_archive.sh b/.travis/create_release_archive.sh
@@ -12,6 +12,7 @@ mkdir release/source
 # Copy files to various directories
 cp -r docs release/docs/markdown
 cp -r site release/docs/html 
+cp -r client_source release/client_source
 cp -r source release/source
 cp -r examples release/examples
 cp -r readme.md release/ 
diff --git a/docs/userguide/annotations.md b/docs/userguide/annotations.md
@@ -5,8 +5,15 @@ The annotation list is based on moder testing framework such as jUnit 5, RSpec.
 
 Annotations allow to configure test infrastructure in a declarative way without anything stored in tables or config files. The framework runner scans the schema for all the suitable annotated packages, automatically configures suites, forms hierarchy from then and executes them.
 
-# Example of annotated package
-```
+Annotations are case-insensitive. But it is recommended to use the lower-case standard as described in the documentation.
+
+Annotation on procedure level must be placed directly before the procedure name.
+
+Annotation `-- %suite` should be placed at the beginning of package specification. It is not required but highly recommended as a practice.
+
+# Example of annotated test package
+
+```sql
 create or replace package test_pkg is
 
   -- %suite(Name of suite)
@@ -51,19 +58,19 @@ create or replace package test_pkg is
 end test_pkg;
 ```
 
-#Annotations meaning
+#Annotations description
 
-| Annotation |Level| Describtion |
+| Annotation |Level| Description |
 | --- | --- | --- |
 | `%suite(<description>)` | Package | Marks package to be a suite of tests This way all testing packages might be found in a schema. Optional schema discription can by provided, similar to `%displayname` annotation. |
-| `%suitepath(<path>)` | Package | Similar to java package. The annotation allows logical grouping of suites into hierarcies. |
-| `%displayname(<description>)` | Package/procedure | Human-familiar describtion of the suite/test. Syntax is based on jUnit annotation: `%displayname(Name of the suite/test)` |
-| `%test(<description>)` | Procedure | Denotes that a method is a test method.  Optional test discription can by provided, similar to `%displayname` annotation. |
+| `%suitepath(<path>)` | Package | Similar to java package. The annotation allows logical grouping of suites into hierarchies. |
+| `%displayname(<description>)` | Package/procedure | Human-familiar description of the suite/test. Syntax is based on jUnit annotation: `%displayname(Name of the suite/test)` |
+| `%test(<description>)` | Procedure | Denotes that a method is a test method.  Optional test description can by provided, similar to `%displayname` annotation. |
 | `%beforeall` | Procedure | Denotes that the annotated procedure should be executed once before all elements of the current suite. |
 | `%afterall` | Procedure | Denotes that the annotated procedure should be executed once after all elements of the current suite. |
 | `%beforeeach` | Procedure | Denotes that the annotated procedure should be executed before each `%test` method in the current suite. |
 | `%aftereach` | Procedure | Denotes that the annotated procedure should be executed after each `%test` method in the current 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 | Configure transaction control behaviour (type). Supported values: `auto`(default) - rollback to savepoint (before the test/suite setup) is issued after each test/suite teardown; `manual` - rollback is never issued automatically. Property can be overridden for child element (test in suite) |
-| `%disable` | Package/procedure | Used to disable a suite or a test |
+| `%disable` | Package/procedure | Used to disable a suite or a test |
diff --git a/docs/userguide/assertions.md b/docs/userguide/assertions.md
diff --git a/docs/userguide/expectations.md b/docs/userguide/expectations.md
@@ -0,0 +1,78 @@
+# Concept of expectation and matcher 
+
+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.
+
+It's best to give an example to get an idea what is what
+```sql
+begin
+  ut.expect( 'the tested value' ).to_( equal('the expected value') );
+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. 
+
+# 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`
+- `be_between`
+
+## match
+Allows regexp_like validations to be executed against the following datatypes:
+- `clob`
+- `varchar2`
+
+Usage:
+```sql
+  ut.expect( a_actual ).to_( match( a_pattern in varchar2, a_modifiers in varchar2 := null) )
+```
+
+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)
+
+## equal
+
+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) )
+```
+
+
+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`
+
+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. 
+
+
+TODO: Finish Expectations concepts 
diff --git a/examples/between_string/test_betwnstr.pkg b/examples/between_string/test_betwnstr.pkg
@@ -1,38 +1,32 @@
 create or replace package test_betwnstr as
 
-  -- %suite
-  -- %displayname(Between string function)
+  -- %suite(Between string function)
 
-  -- %test
-  -- %displayname(Returns substring from start position to end position)
+  -- %test(Returns substring from start position to end position)
   procedure normal_case;
 
-  -- %test
-  -- %displayname(Returns substring when start position is zero)
+  -- %test(Returns substring when start position is zero)
   procedure zero_start_position;
 
-  -- %test
-  -- %displayname(Returns string until end if end position is greated than string length)
+  -- %test(Returns string until end if end position is greater than string length)
   procedure big_end_position;
 
-  -- %test
-  -- %displayname(Returns null for null inlut srting value)
+  -- %test(Returns null for null input string value)
   procedure null_string;
 end;
 /
 create or replace package body test_betwnstr as
 
   procedure normal_case is
   begin
-    ut.expect( betwnstr( '1234567', 2, 5 ) ).to_( equal('2345') );
+    ut.expect( betwnstr( '1234567', 2, 5 ) ).to_equal('2345');
   end;
 
   procedure zero_start_position is
   begin
     ut.expect( betwnstr( '1234567', 0, 5 ) ).to_( equal('12345') );
   end;
 
-
   procedure big_end_position is
   begin
     ut.expect( betwnstr( '1234567', 0, 500 ) ).to_( equal('1234567') );
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -6,6 +6,7 @@ site_description: utPLSQL Documenation Powerful Unit Testing Framework for Oracl
 copyright: Copyright &copy; 2016 - utPLSQL Team
 repo_url: https://github.com/utplsql/utplsql/
 theme: mkdocs
+use_directory_urls: false
 strict: true
 
 pages:
@@ -14,7 +15,7 @@ pages:
        - Installation: userguide/install.md
        - Getting Started: userguide/getting-started.md
        - Annotations: userguide/annotations.md
-       - Assertions: userguide/assertions.md
+       - Expectations: userguide/expectations.md
        - Testing Best Pracitces: userguide/best-practices.md
        - Upgrade utPLSQL : userguide/upgrade.md
   - About:
diff --git a/readme.md b/readme.md
