Added documentation for new functionality.

jgebal · jgebal · commit eeae79be2df3 · 2018-11-17T21:55:19.000Z
Added default value for owner, when calling `get_suites_info`
diff --git a/docs/index.md b/docs/index.md
@@ -10,6 +10,7 @@ The framework follows industry standards and best patterns of modern Unit Testin
        - [Expectations](userguide/expectations.md)
        - [Advanced data comparison](userguide/advanced_data_comparison.md)
        - [Running unit tests](userguide/running-unit-tests.md)
+       - [Querying for test suites](userguide/querying_suites.md)
        - [Testing best pracitces](userguide/best-practices.md)
        - [Upgrade utPLSQL](userguide/upgrade.md)
   - Reporting
diff --git a/docs/userguide/querying_suites.md b/docs/userguide/querying_suites.md
@@ -0,0 +1,83 @@
+# Qyerying for test suites
+
+
+## Obtaining information about suites 
+
+utPLSQL framework provides ability to read inforamtion about unit test suites that exist in a schema.
+
+Pipelined table function `ut_runner.get_suites_info(a_owner, a_package_name)` allows you to retrieve information about:
+
+- all suites that exist in a given user/schema
+- individual test suite pacakage
+
+Querying the data from function provides the follwing details:
+
+- `object_owner`     - the owner of test suite packages
+- `object_name`      - the name of test suite package
+- `item_name`        - the name of suite/test
+- `item_description` - the description of suite/suite item
+- `item_type`        - the type of item (UT_SUITE/UT_SUITE_CONTEXT/UT_TEST/UT_LOGICAL_SUITE)
+- `item_line_no`     - line_number where annotation identifying the item exists
+- `path`             - suitepath of the item
+- `disabled_flag`    - (0/1) indicator if item is disabled by --%disabled annotation
+    
+To get list of all test suites in current schema 
+```sql
+select * from table(ut_runner.get_suites_info()) where item_type = 'UT_SUITE';
+``` 
+
+To get list of all tests for test suite `TEST_STUFF` in current user schema  
+```sql
+select * from table(ut_runner.get_suites_info(USER, 'TEST_STUFF')) where item_type = 'UT_TEST';
+``` 
+
+To get a full information about suite `TEST_STUFF` including suite description, all contexts and tests in a suite  
+```sql
+select * from table(ut_runner.get_suites_info(USER, 'TEST_STUFF')) where item_type = 'UT_TEST';
+``` 
+
+## Checking if schema contains tests
+
+Function `ut_runner.has_suites(a_owner)` returns boolean value indicating if given schema contains test suites.
+
+Example:
+```sql
+begin
+  if ut_runner.has_suites(USER) then
+    dbms_output.put_line( 'User '||USER||' owns test suites' );
+  else
+    dbms_output.put_line( 'User '||USER||' does not own test suites' );
+  end if;
+end;
+```
+
+## Checking if package is a test suite
+
+Function `ut_runner.is_suite(a_owner, a_package_name) ` returns boolean value indicating if given package is a test suites.
+
+Example:
+```sql
+begin
+  if ut_runner.is_suite(USER,'TEST_STUFF') then
+    dbms_output.put_line( 'Package '||USER||'.TEST_STUFF is a test suite' );
+  else
+    dbms_output.put_line( 'Package '||USER||'.TEST_STUFF is not a test suite' );
+  end if;
+end;
+```
+
+## Checking if procedure is a test within a suite
+
+Function `ut_runner.is_test(a_owner, a_package_name, a_procedure_name) ` returns boolean value indicating if given package is a test suites.
+
+Example:
+```sql
+begin
+  if ut_runner.is_test(USER,'TEST_STUFF','A_TEST_TO_CHECK_STUFF') then
+    dbms_output.put_line( 'Procedure '||USER||'.TEST_STUFF.A_TEST_TO_CHECK_STUFF is a test' );
+  else
+    dbms_output.put_line( 'Procedure '||USER||'.TEST_STUFF.A_TEST_TO_CHECK_STUFF is not a test' );
+  end if;
+end;
+```
+
diff --git a/docs/userguide/running-unit-tests.md b/docs/userguide/running-unit-tests.md
@@ -1,12 +1,12 @@
 # Running tests
 
-The utPLSQL framework provides two main entry points to run unit tests from within the database: 
+utPLSQL framework provides two main entry points to run unit tests from within the database: 
 
 - `ut.run` procedures and functions
 - `ut_runner.run` procedures
 
 These two entry points differ in purpose and behavior.
-Most of the time you will want to use `ut.run` as `ut_runner` is designed for API integration and does not output the results to the screen directly.
+Most of the time you will want to use `ut.run` as `ut_runner.run` is designed for API integration and does not display the results to the screen.
 
 # Running from CI servers and command line
 
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -18,6 +18,7 @@ nav:
        - Expectations: userguide/expectations.md
        - Advanced data comparison: userguide/advanced_data_comparison.md
        - Running unit tests: userguide/running-unit-tests.md
+       - Querying for test suites: userguide/querying_suites.md
        - Testing best pracitces: userguide/best-practices.md
        - Upgrade utPLSQL: userguide/upgrade.md
   - Reporting:
diff --git a/source/api/ut_runner.pkb b/source/api/ut_runner.pkb
@@ -165,12 +165,12 @@ 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, a_package_name varchar2 := null) return ut_suite_items_info pipelined is
+  function get_suites_info(a_owner varchar2 := null, a_package_name varchar2 := null) return ut_suite_items_info pipelined is
     l_cursor      sys_refcursor;
     l_results     ut_suite_items_info;
     c_bulk_limit  constant integer := 10;
   begin
-    l_cursor := ut_suite_manager.get_suites_info( a_owner, a_package_name );
+    l_cursor := ut_suite_manager.get_suites_info( nvl(a_owner,sys_context('userenv', 'current_schema')), a_package_name );
     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
@@ -91,11 +91,11 @@ create or replace package ut_runner authid current_user is
   /**
   * Returns a pipelined collection 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 optional name of unit test package to retrieve, if NULLm all unit test packages are returned
+  * @param   a_owner        owner of unit tests to retrieve (optional), if NULL, current schema is used
+  * @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, a_package_name varchar2 := null) return ut_suite_items_info pipelined;
+  function get_suites_info(a_owner varchar2 := null, a_package_name varchar2 := null) return ut_suite_items_info pipelined;
 
 
   /**
diff --git a/test/api/test_ut_runner.pkb b/test/api/test_ut_runner.pkb
@@ -284,7 +284,7 @@ end;';
              'dummy_test_package.some_dummy_test_procedure' path, 0 disabled_flag
         from dual;
     --Act
-    open l_actual for select * from table(ut3.ut_runner.get_suites_info('UT3_TESTER','DUMMY_TEST_PACKAGE'));
+    open l_actual for select * from table(ut3.ut_runner.get_suites_info(NULL,'DUMMY_TEST_PACKAGE'));
     --Assert
     ut.expect(l_actual).to_equal(l_expected);
   end;
