Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit bd05e4c

Browse files
jgebaljgebal
committed
Coverage documentation improvements.
Fixed datatype for ut_coverage_options.tps attributes Formatting.
1 parent 0a2f478 commit bd05e4c

3 files changed

Lines changed: 91 additions & 60 deletions

File tree

‎docs/userguide/coverage.md‎

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

33
# Coverage
4-
utPLSQL comes with a built-in coverage reporting engine. The code coverage reporting uses DBMS_PROFILER package provided with Oracle database.
4+
utPLSQL comes with a built-in coverage reporting engine. The code coverage reporting uses package DBMS_PROFILER (and DBMS_PLSQL_CODE_COVERAGE on Oracle database version 12.2 and above) provided with Oracle database.
55
Code coverage is gathered for the following source types:
66
* package bodies
77
* type bodies
@@ -15,7 +15,7 @@ Code coverage is gathered for the following source types:
1515
1616
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:
18-
* `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)
18+
* `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 the code is accessible for test user)
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)
2020
* `ut_coverage_sonar_reporter` - generates a [Sonar Compatible XML](https://docs.sonarqube.org/latest/analysis/generic-test/) coverage report providing detailed information on code coverage with line numbers. This coverage report is designed to be consumed by services like [SonarQube](https://www.sonarqube.org/) and [SonarCloud](https://about.sonarcloud.io/)
2121
* `ut_coverage_cobertura_reporter` - generates a basic Cobertura coverage (http://cobertura.sourceforge.net/xml/coverage-04.dtd) report providing detailed information on code coverage with line numbers. This coverage report is designed to be consumed by services like TFS and Jenkins. Check this link for an example of XML generated by Java: https://raw.githubusercontent.com/jenkinsci/cobertura-plugin/master/src/test/resources/hudson/plugins/cobertura/coverage-with-data.xml
@@ -30,7 +30,7 @@ In order to be able to gather coverage information, the user executing unit test
3030

3131
If you have `execute` privilege on the code that is being tested, but do not have `create any procedure` system privilege, then the code that is being tested will be reported as not covered (coverage = 0%).
3232
If you have `execute` privilege only on the unit tests, but do not have `execute` privilege on the code that is being tested, the code will not be reported by coverage - as if it did not exist in the database.
33-
If the code that is being tested is complied as NATIVE, the code coverage will not be reported as well.
33+
If the code that is being tested is compiled as NATIVE, the code coverage will not be reported as well.
3434

3535
## Running unit tests with coverage
3636
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.
@@ -65,6 +65,7 @@ Due to security model of `dbms_plsql_code_coverage` package, utPLSQL grants acce
6565
The access and synonyms will be public when using the headless installation. This approach avoids complexity of forcing every user of utPLSQL framework to create tables on their own.
6666

6767
Sample output:
68+
6869
![Package Coverage Summary](../images/extended_coverage_html_summary.png)
6970

7071
![Line Coverage Details](../images/extended_coverage_html_line.png)
@@ -128,42 +129,80 @@ exec ut.run('unit_test_schema', ut_coverage_html_reporter(), a_coverage_schemes
128129

129130
#### Filtering objects in coverage reports
130131

131-
There are six options that can be used to narrow down the scope of coverage report:
132-
- `a_include_objects` - list of `[object_owner.].object_name` to be included in the coverage report.
133-
- `a_exclude_objects` - list of `[object_owner.].object_name` to be excluded from the coverage report
134-
- `a_include_schema_expr` - string of regex expression of schemas to be included in the coverage report. It will override `a_include_objects` for example :
135-
```sql
136-
a_include_schema_expr => '^ut3_develop',
137-
a_include_objects => ut3_develop.ut_varchar2_list( 'ut3_tester_helper.regex_dummy_cov' )
138-
```
139-
Will result in showing coverage for all schemas that match regular expression `^ut3_develop` and ignore objectes defined by parameter `a_include_objects`
140-
141-
- `a_include_object_expr` - string of regex expression of objects ( no schema names included ) to be included in the coverage report. It will override `a_include_objects` for example:
142-
```sql
143-
a_include_object_expr => 'regex123',
144-
a_include_objects => ut3_develop.ut_varchar2_list( 'ut3_tester_helper.regex_dummy_cov' )
145-
```
146-
Will result in showing coverage for all objects that name match regular expression `regex123` and ignore objectes defined by parameter `a_include_objects`
147-
148-
- `a_exclude_schema_expr` - string of regex expression of schemas to be excluded from the coverage report. It will override `a_exclude_objects` for example:
149-
```sql
150-
a_exclude_schema_expr => '^ut3_tester',
151-
a_exclude_objects => ut3_develop.ut_varchar2_list( 'ut3_develop.regex_dummy_cov' )
152-
```
153-
Will result in showing coverage for all objects that schema is not matching regular expression `^ut3_tester` and ignore exclusion defined by parameter `a_exclude_objects`
154-
155-
- `a_exclude_object_expr` - string of regex expression of objects to be excluded from the coverage report. It will override `a_exclude_objects` for example
156-
```sql
157-
a_exclude_object_expr => 'regex123',
158-
a_exclude_objects => ut3_develop.ut_varchar2_list( 'ut3_develop.regex_dummy_cov' )
159-
```
160-
Will result in showing coverage for all objects that name is not matching regular expression `regex123` and ignore exclusion defined by parameter `a_exclude_objects`
161-
132+
There are multiple parameters that can be used to define the scope of coverage report:
133+
- `a_source_file_mappings ( ut_file_mappings )` - map of filenames to database objects. It is used for file-based coverage - see below.
134+
- `a_include_schema_expr ( varchar(4000) )` - string of regex expression of schemas to be included in the coverage report.
135+
- `a_include_object_expr ( varchar(4000) )` - string of regex expression of objects ( without schema name ) to be included in the coverage report.
136+
- `a_exclude_schema_expr ( varchar(4000) )` - string of regex expression of schemas to be excluded from the coverage report.
137+
- `a_exclude_object_expr ( varchar(4000) )` - string of regex expression of objects to be excluded from the coverage report.
138+
- `a_coverage_schemes ( ut_varchar2_list )` - List of database schema names to gather coverage on.
139+
- `a_include_objects ( ut_varchar2_list )` - list of `[object_owner.]object_name` to be included in the coverage report.
140+
- `a_exclude_objects ( ut_varchar2_list )` - list of `[object_owner.]object_name` to be excluded from the coverage report.
162141

163142
You may specify both _include_ and _exclude_ options to gain more control over what needs to be included / excluded from the coverage report.
164143

165-
The object owner is optional in the object list.
166-
If you do not provide an object owner, the _include_/_exclude_ list will be considered for every schema used for coverage gathering (as described above).
144+
**Important notes**
145+
The order of priority is for evaluation of include/exclude filter parameters is as follows.
146+
- if `a_source_file_mappings` is defined then all include/exclude parameters are ignored (see section below for usage of `a_source_file_mappings` parameter )
147+
- else if `a_include_schema_expr` or `a_include_object_expr` parameter is specified then parameters `a_coverage_schemes` and `a_include_objects` are ignored
148+
- else if `a_include_objects` is specified then the coverage is gathered only on specified database objects.
149+
- if `a_coverage_schemes` is specified then those schemas are used for objects in `a_include_objects` without schema name
150+
- if `a_coverage_schemes` is not specified then schema from paths (`a_paths`) parameter are used for objects in `a_include_objects` without schema name
151+
- else if, only the `a_coverage_schemes` is specified then the coverage is gathered only on specified database schemas
152+
- else if no coverage specific parameters are provided coverage is gathered on all schemas specified in paths passed to run procedure
153+
- else if no paths were specified, the coverage is gathered on current schema of the session running the tests
154+
155+
156+
Example: Limiting coverage by schema regex.
157+
```sql
158+
begin
159+
ut.run(ut_varchar2_list('user_1','user_2'), ut_coverage_html_reporter(),
160+
a_include_schema_expr => '^ut3_develop'
161+
);
162+
end;
163+
```
164+
Will result in showing coverage for all schemas that match regular expression `^ut3_develop`
165+
166+
```sql
167+
begin
168+
ut.run(ut_varchar2_list('user_1','user_2'), ut_coverage_html_reporter(),
169+
a_include_schema_expr => '^ut3_develop', a_include_objects => ut_varchar2_list( 'ut3_tester_helper.regex_dummy_cov' )
170+
);
171+
end;
172+
```
173+
Will result in showing coverage for all schemas that match regular expression `^ut3_develop`.
174+
Will ignore the `a_include_objects` parameter
175+
176+
```sql
177+
begin
178+
ut.run(ut_varchar2_list('user_1','user_2'), ut_coverage_html_reporter(),
179+
a_include_object_expr => 'regex123', a_include_objects => ut_varchar2_list( 'ut3_tester_helper.regex_dummy_cov' )
180+
);
181+
end;
182+
```
183+
Will result in showing coverage for all objects that name match regular expression `regex123`.
184+
Will ignore the `a_include_objects` parameter.
185+
186+
```sql
187+
begin
188+
ut.run(ut_varchar2_list('user_1','user_2'), ut_coverage_html_reporter(),
189+
a_exclude_schema_expr => '^ut3_tester', a_exclude_objects => ut_varchar2_list( 'regex_dummy_cov' )
190+
);
191+
end;
192+
```
193+
Will result in showing coverage for objects in all schema except schemas that are matching regular expression `^ut3_tester`
194+
Will ignore exclusion defined by parameter `a_exclude_objects`
195+
196+
```sql
197+
begin
198+
ut.run(ut_varchar2_list('user_1','user_2'), ut_coverage_html_reporter(),
199+
a_exclude_object_expr => 'regex123', a_exclude_objects => ut_varchar2_list( 'regex_dummy_cov' )
200+
);
201+
end;
202+
```
203+
Will result in showing coverage for all objects that name is not matching regular expression `regex123`.
204+
Will ignore exclusion defined by parameter `a_exclude_objects`.
205+
167206

168207
Example: Limiting coverage by object name, for tested code located in the same schema as the unit tests.
169208
```sql
@@ -214,7 +253,8 @@ Executes test `test_award_bonus` in schema `unit_test_schema`. Coverage will be
214253
215254
**Note**
216255
> When running coverage on schema objects, all source code of package bodies, functions, procedures, type bodies and triggers that were not executed will be reported as having 0% code coverage and all source code lines will show as uncovered.
217-
> This is different than the behavior when gathering coverage on project files.
256+
> This is different from the behavior when gathering coverage on project files.
257+
218258

219259
### Project based Coverage
220260

@@ -687,7 +727,7 @@ begin
687727
end;
688728
```
689729

690-
## Reporting coverage outside of utPLSQL
730+
## Reporting coverage outside utPLSQL and in parallel sessions
691731

692732
utPSLQL allows fo standalone reporting code coverage across multiple database sessions. This functionality enables coverage reporting for external testing tools.
693733

@@ -811,9 +851,3 @@ If the identifier is not unique, previous runs of coverage that used the same `c
811851
For details on the meaning of `schema_names`, `exclude_objects`, `include_objects`, `file_mappings` see sections above.
812852
Note that data-types of include/exclude/schema lists are different when calling `ut.run` vs. calling `get_report/get_report_cursor`.
813853

814-
The order of priority is for evaluation of include/exclude is as follows.
815-
- if `file_mappings` is specified then all include/exclude parameters are ignored
816-
- else if `..._expr` is specified then include_objects/exclude_objects parameters are ignored
817-
- else if `schema_names` is specified then the coverage is gathered on all object of specified schemas
818-
- else coverage is gathered on all schemas specified in paths passed to run procedure
819-
- if no paths were specified, the coverage is gathered on current schema of the session running the tests

‎source/core/coverage/ut_coverage.pkb‎

Lines changed: 9 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -180,21 +180,18 @@ create or replace package body ut_coverage is
180180
ut_event_manager.trigger_event(ut_event_manager.gc_debug, ut_key_anyvalues().put('l_sql',l_sql) );
181181

182182
if a_coverage_options.file_mappings is not empty then
183-
open l_cursor for l_sql using a_coverage_options.file_mappings,a_coverage_options.exclude_schema_expr,
184-
a_coverage_options.exclude_object_expr,l_excluded_objects,
185-
l_skip_objects;
183+
open l_cursor for l_sql using a_coverage_options.file_mappings, a_coverage_options.exclude_schema_expr,
184+
a_coverage_options.exclude_object_expr, l_excluded_objects, l_skip_objects;
186185
elsif coalesce(a_coverage_options.include_schema_expr,a_coverage_options.include_object_expr) is not null then
187-
open l_cursor for l_sql using a_coverage_options.include_schema_expr,a_coverage_options.include_object_expr,
188-
a_coverage_options.exclude_schema_expr,a_coverage_options.exclude_object_expr,
189-
l_excluded_objects,l_skip_objects;
186+
open l_cursor for l_sql using a_coverage_options.include_schema_expr, a_coverage_options.include_object_expr,
187+
a_coverage_options.exclude_schema_expr, a_coverage_options.exclude_object_expr,
188+
l_excluded_objects, l_skip_objects;
190189
elsif a_coverage_options.include_objects is not empty then
191-
open l_cursor for l_sql using a_coverage_options.include_objects,a_coverage_options.exclude_schema_expr,
192-
a_coverage_options.exclude_object_expr,l_excluded_objects,
193-
l_skip_objects;
190+
open l_cursor for l_sql using a_coverage_options.include_objects, a_coverage_options.exclude_schema_expr,
191+
a_coverage_options.exclude_object_expr, l_excluded_objects, l_skip_objects;
194192
else
195-
open l_cursor for l_sql using a_coverage_options.schema_names,a_coverage_options.exclude_schema_expr,
196-
a_coverage_options.exclude_object_expr,l_excluded_objects,
197-
l_skip_objects;
193+
open l_cursor for l_sql using a_coverage_options.schema_names, a_coverage_options.exclude_schema_expr,
194+
a_coverage_options.exclude_object_expr, l_excluded_objects, l_skip_objects;
198195
end if;
199196
return l_cursor;
200197
end;

‎source/core/types/ut_coverage_options.tps‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,10 @@ create or replace type ut_coverage_options force as object (
2121
exclude_objects ut_object_names,
2222
include_objects ut_object_names,
2323
file_mappings ut_file_mappings,
24-
include_schema_expr varchar2(32767),
25-
include_object_expr varchar2(32767),
26-
exclude_schema_expr varchar2(32767),
27-
exclude_object_expr varchar2(32767),
24+
include_schema_expr varchar2(4000),
25+
include_object_expr varchar2(4000),
26+
exclude_schema_expr varchar2(4000),
27+
exclude_object_expr varchar2(4000),
2828
constructor function ut_coverage_options(
2929
self in out nocopy ut_coverage_options,
3030
coverage_run_id raw,

0 commit comments

Comments
 (0)