From d730e39f7cdd3cdf1fddf5770ee71438b91d6c90 Mon Sep 17 00:00:00 2001
From: Jacek <jgebal@users.noreply.github.com>
Date: Wed, 25 Oct 2017 23:52:21 +0100
Subject: [PATCH 1/2] Added example of handling exceptions to documentation.

---
 docs/userguide/expectations.md | 58 ++++++++++++++++++++++++++++------
 1 file changed, 48 insertions(+), 10 deletions(-)

diff --git a/docs/userguide/expectations.md b/docs/userguide/expectations.md
index efd1ac5a4..14936147f 100644
--- a/docs/userguide/expectations.md
+++ b/docs/userguide/expectations.md
@@ -247,6 +247,22 @@ begin
 end;
 ```
 
+## match
+Validates that the actual value is matching the expected regular expression.
+
+Usage:
+```sql
+begin 
+  ut.expect( a_actual => '123-456-ABcd' ).to_match( a_pattern => '\d{3}-\d{3}-[a-z]', a_modifiers => 'i' );
+  ut.expect( 'some value' ).to_match( '^some.*' );
+  --or 
+  ut.expect( a_actual => '123-456-ABcd' ).to_( match( a_pattern => '\d{3}-\d{3}-[a-z]', a_modifiers => 'i' ) );
+  ut.expect( 'some value' ).to_( match( '^some.*' ) );
+end;
+```
+
+Parameters `a_pattern` and `a_modifiers` represent a valid regexp pattern accepted by [Oracle REGEXP_LIKE condition](https://docs.oracle.com/database/121/SQLRF/conditions007.htm#SQLRF00501)
+
 ## equal
 
 The equal matcher is a very restrictive matcher. It only returns true if the compared data-types are the same.
@@ -458,22 +474,44 @@ end;
 
 This test will fail as `v_actual` is not equal `v_expected`. 
 
-## match
-Validates that the actual value is matching the expected regular expression.
+# Expecting exceptions
+
+Below example illustrates how to write test to check for expected exceptions (thrown by tested code).
 
-Usage:
 ```sql
-begin 
-  ut.expect( a_actual => '123-456-ABcd' ).to_match( a_pattern => '\d{3}-\d{3}-[a-z]', a_modifiers => 'i' );
-  ut.expect( 'some value' ).to_match( '^some.*' );
-  --or 
-  ut.expect( a_actual => '123-456-ABcd' ).to_( match( a_pattern => '\d{3}-\d{3}-[a-z]', a_modifiers => 'i' ) );
-  ut.expect( 'some value' ).to_( match( '^some.*' ) );
+create or replace procedure divide(p_a number, p_b number) is 
+begin
+  return p_a / p_b; 
 end;
+/
+
+create or replace package test_divide is 
+  --%suite(Divide functionality)
+  
+  --%test(Raises exception when divisor is zero)
+  procedure divide_raises_zero_divisor;
+end;
+/
+create or replace package body test_divide is 
+  procedure divide_raises_zero_divisor is
+    l_my_number number;
+  begin
+    l_my_number := divide(1,0); -- PLSQL call throwing ORA-01476 exception
+    ut.fail('Expected exception but nothing was raised');
+  exception
+    when others then
+      ut.expect( sqlcode ).to_equal( -1476 );
+      ut.expect( sqlerrm ).to_match( 'equal to zero' );
+  end;
+end;
+/
 ```
 
-Parameters `a_pattern` and `a_modifiers` represent a valid regexp pattern accepted by [Oracle REGEXP_LIKE condition](https://docs.oracle.com/database/121/SQLRF/conditions007.htm#SQLRF00501)
+The call to `ut.fail` is required to make sure that the test fails, if we expect an exception, but the tested code does not throw any.
+
+The call to `ut.expect` uses `equal` matcher to check that the exception that was raised was exactly the one we were expecting to get in particular situation.
 
+Depending on the situation you might want to check for both `sqlcode` and `sqlerrm` or even check if no changes were made in DB tables.
 
 
 # Supported data types

From 80493a5e9cc04cf1fc59e64a2ca1d059b18f9655 Mon Sep 17 00:00:00 2001
From: Jacek <jgebal@users.noreply.github.com>
Date: Thu, 26 Oct 2017 21:06:21 +0100
Subject: [PATCH 2/2] Added example of handling exceptions to documentation.

---
 docs/userguide/expectations.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/userguide/expectations.md b/docs/userguide/expectations.md
index 14936147f..4349f90c6 100644
--- a/docs/userguide/expectations.md
+++ b/docs/userguide/expectations.md
@@ -511,7 +511,7 @@ The call to `ut.fail` is required to make sure that the test fails, if we expect
 
 The call to `ut.expect` uses `equal` matcher to check that the exception that was raised was exactly the one we were expecting to get in particular situation.
 
-Depending on the situation you might want to check for both `sqlcode` and `sqlerrm` or even check if no changes were made in DB tables.
+Depending on the situation you will want to check for `sqlcode`, `sqlerrm`, both or perform additional expectation checks to make sure nothing was changed by the called procedure in the database.
 
 
 # Supported data types