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

Skip to content

Commit 6649502

Browse files
jgebaljgebal
committed
Updated documentation.
1 parent 3dea567 commit 6649502

2 files changed

Lines changed: 126 additions & 30 deletions

File tree

‎docs/userguide/advanced_data_comparison.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@ When using XPath expression, keep in mind the following:
9898
- object type attributes are nested under `<OBJECTY_TYPE>` element
9999
- nested table and varray items type attributes are nested under `<ARRAY><OBJECTY_TYPE>` elements
100100

101+
Example of a valid XPath parameter to include columns: `RN`, `A_Column`, `SOME_COL` in data comparison.
101102
```sql
102103
procedure include_columns_as_xpath is
103104
l_actual sys_refcursor;

‎docs/userguide/expectations.md‎

Lines changed: 125 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -329,7 +329,7 @@ The matcher will also fail when comparing a `timestamp` to a `timestamp with tim
329329
The matcher enables detection data-type changes.
330330
If you expect your variable to be a number and it is now some other type, the test will fail and give you early indication of a potential problem.
331331

332-
To keep it simple, the `equal` will only succeed if you compare apples to apples.
332+
To keep it simple, the `equal` matcher will only succeed if you compare apples to apples.
333333

334334
Example usage
335335
```sql
@@ -406,8 +406,9 @@ create or replace package body test_animals_getter is
406406
end;
407407
```
408408

409-
**Comparing NULLs is by default!**
409+
**Comparing NULLs is by default a success!**
410410
The `a_nulls_are_equal` parameter controls the behavior of a `null = null` comparison.
411+
To change the behavior of `NULL = NULL` comparison pass the `a_nulls_are_equal => false` to the `equal` matcher.
411412

412413

413414
## Comparing objects, cursors, collections of data
@@ -418,9 +419,9 @@ utPLSQL is capable of comparing compound data-types including:
418419
- nested table/varray types
419420

420421
### Notes on comparison of compound data
421-
- Compound data can contain elements of any data-type. This includes blob, clob, object type, nested table, varray or nested-cursor.
422+
- 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.
422423
- Cursors, nested table and varray types are compared as **ordered lists of elements**. If order of elements differ, expectation will fail.
423-
- Comparison of compound data does not currently support data-type check on attribute/column level. This might be changed in the future.
424+
- 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.
424425
- 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.
425426
- To compare nested table/varray type you need to convert it to `anydata` by using `anydata.convertCollection()`
426427
- To compare object type you need to convert it to `anydata` by using `anydata.convertObject()`
@@ -436,45 +437,139 @@ utPLSQL offers advanced data-comparison options, for comparing compound data-typ
436437

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

440+
### Diff functionality for compound data-types
439441

440-
### Compound data comparison examples
442+
When comparing compound data, utPLSQL will determine diff between expected and actual data.
443+
The diff includes:
444+
- differences in column names, column positions and column data-type for cursor data
445+
- only data in columns/rows that differ
441446

442-
Cursor comparison.
447+
The diff aims to make it easier to identify what is not expected in the actual data.
448+
449+
Consider the following expected cursor data
450+
451+
| ID (NUMBER)| FIRST_NAME (VARCHAR2) | LAST_NAME (VARCHAR2) | SALARY (NUMBER) |
452+
|:----------:|:----------------------:|:----------------------:|:---------------:|
453+
| 1 | JACK | SPARROW | 10000 |
454+
| 2 | LUKE | SKYWALKER | 1000 |
455+
| 3 | TONY | STARK | 1000000 |
456+
457+
And the actual cursor data:
458+
459+
| *GENDER (VARCHAR2)* | FIRST_NAME (VARCHAR2) | LAST_NAME (VARCHAR2) | SALARY *(VARCHAR2)* | *ID* (NUMBER) |
460+
|:-------------------:|:---------------------:|:--------------------:|:-------------------:|:-------------:|
461+
| M | JACK | SPARROW | *25000* | 1 |
462+
| M | TONY | STARK | 1000000 | 3 |
463+
| *F* | *JESSICA* | *JONES** | *2345* | *4* |
464+
| M | LUKE | SKYWALKER | 1000 | 2 |
465+
466+
467+
When considering the data-sets as ordered, there are following following differences:
468+
- column ID is misplaced (should be first column but is last)
469+
- column SALARY has data-type VARCHAR2 but should be NUMBER
470+
- column GENDER exists in actual but not in the expected (it ir an Extra column)
471+
- data in column SALARY for row number 1 in actual is not matching expected
472+
- row number 2 in actual (ID=3) is not matching expected
473+
- row number 3 in actual (ID=4) is not matching expected
474+
- row number 4 in actual (ID=2) is not expected in results (Extra row in actual)
475+
476+
utPLSQL will report all of the above differences in a readable format to help you identify what is not correct in compared data-set.
477+
478+
Below example illustrates, how utPLSQL will report such differences.
443479
```sql
444-
create or replace function get_user_tables return sys_refcursor is
445-
l_result sys_refcursor;
446-
begin
447-
open l_result for select d.* from user_tables d;
448-
return l_result;
480+
create or replace package test_cursor_compare as
481+
--%suite
482+
483+
--%test
484+
procedure do_test;
449485
end;
450486
/
451487

452-
create or replace package test_cursor_example is
453-
--%suite(example)
454-
455-
--%test(compare cursors)
456-
procedure test_cursors;
457-
end;
458-
/
459-
create or replace package body test_cursor_example is
460-
procedure test_cursors is
488+
create or replace package body test_cursor_compare as
489+
procedure do_test is
490+
l_actual sys_refcursor;
461491
l_expected sys_refcursor;
462492
begin
463-
--Arrange
464-
open l_expected for select d.* from user_tables d;
465-
--Act/Assert
466-
ut.expect( get_user_tables() ).to_equal( l_expected );
493+
open l_expected for
494+
select 1 as ID, 'JACK' as FIRST_NAME, 'SPARROW' AS LAST_NAME, 10000 AS SALARY
495+
from dual union all
496+
select 2 as ID, 'LUKE' as FIRST_NAME, 'SKYWALKER' AS LAST_NAME, 1000 AS SALARY
497+
from dual union all
498+
select 3 as ID, 'TONY' as FIRST_NAME, 'STARK' AS LAST_NAME, 100000 AS SALARY
499+
from dual;
500+
open l_actual for
501+
select 'M' AS GENDER, 'JACK' as FIRST_NAME, 'SPARROW' AS LAST_NAME, 1 as ID, '25000' AS SALARY
502+
from dual union all
503+
select 'M' AS GENDER, 'TONY' as FIRST_NAME, 'STARK' AS LAST_NAME, 3 as ID, '100000' AS SALARY
504+
from dual union all
505+
select 'F' AS GENDER, 'JESSICA' as FIRST_NAME, 'JONES' AS LAST_NAME, 4 as ID, '2345' AS SALARY
506+
from dual union all
507+
select 'M' AS GENDER, 'LUKE' as FIRST_NAME, 'SKYWALKER' AS LAST_NAME, 2 as ID, '1000' AS SALARY
508+
from dual;
509+
ut.expect(l_actual).to_equal(l_expected);
467510
end;
468511
end;
469512
/
470-
begin
471-
ut.run('test_cursor_example');
472-
end;
473-
/
474-
drop package test_cursor_example;
475-
drop function get_user_tables;
476513
```
477514

515+
When the test package is executed using:
516+
517+
```sql
518+
set serverout on
519+
exec ut.run('test_cursor_compare');
520+
```
521+
We get the following report:
522+
```
523+
test_cursor_compare
524+
do_test [.052 sec] (FAILED - 1)
525+
526+
Failures:
527+
528+
1) do_test
529+
Actual: refcursor [ count = 4 ] was expected to equal: refcursor [ count = 3 ]
530+
Diff:
531+
Columns:
532+
Column <ID> is misplaced. Expected position: 1, actual position: 4.
533+
Column <SALARY> data-type is invalid. Expected: NUMBER, actual: VARCHAR2.
534+
Column <GENDER> [position: 1, data-type: CHAR] is not expected in results.
535+
Rows: [ 4 differences ]
536+
Row No. 1 - Actual: <SALARY>25000</SALARY>
537+
Row No. 1 - Expected: <SALARY>10000</SALARY>
538+
Row No. 2 - Actual: <FIRST_NAME>TONY</FIRST_NAME><LAST_NAME>STARK</LAST_NAME><ID>3</ID><SALARY>100000</SALARY>
539+
Row No. 2 - Expected: <ID>2</ID><FIRST_NAME>LUKE</FIRST_NAME><LAST_NAME>SKYWALKER</LAST_NAME><SALARY>1000</SALARY>
540+
Row No. 3 - Actual: <FIRST_NAME>JESSICA</FIRST_NAME><LAST_NAME>JONES</LAST_NAME><ID>4</ID><SALARY>2345</SALARY>
541+
Row No. 3 - Expected: <ID>3</ID><FIRST_NAME>TONY</FIRST_NAME><LAST_NAME>STARK</LAST_NAME><SALARY>100000</SALARY>
542+
Row No. 4 - Extra: <GENDER>M</GENDER><FIRST_NAME>LUKE</FIRST_NAME><LAST_NAME>SKYWALKER</LAST_NAME><ID>2</ID><SALARY>1000</SALARY>
543+
at "UT3.TEST_CURSOR_COMPARE", line 22 ut.expect(l_actual).to_equal(l_expected);
544+
545+
546+
Finished in .053553 seconds
547+
1 tests, 1 failed, 0 errored, 0 disabled, 0 warning(s)
548+
```
549+
550+
utPLSQL identifies and reports on columns:
551+
- column misplacement
552+
- column data-type mismatch
553+
- extra/missing columns
554+
555+
When comparing rows utPLSQL:
556+
- reports only mismatched columns, when rows match
557+
- reports columns existing in both data-sets when whole row is not matching
558+
- reports whole extra (not expected) row from actual, when actual has extra rows
559+
- reports whole missing (expected) row from expected, when expected has extra rows
560+
561+
562+
### Object and collection data-type comparison examples
563+
564+
When comparing object type to object type or collection to collection, utPLSQL will check:
565+
- if data-types match
566+
- id data in the compared objects/collections are the same.
567+
568+
The diff functionality for objects and collections is similar to diff on cursors.
569+
When diffing objects/collections however, utPLSQL will not check attribute names and data-types.
570+
571+
Below examples demonstrate how to compare object and collection data-types.
572+
478573
Object type comparison.
479574
```sql
480575
create type department as object(name varchar2(30))

0 commit comments

Comments
 (0)