Added example for custom expectation-fail message

pesse · web-flow · commit 4381f756aac6 · 2017-09-28T17:31:05.000+02:00
Fixes #485
diff --git a/docs/userguide/expectations.md b/docs/userguide/expectations.md
@@ -471,3 +471,55 @@ end;
 ```
 Since NULL is neither *true* nor *not true*, both expectations will report failure.
 
+# Provide a custom error message
+Expectations allow you to provide a custom error message as second argument:
+````sql
+ut.expect( a_actual {data-type}, 'custom error message if expectation fails' ).to_{matcher};
+````
+The message is added to the normal error message returned by the matcher.
+
+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.
+
+## Dynamic tests example
+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:
+
+````sql
+procedure test_data_existance( i_tableName varchar2 ) 
+  as
+    v_count_real integer;
+    v_count_archive integer;
+  begin
+    
+    execute immediate 'select count(*) from ' || i_tablename || '' into v_count_real;
+    execute immediate 'select count(*) from ' || i_tablename || '_archive' into v_count_archive;
+
+    ut.expect( v_count_archive, 'error checking entry-count of ' || i_tablename || '_archive' ).to_( equal(1) );
+    ut.expect( v_count_real, 'error checking entry-count of ' || i_tablename ).to_( equal(0) );
+
+  end;
+
+ procedure test_archive_data
+  as
+  begin
+    -- Arrange
+   -- insert several data into real-tables here
+
+    -- Act
+    package_to_test.archive_data();
+
+    -- Assert
+    test_data_existance('TABLE_A');
+    test_data_existance('TABLE_B');
+    test_data_existance('TABLE_C');
+    test_data_existance('TABLE_D');
+end;
+````
+A failed output will look like this:
+````
+Failures:
+ 
+  1) test_archive_data
+      "error checking entry-count of TABLE_A_archive"
+      Actual: 2 (number) was expected to equal: 1 (number) 
+      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) );
+````
