Small fixes and updates regarding peer review.

lwasylow · lwasylow · commit 48ad81e7d572 · 2018-12-07T12:53:03.000Z
Updated documentation
diff --git a/docs/images/venn21.gif b/docs/images/venn21.gif
diff --git a/docs/images/venn22.gif b/docs/images/venn22.gif
diff --git a/docs/userguide/advanced_data_comparison.md b/docs/userguide/advanced_data_comparison.md
@@ -6,7 +6,7 @@ utPLSQL expectations incorporates advanced data comparison options when comparin
 - object type
 - nested table and varray  
 
-Advanced data-comparison options are available for the [`equal`](expectations.md#equal) and  [`include/ contain`](expectations.md#include) matcher.
+Advanced data-comparison options are available for the [`equal`](expectations.md#equal) and  [`include / contain`](expectations.md#include) matcher.
 
 ## Syntax
 
@@ -27,7 +27,7 @@ Advanced data-comparison options are available for the [`equal`](expectations.md
  - `exclude(a_items varchar2)` - item or comma separated list of items to exclude
  - `include(a_items ut_varchar2_list)` - table of items to include 
  - `exclude(a_items ut_varchar2_list)` - table of items to exclude
- - `unordered` - perform compare on unordered set of data, return only missing or actual  ***not supported for `include / contain`***
+ - `unordered` - perform compare on unordered set of data, return only missing or actual,  ***not supported for `include / contain`*** , as alternative `join_by` can be used
  - `join_by(a_columns varchar2)` - columns or comma separated list of columns to join two cursors by
  - `join_by(a_columns ut_varchar2_list)` - table of columns to join two cursors by
 
diff --git a/docs/userguide/expectations.md b/docs/userguide/expectations.md
@@ -437,15 +437,17 @@ To change the behavior of `NULL = NULL` comparison pass the `a_nulls_are_equal =
 
 This matcher supports only cursor comparison. It check if the give set contain all values from given subset.
 
-Test using this matcher behaves similar to `equal`  in respect that it succeeds only when the compared data-types are exactly the same.
+when comparing data using `include / contain` matcher, the data-types of columns for compared cursors must be exactly the same.
 
 The matcher supports all advanced comparison options as `equal` e.g. include , exclude, join_by.
 
-The matcher will be successful only when all of the values in expected results are part of actual set.
+The matcher is successful when all of the values from expected results are included in actual data set.
 
-In situation where the duplicate is present in expected set we would also expect matching number of occurrences in actual set for matcher to be success.
+The matcher will cause a test to fail if any of expected values are not included in actual data set.
 
-*Example 1*
+![](D:\Oracle\Devwork\mygit\utPLSQL_pure_sql_cursor\docs\images\venn21.gif)
+
+*Example 1*.
 
 ```sql
    PROCEDURE ut_refcursors IS
@@ -474,11 +476,56 @@ Will result in failure message
       Missing:  <ROW><RN>1</RN></ROW>
 ```
 
+When duplicate rows are present in expected data set, actual data set must also include the same amount of duplicate.
+
+*Example 2.*
 
 
-Similar negated `not_to_include`/ `not_to_contain` will be successful only when none of the values from expected set are part of actual e.g.
 
-*Example 2.*
+```sql
+create or replace package ut_duplicate_test is
+
+   --%suite(Sample Test Suite)
+
+   --%test(Ref Cursor contain duplicates)
+   procedure ut_duplicate_include;
+
+end ut_duplicate_test;
+/
+
+create or replace package body ut_duplicate_test is
+  procedure ut_duplicate_include is
+      l_actual   sys_refcursor;
+      l_expected sys_refcursor;
+  begin
+    open l_expected for select mod(level,2) as rn from dual connect by level < 5;
+    open l_actual   for select mod(level,8) as rn from dual connect by level < 9;
+    ut.expect(l_actual).to_include(l_expected);
+   end;
+   
+end ut_duplicate_test;
+```
+
+Will result in failure test message
+
+```sql
+  1) ut_duplicate_include
+      Actual: refcursor [ count = 8 ] was expected to include: refcursor [ count = 4 ]
+      Diff:
+      Rows: [ 2 differences ]
+      Missing:  <RN>0</RN>
+      Missing:  <RN>1</RN>
+```
+
+
+
+The negated version of `include / contain` ( `not_to_include`/ `not_to_contain` ) is successful only when all values from expected set are not part of actual (they are disjoint and there is no overlap).
+
+
+
+![](D:\Oracle\Devwork\mygit\utPLSQL_pure_sql_cursor\docs\images\venn22.gif)
+
+*Example 3.*
 
 Set 1 is defined as [ A , B , C ] 
 
@@ -488,7 +535,7 @@ Set 1 is defined as [ A , B , C ]
 
 
 
-*Example 2.*
+*Example 4.*
 
 Set 1 is defined as [ A , B , C , D ] 
 
@@ -498,7 +545,7 @@ Set 1 is defined as [ A , B , C , D ]
 
 
 
-*Example 3*
+*Example 5.
 
 Set 1 is defined as [ A , B , C  ] 
 
@@ -681,9 +728,9 @@ utPLSQL is capable of comparing compound data-types including:
 ### Notes on comparison of compound data
 - Compound data can contain elements of any data-type. This includes blob, clob, object type, nested table, varray or even a nested-cursor within a cursor.   
 
-- Nested table and varray types are compared as **ordered lists of elements**. If order of elements differ, expectation will fail.   
+- Attributes in nested table and array types are compared as **ordered lists of elements**. If order of attributes in nested table and array differ, expectation will fail.   
 
-- Cursors are compared as **unordered list of elements** by default. If order of elements is of importance the option has to be passed to enforce column order comparison  `ordered_columns` e.g.
+- Columns in cursors are compared as **unordered list of elements** by default. If order of columns in cursor is of importance the option has to be passed to enforce column order comparison  `ordered_columns` e.g.
 
     ```sql
     procedure ut_refcursors1 is
diff --git a/source/core/types/ut_cursor_info.tps b/source/core/types/ut_cursor_info.tps
diff --git a/source/core/ut_utils.pkb b/source/core/ut_utils.pkb
@@ -692,10 +692,5 @@ create or replace package body ut_utils is
     return l_result;
   end;
 
-  function serialize_data (a_data clob) return clob is
-  begin
-    return replace(a_data,chr(10));    
-  end;
-
 end ut_utils;
 /
diff --git a/source/core/ut_utils.pks b/source/core/ut_utils.pks
@@ -354,8 +354,5 @@ create or replace package ut_utils authid definer is
   */
   function replace_multiline_comments(a_source clob) return clob;
 
-  --TODO optimize clob replace to be more efficient as might not work replace on large clobs
-  function serialize_data (a_data clob) return clob;
-
 end ut_utils;
 /
diff --git a/source/expectations/data_values/ut_compound_data_helper.pkb b/source/expectations/data_values/ut_compound_data_helper.pkb
@@ -20,7 +20,7 @@ create or replace package body ut_compound_data_helper is
   g_diff_count        integer;
   g_filter_tab        ut_varchar2_list;
   
-  type t_type_name_map is table of varchar2(100) index by binary_integer;
+  type t_type_name_map is table of varchar2(128) index by binary_integer;
   g_type_name_map           t_type_name_map;
   g_anytype_name_map        t_type_name_map;
   g_anytype_collection_name t_type_name_map;
@@ -352,7 +352,7 @@ create or replace package body ut_compound_data_helper is
   
   begin
     dbms_lob.createtemporary(l_compare_sql, true);
-    gen_sql_pieces_out_of_cursor(a_other.cursor_details.cursor_info, a_join_by_list, 
+    gen_sql_pieces_out_of_cursor(a_other.cursor_details.cursor_columns_info, a_join_by_list, 
       l_xmltable_stmt, l_select_stmt, l_partition_stmt, l_equal_stmt, 
       l_join_on_stmt, l_not_equal_stmt);
       
diff --git a/source/expectations/data_values/ut_cursor_column.tps b/source/expectations/data_values/ut_cursor_column.tps
@@ -1,16 +1,16 @@
 create or replace type ut_cursor_column force authid current_user as object
 (
-   parent_name      varchar2(100),
-   access_path      varchar2(500),
+   parent_name      varchar2(4000),
+   access_path      varchar2(4000),
    has_nested_col   number(1,0),
    transformed_name varchar2(32),
    hierarchy_level  number,
    column_position  number,
-   xml_valid_name   varchar2(100),
-   column_name      varchar2(100),
-   column_type      varchar2(100),
-   column_type_name varchar2(100),
-   column_schema    varchar2(100),
+   xml_valid_name   varchar2(128),
+   column_name      varchar2(128),
+   column_type      varchar2(128),
+   column_type_name varchar2(128),
+   column_schema    varchar2(128),
    column_len       integer,
    is_sql_diffable  number(1, 0),
    is_collection    number(1, 0),
diff --git a/source/expectations/data_values/ut_cursor_details.tpb b/source/expectations/data_values/ut_cursor_details.tpb
@@ -5,14 +5,14 @@ create or replace type body ut_cursor_details as
   begin   
     if self.is_column_order_enforced = 1 then
       select count(1) into l_diffs
-      from table(self.cursor_info) a full outer join table(a_other.cursor_info) e
+      from table(self.cursor_columns_info) a full outer join table(a_other.cursor_columns_info) e
       on  ( decode(a.parent_name,e.parent_name,1,0)= 1 and a.column_name = e.column_name and 
         REPLACE(a.column_type,'VARCHAR2','CHAR') =  REPLACE(e.column_type,'VARCHAR2','CHAR')
        and  a.column_position = e.column_position )
       where a.column_name is null or e.column_name is null;  
     else
       select count(1) into l_diffs
-      from table(self.cursor_info) a full outer join table(a_other.cursor_info) e
+      from table(self.cursor_columns_info) a full outer join table(a_other.cursor_columns_info) e
       on  ( decode(a.parent_name,e.parent_name,1,0)= 1 and a.column_name = e.column_name and 
         REPLACE(a.column_type,'VARCHAR2','CHAR') =  REPLACE(e.column_type,'VARCHAR2','CHAR'))
       where a.column_name is null or e.column_name is null;   
@@ -155,8 +155,8 @@ create or replace type body ut_cursor_details as
       end if;
       
       l_is_collection := ut_compound_data_helper.is_collection(l_attribute_typecode);
-      self.cursor_info.extend;
-      self.cursor_info(cursor_info.last) := ut_cursor_column( l_aname,
+      self.cursor_columns_info.extend;
+      self.cursor_columns_info(cursor_columns_info.last) := ut_cursor_column( l_aname,
                                                               l_schema_name,
                                                               null,
                                                               l_len,
@@ -176,7 +176,7 @@ create or replace type body ut_cursor_details as
     
   constructor function ut_cursor_details(self in out nocopy ut_cursor_details) return self as result is
   begin
-    self.cursor_info := ut_cursor_column_tab();
+    self.cursor_columns_info := ut_cursor_column_tab();
     return;
   end;
 
@@ -192,7 +192,7 @@ create or replace type body ut_cursor_details as
     l_hierarchy_level    integer := 1;
     l_anytype            anytype;
    begin
-      self.cursor_info := ut_cursor_column_tab();
+      self.cursor_columns_info := ut_cursor_column_tab();
       dbms_sql.describe_columns3(a_cursor_number,
                                  l_columns_count,
                                  l_columns_desc);
@@ -205,8 +205,8 @@ create or replace type body ut_cursor_details as
       **/   
       for cur in 1 .. l_columns_count loop
          l_is_collection := ut_compound_data_helper.is_collection(l_columns_desc(cur).col_schema_name,l_columns_desc(cur).col_type_name);
-         self.cursor_info.extend;
-         self.cursor_info(cursor_info.last) := ut_cursor_column(  l_columns_desc(cur).col_name,
+         self.cursor_columns_info.extend;
+         self.cursor_columns_info(cursor_columns_info.last) := ut_cursor_column(  l_columns_desc(cur).col_name,
                                                                   l_columns_desc(cur).col_schema_name,
                                                                   l_columns_desc(cur).col_type_name,
                                                                   l_columns_desc(cur).col_max_len,
diff --git a/source/expectations/data_values/ut_cursor_details.tps b/source/expectations/data_values/ut_cursor_details.tps
@@ -1,6 +1,6 @@
 create or replace type ut_cursor_details force authid current_user as object
 (
-   cursor_info ut_cursor_column_tab,
+   cursor_columns_info ut_cursor_column_tab,
    is_column_order_enforced number(1,0),
    order member function compare(a_other ut_cursor_details) return integer,
    member procedure get_anytype_members_info(a_anytype anytype, a_attribute_typecode out pls_integer,
diff --git a/source/expectations/data_values/ut_data_value_refcursor.tpb b/source/expectations/data_values/ut_data_value_refcursor.tpb
@@ -102,7 +102,7 @@ create or replace type body ut_data_value_refcursor as
   overriding member function to_string return varchar2 is
     l_result        clob;
     l_result_string varchar2(32767);
-    l_cursor_details ut_cursor_column_tab := self.cursor_details.cursor_info;
+    l_cursor_details ut_cursor_column_tab := self.cursor_details.cursor_columns_info;
     
     l_query   varchar2(32767);
     l_column_info   xmltype;
@@ -204,13 +204,13 @@ create or replace type body ut_data_value_refcursor as
     end if;
     l_actual := treat(a_other as ut_data_value_refcursor);
 
-    l_act_cols  := l_actual.cursor_details.cursor_info;
-    l_exp_cols  := self.cursor_details.cursor_info;
+    l_act_cols  := l_actual.cursor_details.cursor_columns_info;
+    l_exp_cols  := self.cursor_details.cursor_columns_info;
 
     dbms_lob.createtemporary(l_result,true);
     --diff columns
     if not self.is_null and not l_actual.is_null then
-      l_column_diffs := ut_compound_data_helper.get_columns_diff(self.cursor_details.cursor_info,l_actual.cursor_details.cursor_info,l_column_order_enforce);
+      l_column_diffs := ut_compound_data_helper.get_columns_diff(self.cursor_details.cursor_columns_info,l_actual.cursor_details.cursor_columns_info,l_column_order_enforce);
     
       if l_column_diffs.count > 0 then
         ut_utils.append_to_clob(l_result,chr(10) || 'Columns:' || chr(10));
@@ -220,8 +220,8 @@ create or replace type body ut_data_value_refcursor as
         l_results(l_results.last) := get_col_diff_text(l_column_diffs(i));
       end loop;
       ut_utils.append_to_clob(l_result, l_results);
-      l_act_cols  := remove_incomparable_cols(l_actual.cursor_details.cursor_info,l_column_diffs);
-      l_exp_cols  := remove_incomparable_cols(self.cursor_details.cursor_info,l_column_diffs);
+      l_act_cols  := remove_incomparable_cols(l_actual.cursor_details.cursor_columns_info,l_column_diffs);
+      l_exp_cols  := remove_incomparable_cols(self.cursor_details.cursor_columns_info,l_column_diffs);
     end if;
     
     --check for missing pk 
@@ -260,8 +260,8 @@ create or replace type body ut_data_value_refcursor as
           ut_utils.append_to_clob(l_result, get_missing_key_message(l_missing_pk(i))|| chr(10));
         end loop;
         
-        if ut_compound_data_helper.contains_collection(self.cursor_details.cursor_info) > 0 
-           or ut_compound_data_helper.contains_collection(l_actual.cursor_details.cursor_info) > 0 then
+        if ut_compound_data_helper.contains_collection(self.cursor_details.cursor_columns_info) > 0 
+           or ut_compound_data_helper.contains_collection(l_actual.cursor_details.cursor_columns_info) > 0 then
           ut_utils.append_to_clob(l_result,'  Please make sure that your join clause is not refferring to collection element'|| chr(10));
         end if;
         
@@ -286,7 +286,7 @@ create or replace type body ut_data_value_refcursor as
     l_actual   := treat(a_other as ut_data_value_refcursor);
      
     if a_join_by_list.count > 0 then
-      l_pk_missing_tab := ut_compound_data_helper.get_missing_pk(self.cursor_details.cursor_info,l_actual.cursor_details.cursor_info,a_join_by_list);
+      l_pk_missing_tab := ut_compound_data_helper.get_missing_pk(self.cursor_details.cursor_columns_info,l_actual.cursor_details.cursor_columns_info,a_join_by_list);
       l_result := case when (l_pk_missing_tab.count > 0) then 1 else 0 end;
     end if;
         
@@ -309,8 +309,8 @@ create or replace type body ut_data_value_refcursor as
   member function update_cursor_details (a_exclude_xpath ut_varchar2_list, a_include_xpath ut_varchar2_list,a_ordered_columns boolean := false) return ut_data_value_refcursor is
     l_result ut_data_value_refcursor := self;
   begin   
-    if l_result.cursor_details.cursor_info is not null then
-      l_result.cursor_details.cursor_info := ut_compound_data_helper.inc_exc_columns_from_cursor(l_result.cursor_details.cursor_info,a_exclude_xpath,a_include_xpath);
+    if l_result.cursor_details.cursor_columns_info is not null then
+      l_result.cursor_details.cursor_columns_info := ut_compound_data_helper.inc_exc_columns_from_cursor(l_result.cursor_details.cursor_columns_info,a_exclude_xpath,a_include_xpath);
       l_result.cursor_details.ordered_columns(a_ordered_columns);
     end if;    
     return l_result;

Original file line number	Diff line number	Diff line change
`@@ -354,8 +354,5 @@ create or replace package ut_utils authid definer is`
`354`	`354`	`*/`
`355`	`355`	`function replace_multiline_comments(a_source clob) return clob;`
`356`	`356`
`357`		`- --TODO optimize clob replace to be more efficient as might not work replace on large clobs`
`358`		`- function serialize_data (a_data clob) return clob;`
`359`		`-`
`360`	`357`	`end ut_utils;`
`361`	`358`	`/`