Fixed issue with spaces in column lists.

Updated documentation.
utPLSQL · jgebal · Mar 15, 2019 · Oct 6, 2018 · Oct 6, 2018 · Oct 6, 2018
commit d7a271160e672a6f5bb6d9b95b27da9adb795e31
diff --git a/docs/userguide/advanced_data_comparison.md b/docs/userguide/advanced_data_comparison.md
@@ -28,7 +28,7 @@ Advanced data-comparison options are available for the [`equal`](expectations.md
  - `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`*** , 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 varchar2)` - column 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
 
 Each item in the comma separated list can be:
@@ -58,7 +58,7 @@ procedure test_cur_skip_columns_cn is
   l_expected sys_refcursor;
   l_actual   sys_refcursor;
 begin
-  open l_expected for select 'text' ignore_me, d.* from user_tables d;
+  open l_expected for select 'text' ignore_me, d.* from user_tables d where rownum = 1;
   open l_actual   for select sysdate "ADate",  d.* from user_tables d;
   ut.expect( l_actual ).to_include( l_expected ).exclude( 'IGNORE_ME,ADate' );
 end;
@@ -127,99 +127,106 @@ Only the columns 'RN', "A_Column" will be compared. Column 'SOME_COL' is exclude
 
 This option can be useful in scenarios where you need to narrow-down the scope of test so that the test is only focused on very specific data.  
 
-##Unordered
+## Unordered
 
 Unordered option allows for quick comparison of two cursors without need of ordering them in any way.
 
 Result of such comparison will be limited to only information about row existing or not existing in given set without actual information about exact differences.
 
-**This option is not supported for `include / contain` matcher**
-
-
-
 ```sql
 procedure unordered_tst is
     l_actual   sys_refcursor;
     l_expected sys_refcursor;
 begin
-    open l_expected for select username, user_id from all_users
-    union all
-    select 'TEST' username, -600 user_id from dual
-    order by 1 desc;
-    open l_actual   for select username, user_id from all_users
-    union all
-    select 'TEST' username, -610 user_id from dual
-    order by 1 asc;
+    open l_expected for
+      select username, user_id from all_users
+      union all
+      select 'TEST' username, -600 user_id from dual
+      order by 1 desc;
+    open l_actual for 
+      select username, user_id from all_users
+      union all
+      select 'TEST' username, -610 user_id from dual
+      order by 1 asc;
     ut.expect( l_actual ).to_equal( l_expected ).unordered;
 end;
 ```
 
-
-
 Above test will result in two differences of one row extra and one row missing. 
 
-
-
 ```sql
       Diff:
       Rows: [ 2 differences ]
       Missing:  <ROW><USERNAME>TEST</USERNAME><USER_ID>-600</USER_ID></ROW>
       Extra:    <ROW><USERNAME>TEST</USERNAME><USER_ID>-610</USER_ID></ROW>
 ```
 
+**Note**
 
-
+> `include / contain` matcher is not considering order of compared data-sets by default so using `unordered` makes no difference (it's default)
 
 
 ## Join By option
 
-You can now join two cursors by defining a primary key or composite key that will be used to uniquely identify and compare rows. This option allows us to exactly show which rows are missing, extra and which are different without ordering clause. In the situation where the join key is not unique, join will partition set over rows with a same key and join on row number as well as given join key. The extra rows or missing will be presented to user as well as not matching rows. 
+The `join_by` syntax enables comparison of unordered cursors by joining cursor data using specified columns. 
 
-Join by option can be used in conjunction with include or exclude options. However if any of the join keys is part of exclude set, comparison will fail and report to user that sets could not be joined on specific key  (excluded).
+You can join two cursors by defining join column(s) that will be used to uniquely identify and compare rows. 
+With this option, framework is able to identify which rows are missing, which are extra and which are different without need to have both cursors uniformly ordered. 
+When the specified join column(s) are not unique, join will partition set over rows with the same key and join on row number as well as given join key. 
+The extra or missing rows will be presented to user as well as all non-matching rows. 
+
+Join by option can be used in conjunction with include or exclude options. 
+However if any of the join keys is part of exclude set, comparison will fail and report to user that sets could not be joined on specific key, as the key was excluded.
 
 ```sql
 procedure join_by_username is
     l_actual   sys_refcursor;
     l_expected sys_refcursor;
 begin
-    open l_expected for select username, user_id from all_users
-    union all
-    select 'TEST' username, -600 user_id from dual
-    order by 1 desc;
-    open l_actual   for select username, user_id from all_users
-    union all
-    select 'TEST' username, -610 user_id from dual
-    order by 1 asc;
+    open l_expected for 
+      select username, user_id from all_users
+      union all
+      select 'TEST' username, -600 user_id from dual
+      order by 1 desc;
+    open l_actual for 
+      select username, user_id from all_users
+      union all
+      select 'TEST' username, -610 user_id from dual
+      order by 1 asc;
     ut.expect( l_actual ).to_equal( l_expected ).join_by('USERNAME');
 end;
 ```
-This will show you difference in row 'TEST' regardless of order.
+
+Above test will result in a difference in row 'TEST' regardless of data order.
 
 ```sql
       Rows: [ 1 differences ]
         PK <USERNAME>TEST</USERNAME> - Expected: <USER_ID>-600</USER_ID>
         PK <USERNAME>TEST</USERNAME> - Actual:   <USER_ID>-610</USER_ID>
 ```
 
-Assumption is that join by is made by column name so that what will be displayed as part of results.
+**Note** 
 
-Consider this example using `contain / include `
+> When using `join_by`, the join column(s) are displayed first (as PK) to help you identify the mismatched rows/columns.
+
+You can use `join_by` extended syntax in combination with `contain / include ` matcher.
 
 ```sql
 procedure join_by_username_cn is
     l_actual   sys_refcursor;
     l_expected sys_refcursor;
 begin
-    open l_actual for select username, user_id from all_users;
-    open l_expected   for select username, user_id from all_users
-    union all
-    select 'TEST' username, -610 user_id from dual;
+    open l_actual   for select username, user_id from all_users;
+    open l_expected for 
+      select username, user_id from all_users
+      union all
+      select 'TEST' username, -610 user_id from dual;
 
     ut.expect( l_actual ).to_contain( l_expected ).join_by('USERNAME');
 end;
 ```
 
-This will show you that one value is not included in actual set:
+Above test will indicate that in actual data-set
 
 ```sql
      Actual: refcursor [ count = 43 ] was expected to include: refcursor [ count = 44 ]
@@ -229,59 +236,120 @@ This will show you that one value is not included in actual set:
 ```
 
 
+### Joining cursors using multiple columns
 
-Join by options currently doesn't support nested table inside cursor comparison, however is still possible to compare a collection as a whole.
-
-Example.
+You can specify multiple columns in `join_by`
 
 ```sql
- procedure compare_collection_in_rec is
+procedure test_join_by_many_columns is
     l_actual   sys_refcursor;
     l_expected sys_refcursor;
-    l_actual_tab ut3.ut_annotated_object;
-    l_expected_tab ut3.ut_annotated_object;
-    l_expected_message varchar2(32767);
-    l_actual_message   varchar2(32767);
-  begin
-    select ut3.ut_annotated_object('TEST','TEST','TEST',
-      ut3.ut_annotations(ut3.ut_annotation(1,'test','test','test'),
-                         ut3.ut_annotation(2,'test','test','test'))
-    )
-    into l_actual_tab from dual;
+begin
+    open l_expected for
+      select username, user_id, created from all_users
+       order by 1 desc;
+    open l_actual for
+      select username, user_id, created  from all_users
+       union all
+      select 'TEST' username, -610 user_id, sysdate from dual
+       order by 1 asc;
+    ut.expect( l_actual ).to_equal( l_expected ).join_by('USERNAME, USER_ID');
+end;
+```
 
-    select ut3.ut_annotated_object('TEST','TEST','TEST',
-      ut3.ut_annotations(ut3.ut_annotation(1,'test','test','test'),
-                         ut3.ut_annotation(2,'test','test','test'))
-    )
-    into l_expected_tab from dual;
-
-    --Arrange
-    open l_actual for select l_actual_tab as nested_table from dual;
-
-    open l_expected for select l_expected_tab as nested_table from dual;
-
-    --Act
-    ut3.ut.expect(l_actual).to_equal(l_expected).join_by('NESTED_TABLE/ANNOTATIONS');
+### Joining cursors using attributes of object in column list
 
-  end;   
-```
+`join_by` allows for joining cursor data by attributes of object from column list of the compared cursors.
+
+To reference attribute as PK, use slash symbol `/` to separate nested elements.
+
+In the below example, cursors are joined using the `NAME` attribute of object in column `SOMEONE`
+
+```sql
+create or replace type person as object(
+  name varchar2(100),
+  age  integer
+)
+/
+create or replace type people as table of person
+/
+
+create or replace package test_join_by is
+--%suite
+
+--%test
+procedure test_join_by_object_attribute;
+
+end;
+/
 
+create or replace package body test_join_by is
+  procedure test_join_by_object_attribute is
+    l_actual   sys_refcursor;
+    l_expected sys_refcursor;
+  begin
+    open l_expected for
+      select person('Jack',42) someone from dual union all
+      select person('Pat', 44) someone from dual union all
+      select person('Matt',45) someone from dual;
+    open l_actual for
+      select person('Matt',55) someone from dual union all
+      select person('Pat', 44) someone from dual;
+    ut.expect( l_actual ).to_equal( l_expected ).join_by( 'SOMEONE/NAME' );
+  end;
 
+end;
+/
 
-In case when a there is detected collection inside cursor and we cannot join key. Comparison will present a failed joins and also a message about collection being detected.
+``` 
+
+**Note**
+> `join_by` does not support joining on individual elements of nested table. You can still use data of the nested table as a PK value.
+> When collection is referenced in `join_by`, test will fail with appropriate message, as it cannot perform a join.
 
 ```sql
+create or replace type person as object(
+  name varchar2(100),
+  age  integer
+)
+/
+create or replace type people as table of person
+/
+
+create or replace package test_join_by is
+--%suite
+
+--%test
+procedure test_join_by_collection_elem;
+
+end;
+/
+
+create or replace package body test_join_by is
+  procedure test_join_by_collection_elem is
+    l_actual   sys_refcursor;
+    l_expected sys_refcursor;
+  begin
+    open l_expected for select people(person('Matt',45)) persons from dual;
+    open l_actual for select people(person('Matt',45)) persons from dual;
+    ut.expect( l_actual ).to_equal( l_expected ).join_by('PERSONS/PERSON/NAME');
+  end;
+
+end;
+/
+```
+
+```
 Actual: refcursor [ count = 1 ] was expected to equal: refcursor [ count = 1 ]
 Diff:
-	Unable to join sets:
-	Join key NESTED_TABLE/ANNOTATIONS/TEXT does not exists in expected
-	Join key NESTED_TABLE/ANNOTATIONS/TEXT does not exists in actual
-	Please make sure that your join clause is not refferring to collection element
+Unable to join sets:
+  Join key PERSONS/PERSON/NAME does not exists in expected
+  Join key PERSONS/PERSON/NAME does not exists in actual
+  Please make sure that your join clause is not refferring to collection element
 ```
 
-
-
-***Please note that .join_by option will take longer to process due to need of parsing via primary keys.***
+***Note***
+>`join_by` option is slower to process as it needs to perform a cursor join.
 
 ## Defining item lists in option
 XPath expressions are deprecated. They are currently still supported but in future versions they can be removed completely. Please use a current standard of defining items filter.
@@ -293,21 +361,13 @@ When using item list expression, keep in mind the following:
 
 Example of a valid parameter to include columns: `RN`, `A_Column`, `SOME_COL` in data comparison. 
 ```sql
-procedure include_col_list_eq is
+procedure include_col_list is
     l_actual   sys_refcursor;
     l_expected sys_refcursor;
 begin
     open l_expected for select rownum as rn, 'a' as "A_Column", 'x' SOME_COL from dual a connect by level < 4;
     open l_actual   for select rownum as rn, 'a' as "A_Column", 'x' SOME_COL, a.* from all_objects a where rownum < 4;
     ut.expect( l_actual ).to_equal( l_expected ).include( 'RN,A_Column,SOME_COL' );
-end;
-
-procedure include_col_list_eq is
-    l_actual   sys_refcursor;
-    l_expected sys_refcursor;
-begin
-    open l_expected for select rownum as rn, 'a' as "A_Column", 'x' SOME_COL from dual a connect by level < 4;
-    open l_actual   for select rownum as rn, 'a' as "A_Column", 'x' SOME_COL, a.* from all_objects a where rownum < 6;
-    ut.expect( l_actual ).to_include( l_expected ).include( 'RN,A_Column,SOME_COL' );
+    ut.expect( l_actual ).to_equal( l_expected ).include( ut_varchar2_list( 'RN', 'A_Column', 'SOME_COL' ) );
 end;
 ```
diff --git a/source/core/ut_utils.pks b/source/core/ut_utils.pks
@@ -344,10 +344,14 @@ create or replace package ut_utils authid definer is
   function get_xml_header(a_encoding varchar2) return varchar2;
 
 
-  /*It takes a collection of type ut_varchar2_list and it trims the characters passed as arguments for every element*/
+  /**
+  * Takes a collection of type ut_varchar2_list and it trims the characters passed as arguments for every element
+  */
   function trim_list_elements(a_list IN ut_varchar2_list, a_regexp_to_trim in varchar2 default '[:space:]') return ut_varchar2_list;
 
-  /*It takes a collection of type ut_varchar2_list and it only returns the elements which meets the regular expression*/
+  /**
+  * Takes a collection of type ut_varchar2_list and it only returns the elements which meets the regular expression
+  */
   function filter_list(a_list IN ut_varchar2_list, a_regexp_filter in varchar2) return ut_varchar2_list;
 
   -- Generates XMLGEN escaped string

diff --git a/source/expectations/data_values/ut_compound_data_helper.pkb b/source/expectations/data_values/ut_compound_data_helper.pkb
@@ -413,7 +413,7 @@ create or replace package body ut_compound_data_helper is
   end;
 
   function get_rows_diff_by_sql(
-    a_act_cursor_info ut_cursor_column_tab,a_exp_cursor_info ut_cursor_column_tab,
+    a_act_cursor_info ut_cursor_column_tab, a_exp_cursor_info ut_cursor_column_tab,
     a_expected_dataset_guid raw, a_actual_dataset_guid raw, a_diff_id raw,
     a_join_by_list ut_varchar2_list, a_unordered boolean, a_enforce_column_order boolean := false
   ) return tt_row_diffs is
@@ -832,6 +832,7 @@ create or replace package body ut_compound_data_helper is
 begin
   g_anytype_name_map(dbms_types.typecode_date)             := 'DATE';
   g_anytype_name_map(dbms_types.typecode_number)           := 'NUMBER';
+  g_anytype_name_map(3 /*INTEGER in object type*/)         := 'NUMBER';
   g_anytype_name_map(dbms_types.typecode_raw)              := 'RAW';
   g_anytype_name_map(dbms_types.typecode_char)             := 'CHAR';
   g_anytype_name_map(dbms_types.typecode_varchar2)         := 'VARCHAR2';

diff --git a/source/expectations/data_values/ut_data_value_refcursor.tpb b/source/expectations/data_values/ut_data_value_refcursor.tpb
@@ -242,7 +242,8 @@ create or replace type body ut_data_value_refcursor as
     l_results := ut_utils.t_clob_tab();
       if l_diff_row_count > 0  then
         l_row_diffs := ut_compound_data_helper.get_rows_diff_by_sql(
-              l_exp_cols,l_act_cols, self.data_id, l_actual.data_id, l_diff_id,a_join_by_list , a_unordered, l_column_order_enforce);
+              l_exp_cols, l_act_cols, self.data_id, l_actual.data_id, l_diff_id, a_join_by_list , a_unordered, l_column_order_enforce
+          );
         l_message := chr(10)
                      ||'Rows: [ ' || l_diff_row_count ||' differences'
                      ||  case when  l_diff_row_count > c_max_rows and l_row_diffs.count > 0 then ', showing first '||c_max_rows end