jgebal · Feb 4, 2022 · Jun 1, 2020 · Jun 2, 2020 · Jun 2, 2020 · Jun 2, 2020
diff --git a/docs/userguide/expectations.md b/docs/userguide/expectations.md
@@ -333,6 +333,7 @@ The matrix below illustrates the data types supported by different matchers.
 |       **be_like**       |      |         |  X   |      |        |           |                               |                                        |    X     |                                 |                                 |        |                             |        |      |
 |      **be_empty**       |  X   |         |  X   |      |        |           |                               |                                        |          |                                 |                                 |   X    |              X              |        |  X   |
 |     **have_count**      |      |         |      |      |        |           |                               |                                        |          |                                 |                                 |   X    |              X              |        |  X   |
+| **be_within().of_()**   |      |         |      |   x  |   x    |           |                               |                                        |          |                                 |                                 |   X    |              X              |        |  X   |
 
 
 # Expecting exceptions
@@ -1093,6 +1094,87 @@ 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
+
+This matcher is created to determine wheter expected value is approximately equal or "close" to another value.
+
+Matcher will allow to compare numbers as well as dates. 
+
+When comparing a number the tolerance / distance can be expressed as another postive number or a percentage.
+
+When comparing a two dates tolerance can be expressed in interval time either Day-To-Second or Year-To-Month.
+
+Matcher for numbers will calculate a absolute distance between expected and actual and check whether that value is within a tolerance.
+
+When comparing a date a distance is measured in interval, the check is done that actual value is within date range of expected taking into account interval plus and minus.
+
+**Example 1.**
+```sql
+begin
+  ut.expect(3).to_be_within(1).of_(4);
+end;
+/
+```
+
+**Example 2.**
+```sql
+begin
+  ut.expect(9).to_be_within_pct(10).of_(10);
+end;
+/
+```
+
+**Example 3.**
+```sql
+begin
+  ut.expect(sysdate).to_be_within_pct(interval '1' day).of_(sysdate + 1);
+end;
+/
+```
+
+**Example 4.**
+```sql
+begin
+  ut.expect(sysdate).to_be_within_pct(interval '1' month).of_(add_months(sysdate,1));
+end;
+/
+```
+
+**Example 5.**
+```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 6.**
+```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
+```
 
 ## Comparing cursors, object types, nested tables and varrays 
 

diff --git a/source/core/ut_utils.pkb b/source/core/ut_utils.pkb
@@ -877,5 +877,58 @@ create or replace package body ut_utils is
         end;
   end;
 
+  function interval_to_text(a_interval dsinterval_unconstrained) return varchar2 is
+    l_day varchar2(100) := extract(day  from a_interval); 
+    l_hour varchar2(100) := extract(hour  from a_interval); 
+    l_minute varchar2(100) := extract(minute  from a_interval);
+    l_second varchar2(100) := extract(second from a_interval);     
+    l_result varchar2(32767);  
+  begin
+    l_result := case 
+                  when l_day = 1 then l_day ||' day' 
+                  when l_day > 1 then l_day ||' days' 
+                  else null 
+                end;
+    l_result := l_result || 
+                case 
+                  when l_hour = 1 then ' '|| l_hour ||' hour' 
+                  when l_hour > 1 then ' '|| l_hour ||' hours' 
+                  else null 
+                end;
+    l_result := l_result || 
+                case 
+                  when l_minute = 1 then ' '||l_minute ||' minute' 
+                  when l_minute > 1 then ' '||l_minute ||' minutes' 
+                  else null 
+                end; 
+    l_result := l_result || 
+                case 
+                  when l_second = 1 then ' '||l_second ||' second' 
+                  when l_second > 1 then ' '||l_second ||' seconds' 
+                  else null 
+                end;    
+    return trim(leading ' ' from l_result);
+  end;
+
+  function interval_to_text(a_interval yminterval_unconstrained) return varchar2 is
+    l_year varchar2(4) :=  extract(year from a_interval); 
+    l_month varchar2(20) := extract(month from a_interval);   
+    l_result varchar2(32767);     
+  begin
+    l_result := case 
+                  when l_year = 1 then l_year ||' year' 
+                  when l_year > 1 then l_year ||' years'
+                  else null 
+                end;
+    l_result := l_result || 
+                case 
+                  when l_month = 1 then  ' '||l_month ||' month' 
+                  when l_month > 1 then  ' '||l_month ||' months' 
+                  else null 
+                end;   
+    return trim(leading ' ' from l_result);
+  end;
+
+
 end ut_utils;
 /
diff --git a/source/core/ut_utils.pks b/source/core/ut_utils.pks
@@ -434,6 +434,13 @@ create or replace package ut_utils authid definer is
   * If null value passed returns null
   */
   function qualified_sql_name(a_name varchar2) return varchar2;
-
+
+  /*
+  * Return value of interval in plain english
+  */  
+  function interval_to_text(a_interval dsinterval_unconstrained) return varchar2;
+
+  function interval_to_text(a_interval yminterval_unconstrained) return varchar2;
+
 end ut_utils;
 /
diff --git a/source/expectations/data_values/ut_data_value_dsinterval.tpb b/source/expectations/data_values/ut_data_value_dsinterval.tpb
@@ -31,7 +31,7 @@ create or replace type body ut_data_value_dsinterval as
 
   overriding member function to_string return varchar2 is
   begin
-    return ut_utils.to_string(self.data_value);
+    return ut_utils.interval_to_text(self.data_value);
   end;
 
   overriding member function compare_implementation(a_other ut_data_value) return integer is

diff --git a/source/expectations/data_values/ut_data_value_yminterval.tpb b/source/expectations/data_values/ut_data_value_yminterval.tpb
@@ -31,7 +31,7 @@ create or replace type body ut_data_value_yminterval as
 
   overriding member function to_string return varchar2 is
   begin
-    return ut_utils.to_string(self.data_value);
+    return ut_utils.interval_to_text(self.data_value);
   end;
 
   overriding member function compare_implementation(a_other ut_data_value) return integer is

diff --git a/source/expectations/matchers/ut_be_within.tpb b/source/expectations/matchers/ut_be_within.tpb
@@ -0,0 +1,113 @@
+create or replace type body ut_be_within as
+  /*
+  utPLSQL - Version 3
+  Copyright 2016 - 2019 utPLSQL Project
+
+  Licensed under the Apache License, Version 2.0 (the "License"):
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+  */
+
+ member procedure init(self in out nocopy ut_be_within, a_dist ut_data_value, a_is_pct number , a_self_type varchar2 := null) is
+  begin
+    self.dist  := a_dist;
+    self.is_pct := nvl(a_is_pct,0);
+    self.self_type := nvl( a_self_type, $$plsql_unit );
+  end;
+
+  constructor function ut_be_within(self in out nocopy ut_be_within, a_dist number, a_is_pct number) return self as result is
+  begin
+    init(ut_data_value_number(a_dist),a_is_pct);
+    return;
+  end;
+
+  constructor function ut_be_within(self in out nocopy ut_be_within, a_dist dsinterval_unconstrained, a_is_pct number) return self as result is
+  begin
+    init(ut_data_value_dsinterval(a_dist),a_is_pct); 
+    return;
+  end;
+
+  constructor function ut_be_within(self in out nocopy ut_be_within, a_dist yminterval_unconstrained, a_is_pct number) return self as result is
+  begin
+    init(ut_data_value_yminterval(a_dist),a_is_pct);
+    return;
+  end;
+
+  member procedure of_(self in ut_be_within, a_expected number) is
+    l_result ut_be_within := self;
+  begin 
+    l_result.expected := ut_data_value_number(a_expected);
+    l_result.expectation.to_(l_result );        
+  end;
+
+  member procedure of_(self in ut_be_within, a_expected date) is
+    l_result ut_be_within := self;
+  begin 
+    l_result.expected := ut_data_value_date(a_expected);
+    l_result.expectation.to_(l_result );    
+  end;
+
+  overriding member function run_matcher(self in out nocopy ut_be_within, a_actual ut_data_value) return boolean is
+    l_result boolean;
+  begin
+    if self.expected.data_type = a_actual.data_type then
+      if self.expected is of (ut_data_value_number) and self.is_pct = 0 then
+        l_result := abs((treat(self.expected as ut_data_value_number).data_value - treat(a_actual as ut_data_value_number).data_value)) <= 
+                    treat(self.dist as ut_data_value_number).data_value;
+      elsif self.expected is of (ut_data_value_number) and self.is_pct = 1 then
+        l_result := treat(self.dist as ut_data_value_number).data_value >= 
+                    (
+                     ((treat(self.expected as ut_data_value_number).data_value - treat(a_actual as ut_data_value_number).data_value ) * 100 ) /
+                    (treat(self.expected as ut_data_value_number).data_value)) ;      
+      elsif self.expected is of (ut_data_value_date) and self.dist is of ( ut_data_value_yminterval) then      
+        l_result := treat(a_actual as ut_data_value_date).data_value 
+                    between 
+                     (treat(self.expected as ut_data_value_date).data_value) - treat(self.dist as ut_data_value_yminterval).data_value
+                     and 
+                     (treat(self.expected as ut_data_value_date).data_value) + treat(self.dist as ut_data_value_yminterval).data_value;
+      elsif self.expected is of (ut_data_value_date) and self.dist is of ( ut_data_value_dsinterval) then      
+        l_result := treat(a_actual as ut_data_value_date).data_value 
+                    between 
+                      (treat(self.expected as ut_data_value_date).data_value) - treat(self.dist as ut_data_value_dsinterval).data_value
+                      and 
+                      (treat(self.expected as ut_data_value_date).data_value) + treat(self.dist as ut_data_value_dsinterval).data_value;
+      end if;
+    else
+      l_result := (self as ut_matcher).run_matcher(a_actual);
+    end if;
+    return l_result;
+  end;
+
+  overriding member function failure_message(a_actual ut_data_value) return varchar2 is
+    l_distance varchar2(32767);
+  begin
+    l_distance := case 
+                    when self.dist is of (ut_data_value_number) then
+                      treat(self.dist as ut_data_value_number).to_string
+                    when self.dist is of (ut_data_value_yminterval) then
+                      treat(self.dist as ut_data_value_yminterval).to_string 
+                    when self.dist is of (ut_data_value_dsinterval) then
+                      treat(self.dist as ut_data_value_dsinterval).to_string 
+                    else
+                      null
+                    end;
+
+    return (self as ut_matcher).failure_message(a_actual) || ' '||l_distance ||' of '|| expected.to_string_report();
+  end;
+
+  overriding member function failure_message_when_negated(a_actual ut_data_value) return varchar2 is
+    l_result varchar2(32767);
+  begin
+    return (self as ut_matcher).failure_message_when_negated(a_actual) || ': '|| expected.to_string_report();
+  end;  
+
+end;
+/
diff --git a/source/expectations/matchers/ut_be_within.tps b/source/expectations/matchers/ut_be_within.tps
@@ -0,0 +1,38 @@
+create or replace type ut_be_within under ut_comparison_matcher(
+  /*
+  utPLSQL - Version 3
+  Copyright 2016 - 2019 utPLSQL Project
+
+  Licensed under the Apache License, Version 2.0 (the "License"):
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+  */
+
+
+  /**
+  * Holds information about mather options
+  */
+  dist ut_data_value,
+  is_pct number(1,0),
+
+  member procedure init(self in out nocopy ut_be_within, a_dist ut_data_value, a_is_pct number , a_self_type varchar2 := null),
+  constructor function ut_be_within(self in out nocopy ut_be_within, a_dist number, a_is_pct number) return self as result,
+  constructor function ut_be_within(self in out nocopy ut_be_within, a_dist dsinterval_unconstrained, a_is_pct number) return self as result,
+  constructor function ut_be_within(self in out nocopy ut_be_within, a_dist yminterval_unconstrained, a_is_pct number) return self as result,
+  member procedure of_(self in ut_be_within, a_expected number),
+  member procedure of_(self in ut_be_within, a_expected date),
+
+  overriding member function run_matcher(self in out nocopy ut_be_within, a_actual ut_data_value) return boolean,
+  overriding member function failure_message(a_actual ut_data_value) return varchar2,
+  overriding member function failure_message_when_negated(a_actual ut_data_value) return varchar2
+)
+not final
+/