Fixed test execution on 12.1.

Added wrapper procedures `purge_cache`, `rebuild_annotation_cache` in `ut_runner` Added tests for wrappers. Updated documentation for annotation cache calls.
utPLSQL · jgebal · Oct 26, 2017 · Oct 6, 2017 · Oct 6, 2017 · Oct 7, 2017
commit 5967a3afbaf6c1e071738b4779af49ddfceba29b
diff --git a/docs/userguide/annotations.md b/docs/userguide/annotations.md
@@ -214,3 +214,26 @@ When processing the test suite `test_pkg` defined in [Example of annotated test
   rollback to savepoint 'beforeall'
 
 ```
+
+# Annotation cache
+
+utPLSQL needs to scan sources of package specifications to identify and parse annotations.
+To improve framework startup time, specially when dealing with database users owning large amount of packages the framework has build-in persistent cache for annotations.
+
+Cache is checked for staleness and refreshed automatically on every run.
+The initial startup of utPLSQL for a schema will take longer than consecutive executions.
+
+If you're in situation, where your database is controlled via CI/CD server and gets refreshed/wiped before each run of your tests, 
+consider building upfront and creating the snapshot of our database after the cache was refreshed.
+
+To build annotation cache without actually invoking any tests, call `ut_runner.rebuild_annotation_cache(a_object_owner, a_object_type)` sql block for every unit test owner that you want to have annotations cache prebuilt.
+
+Example:
+```sql
+exec ut_runner.rebuild_annotation_cache('HR', 'PACKAGE');
+```
+
+To purge annotations cache call: 
+```sql
+exec ut_runner.purge_cache('HR', 'PACKAGE');
+```
diff --git a/source/api/ut_runner.pkb b/source/api/ut_runner.pkb
@@ -119,5 +119,15 @@ create or replace package body ut_runner is
     );
   end;
 
+  procedure rebuild_annotation_cache(a_object_owner varchar2, a_object_type varchar2) is
+  begin
+    ut_annotation_manager.rebuild_annotation_cache(a_object_owner, a_object_type);
+  end;
+
+  procedure purge_cache(a_object_owner varchar2, a_object_type varchar2) is
+  begin
+    ut_annotation_manager.purge_cache(a_object_owner, a_object_type);
+  end;
+
 end ut_runner;
 /
diff --git a/source/api/ut_runner.pks b/source/api/ut_runner.pks
@@ -58,5 +58,24 @@ create or replace package ut_runner authid current_user is
     a_include_objects ut_varchar2_list := null, a_exclude_objects ut_varchar2_list := null, a_fail_on_errors boolean default false
   );
 
+  /**
+   * Rebuilds annotation cache for a specified schema and object type.
+   *  The procedure is called internally by `get_annotated_objects` function.
+   *  It can be used to speedup initial execution of utPLSQL on a given schema
+   *   if it is executed before any call is made to `ut.run` or `ut_runner.run` procedure.
+   *
+   * @param a_object_owner owner of objects to get annotations for
+   * @param a_object_type type of objects to get annotations for
+   */
+  procedure rebuild_annotation_cache(a_object_owner varchar2, a_object_type varchar2);
+
+  /**
+   * Removes cached information about annotations for objects of specified type and specified owner
+   *
+   * @param a_object_owner owner of objects to purge annotations for
+   * @param a_object_type type of objects to purge annotations for
+   */
+  procedure purge_cache(a_object_owner varchar2, a_object_type varchar2);
+
 end ut_runner;
 /
diff --git a/test/ut_annotation_manager/test_annotation_manager.pkb b/test/ut_annotation_manager/test_annotation_manager.pkb
@@ -64,39 +64,6 @@ create or replace package body test_annotation_manager is
     commit;
   end;
 
-  procedure setup_cache is
-    pragma autonomous_transaction;
-  begin
-    create_dummy_test_package();
-    execute immediate q'[create or replace procedure dummy_test_procedure as
-        --%some_annotation(some_text)
-        --%rollback(manual)
-      begin
-        null;
-      end;]';
-    execute immediate q'[create or replace procedure ut3.dummy_test_procedure as
-        --%some_annotation(some_text)
-        --%rollback(manual)
-      begin
-        null;
-      end;]';
-    ut3.ut_annotation_manager.rebuild_annotation_cache(user,'PACKAGE');
-    ut3.ut_annotation_manager.rebuild_annotation_cache(user,'PROCEDURE');
-    ut3.ut_annotation_manager.rebuild_annotation_cache('UT3','PROCEDURE');
-  end;
-
-  procedure cleanup_cache is
-    pragma autonomous_transaction;
-  begin
-    delete from ut3.ut_annotation_cache_info
-     where object_type = 'PROCEDURE' and object_owner in ('UT3',user)
-        or object_type = 'PACKAGE' and object_owner = user and object_name = 'DUMMY_TEST_PACKAGE';
-    drop_dummy_test_package();
-    execute immediate q'[drop procedure dummy_test_procedure]';
-    execute immediate q'[drop procedure ut3.dummy_test_procedure]';
-  end;
-
-
 
   procedure add_new_package is
     l_actual_cache_id integer;
@@ -285,36 +252,5 @@ create or replace package body test_annotation_manager is
     ut.expect(l_actual).to_be_empty();
   end;
 
-  procedure test_purge_schema_type is
-    l_actual sys_refcursor;
-  begin
-
-    open l_actual for
-      select * from ut3.ut_annotation_cache_info
-       where object_owner = user and object_type = 'PROCEDURE';
-    ut.expect(l_actual).not_to_be_empty();
-
-    --Act
-    ut3.ut_annotation_cache_manager.purge_cache(user,'PROCEDURE');
-
-    --Assert
-    open l_actual for
-      select * from ut3.ut_annotation_cache_info
-       where object_owner = user and object_type = 'PROCEDURE';
-    --Cache purged for object owner/type
-    ut.expect(l_actual).to_be_empty();
-    open l_actual for
-      select * from ut3.ut_annotation_cache_info
-       where object_owner = user and object_type = 'PACKAGE';
-    --Cache not purged for other types
-    ut.expect(l_actual).not_to_be_empty();
-    open l_actual for
-      select * from ut3.ut_annotation_cache_info
-       where object_owner != user and object_type = 'PROCEDURE';
-    --Cache not purged for other owners
-    ut.expect(l_actual).not_to_be_empty();
-
-  end;
-
 end test_annotation_manager;
 /
diff --git a/test/ut_annotation_manager/test_annotation_manager.pks b/test/ut_annotation_manager/test_annotation_manager.pks
@@ -42,13 +42,5 @@ create or replace package test_annotation_manager is
   --%beforetest(create_dummy_test_package)
   procedure no_data_for_dropped_object;
 
-  procedure setup_cache;
-  procedure cleanup_cache;
-
-  --%test(Purges cache for a given schema and object type)
-  --%beforetest(setup_cache)
-  --%aftertest(cleanup_cache)
-  procedure test_purge_schema_type;
-
 end test_annotation_manager;
 /
diff --git a/test/ut_runner/test_ut_runner.pkb b/test/ut_runner/test_ut_runner.pkb
@@ -1,5 +1,50 @@
 create or replace package body test_ut_runner is
 
+  procedure setup_cache_objects is
+    pragma autonomous_transaction;
+  begin
+    execute immediate q'[create or replace package dummy_test_package as
+        --%suite(dummy_test_suite)
+        --%rollback(manual)
+
+        --%test(dummy_test)
+        --%beforetest(some_procedure)
+        procedure some_dummy_test_procedure;
+      end;]';
+    execute immediate q'[create or replace procedure dummy_test_procedure as
+        --%some_annotation(some_text)
+        --%rollback(manual)
+      begin
+        null;
+      end;]';
+    execute immediate q'[create or replace procedure ut3.dummy_test_procedure as
+        --%some_annotation(some_text)
+        --%rollback(manual)
+      begin
+        null;
+      end;]';
+  end;
+
+  procedure setup_cache is
+    pragma autonomous_transaction;
+  begin
+    setup_cache_objects();
+    ut3.ut_annotation_manager.rebuild_annotation_cache(user,'PACKAGE');
+    ut3.ut_annotation_manager.rebuild_annotation_cache(user,'PROCEDURE');
+    ut3.ut_annotation_manager.rebuild_annotation_cache('UT3','PROCEDURE');
+  end;
+
+  procedure cleanup_cache is
+    pragma autonomous_transaction;
+  begin
+    delete from ut3.ut_annotation_cache_info
+     where object_type = 'PROCEDURE' and object_owner in ('UT3',user)
+        or object_type = 'PACKAGE' and object_owner = user and object_name = 'DUMMY_TEST_PACKAGE';
+    execute immediate q'[drop package dummy_test_package]';
+    execute immediate q'[drop procedure dummy_test_procedure]';
+    execute immediate q'[drop procedure ut3.dummy_test_procedure]';
+  end;
+
   procedure create_test_spec
   as
     pragma autonomous_transaction;
@@ -160,5 +205,58 @@ end;';
     drop_test_package();
   end;
 
+  procedure test_purge_cache_schema_type is
+    l_actual sys_refcursor;
+  begin
+
+    open l_actual for
+      select * from ut3.ut_annotation_cache_info
+       where object_owner = user and object_type = 'PROCEDURE';
+    ut.expect(l_actual).not_to_be_empty();
+
+    --Act
+    ut3.ut_runner.purge_cache(user,'PROCEDURE');
+
+    --Assert
+    open l_actual for
+      select * from ut3.ut_annotation_cache_info
+       where object_owner = user and object_type = 'PROCEDURE';
+    --Cache purged for object owner/type
+    ut.expect(l_actual).to_be_empty();
+    open l_actual for
+      select * from ut3.ut_annotation_cache_info
+       where object_owner = user and object_type = 'PACKAGE';
+    --Cache not purged for other types
+    ut.expect(l_actual).not_to_be_empty();
+    open l_actual for
+      select * from ut3.ut_annotation_cache_info
+       where object_owner = 'UT3' and object_type = 'PROCEDURE';
+    --Cache not purged for other owners
+    ut.expect(l_actual).not_to_be_empty();
+
+  end;
+
+  procedure test_rebuild_cache_schema_type is
+    l_actual integer;
+  begin
+    --Act
+    ut3.ut_annotation_manager.rebuild_annotation_cache(user,'PACKAGE');
+    --Assert
+    select count(1) into l_actual
+      from ut3.ut_annotation_cache_info i
+      join ut3.ut_annotation_cache c on c.cache_id = i.cache_id
+     where object_owner = user and object_type = 'PACKAGE' and object_name = 'DUMMY_TEST_PACKAGE';
+    --Rebuild cache for user/packages
+    ut.expect(l_actual).to_equal(4);
+
+    select count(1) into l_actual
+      from ut3.ut_annotation_cache_info i
+      join ut3.ut_annotation_cache c on c.cache_id = i.cache_id
+     where object_owner = 'UT3' and object_type = 'PROCEDURE';
+
+    --Did not rebuild cache for ut3/procedures
+    ut.expect(l_actual).to_equal(0);
+  end;
+
 end;
 /
diff --git a/test/ut_runner/test_ut_runner.pks b/test/ut_runner/test_ut_runner.pks
@@ -28,5 +28,20 @@ create or replace package test_ut_runner is
   --%test(does not consume dbms_output from before the run)
   procedure run_keep_dbms_output_buffer;
 
+  procedure setup_cache;
+  procedure cleanup_cache;
+
+  --%test(Purges cache for a given schema and object type)
+  --%beforetest(setup_cache)
+  --%aftertest(cleanup_cache)
+  procedure test_purge_cache_schema_type;
+
+  procedure setup_cache_objects;
+
+  --%test(Rebuilds cache for a given schema and object type)
+  --%beforetest(setup_cache_objects)
+  --%aftertest(cleanup_cache)
+  procedure test_rebuild_cache_schema_type;
+
 end;
 /