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

Skip to content

Commit c81bfca

Browse files
pessepesse
authored
Including suggested changes
replaced "error" with "failure", moved section as sub-section of Concepts, reworked Concepts slightly
1 parent 4381f75 commit c81bfca

1 file changed

Lines changed: 60 additions & 54 deletions

File tree

‎docs/userguide/expectations.md‎

Lines changed: 60 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -6,17 +6,18 @@ To achieve that, we use a combination of expectation and matcher to perform the
66
Example of a unit test procedure body.
77
```sql
88
begin
9-
ut.expect( 'the tested value' ).to_( equal('the expected value') );
9+
ut.expect( 'the tested value', 'optional custom failure message' ).to_( equal('the expected value') );
1010
end;
1111
```
1212

1313
Expectation is a set of the expected value(s), actual values(s) and the matcher(s) to run on those values.
14+
You can also add a custom failure message for an expectation.
1415

1516
Matcher defines the comparison operation to be performed on expected and actual values.
1617
Pseudo-code:
1718
```
18-
ut.expect( a_actual {data-type} ).to_( {matcher} );
19-
ut.expect( a_actual {data-type} ).not_to( {matcher} );
19+
ut.expect( a_actual {data-type} [, a_message {varchar2}] ).to_( {matcher} );
20+
ut.expect( a_actual {data-type} [, a_message {varchar2}] ).not_to( {matcher} );
2021
```
2122

2223
All matchers have shortcuts like:
@@ -25,6 +26,62 @@ All matchers have shortcuts like:
2526
ut.expect( a_actual {data-type} ).not_to_{matcher};
2627
```
2728

29+
## Providing a custom failure message
30+
Expectations allow you to provide a custom error message as second argument:
31+
````sql
32+
-- Pseudocode
33+
ut.expect( a_actual {data-type}, a_message {varchar2} ).to_{matcher};
34+
-- Example
35+
ut.expect( 'supercat', 'checked superhero-animal was not a dog' ).to_( equal('superdog') );
36+
````
37+
The message is added to the normal failure message returned by the matcher.
38+
39+
This is not only useful to give more detailed and specific information about a test, but also if you have some kind of dynamic tests.
40+
41+
### Dynamic tests example
42+
You have a bunch of tables and an archive-functionality for them and you want to test if the things you put into live-tables are removed from live-tables and present in archive-tables:
43+
44+
````sql
45+
procedure test_data_existance( i_tableName varchar2 )
46+
as
47+
v_count_real integer;
48+
v_count_archive integer;
49+
begin
50+
51+
execute immediate 'select count(*) from ' || i_tablename || '' into v_count_real;
52+
execute immediate 'select count(*) from ' || i_tablename || '_archive' into v_count_archive;
53+
54+
ut.expect( v_count_archive, 'failure checking entry-count of ' || i_tablename || '_archive' ).to_( equal(1) );
55+
ut.expect( v_count_real, 'failure checking entry-count of ' || i_tablename ).to_( equal(0) );
56+
57+
end;
58+
59+
procedure test_archive_data
60+
as
61+
begin
62+
-- Arrange
63+
-- insert several data into real-tables here
64+
65+
-- Act
66+
package_to_test.archive_data();
67+
68+
-- Assert
69+
test_data_existance('TABLE_A');
70+
test_data_existance('TABLE_B');
71+
test_data_existance('TABLE_C');
72+
test_data_existance('TABLE_D');
73+
end;
74+
````
75+
A failed output will look like this:
76+
````
77+
Failures:
78+
79+
1) test_archive_data
80+
"failure checking entry-count of TABLE_A_archive"
81+
Actual: 2 (number) was expected to equal: 1 (number)
82+
at "UT_TEST_PACKAGE.TEST_DATA_EXISTANCE", line 12 ut.expect( v_count_archive, 'failure checking entry-count of ' || i_tablename || '_archive' ).to_( equal(1) );
83+
````
84+
2885
# Matchers
2986
utPLSQL provides the following matchers to perform checks on the expected and actual values.
3087

@@ -471,55 +528,4 @@ end;
471528
```
472529
Since NULL is neither *true* nor *not true*, both expectations will report failure.
473530

474-
# Provide a custom error message
475-
Expectations allow you to provide a custom error message as second argument:
476-
````sql
477-
ut.expect( a_actual {data-type}, 'custom error message if expectation fails' ).to_{matcher};
478-
````
479-
The message is added to the normal error message returned by the matcher.
480-
481-
This is not only useful to give more detailed and specific information about a test, but also if you have some kind of dynamic tests.
482-
483-
## Dynamic tests example
484-
You have a bunch of tables and an archive-functionality for them and you want to test if the things you put into live-tables are removed from live-tables and present in archive-tables:
485531

486-
````sql
487-
procedure test_data_existance( i_tableName varchar2 )
488-
as
489-
v_count_real integer;
490-
v_count_archive integer;
491-
begin
492-
493-
execute immediate 'select count(*) from ' || i_tablename || '' into v_count_real;
494-
execute immediate 'select count(*) from ' || i_tablename || '_archive' into v_count_archive;
495-
496-
ut.expect( v_count_archive, 'error checking entry-count of ' || i_tablename || '_archive' ).to_( equal(1) );
497-
ut.expect( v_count_real, 'error checking entry-count of ' || i_tablename ).to_( equal(0) );
498-
499-
end;
500-
501-
procedure test_archive_data
502-
as
503-
begin
504-
-- Arrange
505-
-- insert several data into real-tables here
506-
507-
-- Act
508-
package_to_test.archive_data();
509-
510-
-- Assert
511-
test_data_existance('TABLE_A');
512-
test_data_existance('TABLE_B');
513-
test_data_existance('TABLE_C');
514-
test_data_existance('TABLE_D');
515-
end;
516-
````
517-
A failed output will look like this:
518-
````
519-
Failures:
520-
521-
1) test_archive_data
522-
"error checking entry-count of TABLE_A_archive"
523-
Actual: 2 (number) was expected to equal: 1 (number)
524-
at "UT_TEST_PACKAGE.TEST_DATA_EXISTANCE", line 12 ut.expect( v_count_archive, 'error checking entry-count of ' || i_tablename || '_archive' ).to_( equal(1) );
525-
````

0 commit comments

Comments
 (0)