utPLSQL · jgebal · Nov 18, 2018 · Oct 30, 2018 · Nov 2, 2018 · Nov 4, 2018
diff --git a/.gitignore b/.gitignore
@@ -15,6 +15,7 @@ node_modules/
 utPLSQL_latest_release/
 utPLSQL-cli/
 development/env.sh
+development/*.jar
 *.log
 
 # exclusions based on artifacts created via actions documented in CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -89,14 +89,18 @@ export CONNECTION_STR=127.0.0.1:1521/xe # Adjust the connect string
 export ORACLE_PWD=oracle # Adjust your local SYS password
 ```
 
+### Download Oracle JDBC drivers
+
+Download `ojdbc8-xxx.jar` and `orai18n-xxx.jar` from [Oracle](https://www.oracle.com/technetwork/database/features/jdbc/jdbc-ucp-122-3110062.html).
+Place them in `development` directory of the project.
+
+
 ### Download utPLSQL release sources and utplsq-cli
 
 The below script is fetching latest release version from utPLSQL repository. Latest release version is used for self-testing.
 ```bash
 development/refresh_sources.sh
 ```
-> **Important notice:**
-> You'll have to provide the ojdbc.jar in the folder utPLSQL-cli/lib manually due to Oracle licensing restrictions.
 
 ### Setup local database for utPLSQL development
 

diff --git a/development/refresh_sources.sh b/development/refresh_sources.sh
@@ -16,3 +16,4 @@ curl -Lk -o utPLSQL-cli.zip https://github.com/utPLSQL/utPLSQL-cli/releases/down
 # unzip utPLSQL-cli and remove the zip file
 unzip utPLSQL-cli.zip && chmod u+x utPLSQL-cli/bin/utplsql && rm utPLSQL-cli.zip
 
+cp development/*.jar utPLSQL-cli/lib/
diff --git a/development/releasing.md b/development/releasing.md
@@ -9,7 +9,8 @@ To create a release:
    - wait for th build to complete successfully
    - merge the release branch to master and wait for master build to complete successfully
    - create a release from the master branch using [github releases page](https://github.com/utPLSQL/utPLSQL/releases) and populate release description using information found on the issues and pull requests since previous release.
-   To find issues closed after certain date use [advanced filters](https://help.github.com/articles/searching-issues-and-pull-requests/#search-by-open-or-closed-state) 
+   To find issues closed after certain date use [advanced filters](https://help.github.com/articles/searching-issues-and-pull-requests/#search-by-open-or-closed-state). 
+   Example: [`is:issue closed:>2018-07-22`](https://github.com/utPLSQL/utPLSQL/issues?utf8=%E2%9C%93&q=is%3Aissue+closed%3A%3E2018-07-22+) 
 
 The following will happen:
    - build executed on branch `release/vX.Y.Z-[something]` updates files `sonar-project.properties`, `VERSION` with project version derived from the release branch name

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/examples/RunDeveloperExamples.sql b/examples/RunDeveloperExamples.sql
@@ -6,8 +6,6 @@ set linesize 1000
 
 exec ut_ansiconsole_helper.color_enabled(true);
 --developer examples
-prompt RunExampleComplexSuiteWithCustomReporter
-@@developer_examples/RunExampleComplexSuiteWithCustomReporter.sql
 prompt RunExampleTestSuiteWithCustomReporter
 @@developer_examples/RunExampleTestSuiteWithCustomReporter.sql
 prompt RunExampleTestAnnotationsParsingTimeHugePackage

diff --git a/examples/developer_examples/RunExampleComplexSuiteWithCustomReporter.sql b/examples/developer_examples/RunExampleComplexSuiteWithCustomReporter.sql
diff --git a/examples/developer_examples/RunExampleTestSuite.sql b/examples/developer_examples/RunExampleTestSuite.sql
@@ -15,19 +15,21 @@ declare
   l_test          ut_test;
   l_expectation   ut_expectation_result;
 begin
-  l_suite := ut_suite(user, 'ut_exampletest');
+  l_suite := ut_suite(user, 'ut_exampletest',a_line_no=>1);
   l_suite.description := 'Test Suite Name';
-  l_test := ut_test(user, 'ut_exampletest','ut_exAmpletest');
+  l_test := ut_test(user, 'ut_exampletest','ut_exAmpletest',a_line_no=>3);
   l_test.description := 'Example test1';
   l_test.before_test_list := ut_executables(ut_executable(user, 'ut_exampletest','Setup',ut_utils.gc_before_test));
   l_test.after_test_list  := ut_executables(ut_executable(user, 'ut_exampletest','tEardown',ut_utils.gc_after_test));
-  l_suite.add_item(l_test);
+  l_suite.items.extend;
+  l_suite.items(l_suite.items.last) := l_test;
 
-  l_test := ut_test(user, 'UT_EXAMPLETEST2','ut_exAmpletest');
+  l_test := ut_test(user, 'UT_EXAMPLETEST2','ut_exAmpletest',a_line_no=>6);
   l_test.description := 'Another example test';
   l_test.before_test_list := ut_executables(ut_executable(user, 'UT_EXAMPLETEST2','SETUP',ut_utils.gc_before_test));
   l_test.after_test_list  := ut_executables(ut_executable(user, 'UT_EXAMPLETEST2','TEARDOWN',ut_utils.gc_after_test));
-  l_suite.add_item(l_test);
+  l_suite.items.extend;
+  l_suite.items(l_suite.items.last) := l_test;
 
   l_suite.do_execute();
 

diff --git a/examples/developer_examples/RunExampleTestSuiteWithCompositeReporter.sql b/examples/developer_examples/RunExampleTestSuiteWithCompositeReporter.sql
@@ -12,7 +12,7 @@ set echo off
 
 PROMPT Runs test report using composite reporter
 declare
-  suite          ut_logical_suite;
+  l_suite        ut_logical_suite;
   l_doc_reporter ut_output_reporter_base := ut_documentation_reporter();
   l_tc_reporter  ut_output_reporter_base := ut_teamcity_reporter();
   l_run          ut_run;
@@ -21,14 +21,16 @@ begin
   ut_event_manager.add_listener(l_doc_reporter);
   ut_event_manager.add_listener(l_tc_reporter);
 
-  suite := ut_suite(user, 'ut_exampletest');
-  suite.description := 'Test Suite Name';
+  l_suite := ut_suite(user, 'ut_exampletest',a_line_no=>1);
+  l_suite.description := 'Test Suite Name';
 
-  suite.add_item(ut_test(user,'ut_exampletest','ut_exAmpletest'));
-  suite.add_item(ut_test(user, 'UT_EXAMPLETEST2','UT_EXAMPLETEST'));
+  l_suite.items.extend;
+  l_suite.items(l_suite.items.last) := ut_test(user,'ut_exampletest','ut_exAmpletest',a_line_no=>3);
+  l_suite.items.extend;
+  l_suite.items(l_suite.items.last) := ut_test(user, 'UT_EXAMPLETEST2','UT_EXAMPLETEST',a_line_no=>6);
 
   -- provide a reporter to process results
-  l_run := ut_run(ut_suite_items(suite));
+  l_run := ut_run(ut_suite_items(l_suite));
   l_run.do_execute();
 
   ut_event_manager.trigger_event(ut_utils.gc_finalize, l_run);

diff --git a/examples/developer_examples/RunExampleTestSuiteWithCustomReporter.sql b/examples/developer_examples/RunExampleTestSuiteWithCustomReporter.sql
@@ -22,19 +22,21 @@ begin
   ut_event_manager.initialize();
   -- Install ut_custom_reporter first from example folder
 
-  l_suite := ut_suite(user, 'ut_exampletest');
+  l_suite := ut_suite(user, 'ut_exampletest',a_line_no=>1);
 
-  l_test := ut_test(user, 'ut_exampletest','ut_exAmpletest');
+  l_test := ut_test(user, 'ut_exampletest','ut_exAmpletest',a_line_no=>3);
   l_test.description := 'Example test1';
   l_test.before_test_list := ut_executables(ut_executable(user, 'ut_exampletest','Setup',ut_utils.gc_before_test));
   l_test.after_test_list  := ut_executables(ut_executable(user, 'ut_exampletest','tEardown',ut_utils.gc_after_test));
-  l_suite.add_item(l_test);
+  l_suite.items.extend;
+  l_suite.items(l_suite.items.last) := l_test;
 
-  l_test := ut_test(user, 'UT_EXAMPLETEST2','ut_exAmpletest');
+  l_test := ut_test(user, 'UT_EXAMPLETEST2','ut_exAmpletest',a_line_no=>6);
   l_test.description := 'Another example test';
   l_test.before_test_list := ut_executables(ut_executable(user, 'ut_exampletest','SETUP',ut_utils.gc_before_test));
   l_test.after_test_list  := ut_executables(ut_executable(user, 'ut_exampletest','TEARDOWN',ut_utils.gc_after_test));
-  l_suite.add_item(l_test);
+  l_suite.items.extend;
+  l_suite.items(l_suite.items.last) := l_test;
 
   -- provide a reporter to process results tabbing each hierarcy level by tab_size
   l_reporter := ut_custom_reporter(a_tab_size => 2);

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:
Original file line number	Diff line number	Diff line change
Expand Up		@@ -16,3 +16,4 @@ curl -Lk -o utPLSQL-cli.zip https://github.com/utPLSQL/utPLSQL-cli/releases/down
		# unzip utPLSQL-cli and remove the zip file
		unzip utPLSQL-cli.zip && chmod u+x utPLSQL-cli/bin/utplsql && rm utPLSQL-cli.zip

		cp development/*.jar utPLSQL-cli/lib/