10000 Made coverage_run_id mandatory in `ut_coverage_options` · utPLSQL/utPLSQL@955de5c · GitHub
[go: up one dir, main page]
Skip to content

Commit 955de5c

Browse files
jgebaljgebal
committed
Made coverage_run_id mandatory in ut_coverage_options
Added documentation
1 parent 0e72abc commit 955de5c

File tree

4 files changed

+134
-16
lines changed

4 files changed

+134
-16
lines changed

‎docs/userguide/coverage.md

Lines changed: 130 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
![version](https://img.shields.io/badge/version-v3.1.11.3392--develop-blue.svg)
22

33
# Coverage
4-
utPLSQL comes with a built-in coverage reporting engine. The code coverage reporting is based on the DBMS_PROFILER package provided with Oracle database.
4+
utPLSQL comes with a built-in coverage reporting engine. The code coverage reporting uses DBMS_PROFILER package provided with Oracle database.
55
Code coverage is gathered for the following source types:
66
* package bodies
77
* type bodies
@@ -11,9 +11,9 @@ Code coverage is gathered for the following source types:
1111

1212
**Note**
1313

14-
> The package and type specifications are explicitly excluded from code coverage analysis. This limitation is introduced to avoid false-negatives. Typically package specifications contain no executable code. The only exception is initialization of global constants and variables in package specification. Since most package specifications are not executable at all, there is no information available on the number of lines covered and those would be reported as 0% covered, which is not desirable.
14+
> The package and type specifications are excluded from code coverage analysis. This limitation is introduced to avoid false-negatives. Typically package specifications contain no executable code. The only exception is initialization of global constants and variables in package specification. Since most package specifications are not executable at all, there is no information available on the number of lines covered and those would be reported as 0% covered, which is not desirable.
1515
16-
To obtain information about code coverage of your unit tests, all you need to do is run your unit tests with one of built-in code coverage reporters.
16+
To obtain information about code coverage for unit tests, run utPLSQL with one of built-in code coverage reporters.
1717
The following code coverage reporters are supplied with utPLSQL:
1818
* `ut_coverage_html_reporter` - generates a HTML coverage report providing summary and detailed information on code coverage. The HTML reporter is based on the open-source [simplecov-html](https://github.com/colszowka/simplecov-html) reporter for Ruby. It includes source code of the code that was covered (if possible)
1919
* `ut_coveralls_reporter` - generates a [Coveralls compatible JSON](https://coveralls.zendesk.com/hc/en-us/articles/201774865-API-Introduction) coverage report providing detailed information on code coverage with line numbers. This coverage report is designed to be consumed by cloud services like [Coveralls](https://coveralls.io)
@@ -33,8 +33,8 @@ If you have `execute` privilege only on the unit tests, but do not have `execute
3333
If the code that is being tested is complied as NATIVE, the code coverage will not be reported as well.
3434

3535
## Running unit tests with coverage
36-
Using the code coverage functionality is as easy as using any other [reporter](reporters.md) for the utPLSQL project. You just run your tests from your preferred SQL tool and save the reporter results to a file.
37-
All you need to do is pass the constructor of the reporter to your `ut.run`
36+
Using the code coverage functionality is as easy as using any other [reporter](reporters.md) for the utPLSQL test-run. You just run your tests from your preferred SQL tool and save the reporter results to a file.
37+
All you need to do is pass the constructor of the reporter to the `ut.run` procedure call.
3838

3939
Example:
4040
```sql
@@ -43,10 +43,10 @@ begin
4343
end;
4444
/
4545
```
46-
Executes all unit tests in the current schema, gathers information about code coverage and outputs the HTML text into DBMS_OUTPUT.
46+
The above command executes all unit tests in the **current schema**, gathers information about code coverage and outputs the HTML report as text into DBMS_OUTPUT.
4747
The `ut_coverage_html_reporter` will produce an interactive HTML report. You can see a sample of code coverage for the utPLSQL project [here](https://utplsql.github.io/utPLSQL-coverage-html/)
4848

49-
The report provides summary information with a list of source code that was expected to be covered.
49+
The report provides summary information with a list of source code that should be covered.
5050

5151
![Coverage Summary page](../images/coverage_html_summary.png)
5252

@@ -57,8 +57,8 @@ The report allow you to navigate to each source file and inspect line by line co
5757

5858
#### Oracle 12.2 extended coverage with profiler and block coverage
5959
Using data collected from profiler and block coverage running parallel we are able to enrich information about coverage.
60-
For every line recorded by profiler if we have a partially covered same line in block coverage we will display that information
61-
presenting line as partially covered, displaying number of block and how many blocks been covered in that line.The feature will be automatically enabled in the Oracle database version 12.2 and higher, for older versions current profiler will be used.
60+
For every line recorded by the profiler if we have a partially covered same line in block coverage we will display that information
61+
presenting line as partially covered, displaying number of block and how many blocks have been covered in that line.The feature will be automatically enabled in the Oracle database version 12.2 and higher, for older versions current profiler will be used.
6262

6363
utPLSQL installation automatically creates tables needed by `dbms_plsql_code_coverage` on databases in versions above 12c Release 1.
6464
Due to security model of `dbms_plsql_code_coverage` package, utPLSQL grants access to those tables and creates synonyms for those tables.
@@ -92,7 +92,8 @@ The default behavior of coverage reporting can be altered using invocation param
9292

9393
### Schema based Coverage
9494

95-
To simply gather coverage for all objects in your current schema execute tests with coverage reporting.
95+
To gather coverage for all objects in the **current schema** execute tests with coverage report as argument.
96+
This is the default reporting option and therefore additional coverage options don't need to be provided.
9697

9798
```sql
9899
exec ut.run(ut_coverage_html_reporter());
@@ -109,7 +110,7 @@ exec ut.run(ut_coverage_html_reporter());
109110
#### Setting coverage schema(s)
110111

111112
By default, coverage is gathered on the schema(s) derived from suite paths provided to execute tests.
112-
This is correct as long as your test packages and tested code share the same schema.
113+
This is a valid approach as long as your test packages and tested code share the same schema.
113114

114115
So when you run:
115116
```sql
@@ -531,8 +532,8 @@ Unit test code is mapped to files in `test_results.xml`
531532

532533
In order to allow deterministic and accurate mapping of database source-code into project files, the project directo 57AE ry and file structure needs to meet certain criteria.
533534
- Source code is kept separate from test code (separate directories)
534-
- Each database (source-code) object is stored in individual file. Package/type specification is kept separate from it's body.
535-
- File name (file path) contains name of database object
535+
- Each database (source-code) object is stored in an individual file. Package/type specification is kept separate from its body.
536+
- File name (file path) contains the name of database object
536537
- Each file-path clearly identifies object type (by file extension)
537538
- Each file contains representation of database object "as is". No extra commands (like `set echo off` `ALTER SESSION SET PLSQL_CCFLAGS = 'debug:TRUE';`) or blank lines are present before `CREATE TYPE`,`CREATE TYPE` etc.
538539
- When project is spanning across multiple database schemes, each file-path clearly and uniformly identifies object owner
@@ -659,3 +660,119 @@ begin
659660
end;
660661
```
661662

663+
## Reporting coverage outside of utPLSQL
664+
665+
utPSLQL allows fo standalone reporting code coverage across multiple database sessions. This functionality enables coverage reporting for external testing tools.
666+
667+
Following API calls enable the standalone coverage reporting.
668+
669+
- `ut_runner.coverage_start( coverage_run_id );` - initiates code coverage within a session
670+
- `ut_runner.coverage_stop();` - stops gathering of code coverage within a session
671+
- `.get_report( ... )` - coverage reporters function producing coverage report as pipelined data-set (to be used in SQL query)
672+
- `.get_report_cursor( ... )` - coverage reporters function producing coverage report as ref-cursor
673+
674+
Example:
675+
```sql
676+
--SESSION 1
677+
-- gather coverage on code using specific coverage_run_id value
678+
declare
679+
l_coverage_run_id raw(32);
680+
begin
681+
l_coverage_run_id := 'A6AA5B7361251CE6E053020011ACA055';
682+
-- l_coverage_run_id := sys_guid;
683+
ut_runner.coverage_start(l_coverage_run_id);
684+
685+
--The code to gather coverage on goes here
686+
687+
ut_runner.coverage_stop();
688+
end;
689+
/
690+
```
691+
692+
```sql
693+
--SESSION 2
694+
-- alternative approach
695+
-- gather coverage on code using specific coverage_run_id value
696+
exec ut_runner.coverage_start('A6AA5B7361251CE6E053020011ACA055');
697+
698+
--The code to gather coverage on goes here
699+
700+
exec ut_runner.coverage_stop();
701+
```
702+
703+
704+
```sql
705+
--SESSION 1 or SESSION2 2 or SESSION 3
706+
-- run after calls in SESSION 1 & 2 are finshed
707+
-- retrieve coverage report in HTML format coverage_run_id value
708+
select *
709+
from table(
710+
ut_coverage_html_reporter().get_report(
711+
a_coverage_options => ut_coverage_options(
712+
coverage_run_id => 'A6AA5B7361251CE6E053020011ACA055'
713+
)
714+
)
715+
);
716+
```
717+
718+
```sql
719+
--SESSION 1 or SESSION2 2 or SESSION 3
720+
-- run after calls in SESSION 1 & 2 are finshed
721+
declare
722+
l_results_cursor sys_refcursor;
723+
begin
724+
l_results_cursor := ut_coverage_html_reporter().get_report_cursor(
725+
a_coverage_options => ut_coverage_options(
726+
coverage_run_id => 'A6AA5B7361251CE6E053020011ACA055'
727+
)
728+
);
729+
--fetch and process the cursor results
730+
close l_results_cursor;
731+
end;
732+
/
733+
```
734+
735+
Specification of parameters for `get_report` and `get_report_cursor`
736+
```sql
737+
function get_report(
738+
a_coverage_options ut_coverage_options,
739+
a_client_character_set varchar2 := null
740+
) return ut_varchar2_rows pipelined
741+
```
742+
743+
```sql
744+
function get_report_cursor(
745+
a_coverage_options ut_coverage_options,
746+
a_client_character_set varchar2 := null
747+
) return sys_refcursor
748+
```
749+
```sql
750+
ut_coverage_options(
751+
coverage_run_id raw,
752+
schema_names ut_varchar2_rows := null,
753+
exclude_objects ut_varchar2_rows := null,
754+
include_objects ut_varchar2_rows := null,
755+
file_mappings ut_file_mappings := null
756+
);
757+
```
758+
759+
The `a_client_character_set` is used to provide character set to the report. Coverage reports in XML and HTML format include this information to assure that HMTL/XML encoding tag is aligned with encoding of the report produced.
760+
Use this parameter to provide encoding of your client application.
761+
762+
The `a_coverage_options` parameter is used to control the scope and formatting of data returned by report.
763+
764+
`ut_coverage_options` object accepts the following arguments
765+
766+
- `coverage_run_id` - identifier of coverage run to generate report for - data-type `RAW(32)`
767+
- `schema_names` - optional - list of schema names to include in coverage report - data-type `UT_VARCHAR2_ROWS`
768+
- `exclude_objects` - optional - list of object names to exclude from report - data-type `UT_VARCHAR2_ROWS`
769+
- `include_objects` - optional - list of object names to gather coverage on - data-type `UT_VARCHAR2_ROWS`
770+
- `file_mappings` - optional - list of schema names to gather coverage on - data-type `UT_FILE_MAPPINGS`
771+
772+
`coverage_run_id` parameter identifies a common coverage run. The valid value type for that parameter is RAW(32).
773+
It is recommended to use `sys_guid()` to generate a common, unique identifier for a specific coverage run.
774+
If the identifier is not unique, previous runs of coverage that used the same `coverage_run_id` will be aggregated to the resulting coverage report.
775+
776+
For details on the meaning of `schema_names`, `exclude_objects`, `include_objects`, `file_mappings` see sections above.
777+
Note that data-types of include/exclude/schema lists are different when calling `ut.run` vs. calling `get_report/get_report_cursor`.
778+

‎source/api/ut_runner.pkb

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,7 @@ create or replace package body ut_runner is
124124
l_run := ut_run(
125125
a_run_paths => l_paths,
126126
a_coverage_options => ut_coverage_options(
127+
coverage_run_id => sys_guid(),
127128
schema_names => l_coverage_schema_names,
128129
exclude_objects => ut_utils.convert_collection(a_exclude_objects),
129130
include_objects => ut_utils.convert_collection(a_include_objects),

‎source/core/types/ut_coverage_options.tpb

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ create or replace type body ut_coverage_options as
1818

1919
constructor function ut_coverage_options(
2020
self in out nocopy ut_coverage_options,
21-
coverage_run_id raw := null,
21+
coverage_run_id raw,
2222
schema_names ut_varchar2_rows := null,
2323
exclude_objects ut_varchar2_rows := null,
2424
include_objects ut_varchar2_rows := null,
@@ -46,7 +46,7 @@ create or replace type body ut_coverage_options as
4646
return l_result;
4747
end;
4848
begin
49-
self.coverage_run_id := coalesce(coverage_run_id, sys_guid());
49+
self.coverage_run_id := coverage_run_id;
5050
self.file_mappings := file_mappings;
5151
self.schema_names := schema_names;
5252
self.exclude_objects := ut_object_names();

‎source/core/types/ut_coverage_options.tps

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ create or replace type ut_coverage_options force as object (
2323
file_mappings ut_file_mappings,
2424
constructor function ut_coverage_options(
2525
self in out nocopy ut_coverage_options,
26-
coverage_run_id raw := null,
26+
coverage_run_id raw,
2727
schema_names ut_varchar2_rows := null,
2828
exclude_objects ut_varchar2_rows := null,
2929
include_objects ut_varchar2_rows := null,

0 commit comments

Comments
 (0)
0