Update documentation and tests

utPLSQL · jgebal · Feb 4, 2022 · Jun 1, 2020 · Jun 2, 2020 · Jun 2, 2020
commit 9ee0e75cfa6f3e8cfef95e7f47d54f62c1990d93
diff --git a/docs/userguide/expectations.md b/docs/userguide/expectations.md
@@ -1096,15 +1096,85 @@ SUCCESS

 ## to_be_within of

-This fuzzy matcher is designed to allow user to compare a numbers and dates within distance of error.
+This matcher is created to determine wheter expected value is approximately equal or "close" to another value.

-We are allowing a numbers to be compared within a absolute distance from other number of within a percentage calculated based on expected value.
+Matcher will allow to compare numbers as well as dates. 

-When comparing a date a distance is measured in interval.
+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
@@ -884,10 +884,29 @@ create or replace package body ut_utils is
    l_second varchar2(100) := extract(second from a_interval);     
    l_result varchar2(32767);  
  begin
-    l_result := case when l_day > 0 then l_day ||' day' else null end;
-    l_result := l_result || case when l_hour > 0 then ' '|| l_hour ||' hour' else null end;
-    l_result := l_result || case when l_minute> 0 then ' '||l_minute ||' minute' else null end; 
-    l_result := l_result || case when l_second > 0 then ' '||l_second ||' second' else null end;    
+    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;

@@ -896,8 +915,17 @@ create or replace package body ut_utils is
    l_month varchar2(20) := extract(month from a_interval);   
    l_result varchar2(32767);     
  begin
-    l_result := case when l_year > 0 then l_year ||' year' else null end;
-    l_result := l_result || case when l_month > 0 then  ' '||l_month ||' month' else null end;   
+    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;


diff --git a/source/expectations/matchers/ut_be_within.tpb b/source/expectations/matchers/ut_be_within.tpb
@@ -60,16 +60,25 @@ create or replace type body ut_be_within as
  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;
+        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) ;      
+        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;
+        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;
+        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);

diff --git a/test/ut3_tester/core/test_ut_utils.pkb b/test/ut3_tester/core/test_ut_utils.pkb
@@ -432,5 +432,62 @@ end;
    --Assert
    ut.expect(l_actual).to_equal(l_expected);
  end;
+
+  procedure int_conv_ds_sec is
+    l_expected varchar2(100) := '1 second';
+    l_actual   varchar2(200) := ut3_develop.ut_utils.interval_to_text(interval '1' second);
+  begin
+    ut.expect(l_expected).to_equal(l_actual);
+  end;
+
+  procedure int_conv_ds_minute is
+    l_expected varchar2(100) := '1 minute';
+    l_actual   varchar2(200) := ut3_develop.ut_utils.interval_to_text(interval '1' minute);
+  begin
+    ut.expect(l_expected).to_equal(l_actual);
+  end;
+
+  procedure int_conv_ds_hour is
+    l_expected varchar2(100) := '1 hour';
+    l_actual   varchar2(200) := ut3_develop.ut_utils.interval_to_text(interval '1' hour);
+  begin
+    ut.expect(l_expected).to_equal(l_actual);
+  end;
+
+  procedure int_conv_ds_day is
+    l_expected varchar2(100) := '1 day';
+    l_actual   varchar2(200) := ut3_develop.ut_utils.interval_to_text(interval '1' day);
+  begin
+    ut.expect(l_expected).to_equal(l_actual);
+  end;
+
+  procedure int_conv_ds_date is
+    l_expected varchar2(100) := '2 days 3 hours 4 minutes 11.333 seconds';
+    l_actual   varchar2(200) := ut3_develop.ut_utils.interval_to_text(INTERVAL '2 3:04:11.333' DAY TO SECOND);
+  begin
+    ut.expect(l_expected).to_equal(l_actual);
+  end; 
+
+  procedure int_conv_ym_year is
+    l_expected varchar2(100) := '1 year';
+    l_actual   varchar2(200) := ut3_develop.ut_utils.interval_to_text(interval '1' year);
+  begin
+    ut.expect(l_expected).to_equal(l_actual);
+  end;
+
+  procedure int_conv_ym_month is
+    l_expected varchar2(100) := '1 month';
+    l_actual   varchar2(200) := ut3_develop.ut_utils.interval_to_text(interval '1' month);
+  begin
+    ut.expect(l_expected).to_equal(l_actual);
+  end;
+
+  procedure int_conv_ym_date is
+    l_expected varchar2(100) := '1 year 2 months';
+    l_actual   varchar2(200) := ut3_develop.ut_utils.interval_to_text(INTERVAL '1-2' YEAR TO MONTH);
+  begin
+    ut.expect(l_expected).to_equal(l_actual);
+  end;   
+
 end test_ut_utils;
 /
diff --git a/test/ut3_tester/core/test_ut_utils.pks b/test/ut3_tester/core/test_ut_utils.pks
@@ -128,5 +128,34 @@ create or replace package test_ut_utils is
  --%test(replace_multiline_comments - replaces multi-line comments with empty lines)
  procedure replace_multiline_comments;

+  --%context(interval_converter_to_strin)
+
+  --%test(Test day to second interval passing a second)
+  procedure int_conv_ds_sec; 
+
+  --%test(Test day to second interval passing a minute)    
+  procedure int_conv_ds_minute; 
+
+  --%test(Test day to second interval passing a hour)    
+  procedure int_conv_ds_hour;  
+
+  --%test(Test day to second interval passing a day)  
+  procedure int_conv_ds_day; 
+
+  --%test(Test day to second interval passing a custom date )  
+  procedure int_conv_ds_date; 
+
+  --%test(Test year to month interval passing a hour)    
+  procedure int_conv_ym_year;  
+
+  --%test(Test year to month interval passing a day)  
+  procedure int_conv_ym_month; 
+
+  --%test(Test year to month interval passing a custom date )  
+  procedure int_conv_ym_date;   
+
+
+  --%endcontext
+
 end test_ut_utils;
 /
diff --git a/test/ut3_user/expectations/binary/test_to_be_within.pkb b/test/ut3_user/expectations/binary/test_to_be_within.pkb
@@ -103,7 +103,7 @@ create or replace package body test_to_be_within is
    --Act
    ut3_develop.ut.expect(sysdate).to_be_within(INTERVAL '2 3:04:11.333' DAY TO SECOND).of_(sysdate+100);
    --Assert
-    l_expected_message := q'[Actual: % (date) was expected to be within 2 day 3 hour 4 minute 11.333 second of % (date)]';
+    l_expected_message := q'[Actual: % (date) was expected to be within 2 days 3 hours 4 minutes 11.333 seconds of % (date)]';
    l_actual_message := ut3_tester_helper.main_helper.get_failed_expectations(1);
    --Assert
    ut.expect(l_actual_message).to_be_like(l_expected_message);
@@ -131,7 +131,7 @@ create or replace package body test_to_be_within is
    --Act
    ut3_develop.ut.expect(sysdate).to_be_within(INTERVAL '1-3' YEAR TO MONTH).of_(sysdate+720);
    --Assert
-    l_expected_message := q'[Actual: % (date) was expected to be within 1 year 3 month % (date)]';
+    l_expected_message := q'[Actual: % (date) was expected to be within 1 year 3 months % (date)]';
    l_actual_message := ut3_tester_helper.main_helper.get_failed_expectations(1);
    --Assert
    ut.expect(l_actual_message).to_be_like(l_expected_message);