Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 97cd079

Browse files
jgebaljgebal
committed
Improved documentation for unordered and unordered_columns options.
Added more tests to document how things work.
1 parent d7a2711 commit 97cd079

4 files changed

Lines changed: 212 additions & 103 deletions

File tree

‎docs/userguide/advanced_data_comparison.md‎

Lines changed: 53 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,10 @@ Advanced data-comparison options are available for the [`equal`](expectations.md
2727
- `exclude(a_items varchar2)` - item or comma separated list of items to exclude
2828
- `include(a_items ut_varchar2_list)` - table of items to include
2929
- `exclude(a_items ut_varchar2_list)` - table of items to exclude
30-
- `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
30+
- `unordered` - ignore order of data sets when comparing data. Default when comparing data-sets with `to_inclide` / `to_contain`
3131
- `join_by(a_columns varchar2)` - column or comma separated list of columns to join two cursors by
3232
- `join_by(a_columns ut_varchar2_list)` - table of columns to join two cursors by
33+
- `unordered_columns` / `uc` - ignore the ordering of columns / attributes in compared data-sets. Column/attribute names will be used to identify data to be compared and the position will be ignored.
3334

3435
Each item in the comma separated list can be:
3536
- a column name of cursor to be compared
@@ -163,7 +164,7 @@ Above test will result in two differences of one row extra and one row missing.
163164

164165
**Note**
165166

166-
> `include / contain` matcher is not considering order of compared data-sets by default so using `unordered` makes no difference (it's default)
167+
> `include / contain` matcher is not considering order of compared data-sets. Using `unordered` makes no difference (it's default)
167168
168169

169170
## Join By option
@@ -371,3 +372,53 @@ begin
371372
ut.expect( l_actual ).to_equal( l_expected ).include( ut_varchar2_list( 'RN', 'A_Column', 'SOME_COL' ) );
372373
end;
373374
```
375+
376+
## Unordered columns / uc option
377+
378+
If you need to perform data comparison of cursors without strictly deending on column order in the returned result-set, use the `unordered_columns` option.
379+
Shortcut name `uc` is also available for that option.
380+
381+
Expectations that compare cursor data with `unordered_Columns` option, will not fail when columns are ordered differently.
382+
383+
This option can be useful whn we have no control over the ordering of the column or the column order is not of importance from testing perspective.
384+
385+
```sql
386+
create or replace package test_unordered_columns as
387+
--%suite
388+
389+
--%test
390+
procedure cursor_include_unordered_cols;
391+
end;
392+
/
393+
394+
create or replace package body test_unordered_columns as
395+
396+
procedure cursor_include_unordered_cols is
397+
l_actual sys_refcursor;
398+
l_expected sys_refcursor;
399+
begin
400+
--Arrange
401+
open l_actual for select owner, object_name,object_type from all_objects where owner = user
402+
order by 1,2,3 asc;
403+
open l_expected for select object_type, owner, object_name from all_objects where owner = user
404+
and rownum < 20;
405+
406+
--Assert
407+
ut.expect(l_actual).to_include(l_expected).unordered_columns();
408+
end;
409+
end;
410+
/
411+
412+
exec ut.run('test_unordered_columns');
413+
```
414+
415+
The above test is successful despite the fact that column ordering in cursor is different.
416+
417+
```
418+
test_unordered_columns
419+
cursor_include_unordered_cols [.042 sec]
420+
421+
Finished in .046193 seconds
422+
1 tests, 0 failed, 0 errored, 0 disabled, 0 warning(s)
423+
```
424+

‎docs/userguide/expectations.md‎

Lines changed: 6 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -709,38 +709,15 @@ utPLSQL is capable of comparing compound data-types including:
709709
- nested table/varray types
710710

711711
### Notes on comparison of compound data
712-
- 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.
713-
714-
- 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.
715-
716-
- Columns in cursors are compared as **ordered list of elements** by default. If order of columns in cursor is not of importance the option has to be passed to enforce column order comparison ` unordered_columns` or a short version `uc` e.g.
717-
718-
```sql
719-
procedure ut_refcursors1 is
720-
l_actual sys_refcursor;
721-
l_expected sys_refcursor;
722-
l_expected_message varchar2(32767);
723-
l_actual_message varchar2(32767);
724-
begin
725-
open l_actual for select 1 user_id,'s' a_col,'test' username from dual;
726-
open l_expected for select 'test' username,'s' a_col,1 user_id from dual;
727-
--Act
728-
ut.expect(l_actual).to_equal(l_expected).join_by('USER_ID').unordered_columns();
729-
ut.expect(l_actual).to_equal(l_expected).join_by('USER_ID').uc();
730-
end;
731-
```
732712

713+
- 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.
714+
- 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.
715+
- Columns in cursors are compared as **ordered list of elements** by default. Use `unordered_columns` option when order of columns in cursor is not relevant
733716
- Comparison of compound data is data-type aware. So a column `ID NUMBER` in a cursor is not the same as `ID VARCHAR2(100)`, even if they both hold the same numeric values.
734-
735717
- Comparison of cursor columns containing `DATE` will only compare date part **and ignore time** by default. See [Comparing cursor data containing DATE fields](#comparing-cursor-data-containing-date-fields) to check how to enable date-time comparison in cursors.
736-
737-
- Comparison of cursor returning `TIMESTAMP` **columns** against cursor returning `TIMESTAMP` **bind variables** requires variables to be casted to proper precision. This is an Oracle SQL - PLSQL compatibility issue and usage of CAST is the only known workaround for now.
738-
See [Comparing cursor data containing TIMESTAMP bind variables](#comparing-cursor-data-containing-timestamp-bind-variables) for examples.
739-
718+
- Comparison of cursor returning `TIMESTAMP` **columns** against cursor returning `TIMESTAMP` **bind variables** requires variables to be casted to proper precision. This is an Oracle SQL - PLSQL compatibility issue and usage of CAST is the only known workaround for now. See [Comparing cursor data containing TIMESTAMP bind variables](#comparing-cursor-data-containing-timestamp-bind-variables) for examples.
740719
- To compare nested table/varray type you need to convert it to `anydata` by using `anydata.convertCollection()`
741-
742720
- To compare object type you need to convert it to `anydata` by using `anydata.convertObject()`
743-
744721
- It is possible to compare PL/SQL records, collections, varrays and associative arrays. To compare this types of data, use cursor comparison feature of utPLSQL and TABLE operator in SQL query
745722
- On Oracle 11g Release 2 - pipelined table functions are needed (see section [Implicit (Shadow) Types in this artcile](https://oracle-base.com/articles/misc/pipelined-table-functions))
746723
- On Oracle 12c and above - use [TABLE function on nested tables/varrays/associative arrays of PL/SQL records](https://oracle-base.com/articles/12c/using-the-table-operator-with-locally-defined-types-in-plsql-12cr1)
@@ -749,7 +726,7 @@ utPLSQL is capable of comparing compound data-types including:
749726
utPLSQL offers advanced data-comparison options, for comparing compound data-types. The options allow you to:
750727
- define columns/attributes to exclude from comparison
751728
- define columns/attributes to include in comparison
752-
- and more
729+
- and more ...
753730

754731
For details on available options and how to use them, read the [advanced data comparison](advanced_data_comparison.md) guide.
755732

@@ -780,7 +757,7 @@ And the actual cursor data:
780757
| M | LUKE | SKYWALKER | 1000 | 2 |
781758

782759

783-
The two datasets above have the following differences:
760+
The two data-sets above have the following differences:
784761
- column ID is misplaced (should be first column but is last)
785762
- column SALARY has data-type VARCHAR2 but should be NUMBER
786763
- column GENDER exists in actual but not in the expected (it is an Extra column)

0 commit comments

Comments
 (0)