[](https://github.com/utPLSQL/utPLSQL-cli/releases)
[](https://www.apache.org/licenses/LICENSE-2.0)
[](https://github.com/utPLSQL/utPLSQL-cli/actions/workflows/build.yml)
[](https://sonarcloud.io/summary/new_code?id=utPLSQL_utPLSQL-cli)
----------
# utPLSQL-cli
Java command-line client for [utPLSQL v3](https://github.com/utPLSQL/utPLSQL/).
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.
## Downloading
Published releases are available for download on the [utPLSQL-cli GitHub Releases Page.](https://github.com/utPLSQL/utPLSQL-cli/releases)
Development (`develop` branch) builds are not published as downloadable artifacts. To use the latest development version, build it from source:
```
git clone https://github.com/utPLSQL/utPLSQL-cli.git
cd utPLSQL-cli
mvn package appassembler:assemble
```
## Requirements
* [Java SE Runtime Environment 17](https://www.oracle.com/java/technologies/downloads/) or newer
* When using reporters for Sonar, client needs to be invoked from project's root directory.
## Compatibility
The latest CLI is compatible with database frameworks of the same **minor** version.
For example CLI-3.2.0 is compatible with database framework 3.2.* but not necessarily with framework 3.1.* or 3.3.*
## 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](https://www.oracle.com/technetwork/database/database-technologies/globalization/nls-lang-099431.html#_Toc110410543)
Example: "NLS_LANG" of `AMERICAN_AMERICA.UTF8` will lead to the following statements:
```sql
ALTER SESSION SET NLS_LANGUAGE='AMERICAN';
ALTER SESSION SET NLS_TERRITORY='AMERICA';
```
## Charset
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.
## Usage
Currently, utPLSQL-cli supports the following sub-commands:
- run
- info
- reporters
- help
To get more info about a command, use
```
utplsql -h
```
Example:
```
utplsql run -h
```
#### ConnectionURL
This is used in all commands as first parameter (though it's optional for `info`).
Accepted formats:
- `/@//[:]/`
- `/@::`
- `/@`
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
```
### run
`utplsql run []`
#### 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:
schema[.package[.procedure]]
schema:suite[.suite[.suite][...]][.procedure]
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 include or exclude in the run.
The excluded tags must be preceeded by a `-` (minus) sign and the entire expression must be surrounded by escaped doubleqotes in command line.
Format: --tags=tag1[,tag2,...,tagN]
or
Format: --tags=\"-tag1\"[,\"-tag2\",...,tagN]
-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:
-owner="app"
-regex_expression="pattern"
-type_mapping="matched_string=TYPE[/matched_string=TYPE]*"
-owner_subexpression=subexpression_number
-type_subexpression=subexpression_number
-name_subexpression=subexpression_number
-test_path=test - path to project test files, use the following options to enable custom type mappings:
-owner="app"
-regex_expression="pattern"
-type_mapping="matched_string=TYPE[/matched_string=TYPE]*"
-owner_subexpression=subexpression_number
-type_subexpression=subexpression_number
-name_subexpression=subexpression_number
-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).
--failure-exit-code=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
compatibility-check)
-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
(--random-test-order-seed)
--coverage-schemes - A comma separated list of schemas on which coverage should be gathered
Format: --coverage-schemes=schema1[,schema2[,schema3]]
--ora-stuck-timeout - Sets a timeout around Reporter creation and retries when not ready after a while. 0 = no timeout.
```
Parameters -f, -o, -s are correlated. That is parameters -o and -s are controlling outputs for reporter specified by the preceding -f parameter.
Sonar 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.
#### Examples
```
> 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.
### info
`utplsql info []`
#### Examples
```
> 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 3.1.2.1913
```
### reporters
`utplsql reporters `
#### Examples
```
> utplsql reporters app/app@localhost:1521/ORCLPDB1
UT_COVERAGE_COBERTURA_REPORTER:
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: http://cobertura.sourceforge.net/xml/coverage-04.dtd.
Sample file: https://github.com/leobalter/testing-examples/blob/master/solutions/3/report/cobertura-coverage.xml.
UT_COVERAGE_HTML_REPORTER:
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
UT_COVERAGE_SONAR_REPORTER:
Generates a JSON coverage report providing information on code coverage with line numbers.
Designed for [SonarQube](https://about.sonarqube.com/) to report coverage.
JSON format returned conforms with the Sonar specification: https://docs.sonarqube.org/display/SONAR/Generic+Test+Data
UT_DEBUG_REPORTER:
No description available
UT_DOCUMENTATION_REPORTER:
A textual pretty-print of unit test results (usually use for console output)
Provides additional properties lvl and failed
UT_JUNIT_REPORTER:
Provides outcomes in a format conforming with JUnit 4 and above as defined in: https://gist.github.com/kuzuha/232902acab1344d6b578
UT_REALTIME_REPORTER:
Provides test results in a XML format, for clients such as SQL Developer interested in showing progressing details.
UT_SONAR_TEST_REPORTER:
Generates a JSON report providing detailed information on test execution.
Designed for [SonarQube](https://about.sonarqube.com/) to report test execution.
JSON format returned conforms with the Sonar specification: https://docs.sonarqube.org/display/SONAR/Generic+Test+Data
UT_TEAMCITY_REPORTER:
Provides the TeamCity (a CI server by jetbrains) reporting-format that allows tracking of progress of a CI step/task as it executes.
https://confluence.jetbrains.com/display/TCD9/Build+Script+Interaction+with+TeamCity
UT_TFS_JUNIT_REPORTER:
Provides outcomes in a format conforming with JUnit version for TFS / VSTS.
As defined by specs :https://docs.microsoft.com/en-us/vsts/build-release/tasks/test/publish-test-results?view=vsts
Version is based on windy road junit https://github.com/windyroad/JUnit-Schema/blob/master/JUnit.xsd.
UT_XUNIT_REPORTER:
Depracated reporter. Please use Junit.
Provides outcomes in a format conforming with JUnit 4 and above as defined in: https://gist.github.com/kuzuha/232902acab1344d6b578
```
## 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](http://adoxa.altervista.org/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
```