utPLSQL provides the following reporting formats.

#Documentation reporter

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

It provides a human readable test results.

To invoke tests with documentation reporter use one of following calls from sql console (SQLPlus)

You may also invoke unit tests directly from command line by calling.

Invoking tests from command line tool `ut_run.sql` allows you to track progress of test execution.

In that case, the documentation reporter will provide information about each test that was executed as soon as it's execution finishes.

For more details on using the `ut_run.sql` script look into [ut_run.sql](ut_run-script.md) documentation.

The `ut_documentation_reporter` doesn't accept any arguments.

Example outputs from documentation reporter.


The documentation report provides the following information.

- Test suite name or test package name (nested with suitepath if suitepath is used)

- Test description name or test procedure name

- Information about test failing `(FAILED - n)`

- Information about disabled test `(IGNORED)`

- List of all errors and failures

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

##Color output from documentation reporter

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.

To invoke tests with documentation reporter in color mode use one of following calls.

Example outputs from documentation reporter.


#XUnit 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).

Invocation of tests with XUnit reporter.

The `ut_xunit_reporter` doesn't accept any arguments.

Example of xunit report integrated with [Jenkins CI](https://jenkins.io/)


Example of failure report details


#Teamcity reporter

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

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

Invocation of tests with Teamcity reporter.

The `ut_teamcity_reporter` doesn't accept any arguments.

Example of unit test report from Teamcity CI server.


Example of failure report details


utPLSQL comes with a set of build-in coverage reporters. Have a look into the [coverage documentation](coverage.md) to learn more about them.

utPLSQL framework provides two main entry points to run unit tests from within database:

- `ut.run` procedures and functions

- `ut_runner.run` procedures

Those two entry points differ in purpose and behavior.

Package `ut` contains overloaded procedures and functions `run`.

The `run` API is designed to be called directly by developer, when using IDE/SQL console to execute unit tests.

The main benefit of using this API is it's simplicity.

One-line call is enough to execute a set of tests form one or multiple schemes.

The **procedures** execute specified tests and produces outputs to DBMS_OUTPUT suing specified reporter

The **functions** can only be used in SELECT statements. They execute specified tests and produce outputs as a pipelined data stream to be consumed by select satement.

Examples:

alter session set current_schema=hr;

ut.run();

end;

Execute all tests in current schema (_HR_).

ut.run('HR');

end;

Execute all tests in specified schema (_HR_).

ut.run('hr.test_apply_bonus');

end;

Execute all tests from package _HR.TEST_APPLY_BONUS_.

ut.run('hr.test_apply_bonus.bonus_cannot_be_negative');

end;

Execute single test procedure _HR.TEST_APPLY_BONUS.BONUS_CANNOT_BE_NEGATIVE_.

ut.run(ut_varcahr2_list('hr.test_apply_bonus','cust'));

end;

Execute all tests from package _HR.TEST_APPLY_BONUS_ and all tests from schema _CUST_.

Using a list of things to execute allows you to execute a fine-grained set of tests.

ut.run('hr:com.my_org.my_project');

end;

Execute all tests from all packages that are on the _COM.MY_ORG.MY_PROJECT_ suitepath.

Check the [annotations documentation](annotations.md) to find out about suitepaths and how they can be used to group test packages.

**Note:**

`ut_documentation_reporter` is default reporter for all API's defined for running unit tests.

The `ut.run` procedures and functions accept `a_reporter` attribute that defines the reporter to be used in the run.

You can execute any set of tests with any of the predefined reporters.

ut.run('hr.test_apply_bonus', ut_xunit_reporter());

end;

Execute all tests from package _HR.TEST_APPLY_BONUS_ and provide outputs to DBMS_OUTPUT using the XUnit reporter.

For details on build-in reporters look at [reporters documentation](reporters.md).

The `ut.run` functions provide exactly the same functionality as the procedures. You may use the same sets of parameters with both functions and procedures. The only difference is the output of the results.

Functions provide outputs as pipelined stream and therefore need to be executed as select statements.

Example.

select * from table(ut.run('hr.test_apply_bonus', ut_xunit_reporter()));

The `ut_runner` provides API for integrating utPLSQL with other products. Maven, Jenkins, SQL Develper, PL/SQL Developer, TOAD and others can leverage this API to call utPLSQL.

The main difference as compared to `ut.run` API is that the `ut_runner.run` does not provide outputs.

`ut_runner.run` accepts multiple reporters. Each reporter produces outputs into 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.

- in 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_id's.

- as a separate thread, start the `ut_runner.run` and pass reporters with previously defined output_id's

- for each reporter start a separate thread and read outputs from `ut_output_buffer.get_lines` table function by providing the output_id defined in the main thread.

The `ut_run.sql` script is designed to allow invocation of utPLSQL with multiple reporters.

It allows saving of outcomes into multiple output files.

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

Current limit of script parameters is 39

#Scrip invocation

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

#Parameters

Parameters -f, -o, -s are correlated. That is parameters -o and -s are defining outputs for -f.

Examples of invocation using sqlplus from command line:

All Unit tests from schema/package "hr_test" will be be invoked with two reporters:

- ut_documentation_reporter - will output to screen and save it's output to file "run.log"

- ut_teamcity_reporter - will save it's output to file "teamcity.xml"

All Unit tests from schema "hr" will be be invoked with ut_documentation_reporter as a format and the results will be printed to screen

utPLSQL is a Unit Testing framework for Oracle PL/SQL and SQL.

The framework follows industry standards and best patterns of modern Unit Testing frameworks like [JUnit](http://junit.org/junit4/) and [RSpec](http://rspec.info/)

- Support for all basic scalar data-types except ROWID and RAW

- Data-type aware testing - number 1 is not equal to string '1'

- [Annotations](docs/userguide/annotations.md) are used to define and configure tests

- Extensible [expectations](docs/userguide/expectations.md)

We welcome new developers to join our community and contribute to the utPLSQL project.

If you are interested in helping please read our [guide to contributing](docs/about/CONTRIBUTING.md)

The best place to start is to read the documentation and get familiar existing with code base.

A [slack chat](https://utplsql.slack.com/) is the place to go isf you want to talk with team members.

To sign up to the chat use [this link](http://utplsql-slack-invite.herokuapp.com/)