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

Skip to content

Commit 03ad5ec

Browse files
lwasylowlwasylow
committed
Update documentation
1 parent 5aa19ea commit 03ad5ec

2 files changed

Lines changed: 309 additions & 32 deletions

File tree

‎docs/userguide/advanced_data_comparison.md‎

Lines changed: 84 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ utPLSQL expectations incorporates advanced data comparison options when comparin
66
- object type
77
- nested table and varray
88

9-
Advanced data-comparison options are available for the [`equal`](expectations.md#equal) matcher.
9+
Advanced data-comparison options are available for the [`equal`](expectations.md#equal) and [`include/ contain`](expectations.md#include) matcher.
1010

1111
## Syntax
1212

@@ -15,6 +15,10 @@ Advanced data-comparison options are available for the [`equal`](expectations.md
1515
ut.expect( a_actual {data-type} ).not_to( equal( a_expected {data-type})[.extendend_option()[.extendend_option()[...]]]) );
1616
ut.expect( a_actual {data-type} ).to_equal( a_expected {data-type})[.extendend_option()[.extendend_option()[...]]]);
1717
ut.expect( a_actual {data-type} ).not_to_equal( a_expected {data-type})[.extendend_option()[.extendend_option()[...]]] );
18+
ut.expect( a_actual {data-type} ).to_contain( a_expected {data-type})[.extendend_option()[.extendend_option()[...]]]);
19+
ut.expect( a_actual {data-type} ).to_include( a_expected {data-type})[.extendend_option()[.extendend_option()[...]]]);
20+
ut.expect( a_actual {data-type} ).not_to_include( a_expected {data-type})[.extendend_option()[.extendend_option()[...]]]);
21+
ut.expect( a_actual {data-type} ).not_to_contain( a_expected {data-type})[.extendend_option()[.extendend_option()[...]]]);
1822
```
1923

2024
`extended_option` can be one of:
@@ -23,8 +27,8 @@ Advanced data-comparison options are available for the [`equal`](expectations.md
2327
- `exclude(a_items varchar2)` - item or comma separated list of items to exclude
2428
- `include(a_items ut_varchar2_list)` - table of items to include
2529
- `exclude(a_items ut_varchar2_list)` - table of items to exclude
26-
- `unordered` - perform compare on unordered set of data, return only missing or actual
27-
- `join_by(a_columns varchar2)` - columns or comma seperated list of columns to join two cursors by
30+
- `unordered` - perform compare on unordered set of data, return only missing or actual ***not supported for `include / contain`***
31+
- `join_by(a_columns varchar2)` - columns or comma separated list of columns to join two cursors by
2832
- `join_by(a_columns ut_varchar2_list)` - table of columns to join two cursors by
2933

3034
Each item in the comma separated list can be:
@@ -42,43 +46,61 @@ When specifying column/attribute names, keep in mind that the names are **case s
4246

4347
## Excluding elements from data comparison
4448

45-
Consider the following example
49+
Consider the following examples
4650
```sql
47-
procedure test_cursors_skip_columns is
51+
procedure test_cur_skip_columns_eq is
4852
l_expected sys_refcursor;
4953
l_actual sys_refcursor;
5054
begin
5155
open l_expected for select 'text' ignore_me, d.* from user_tables d;
5256
open l_actual for select sysdate "ADate", d.* from user_tables d;
5357
ut.expect( l_actual ).to_equal( l_expected ).exclude( 'IGNORE_ME,ADate' );
5458
end;
59+
60+
procedure test_cur_skip_columns_cn is
61+
l_expected sys_refcursor;
62+
l_actual sys_refcursor;
63+
begin
64+
open l_expected for select 'text' ignore_me, d.* from user_tables d;
65+
open l_actual for select sysdate "ADate", d.* from user_tables d;
66+
ut.expect( l_actual ).to_include( l_expected ).exclude( 'IGNORE_ME,ADate' );
67+
end;
5568
```
5669

5770
Columns 'ignore_me' and "ADate" will get excluded from cursor comparison.
58-
The cursor data is equal, when those columns are excluded.
71+
The cursor data is equal or includes expected, when those columns are excluded.
5972

6073
This option is useful in scenarios, when you need to exclude incomparable/unpredictable column data like CREATE_DATE of a record that is maintained by default value on a table column.
6174

6275
## Selecting columns for data comparison
6376

6477
Consider the following example
6578
```sql
66-
procedure include_columns_as_csv is
79+
procedure include_col_as_csv_eq is
6780
l_actual sys_refcursor;
6881
l_expected sys_refcursor;
6982
begin
7083
open l_expected for select rownum as rn, 'a' as "A_Column", 'x' SOME_COL from dual a connect by level < 4;
7184
open l_actual for select rownum as rn, 'a' as "A_Column", 'x' SOME_COL, a.* from all_objects a where rownum < 4;
7285
ut.expect( l_actual ).to_equal( l_expected ).include( 'RN,A_Column,SOME_COL' );
7386
end;
87+
88+
procedure include_col_as_csv_cn is
89+
l_actual sys_refcursor;
90+
l_expected sys_refcursor;
91+
begin
92+
open l_expected for select rownum as rn, 'a' as "A_Column", 'x' SOME_COL from dual a connect by level < 4;
93+
open l_actual for select rownum as rn, 'a' as "A_Column", 'x' SOME_COL, a.* from all_objects a where rownum < 6;
94+
ut.expect( l_actual ).to_contain( l_expected ).include( 'RN,A_Column,SOME_COL' );
95+
end;
7496
```
7597

7698
## Combining include/exclude options
7799
You can chain the advanced options in an expectation and mix the `varchar2` with `ut_varchar2_list` arguments.
78-
When doing so, the fianl list of items to include/exclude will be a concatenation of all items.
100+
When doing so, the final list of items to include/exclude will be a concatenation of all items.
79101

80102
```sql
81-
procedure include_columns_as_csv is
103+
procedure include_col_as_csv_eq is
82104
l_actual sys_refcursor;
83105
l_expected sys_refcursor;
84106
begin
@@ -89,6 +111,19 @@ begin
89111
.include( ut_varchar2_list( 'A_Column', 'SOME_COL' ) )
90112
.exclude( 'SOME_COL' );
91113
end;
114+
115+
procedure include_col_as_csv_cn is
116+
l_actual sys_refcursor;
117+
l_expected sys_refcursor;
118+
begin
119+
open l_expected for select rownum as rn, 'a' as "A_Column", 'x' SOME_COL from dual a connect by level < 4;
120+
open l_actual for select rownum as rn, 'a' as "A_Column", 'Y' SOME_COL, a.* from all_objects a where rownum < 6;
121+
ut.expect( l_actual ).to_contain( l_expected )
122+
.include( 'RN')
123+
.include( ut_varchar2_list( 'A_Column', 'SOME_COL' ) )
124+
.exclude( 'SOME_COL' );
125+
end;
126+
92127
```
93128

94129
Only the columns 'RN', "A_Column" will be compared. Column 'SOME_COL' is excluded.
@@ -101,6 +136,8 @@ Unordered option allows for quick comparison of two cursors without need of orde
101136

102137
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.
103138

139+
**This option is not supported for `include / contain` matcher**
140+
104141

105142

106143
```sql
@@ -169,6 +206,33 @@ This will show you difference in row 'TEST' regardless of order.
169206

170207
Assumption is that join by is made by column name so that what will be displayed as part of results.
171208

209+
Consider this example using `contain / include `
210+
211+
```sql
212+
procedure join_by_username_cn is
213+
l_actual sys_refcursor;
214+
l_expected sys_refcursor;
215+
begin
216+
open l_actual for select username, user_id from all_users;
217+
open l_expected for select username, user_id from all_users
218+
union all
219+
select 'TEST' username, -610 user_id from dual;
220+
221+
ut.expect( l_actual ).to_contain( l_expected ).join_by('USERNAME');
222+
end;
223+
```
224+
225+
This will show you that one value is not included in actual set:
226+
227+
```sql
228+
Actual: refcursor [ count = 43 ] was expected to include: refcursor [ count = 44 ]
229+
Diff:
230+
Rows: [ 1 differences ]
231+
PK <USERNAME>TEST</USERNAME> - Missing <USER_ID>-610</USER_ID>
232+
```
233+
234+
235+
172236
Join by options currently doesn't support nested table inside cursor comparison, however is still possible to compare a collection as a whole.
173237

174238
Example.
@@ -220,9 +284,7 @@ Diff:
220284

221285

222286

223-
224-
225-
**Please note that .join_by option will take longer to process due to need of parsing via primary keys.**
287+
***Please note that .join_by option will take longer to process due to need of parsing via primary keys.***
226288

227289
## Defining item as XPath
228290
When using XPath expression, keep in mind the following:
@@ -233,12 +295,21 @@ When using XPath expression, keep in mind the following:
233295

234296
Example of a valid XPath parameter to include columns: `RN`, `A_Column`, `SOME_COL` in data comparison.
235297
```sql
236-
procedure include_columns_as_xpath is
298+
procedure include_col_as_xpath_eq is
237299
l_actual sys_refcursor;
238300
l_expected sys_refcursor;
239301
begin
240302
open l_expected for select rownum as rn, 'a' as "A_Column", 'x' SOME_COL from dual a connect by level < 4;
241303
open l_actual for select rownum as rn, 'a' as "A_Column", 'x' SOME_COL, a.* from all_objects a where rownum < 4;
242304
ut.expect( l_actual ).to_equal( l_expected ).include( '/ROW/RN|/ROW/A_Column|/ROW/SOME_COL' );
243305
end;
306+
307+
procedure include_col_as_xpath_cn is
308+
l_actual sys_refcursor;
309+
l_expected sys_refcursor;
310+
begin
311+
open l_expected for select rownum as rn, 'a' as "A_Column", 'x' SOME_COL from dual a connect by level < 4;
312+
open l_actual for select rownum as rn, 'a' as "A_Column", 'x' SOME_COL, a.* from all_objects a where rownum < 6;
313+
ut.expect( l_actual ).to_include( l_expected ).include( '/ROW/RN|/ROW/A_Column|/ROW/SOME_COL' );
314+
end;
244315
```

0 commit comments

Comments
 (0)