Added test info API to ut_runner returning ref-cursor with columns:

OWNER, PACKAGE_NAME, PROCEDURE_NAME, ANNOTATION, ANNOTATION_TEXT

Resolves #571

docs/userguide/annotations.md

@@ -224,13 +224,13 @@ The annotation cache is checked for staleness and refreshed automatically on eve
 
 If you are in a situation where your database is controlled via CI/CD server and is refreshed/wiped before each run of your tests, consider building the annotation cache upfront and taking a snapshot of the database after the cache has been refreshed.
 
-To build the annotation cache without actually invoking any tests, call `ut_runner.rebuild_annotation_cache(a_object_owner, a_object_type)` for every unit test owner for which you want to have the annotation cache prebuilt.
+To build the annotation cache without actually invoking any tests, call `ut_runner.rebuild_annotation_cache(a_object_owner)` for every unit test owner for which you want to have the annotation cache prebuilt.
 Example:
 ```sql
-exec ut_runner.rebuild_annotation_cache('HR', 'PACKAGE');
+exec ut_runner.rebuild_annotation_cache('HR');
 ```
 
-To purge the annotation cache call `ut_runner.purge_cache(a_object_owner, a_object_type)`.
+To purge the annotation cache call `ut_runner.purge_cache(a_object_owner)`.
 Example:
 ```sql
 exec ut_runner.purge_cache('HR', 'PACKAGE');

source/api/ut_runner.pkb

@@ -106,14 +106,31 @@ create or replace package body ut_runner is
     end if;
   end;
 
-  procedure rebuild_annotation_cache(a_object_owner varchar2, a_object_type varchar2) is
+  procedure rebuild_annotation_cache(a_object_owner varchar2, a_object_type varchar2 := null) is
   begin
-    ut_annotation_manager.rebuild_annotation_cache(a_object_owner, a_object_type);
+    ut_annotation_manager.rebuild_annotation_cache(a_object_owner, coalesce(a_object_type,'PACKAGE'));
   end;
 
-  procedure purge_cache(a_object_owner varchar2, a_object_type varchar2) is
+  procedure purge_cache(a_object_owner varchar2, a_object_type varchar2 := null) is
   begin
-    ut_annotation_manager.purge_cache(a_object_owner, a_object_type);
+    ut_annotation_manager.purge_cache(a_object_owner, coalesce(a_object_type,'PACKAGE'));
+  end;
+
+  function get_unit_tests_info(a_owner varchar2, a_package_name varchar2 := null) return sys_refcursor is
+    l_result   sys_refcursor;
+    l_filter   varchar2(100);
+    l_ut_owner varchar2(250) := ut_utils.ut_owner;
+  begin
+    l_filter := case when a_package_name is null then 'is null' else '= o.object_name' end;
+    open l_result for
+      'select o.object_owner owner, o.object_name as package_name, upper(a.subobject_name) as procedure_name,' ||
+      '       a.name annotation, a.text annotation_text' ||
+      '  from table('||l_ut_owner||'.ut_annotation_manager.get_annotated_objects(:a_owner, ''PACKAGE'')) o,' ||
+      '       table(o.annotations) a' ||
+      ' where exists (select 1 from table(o.annotations) s where s.name=''suite'') ' ||
+      '  and :a_package_name ' || l_filter
+    using a_owner, a_package_name;
+    return l_result;
   end;
 
 end ut_runner;

source/api/ut_runner.pks

@@ -62,23 +62,32 @@ create or replace package ut_runner authid current_user is
   );
 
   /**
-   * 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);
+  * Rebuilds annotation cache for a specified schema and object type.
+  *  It can be used to speedup execution of utPLSQL on a given schema
+  *   if it is executed before initial call made to `ut.run` or `ut_runner.run` procedure.
+  *
+  * @param a_object_owner owner of objects to get annotations for
+  * @param a_object_type  optional type of objects to get annotations for (defaults to 'PACKAGE')
+  */
+  procedure rebuild_annotation_cache(a_object_owner varchar2, a_object_type varchar2 := null);
 
   /**
-   * 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);
+  * 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  optional type of objects to purge annotations for (defaults to 'PACKAGE')
+  */
+  procedure purge_cache(a_object_owner varchar2, a_object_type varchar2 := null);
+
+
+  /**
+  * Returns a ref_cursor containing information about unit tests package(s) for given owner
+  *
+  * @param   a_owner        owner of unit tests to retrieve
+  * @param   a_package_name optional name of unit test package to retrieve, if NULLm all unit test packages are returned
+  * @return  sys_refcursor  columns: OWNER, PACKAGE_NAME, PROCEDURE_NAME, ANNOTATION, ANNOTATION_TEXT
+  */
+  function get_unit_tests_info(a_owner varchar2, a_package_name varchar2 := null) return sys_refcursor;
 
 end ut_runner;
 /

test/test_ut_runner.pkb → test/api/test_ut_runner.pkb

@@ -258,5 +258,22 @@ end;';
     ut.expect(l_actual).to_equal(0);
   end;
 
+  procedure test_get_unit_tests_info is
+    l_expected sys_refcursor;
+    l_actual   sys_refcursor;
+  begin
+    --Arrange
+    open l_expected for
+      select 'UT3_TESTER' owner, 'DUMMY_TEST_PACKAGE' package_name,
+             to_char(null) procedure_name, 'suite' annotation, 'dummy_test_suite' annotation_text from dual union all
+      select 'UT3_TESTER', 'DUMMY_TEST_PACKAGE', to_char(null), 'rollback', 'manual' from dual union all
+      select 'UT3_TESTER', 'DUMMY_TEST_PACKAGE', 'SOME_DUMMY_TEST_PROCEDURE', 'test', 'dummy_test' from dual union all
+      select 'UT3_TESTER', 'DUMMY_TEST_PACKAGE', 'SOME_DUMMY_TEST_PROCEDURE', 'beforetest', 'some_procedure' from dual;
+    --Act
+    l_actual := ut3.ut_runner.get_unit_tests_info('UT3_TESTER','DUMMY_TEST_PACKAGE');
+    --Assert
+    ut.expect(l_actual).to_equal(l_expected);
+  end;
+
 end;
 /

test/test_ut_runner.pks → test/api/test_ut_runner.pks

@@ -1,7 +1,7 @@
 create or replace package test_ut_runner is
 
   --%suite(ut_runner)
-  --%suitepath(utplsql)
+  --%suitepath(utplsql.api)
   --%rollback(manual)
 
   --%test(transaction stays open after the run if it was opened before the run)
@@ -43,5 +43,10 @@ create or replace package test_ut_runner is
   --%aftertest(cleanup_cache)
   procedure test_rebuild_cache_schema_type;
 
+  --%test(get_unit_tests_info returns a cursor containing records for a newly created test)
+  --%beforetest(setup_cache_objects)
+  --%aftertest(cleanup_cache)
+  procedure test_get_unit_tests_info;
+
 end;
 /

test/install_tests.sql

@@ -27,7 +27,7 @@ whenever oserror exit failure rollback
 @@core/expectations/test_expect_not_to_be_null.pks
 @@core/expectations/test_expect_to_be_not_null.pks
 @@core/expectations/test_expect_to_be_null.pks
-@@test_ut_runner.pks
+@@api/test_ut_runner.pks
 @@core/annotations/test_annotation_manager.pks
 @@core/test_ut_suite.pks
 @@core/test_ut_test.pks
@@ -46,7 +46,7 @@ whenever oserror exit failure rollback
 @@core/expectations/test_expect_not_to_be_null.pkb
 @@core/expectations/test_expect_to_be_not_null.pkb
 @@core/expectations/test_expect_to_be_null.pkb
-@@test_ut_runner.pkb
+@@api/test_ut_runner.pkb
 @@core/annotations/test_annotation_manager.pkb
 @@core/test_ut_suite.pkb
 @@core/test_ut_test.pkb