Improved functionality of reporters to allow for inline calls.

jgebal · jgebal · commit 773eae25b2ea · 2019-07-13T03:50:45.000+01:00
References #955
diff --git a/docs/userguide/running-unit-tests.md b/docs/userguide/running-unit-tests.md
@@ -31,6 +31,8 @@ curl -Lk "${DOWNLOAD_URL}" -o utplsql-cli.zip
 unzip -q utplsql-cli.zip
 ```
 
+Keep in mind that you will need to download/provide Oracle JDBC driver separately, as it is not part of utPLSQL-cli due to licensing restrictions.
+
 # ut.run
 
 The `ut` package contains overloaded `run` procedures and functions.
@@ -167,11 +169,63 @@ The main difference compared to the `ut.run` API is that `ut_runner.run` does no
 `ut_runner.run` accepts multiple reporters. Each reporter pipes to a separate output (uniquely identified by output_id).
 Outputs of multiple reporters can be consumed in parallel. This allows for live reporting of test execution progress with threads and several database sessions.
 
-The concept is pretty simple.
+`ut_runner.run` API is used by utPLSQL-cli, utPLSQL-SQLDeveloper extension and utPLSQL-maven-plugin and allows for:
+- deciding on the scope of test run (by schema names, object names, suite paths or tags )
+- running tests with several concurrent reporters
+- real-time reporting of test execution progress
+- controlling colored text output to the screen
+- controlling scope of code coverage reports
+- mapping of database source code to project files
+- controlling behavior on test-failures
+- controlling client character set for HTML and XML reports
+- controlling rollback behavior of test-run
+- controlling random order of test execution
+
+Running with multiple reporters.
 
 - in the main thread (session), define the reporters to be used. Each reporter has it's output_id and so you need to extract and store those output_ids.
 - as a separate thread, start `ut_runner.run` and pass reporters with previously defined output_ids.
-- for each reporter start a separate thread and read outputs from the `ut_output_buffer.get_lines` table function by providing the output_id defined in the main thread.
+- for each reporter start a separate thread and read outputs from the `reporter.get_lines` table function or from `reporter.get_lines_cursor()` by providing the `reporter_id` defined in the main thread.
+- each reporter for each test-run must have a unique `reporter_id`. The `reporter_id` is used between two sessions to identify the data stream 
+
+Example:
+```sql
+--main test run ( session 1 )
+declare
+  l_reporter      ut_realtime_reporter := ut_realtime_reporter();
+begin
+  l_reporter.set_reporter_id( 'd8a79e85915640a6a4e1698fdf90ba74' );
+  l_reporter.output_buffer.init();
+  ut_runner.run (ut_varchar2_list ('ut3_tester','ut3$user#'), ut_reporters( l_reporter ) );
+end;
+/
+```
+
+```sql
+--report consumer ( session 2 )
+set arraysize 1
+set pagesize 0
+
+select * 
+  from table(
+         ut_realtime_reporter()
+           .set_reporter_id('d8a79e85915640a6a4e1698fdf90ba74')
+           .get_lines()
+  );
+```
+
+```sql
+--alternative version of report consumer ( session 2 )
+set arraysize 1
+set pagesize 0
+
+select
+    ut_realtime_reporter()
+      .set_reporter_id('d8a79e85915640a6a4e1698fdf90ba74')
+      .get_lines_cursor()
+  from dual;
+```
+
   
 # Order of test execution
 
diff --git a/source/core/types/ut_output_reporter_base.tpb b/source/core/types/ut_output_reporter_base.tpb
@@ -31,7 +31,14 @@ create or replace type body ut_output_reporter_base is
   overriding member procedure set_reporter_id(self in out nocopy ut_output_reporter_base, a_reporter_id raw) is
   begin
     self.id := a_reporter_id;
-    self.output_buffer.output_id := a_reporter_id;
+    self.output_buffer.init(a_reporter_id);
+  end;
+
+  member function set_reporter_id(self in ut_output_reporter_base, a_reporter_id raw) return ut_output_reporter_base is
+    l_result ut_output_reporter_base := self;
+  begin
+    l_result.set_reporter_id(a_reporter_id);
+    return l_result;
   end;
 
   overriding member procedure before_calling_run(self in out nocopy ut_output_reporter_base, a_run in ut_run) is
diff --git a/source/core/types/ut_output_reporter_base.tps b/source/core/types/ut_output_reporter_base.tps
@@ -19,6 +19,7 @@ create or replace type ut_output_reporter_base under ut_reporter_base(
   constructor function ut_output_reporter_base(self in out nocopy ut_output_reporter_base) return self as result,
   member procedure init(self in out nocopy ut_output_reporter_base, a_self_type varchar2, a_output_buffer ut_output_buffer_base := null),
   overriding member procedure set_reporter_id(self in out nocopy ut_output_reporter_base, a_reporter_id raw),
+  member function  set_reporter_id(self in ut_output_reporter_base, a_reporter_id raw) return ut_output_reporter_base,
   overriding member procedure before_calling_run(self in out nocopy ut_output_reporter_base, a_run in ut_run),
   
   member procedure print_text(self in out nocopy ut_output_reporter_base, a_text varchar2, a_item_type varchar2 := null),
