- [Contributing](about/CONTRIBUTING.md)

With just three simple steps you can define and run your unit tests for PLSQL code.

1. Install the utPLSQL framework

end test_pkg;

| Annotation |Level| Description |

| --- | --- | --- |

The following are best practices we as utPLSQL have learned about PL/SQL and Unit Testing.

Use a version control system for your code. Don't just trust the database for code storage. This includes both the code you have under test, and the unit tests you develop as well.

* `ut_coveralls_reporter` - generates a JSON 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)

* `ut_coverage_sonar_reporter` - generates a JSON coverage report providing detailed information on code coverage with line numbers. This coverage report is designed to be consumed by local services like [sonarqube](https://about.sonarqube.com/)

Code coverage is using DBMS_PROFILER to gather information about 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)

In order to be able to gather coverage information, user executing unit tests needs to be either:

* Owner of the code that is tested

If you have `execute` privilege only on the unit tests, but do not have `execute` privilege on the code that is tested, the code will not be reported by coverage - as if it did not exist in the database.

If the code that is testes is complied as NATIVE, the code coverage will not be reported as well.

Using code coverage functionality is as easy as using any other [reporter](reporters.md) for utPLSQL project. All you need to do is run your tests from your preferred SQL tool and save the outcomes of reporter to a file.

All you need to do, is pass the constructor of the reporter to your `ut.run`


By default the database schema/schemes containing the tests that were executed during the run, are fully reported by coverage reporter.

All valid unit tests are excluded from the report regardless if they were invoked or not. This way the coverage report is not affected by presence of tests and contains only the tested code.

The default behavior of coverage reporters can be altered, depending on your needs.

The most basic options are the include/exclude objects lists.

You may specify both include and exclude objects lists to specify which objects are to be included in the report and which are to be excluded.

Both of those options are meant to be used to narrow down the scope of unit test runs, that is broad by default.

You can also combine the parameters and both will be applied.

In some architectures, you might end up in a situation, where your unit tests exist in a different schema than the tested code.

This is not the default or recommended approach but is supporter by utPLSQL.

In such scenarios, you would probably have a separate database schema to hold unit tests and a separate schema/schemes to hold the tested code.

Executes test `test_award_bonus` in schema `ut3_user` and gather coverage for that execution on `award_bonus` object from schema `usr`. The exclude list is of no relevance as it is not overlapping with include list.

Both `sonar` and `coveralls` are utilities that are more project-oriented than database-centric. They report statistics and coverage for project files in version control system.

Nowadays, most of database projects are moving away from database-centric approach towards project/product-centric approach.

Coverage reporting of utPLSQL allows you to perform code coverage analysis for your project files.

It is recommended to install utPLSQL in it's own schema. You are free to choose any name for this schema.

The installation user/schema must have the following Oracle system permissions during the installation.

utPLSQL provides the following reporting formats.

The `ut_documentation_reporter` is the default reporting format used by the framework.

It provides a human readable test results.

- Summary with total number of tests, number of tests with status and timing for the execution

When invoking tests with documentation reporter and your command line supports ANSICONSOLE (default on Unix), you can obtain the coloured outputs from the documentation reporter.


Most of continuous integration servers (like Jenkins) are capable of consuming unit test execution results in [XUnit/JUnit](https://en.wikipedia.org/wiki/XUnit) format.

The `ut_xunit_reporter` is producing outcomes as XUnit-compatible XML unit test report, that can be used by CI servers to display their custom reports and provide metrics (like tests execution trends).


[Teamcity](https://www.jetbrains.com/teamcity/) is a CI server by Jetbrains. It supports XUnit reporting and additionally has it's own format of reporting that allows tracking of progress of a CI step/task as it executes.

The TeamCity format developed by Jetbrains is supported by utPLSQL with `ut_teamcity_reporter`.

It also facilitates displaying on screen unit test results while the execution is still ongoing.

Current limit of script parameters is 39

ut_run.sql user/password@database [-p=(ut_path|ut_paths)] [-c] [-f=format [-o=output] [-s] ...]

For detailed instructions on other install options see the [Install Guide](docs/userguide/install.md)

Annotations define that a package is a unit test suite, they also allow defining a description for the suite as well as the test itself.

Package body consists of procedures containing unit test code. To validate [an expectation](docs/userguide/expectations.md) in test, use `ut.expect( actual_data ).to_( ... )` syntax.

create or replace package test_between_string as

procedure normal_case is

begin

end;

procedure zero_start_position is