Deploy to gh-pages branch: base commit 02bf59985086e94732b9d5e5cd8b03f05f8c8040

github-actions[bot] · github-actions[bot] · commit b11f80dccbcf · 2022-02-06T14:53:03.000Z
diff --git a/utPLSQL/develop/about/authors.md b/utPLSQL/develop/about/authors.md
@@ -1,4 +1,4 @@
-![version](https://img.shields.io/badge/version-v3.1.12.3742--develop-blue.svg)
+![version](https://img.shields.io/badge/version-v3.1.12.3791--develop-blue.svg)
 
 ### utPLSQL v3 Major Contributors 
 
diff --git a/utPLSQL/develop/about/license.md b/utPLSQL/develop/about/license.md
@@ -1,4 +1,4 @@
-![version](https://img.shields.io/badge/version-v3.1.12.3742--develop-blue.svg)
+![version](https://img.shields.io/badge/version-v3.1.12.3791--develop-blue.svg)
 
 # Version Information
 
diff --git a/utPLSQL/develop/about/project-details.md b/utPLSQL/develop/about/project-details.md
@@ -1,4 +1,4 @@
-![version](https://img.shields.io/badge/version-v3.1.12.3742--develop-blue.svg)
+![version](https://img.shields.io/badge/version-v3.1.12.3791--develop-blue.svg)
 
 # utPLSQL Project Details
 
diff --git a/utPLSQL/develop/about/support.md b/utPLSQL/develop/about/support.md
@@ -1,4 +1,4 @@
-![version](https://img.shields.io/badge/version-v3.1.12.3742--develop-blue.svg)
+![version](https://img.shields.io/badge/version-v3.1.12.3791--develop-blue.svg)
 
 # How to get support
 
diff --git a/utPLSQL/develop/index.md b/utPLSQL/develop/index.md
@@ -1,4 +1,4 @@
-![version](https://img.shields.io/badge/version-v3.1.12.3742--develop-blue.svg)
+![version](https://img.shields.io/badge/version-v3.1.12.3791--develop-blue.svg)
 
 # Introduction to utPLSQL
 
diff --git a/utPLSQL/develop/userguide/advanced_data_comparison.md b/utPLSQL/develop/userguide/advanced_data_comparison.md
@@ -1,4 +1,4 @@
-![version](https://img.shields.io/badge/version-v3.1.12.3742--develop-blue.svg)
+![version](https://img.shields.io/badge/version-v3.1.12.3791--develop-blue.svg)
 
 # Advanced data comparison
 
diff --git a/utPLSQL/develop/userguide/annotations.md b/utPLSQL/develop/userguide/annotations.md
@@ -1,4 +1,4 @@
-![version](https://img.shields.io/badge/version-v3.1.12.3742--develop-blue.svg)
+![version](https://img.shields.io/badge/version-v3.1.12.3791--develop-blue.svg)
 
 # Annotations
 
diff --git a/utPLSQL/develop/userguide/best-practices.md b/utPLSQL/develop/userguide/best-practices.md
@@ -1,4 +1,4 @@
-![version](https://img.shields.io/badge/version-v3.1.12.3742--develop-blue.svg)
+![version](https://img.shields.io/badge/version-v3.1.12.3791--develop-blue.svg)
 
 # Best Practices
 
diff --git a/utPLSQL/develop/userguide/coverage.md b/utPLSQL/develop/userguide/coverage.md
@@ -1,4 +1,4 @@
-![version](https://img.shields.io/badge/version-v3.1.12.3742--develop-blue.svg)
+![version](https://img.shields.io/badge/version-v3.1.12.3791--develop-blue.svg)
 
 # Coverage
 utPLSQL comes with a built-in coverage reporting engine. The code coverage reporting uses DBMS_PROFILER package provided with Oracle database.
diff --git a/utPLSQL/develop/userguide/exception-reporting.md b/utPLSQL/develop/userguide/exception-reporting.md
@@ -1,4 +1,4 @@
-![version](https://img.shields.io/badge/version-v3.1.12.3742--develop-blue.svg)
+![version](https://img.shields.io/badge/version-v3.1.12.3791--develop-blue.svg)
 
 # Exception handling and reporting
 
diff --git a/utPLSQL/develop/userguide/expectations.md b/utPLSQL/develop/userguide/expectations.md
@@ -1,4 +1,4 @@
-![version](https://img.shields.io/badge/version-v3.1.12.3742--develop-blue.svg)
+![version](https://img.shields.io/badge/version-v3.1.12.3791--develop-blue.svg)
 
 # Expectation 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.
@@ -316,24 +316,25 @@ Since NULL is neither *true* nor *false*, both expectations will report failure.
 
 The matrix below illustrates the data types supported by different matchers.
 
-|         Matcher         | blob | boolean | clob | date | number | timestamp | timestamp<br>with<br>timezone | timestamp<br>with<br>local<br>timezone | varchar2 | interval<br>year<br>to<br>month | interval<br>day<br>to<br>second | cursor | nested<br>table<br>/ varray | object | json |
-| :---------------------: | :--: | :-----: | :--: | :--: | :----: | :-------: | :---------------------------: | :------------------------------------: | :------: | :-----------------------------: | :-----------------------------: | :----: | :-------------------------: | :----: | :--: |
-|     **be_not_null**     |  X   |    X    |  X   |  X   |   X    |     X     |               X               |                   X                    |    X     |                X                |                X                |   X    |              X              |   X    |  X   |
-|       **be_null**       |  X   |    X    |  X   |  X   |   X    |     X     |               X               |                   X                    |    X     |                X                |                X                |   X    |              X              |   X    |  X   |
-|      **be_false**       |      |    X    |      |      |        |           |                               |                                        |          |                                 |                                 |        |                             |        |      |
-|       **be_true**       |      |    X    |      |      |        |           |                               |                                        |          |                                 |                                 |        |                             |        |      |
-|   **be_greater_than**   |      |         |      |  X   |   X    |     X     |               X               |                   X                    |          |                X                |                X                |        |                             |        |      |
-| **be_greater_or_equal** |      |         |      |  X   |   X    |     X     |               X               |                   X                    |          |                X                |                X                |        |                             |        |      |
-|  **be_less_or_equal**   |      |         |      |  X   |   X    |     X     |               X               |                   X                    |          |                X                |                X                |        |                             |        |      |
-|    **be_less_than**     |      |         |      |  X   |   X    |     X     |               X               |                   X                    |          |                X                |                X                |        |                             |        |      |
-|     **be_between**      |      |         |      |  X   |   X    |     X     |               X               |                   X                    |    X     |                X                |                X                |        |                             |        |      |
-|        **equal**        |  X   |    X    |  X   |  X   |   X    |     X     |               X               |                   X                    |    X     |                X                |                X                |   X    |              X              |   X    |  X   |
-|       **contain**       |      |         |      |      |        |           |                               |                                        |          |                                 |                                 |   X    |              X              |   X    |      |
-|        **match**        |      |         |  X   |      |        |           |                               |                                        |    X     |                                 |                                 |        |                             |        |      |
-|       **be_like**       |      |         |  X   |      |        |           |                               |                                        |    X     |                                 |                                 |        |                             |        |      |
-|      **be_empty**       |  X   |         |  X   |      |        |           |                               |                                        |          |                                 |                                 |   X    |              X              |        |  X   |
-|     **have_count**      |      |         |      |      |        |           |                               |                                        |          |                                 |                                 |   X    |              X              |        |  X   |
-
+|         Matcher           | blob | boolean | clob | date | number | timestamp | timestamp<br>with<br>timezone | timestamp<br>with<br>local<br>timezone | varchar2 | interval<br>year<br>to<br>month | interval<br>day<br>to<br>second | cursor | nested<br>table<br>/ varray | object | json |
+| :-----------------------: | :--: | :-----: | :--: | :--: | :----: | :-------: | :---------------------------: | :------------------------------------: | :------: | :-----------------------------: | :-----------------------------: | :----: | :-------------------------: | :----: | :--: |
+|     **be_not_null**       |  X   |    X    |  X   |  X   |   X    |     X     |               X               |                   X                    |    X     |                X                |                X                |   X    |              X              |   X    |  X   |
+|       **be_null**         |  X   |    X    |  X   |  X   |   X    |     X     |               X               |                   X                    |    X     |                X                |                X                |   X    |              X              |   X    |  X   |
+|      **be_false**         |      |    X    |      |      |        |           |                               |                                        |          |                                 |                                 |        |                             |        |      |
+|       **be_true**         |      |    X    |      |      |        |           |                               |                                        |          |                                 |                                 |        |                             |        |      |
+|   **be_greater_than**     |      |         |      |  X   |   X    |     X     |               X               |                   X                    |          |                X                |                X                |        |                             |        |      |
+| **be_greater_or_equal**   |      |         |      |  X   |   X    |     X     |               X               |                   X                    |          |                X                |                X                |        |                             |        |      |
+|  **be_less_or_equal**     |      |         |      |  X   |   X    |     X     |               X               |                   X                    |          |                X                |                X                |        |                             |        |      |
+|    **be_less_than**       |      |         |      |  X   |   X    |     X     |               X               |                   X                    |          |                X                |                X                |        |                             |        |      |
+|     **be_between**        |      |         |      |  X   |   X    |     X     |               X               |                   X                    |    X     |                X                |                X                |        |                             |        |      |
+|        **equal**          |  X   |    X    |  X   |  X   |   X    |     X     |               X               |                   X                    |    X     |                X                |                X                |   X    |              X              |   X    |  X   |
+|       **contain**         |      |         |      |      |        |           |                               |                                        |          |                                 |                                 |   X    |              X              |   X    |      |
+|        **match**          |      |         |  X   |      |        |           |                               |                                        |    X     |                                 |                                 |        |                             |        |      |
+|       **be_like**         |      |         |  X   |      |        |           |                               |                                        |    X     |                                 |                                 |        |                             |        |      |
+|      **be_empty**         |  X   |         |  X   |      |        |           |                               |                                        |          |                                 |                                 |   X    |              X              |        |  X   |
+|     **have_count**        |      |         |      |      |        |           |                               |                                        |          |                                 |                                 |   X    |              X              |        |  X   |
+| **be_within().of_()**     |      |         |      |   X  |   X    |    X      |               X               |                   X                    |          |                                 |                                 |        |                             |        |      |
+| **be_within_pct().of_()** |      |         |      |      |   X    |           |                               |                                        |          |                                 |                                 |        |                             |        |      |              
 
 # Expecting exceptions
 
@@ -1093,6 +1094,111 @@ SUCCESS
       <ROW><UT_VARCHAR2_LIST>D</UT_VARCHAR2_LIST></ROW><ROW><UT_VARCHAR2_LIST>E</UT_VARCHAR2_LIST></ROW><ROW><UT_VARCHAR2_LIST>F</UT_VARCHAR2_LIST></ROW>
 ```
 
+## to_be_within of
+
+Determines wheter expected value is within range (tolerance) from another value.
+
+The logical formual used for calcuating the matcher is: 
+```
+    result := ( abs( expected - actual ) <= distance )
+```
+The actual formula used for calculation is more complex to handle different data-types of expected/actual values as well as differnet types of distance value.
+The matcher will fail if the `expected` and `actual` are more than `distance` apart from each other.
+The matcher will fail if the dataypes of `expected` and `actual` are not the same.
+
+The matcher works with data-types: `number`, `date`, `timestamp`, `timestamp with time zone`, `timestamp with local time zone`
+The data-types of compared values must match exactly and if type does not match, the expectation will fail. 
+
+|  expected/actual<br>data-type  |   distance data-type   |  
+|:------------------------------:|:----------------------:|
+|             number             |         number         |
+|              date              | interval day to second |
+|              date              | interval year to month |
+|           timestamp            | interval day to second |
+|           timestamp            | interval year to month |
+|    timestamp with time zone    | interval day to second |  
+|    timestamp with time zone    | interval year to month |  
+| timestamp with local time zone | interval day to second |  
+| timestamp with local time zone | interval year to month |  
+
+
+The distance must be expressed as a non-negative number or non-negative interval.
+
+>Note:
+> Interval year-to-moth as a distance is giving sucess if the distance between the given dates/timestamps evaluates to value less or equal of the specified interval
+> Keep in mind that a checking for distance of `interval '0-1' year to month` will actuall be successful if the distance is less than a month and 15 days.
+> This is due to how oracle evaluates conversion between timestamp difference converted to `year to month interval`. 
+> The behavior is similar to a call to `months_between()` function with results rounded to full monts ie. round(months_between(date, date))
+
+**Example 1.**
+```sql
+begin
+  ut.expect(3).to_be_within(1).of_(4);
+end;
+/
+```
+
+**Example 2.**
+```sql
+begin
+  ut.expect(3).to_be_within(1).of_(5);
+end;
+/
+```
+
+Returns following output via DBMS_OUTPUT:
+```
+Failures:
+ 
+  1) wihtin_test
+      Actual: 3 (number) was expected to be within 1 of 5 (number)
+      at "UT3_DEVELOP.UT_BE_WITHIN.OF_", line 48 l_result.expectation.to_(l_result );        
+      at "UT3_DEVELOP.TEST_BETWNSTR.WIHTIN_TEST", line 5
+```
+
+**Example 3.**
+```sql
+begin
+  ut.expect(sysdate).to_be_within(interval '1' day).of_(sysdate+2);
+end;
+/
+```
+
+Returns following output via DBMS_OUTPUT:
+```
+Failures:
+ 
+  1) wihtin_test
+      Actual: 2020-06-07T13:32:58 (date) was expected to be within 1 day of 2020-06-09T13:32:58 (date)
+      at "UT3_DEVELOP.UT_BE_WITHIN.OF_", line 55 l_result.expectation.to_(l_result );    
+      at "UT3_DEVELOP.TEST_BETWNSTR.WIHTIN_TEST", line 5
+```
+
+
+## to_be_within_pct of
+
+Determines wheter actual value is within percentage range of expected value. 
+The matcher only works with `number` data-type.
+
+The percentage deviation (distance) must be expressed as a non-negative number.
+The formula used for calcuation of expectation is:
+```
+  result := ( ( distance ) * expected >= abs( expected - actual ) * 100 ) 
+```
+
+**Example 1.**
+```sql
+begin
+  ut.expect(9).to_be_within_pct(10).of_(10);
+end;
+/
+```
+
+```
+SUCCESS
+  Actual: 9 (number) was expected to be within 10 % of 10 (number)
+```
+
 
 ## Comparing cursors, object types, nested tables and varrays 
 
diff --git a/utPLSQL/develop/userguide/getting-started.md b/utPLSQL/develop/userguide/getting-started.md
@@ -1,4 +1,4 @@
-![version](https://img.shields.io/badge/version-v3.1.12.3742--develop-blue.svg)
+![version](https://img.shields.io/badge/version-v3.1.12.3791--develop-blue.svg)
 
 # Getting started with TDD and utPLSQL
 
diff --git a/utPLSQL/develop/userguide/install.md b/utPLSQL/develop/userguide/install.md
@@ -1,4 +1,4 @@
-![version](https://img.shields.io/badge/version-v3.1.12.3742--develop-blue.svg)
+![version](https://img.shields.io/badge/version-v3.1.12.3791--develop-blue.svg)
 
 # Supported database versions
 
diff --git a/utPLSQL/develop/userguide/querying_suites.md b/utPLSQL/develop/userguide/querying_suites.md
@@ -1,4 +1,4 @@
-![version](https://img.shields.io/badge/version-v3.1.12.3742--develop-blue.svg)
+![version](https://img.shields.io/badge/version-v3.1.12.3791--develop-blue.svg)
 
 # Qyerying for test suites
 
diff --git a/utPLSQL/develop/userguide/reporters.md b/utPLSQL/develop/userguide/reporters.md
@@ -1,4 +1,4 @@
-![version](https://img.shields.io/badge/version-v3.1.12.3742--develop-blue.svg)
+![version](https://img.shields.io/badge/version-v3.1.12.3791--develop-blue.svg)
 
 utPLSQL provides the following reporting formats.
 
diff --git a/utPLSQL/develop/userguide/running-unit-tests.md b/utPLSQL/develop/userguide/running-unit-tests.md
@@ -1,4 +1,4 @@
-![version](https://img.shields.io/badge/version-v3.1.12.3742--develop-blue.svg)
+![version](https://img.shields.io/badge/version-v3.1.12.3791--develop-blue.svg)
 
 # Running tests
 
diff --git a/utPLSQL/develop/userguide/upgrade.md b/utPLSQL/develop/userguide/upgrade.md
@@ -1,4 +1,4 @@
-![version](https://img.shields.io/badge/version-v3.1.12.3742--develop-blue.svg)
+![version](https://img.shields.io/badge/version-v3.1.12.3791--develop-blue.svg)
 
 # Upgrading from version 2
 
diff --git a/utPLSQL/index.md b/utPLSQL/index.md
@@ -5,7 +5,7 @@ layout: default
 # Documentation
 
  - [Latest v3.1.11 documentation](latest/) - Created 17 Nov 2021 - 11:42:00 PM
- - [Latest development version](develop/) - Created 29 Jan 2022 - 09:14:58 PM
+ - [Latest development version](develop/) - Created 06 Feb 2022 - 02:53:02 PM
 
 ## Documentation release history
 

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-![version](https://img.shields.io/badge/version-v3.1.12.3742--develop-blue.svg)`
	`1`	`+![version](https://img.shields.io/badge/version-v3.1.12.3791--develop-blue.svg)`
`2`	`2`
`3`	`3`	`### utPLSQL v3 Major Contributors`
`4`	`4`