Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

latest-release license build


Java command-line client for utPLSQL v3.

Provides an easy way of invoking utPLSQL from command-line. Main features:

  • Ability to run tests with multiple reporters simultaneously.
  • Realtime reporting during test-run
  • Ability to save output from every individual reporter to a separate output file.
  • Allows execution of selected suites, subset of suite.
  • Maps project and test files to database objects for reporting purposes.


Published releases are available for download on the utPLSQL-cli GitHub Releases Page.

You can also download all development versions from Bintray.



The latest CLI is always compatible with all database frameworks of the same major version. For example CLI-3.1.0 is compatible with database framework 3.0.0-3.1.* but not with database framework 2.x.

Localization and NLS settings

utPLSQL-cli will use the environment variables "LC_ALL" or "LANG" to change the locale and therefore the client NLS settings. If neither environment variable is available, it will use the JVM default locale.

Example: to change the NLS-settings to English American, you can do the following:

export LC_ALL=en_US.utf-8

The charset-part of LC_ALL is ignored.

In addition, utPLSQL-cli will use an existing "NLS_LANG" environment variable to create corresponding ALTER SESSION-statements during initialization of the connection.

The variable is parsed according to the Oracle globalization documentation

Example: "NLS_LANG" of AMERICAN_AMERICA.UTF8 will lead to the following statements:



Java will use the default charset of your system for any string output.
You can change this by passing the -Dfile.encoding property to the JVM when running a java-application.
To avoid changing the utPLSQL-cli shell- or batchscript, you can define -Dfile.encoding in the environment variable JAVA_TOOL_OPTIONS. This environment variable will be picked up and interpreted by the JVM:

export JAVA_TOOL_OPTIONS='-Dfile.encoding=utf8'
utplsql run user/pw@connecstring

> Picked up JAVA_TOOL_OPTIONS: -Dfile.encoding=utf8

Make sure that the defined charset matches with the codepage your console is using.


Currently, utPLSQL-cli supports the following sub-commands:

  • run
  • info
  • reporters
  • help

To get more info about a command, use

utplsql <sub-command> -h


utplsql run -h


This is used in all commands as first parameter (though it's optional for info).

Accepted formats:

  • <user>/<password>@//<host>[:<port>]/<service>
  • <user>/<password>@<host>:<port>:<SID>
  • <user>/<password>@<TNSName>

To connect using TNS, you need to have the ORACLE_HOME environment variable set. The file tnsnames.ora must exist in path %ORACLE_HOME%/network/admin The file tnsnames.ora must contain valid TNS entries.

In case you use a username containing / or a password containing @ you should encapsulate it with double quotes ":

utplsql run "my/Username"/"myP@ssword"@connectstring


utplsql run <ConnectionURL> [<options>]


-p=suite_path(s)    - A suite path or a comma separated list of suite paths for unit test to be executed.     
(--path)              The path(s) can be in one of the following formats:
                      Both formats can be mixed in the list.
                      If only schema is provided, then all suites owner by that schema are executed.
                      If -p is omitted, the current schema is used.

--tags=tags         - A comma separated list of tags to run. 
                      Format: --tags=tag1[,tag2[,tag3]]
-f=format           - A reporter to be used for reporting.
(--format)            If no -f option is provided, the default ut_documentation_reporter is used.
                      See reporters command for possible values
  -o=output         - Defines file name to save the output from the specified reporter.
                      If defined, the output is not displayed on screen by default. This can be changed with the -s parameter.
                      If not defined, then output will be displayed on screen, even if the parameter -s is not specified.
                      If more than one -o parameter is specified for one -f parameter, the last one is taken into consideration.
  -s                - Forces putting output to to screen for a given -f parameter.
-source_path=source - path to project source files, use the following options to enable custom type mappings:
-test_path=test     - path to project test files, use the following options to enable custom type mappings:
-c                  - If specified, enables printing of test results in colors as defined by ANSICONSOLE standards. 
(--color)             Works only on reporeters that support colors (ut_documentation_reporter).
-fcode=code         - Override the exit code on failure, defaults to 1. You can set it to 0 to always exit with a success status.

-scc                - If specified, skips the compatibility-check with the version of the database framework.
(--skip-              If you skip compatibility-check, CLI will expect the most actual framework version
-include=pckg_list  - Comma-separated object list to include in the coverage report.
                      Format: [schema.]package[,[schema.]package ...].
                      See coverage reporting options in framework documentation.
-exclude=pckg_list  - Comma-separated object list to exclude from the coverage report.
                      Format: [schema.]package[,[schema.]package ...].
                      See coverage reporting options in framework documentation.
-q                  - Does not output the informational messages normally printed to console.
(--quiet)             Default: false
-d                  - Outputs a load of debug information to console
(--debug)             Default: false

-t=timeInMinutes   - Sets the timeout in minutes after which the cli will abort. 
(--timeout)          Default 60
-D                 - Enables DBMS_OUTPUT in the TestRunner-Session
(--dbms_output)      Default: false

-r                 - Enables random order of test executions
(--random-test-order) Default: false

-seed              - Sets the seed to use for random test execution order. If set, it sets -random to true

--coverage-schemes - A comma separated list of schemas on which coverage should be gathered
                     Format: --coverage-schemes=schema1[,schema2[,schema3]]

Parameters -f, -o, -s are correlated. That is parameters -o and -s are controlling outputs for reporter specified by the preceding -f parameter.

Sonar and Coveralls reporter will only provide valid reports, when source_path and/or test_path are provided, and ut_run is executed from your project's root path.


> utplsql run hr/hr@xe -p=hr_test -f=ut_documentation_reporter -o=run.log -s -f=ut_coverage_html_reporter -o=coverage.html -source_path=source

Invokes all Unit tests from schema/package "hr_test" with two reporters:

  • ut_documentation_reporter - will output to screen and save output to file "run.log"
  • ut_coverage_html_reporter - will report only on database objects that are mapping to file structure from "source" folder and save output to file "coverage.html"
> utplsql run hr/hr@xe

Invokes all unit test suites from schema "hr". Results are displayed to screen using default ut_documentation_reporter.


utplsql info [<ConnectionURL>]


> utplsql info

cli 3.1.1-SNAPSHOT.local
utPLSQL-java-api 3.1.1-SNAPSHOT.123
> utplsql info app/app@localhost:1521/ORCLPDB1

cli 3.1.1-SNAPSHOT.local
utPLSQL-java-api 3.1.1-SNAPSHOT.123


utplsql reporters <ConnectionURL>


> utplsql reporters app/app@localhost:1521/ORCLPDB1

    Generates a Cobertura coverage report providing information on code coverage with line numbers.
    Designed for Jenkins and TFS to report coverage.
    Cobertura Document Type Definition can be found:
    Sample file:

    Generates a HTML coverage report with summary and line by line information on code coverage.
    Based on open-source simplecov-html coverage reporter for Ruby.
    Includes source code in the report.
    Will copy all necessary assets to a folder named after the Output-File

    Generates a JSON coverage report providing information on code coverage with line numbers.
    Designed for [SonarQube]( to report coverage.
    JSON format returned conforms with the Sonar specification:

    Generates a JSON coverage report providing information on code coverage with line numbers.
    Designed for [Coveralls](
    JSON format conforms with specification:

    No description available

    A textual pretty-print of unit test results (usually use for console output)
    Provides additional properties lvl and failed

    Provides outcomes in a format conforming with JUnit 4 and above as defined in:

    Provides test results in a XML format, for clients such as SQL Developer interested in showing progressing details.

    Generates a JSON report providing detailed information on test execution.
    Designed for [SonarQube]( to report test execution.
    JSON format returned conforms with the Sonar specification:

    Provides the TeamCity (a CI server by jetbrains) reporting-format that allows tracking of progress of a CI step/task as it executes.

    Provides outcomes in a format conforming with JUnit version for TFS / VSTS.
    As defined by specs :
    Version is based on windy road junit

    Depracated reporter. Please use Junit.
    Provides outcomes in a format conforming with JUnit 4 and above as defined in:

Using utPLSQL-cli as sysdba

Since 3.1.6 it is possible to run utPLSQL-cli as sysdba by running

utplsql run "sys as sysdba"/pw@connectstring

It is, however, not recommended to run utPLSQL with sysdba privileges.

Enabling Color Outputs on Windows

To enable color outputs on Windows cmd you need to install an open-source utility called ANSICON.

Custom Reporters

Since v3.1.0 you can call custom reporters (PL/SQL) via cli, too. Just call the name of the custom reporter as you would do for the core reporters.

utplsql run hr/hr@xe -p=hr_test -f=my_custom_reporter -o=run.log -s