Updating documentation.

Adding get_suites_info override.
utPLSQL · lwasylow · Apr 23, 2022 · Mar 18, 2022 · Mar 19, 2022 · Mar 23, 2022
commit 83dbdaa4ba7ef57dcc8d86771cdb66d6eec19e7c
diff --git a/docs/userguide/querying_suites.md b/docs/userguide/querying_suites.md
@@ -39,6 +39,16 @@ To get a full information about suite `TEST_STUFF` including suite description,
 select * from table(ut_runner.get_suites_info(USER, 'TEST_STUFF')) where item_type = 'UT_TEST';
 ```
 
+To get a full information about suites that have a path like  `ut3:tests.test_package_*` including suite description, all contexts and tests in a suite 
+```sql
+select * from table(ut_runner.get_suites_info('ut3:tests.test_package_*') where item_type = 'UT_TEST';
+```
+
+To get a full information about suites that have object name like  `test_package_*` including suite description, all contexts and tests in a suite 
+```sql
+select * from table(ut_runner.get_suites_info('test_package_*'));
+```
+
 ## Checking if schema contains tests
 
 Function `ut_runner.has_suites(a_owner)` returns boolean value indicating if given schema contains test suites.

diff --git a/docs/userguide/running-unit-tests.md b/docs/userguide/running-unit-tests.md
@@ -45,6 +45,10 @@ The **functions** can only be used in SELECT statements. They execute the specif
 ## ut.run procedures
 
 The examples below illustrate different ways and options to invoke `ut.run` procedures.
+As part of the syntax you can use a wildcard character `*` to call test by part of his name or to call few tests that match a call.
+Schema name is still mandat
10000
ory and cannot contain a wildcard character whether is a suitepath or object.
+
+
 
 ```sql
 alter session set current_schema=hr;
@@ -75,6 +79,14 @@ end;
 Executes all tests from all packages that are on the _com.my_org.my_project_ suitepath.
 Check the [annotations documentation](annotations.md) to find out about suitepaths and how they can be used to organize test packages for your project.
 
+```sql
+set serveroutput on
+begin
+  ut.run('hr:com*');
+end;
+```
+
+Executes all tests from all packages that are on suitepath starting with _com_.
 
 ```sql
 set serveroutput on
@@ -124,6 +136,22 @@ Using a list of items to execute allows you to execute a fine-grained set of tes
 
 List can be passed as a comma separated list or a list of *ut_varchar2_list objects* or as a list within ut_varchar2_list.
 
+```sql
+set serveroutput on
+begin
+  ut.run('hr.test*');
+end;
+```
+Executes all tests from schema _hr_ starting with name _test_.
+
+```sql
+set serveroutput on
+begin
+  ut.run('hr.test_apply_bonus.bonus_*');
+end;
+```
+Executes all test procedures from package _hr.test_apply_bonus_ that starting with _bonus_.
+
 
 **Note:**
 

diff --git a/source/api/ut_runner.pkb b/source/api/ut_runner.pkb
@@ -172,12 +172,31 @@ create or replace package body ut_runner is
     ut_annotation_manager.purge_cache(a_object_owner, a_object_type);
   end;
 
-  function get_suites_info(a_owner varchar2 := null, a_package_name varchar2 := null) return ut_suite_items_info pipelined is
+  function get_suites_info(a_owner varchar2, a_package_name varchar2) return ut_suite_items_info pipelined is
     l_cursor      sys_refcursor;
     l_results     ut_suite_items_info;
     c_bulk_limit  constant integer := 100;
+    l_path        varchar2(4000) := nvl(a_owner,sys_context('userenv', 'current_schema'))||'.'||nvl(a_package_name,'*');
   begin
-    l_cursor := ut_suite_manager.get_suites_info( nvl(a_owner,sys_context('userenv', 'current_schema')), a_package_name );
+
+    l_cursor := ut_suite_manager.get_suites_info(ut_varchar2_list(l_path));
+    loop
+      fetch l_cursor bulk collect into l_results limit c_bulk_limit;
+      for i in 1 .. l_results.count loop
+        pipe row (l_results(i));
+      end loop;
+      exit when l_cursor%notfound;
+    end loop;
+    close l_cursor;
+    return;
+  end;
+
+  function get_suites_info(a_path varchar2 := null) return ut_suite_items_info pipelined is
+    l_cursor       sys_refcursor;
+    l_results      ut_suite_items_info;
+    c_bulk_limit   constant integer := 100;
+  begin
+    l_cursor := ut_suite_manager.get_suites_info(ut_varchar2_list(nvl(a_path,sys_context('userenv', 'current_schema'))));
     loop
       fetch l_cursor bulk collect into l_results limit c_bulk_limit;
       for i in 1 .. l_results.count loop

diff --git a/source/api/ut_runner.pks b/source/api/ut_runner.pks
@@ -104,7 +104,14 @@ create or replace package ut_runner authid current_user is
   * @param   a_package_name name of unit test package to retrieve (optional), if NULL all unit test packages are returned
   * @return  ut_suite_items_info table of objects
   */
-  function get_suites_info(a_owner varchar2 := null, a_package_name varchar2 := null) return ut_suite_items_info pipelined;
+  function get_suites_info(a_owner varchar2, a_package_name varchar2) return ut_suite_items_info pipelined;
+
+  /**
+  * Returns a pipelined collection containing information about unit test suites and the tests contained in them
+  *
+  * @param   a_path a path from which we lookg for object or suite
+  */
+  function get_suites_info(a_path varchar2 := null) return ut_suite_items_info pipelined;
 
 
   /**

diff --git a/source/core/ut_suite_cache_manager.pkb b/source/core/ut_suite_cache_manager.pkb
@@ -148,16 +148,20 @@ create or replace package body ut_suite_cache_manager is
 
     return l_results;
   end;
-
+  /*
+    The object name is populate but suitepath not 
+    We will use that object and try to match.
+    We can pass also a wildcard this will result in one to many.
+
+    Get all data that do not have an wildcard and not require expanding.
+    We will take them as they are.
+      a)suite path is populated 
+      b)suite path and object is empty so schema name is by default ( or passed)
+  */   
   function expand_paths(a_schema_paths ut_path_items) return ut_path_items is
     l_schema_paths ut_path_items:= ut_path_items();
   begin   
-    with paths_to_expand as (
-      /*
-        The object name is populate but suitepath not 
-        We will use that object and try to match.
-        We can pass also a wildcard this will result in one to many.
-      */    
+    with paths_to_expand as ( 
       select /*+ no_parallel */ min(path) as suite_path,sp.schema_name as schema_name,nvl(c.object_name,sp.object_name) as object_name,
         nvl2(sp.procedure_name,c.name,null) as procedure_name
         from table(a_schema_paths) sp left outer join ut_suite_cache c
@@ -174,12 +178,6 @@ create or replace package body ut_suite_cache_manager is
         and c.path like replace(sp.suite_path,'*','%'))       
         where sp.suite_path is not null and instr(sp.suite_path,'*') > 0
       union all
-      /*
-        Get all data that do not have an wildcard and not require expanding.
-        We will take them as they are.
-        a)suite path is populated 
-        b)suite path and object is empty so schema name is by default ( or passed)
-      */
       select /*+ no_parallel */ sp.suite_path as suite_path,sp.schema_name,sp.object_name,sp.procedure_name as procedure_name
        from table(a_schema_paths) sp
        where 
@@ -205,7 +203,6 @@ create or replace package body ut_suite_cache_manager is
     Were the path is populated we need to make sure we dont return duplicates
     as the wildcard can produce multiple results from same path and 
     parents and child for each can be same resulting in duplicates    
-    TODO: Verify that this not duplicate with a expand paths.
   */  
   function get_suite_items (
     a_schema_paths ut_path_items
@@ -484,22 +481,25 @@ create or replace package body ut_suite_cache_manager is
   end;
 
   function get_cached_suite_info(
-    a_object_owner     varchar2,
-    a_object_name      varchar2
+    a_schema_paths     ut_path_items
+  ) return ut_suite_cache_rows is
+  begin
+    return get_cached_suite_rows( a_schema_paths );
+  end;
+
+  function get_suite_items_info(
+    a_suite_cache_items ut_suite_cache_rows
   ) return ut_suite_items_info is
-    l_cache_rows   ut_suite_cache_rows;
     l_results      ut_suite_items_info;
   begin
-    l_cache_rows := get_cached_suite_rows( a_object_owner => a_object_owner, a_object_name =>a_object_name );
     select /*+ no_parallel */ ut_suite_item_info(
              c.object_owner, c.object_name, c.name,
              c.description, c.self_type, c.line_no,
              c.path, c.disabled_flag, c.disabled_reason, c.tags
              )
       bulk collect into l_results
-      from table(l_cache_rows) c;
-
-    return l_results;
+      from table(a_suite_cache_items) c;
+      return l_results;
   end;
 
   function get_cached_packages(

diff --git a/source/core/ut_suite_cache_manager.pks b/source/core/ut_suite_cache_manager.pks
@@ -68,10 +68,13 @@ create or replace package ut_suite_cache_manager authid definer is
   * Not to be used publicly. Used internally for building suites info.
   */
   function get_cached_suite_info(
-    a_object_owner     varchar2,
-    a_object_name      varchar2
+    a_schema_paths     ut_path_items
+  ) return ut_suite_cache_rows;
+
+  function get_suite_items_info(
+    a_suite_cache_items ut_suite_cache_rows
   ) return ut_suite_items_info;
-
+  
   /*
   * Retrieves list of cached suite packages.
   * Returned data is not filtered by user access rights.

diff --git a/source/core/ut_suite_manager.pkb b/source/core/ut_suite_manager.pkb
@@ -533,8 +533,6 @@ create or replace package body ut_suite_manager is
     l_schema_paths       ut_path_items;
     l_reconcile_paths    ut_path_items;
     l_schema             varchar2(4000);
-    l_suites_count       pls_integer := 0;
-    l_index              varchar2(4000 char);
   begin
     ut_event_manager.trigger_event('configure_execution_by_path - start');
     a_suites := ut_suite_items();    
@@ -567,37 +565,34 @@ create or replace package body ut_suite_manager is
   end configure_execution_by_path;
 
   function get_suites_info(
-    a_owner_name     varchar2, 
-    a_package_name   varchar2 := null
+    a_paths     ut_varchar2_list
   ) return sys_refcursor is
-    l_result         sys_refcursor;
-    l_all_suite_info ut_suite_items_info;
-    l_owner_name     varchar2(250) := ut_utils.qualified_sql_name(a_owner_name);
-    l_package_name   varchar2(250) := ut_utils.qualified_sql_name(a_package_name);
+    l_result             sys_refcursor;
+    l_all_suite_info     ut_suite_items_info;
+    l_schema_names       ut_varchar2_rows;
+    l_schema_paths       ut_path_items;
+    l_paths              ut_varchar2_list := a_paths; 
+    l_schema             varchar2(4000);
+    l_unfiltered_rows    ut_suite_cache_rows;
+    l_filtered_rows      ut_suite_cache_rows;
+
   begin
+    l_schema_names := resolve_schema_names(l_paths);
+    --refresh cache
+    l_schema := l_schema_names.first;
+    while l_schema is not null loop
+      refresh_cache(upper(l_schema_names(l_schema)));
+      l_schema := l_schema_names.next(l_schema);
+    end loop;
+    l_schema_paths := ut_suite_cache_manager.get_schema_paths(l_paths);
+    l_unfiltered_rows := ut_suite_cache_manager.get_cached_suite_info(l_schema_paths);
+    l_filtered_rows := get_filtered_cursor(l_unfiltered_rows);
+    l_all_suite_info := ut_suite_cache_manager.get_suite_items_info(l_filtered_rows);
+    open l_result for
+      select /*+ no_parallel */ value(c)
+        from table(l_all_suite_info) c
+        order by c.object_owner, c.object_name, c.item_line_no;
 
-    refresh_cache(l_owner_name);
-
-    l_all_suite_info := ut_suite_cache_manager.get_cached_suite_info( l_owner_name, l_package_name );
-    if can_skip_all_objects_scan( l_owner_name ) then
-      open l_result for
-        select /*+ no_parallel */ value(c)
-          from table(l_all_suite_info) c
-         order by c.object_owner, c.object_name, c.item_line_no;
-    else
-      open l_result for
-        select /*+ no_parallel */ value(c)
-          from table(l_all_suite_info) c
-         where exists
-                 ( select 1
-                     from all_objects a
-                    where a.object_name = c.object_name
-                      and a.owner       = c.object_owner
-                      and a.object_type = 'PACKAGE'
-                 )
-            or c.item_type = 'UT_LOGICAL_SUITE'
-         order by c.object_owner, c.object_name, c.item_line_no;
-    end if;
     return l_result;
   end;
 

diff --git a/source/core/ut_suite_manager.pks b/source/core/ut_suite_manager.pks
@@ -79,15 +79,11 @@ create or replace package ut_suite_manager authid current_user is
   /**
   * Returns a ref cursor containing information about unit test suites and the tests contained in them
   *
-  * @param   a_owner          owner of unit tests to retrieve
-  * @param   a_package_name   name of test package (optional)
-  * @param   a_procedure_name name of test procedure (optional)
-  * @return  ut_suite_items_info table of objects
+  * @param   a_paths          list of paths to be resolved and return a suites.
   */
   function get_suites_info(
-    a_owner_name     varchar2, 
-    a_package_name   varchar2 := null
-  ) return sys_refcursor;
+    a_paths     ut_varchar2_list
+  ) return sys_refcursor; 
 
   /**
   * Returns true if given suite item exists