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

Skip to content

Commit 0486b74

Browse files
jgebaljgebal
authored
Merge pull request #1319 from utPLSQL/feature/update_project_documentation
Update of utPLSQL documentation
2 parents b32e2fb + e5b966b commit 0486b74

303 files changed

Lines changed: 1225 additions & 451 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CHANGELOG.md‎

Lines changed: 600 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/userguide/annotations.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ package test_package is
4646
--%disabled
4747
procedure my_first_procedure;
4848

49-
$if dbms_db_version.version >= 12 $then --This is ok - annotation before procedure
49+
$if dbms_db_version.version >= 19 $then --This is ok - annotation before procedure
5050
--%test()
5151
procedure my_first_procedure;
5252
$end
@@ -71,7 +71,7 @@ package test_package is
7171
procedure proc1;
7272

7373
--%test() --This is wrong as there is a compiler directive between procedure and annotation
74-
$if dbms_db_version.version >= 12 $then
74+
$if dbms_db_version.version >= 19 $then
7575
procedure proc_12;
7676
$end
7777

@@ -1755,7 +1755,7 @@ The `--%throws` annotation allows you to specify a list of exceptions as one of:
17551755
- number literals - example `--%throws(-20134)`
17561756
- variables of type exception defined in a package specification - example `--%throws(exc_pkg.c_exception_No_variable)`
17571757
- variables of type number defined in a package specification - example `--%throws(exc_pkg.c_some_exception)`
1758-
- [predefined oracle exceptions](https://docs.oracle.com/cd/E11882_01/timesten.112/e21639/exceptions.htm#CIHFIGFE) - example `--%throws(no_data_found)`
1758+
- [predefined oracle exceptions](https://docs.oracle.com/en//database/oracle/oracle-database/19/lnpls/predefined-exceptions.html) - example `--%throws(no_data_found)`
17591759

17601760
The annotation is ignored, when no valid arguments are provided. Examples of invalid annotations `--%throws()`,`--%throws`, `--%throws(abe, 723pf)`.
17611761

‎docs/userguide/coverage.md‎

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

3-
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.
3+
utPLSQL comes with a built-in coverage reporting engine. The code coverage reporting combines data from package DBMS_PROFILER and DBMS_PLSQL_CODE_COVERAGE.
44
Code coverage is gathered for the following source types:
55

66
* package bodies
@@ -27,7 +27,7 @@ The following code coverage reporters are supplied with utPLSQL:
2727
* `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
2828

2929
## Security model
30-
utPLSQL code coverage uses DBMS_PROFILER to gather information about the execution of code under test and therefore follows the [DBMS_PROFILER's Security Model](https://docs.oracle.com/database/121/ARPLS/d_profil.htm#ARPLS67465).
30+
utPLSQL code coverage uses DBMS_PROFILER to gather information about the execution of code under test and therefore follows the [DBMS_PROFILER's Security Model](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_PROFILER.html#GUID-DEE5EA97-14AA-4AF2-A5F7-4AB1D004B99F).
3131
In order to be able to gather coverage information, the user executing unit tests needs to be either:
3232

3333
* The owner of the code that is being tested
@@ -63,14 +63,15 @@ The report allow you to navigate to each source file and inspect line by line co
6363
![Coverage Details page](../images/coverage_html_details.png)
6464

6565

66-
### Oracle 12.2 extended coverage with profiler and block coverage
67-
Using data collected from profiler and block coverage running parallel we are able to enrich information about coverage.
68-
For every line recorded by the profiler if we have a partially covered same line in block coverage we will display that information
69-
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.
66+
### Partial Coverage
7067

71-
utPLSQL installation automatically creates tables needed by `dbms_plsql_code_coverage` on databases in versions above 12c Release 1.
72-
Due to security model of `dbms_plsql_code_coverage` package, utPLSQL grants access to those tables and creates synonyms for those tables.
73-
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.
68+
#### What it does
69+
Partial coverage combines two data sources — the profiler and block coverage — to give you a more detailed picture of which parts of your code have been tested.
70+
When a line appears in both sources, and block coverage shows it was only partially covered, the display will reflect that: you'll see the line marked as partially covered, along with how many blocks on that line were executed out of the total.
71+
72+
#### Setup and permissions
73+
utPLSQL automatically creates the tables required by Oracle's dbms_plsql_code_coverage package — you don't need to create them manually.
74+
Because of how dbms_plsql_code_coverage handles security, utPLSQL also takes care of granting access to those tables and creating the necessary synonyms. In a headless installation, both the grants and synonyms are made public, keeping things simple without requiring every utPLSQL user to set up their own tables.
7475

7576
Sample output:
7677

‎docs/userguide/expectations.md‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -648,9 +648,7 @@ Syntax:
648648

649649
`ut.expect( a_actual ).to_be_like( a_mask [, a_escape_char] )`
650650

651-
Parameters `a_mask` and `a_escape_char` represent valid parameters of the [Oracle LIKE condition](https://docs.oracle.com/database/121/SQLRF/conditions007.htm#SQLRF52142).
652-
653-
If you use Oracle Database version 11.2.0.4, you may run into Oracle Bug 14402514: WRONG RESULTS WITH LIKE ON CLOB USING ESCAPE CHARACTER. In this case we recommend to use `match` instead of `be_like`.
651+
Parameters `a_mask` and `a_escape_char` represent valid parameters of the [Oracle LIKE condition](https://docs.oracle.com/en/database/oracle/oracle-database/19/sqlrf/Pattern-matching-Conditions.html).
654652

655653
Usage:
656654
```sql linenums="1"
@@ -1224,9 +1222,7 @@ utPLSQL is capable of comparing compound data-types including:
12241222
- Comparison of cursor returning `TIMESTAMP` **columns** against cursor returning `TIMESTAMP` **bind variables** requires variables to be cast to proper precision. This is an Oracle SQL - PLSQL compatibility issue and usage of CAST is the only known workaround for now. See [Comparing cursor data containing TIMESTAMP bind variables](#comparing-cursor-data-containing-timestamp-bind-variables) for examples.
12251223
- To compare nested table/varray type you need to convert it to `anydata` by using `anydata.convertCollection()`
12261224
- To compare object type you need to convert it to `anydata` by using `anydata.convertObject()`
1227-
- It is possible to compare PL/SQL records, collections, varrays and associative arrays. To compare this types of data, use cursor comparison feature of utPLSQL and TABLE operator in SQL query
1228-
- On Oracle 11g Release 2 - pipelined table functions are needed (see section [Implicit (Shadow) Types in this artcile](https://oracle-base.com/articles/misc/pipelined-table-functions))
1229-
- On Oracle 12c and above - use [TABLE function on nested tables/varrays/associative arrays of PL/SQL records](https://oracle-base.com/articles/12c/using-the-table-operator-with-locally-defined-types-in-plsql-12cr1)
1225+
- It is possible to compare PL/SQL records, collections, varrays and associative arrays. To compare this types of data, use cursor comparison feature of utPLSQL and [TABLE operator in SQL query](https://oracle-base.com/articles/12c/using-the-table-operator-with-locally-defined-types-in-plsql-12cr1)
12301226
- utPLSQL is not able to distinguish between NULL and whitespace-only column/attribute value when comparing compound data. This is due to Oracle limitation on of XMLType.
12311227
See [issue #880](https://github.com/utPLSQL/utPLSQL/issues/880) for details. *Note: This behavior might be fixed in future releases, when utPLSQL is no longer depending on XMLType for compound data comparison.*
12321228
@@ -1763,7 +1759,7 @@ FAILURE
17631759
17641760
## Comparing Json objects
17651761
1766-
utPLSQL is capable of comparing json data-types of `json_element_t` **on Oracle 12.2 and above**, and also `json` **on Oracle 21 and above**
1762+
utPLSQL is capable of comparing json data-types of `json_element_t`, and also `json` **on Oracle 21 and above**
17671763
17681764
!!! note
17691765
Whenever a database is upgraded to compatible version the utPLSQL needs to be reinstalled to pick up json changes. E.g. upgrade from 18c to 21c to enable `json` type compare.

‎docs/userguide/install.md‎

Lines changed: 5 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,11 @@
22

33
## Supported database versions
44

5-
utPLSQL is continuously tested against following versions of Oracle databases
5+
- Oracle Database 19c or newer (SE/EE/Cloud/Free)
66

7-
* 11g R2
8-
* 12c
9-
* 12c R2
10-
* 18c
11-
* 19c
7+
We do our best to assure full compatibility with **actively supported** versions of Oracle databases.
8+
See [this page](https://www.oracle.com/us/support/library/lifetime-support-technology-069183.pdf#page=6) for Oracle Database Releases and their Support Lifetime by Oracle.
129

13-
We do our best to assure full compatibility with supported versions of Oracle databases [See](http://www.oracle.com/us/support/library/lifetime-support-technology-069183.pdf#page=6)
14-
15-
## Requirements
16-
17-
utPLSQL will run on any Oracle Database version 11g relase 2 or above.
1810

1911
### Licensed features required
2012

@@ -179,7 +171,7 @@ If the installing user and utPLSQL owner is one and the same, the user must have
179171

180172
In addition, the user must be granted the execute privilege on `DBMS_LOCK` and `DBMS_CRYPTO` packages.
181173

182-
utPLSQL is using [DBMS_PROFILER tables](https://docs.oracle.com/cd/E18283_01/appdev.112/e16760/d_profil.htm#i999476) for code coverage. The tables required by DBMS_PROFILER will be created in the installation schema unless they already exist.
174+
utPLSQL is using [DBMS_PROFILER tables](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_PROFILER.html) for code coverage. The tables required by DBMS_PROFILER will be created in the installation schema unless they already exist.
183175

184176
It is up to DBA to maintain the storage of the profiler tables.
185177

@@ -274,7 +266,7 @@ select
274266
## Additional requirements
275267

276268
In order to use the Code Coverage functionality of utPLSQL, users executing the tests must have the CREATE privilege on the PLSQL code that the coverage is gathered on.
277-
This is a requirement of [DBMS_PROFILER package](https://docs.oracle.com/cd/E18283_01/appdev.112/e16760/d_profil.htm#i999476).
269+
This is a requirement of [DBMS_PROFILER package](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_PROFILER.html#GUID-DEE5EA97-14AA-4AF2-A5F7-4AB1D004B99F).
278270

279271
In practice, user running tests for PLSQL code that he does not own, needs to have CREATE ANY PROCEDURE/CREATE ANY TRIGGER privileges.
280272
Running code coverage on objects that the user does not own will **not produce any coverage information** without those privileges.

0 commit comments

Comments
 (0)