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.
- Java SE Runtime Environment 8 or newer
- When using reporters for Sonar or Coveralls client needs to be invoked from project's root directory.
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:
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:
ALTER SESSION SET NLS_LANGUAGE='AMERICAN'; ALTER SESSION SET NLS_TERRITORY='AMERICA';
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
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:
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
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: 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 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: -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). -fcode=code - Override the exit code on failure, defaults to 1. You can set it to 0 to always exit with a success status. (--failure-exit-code) -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]]
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 184.108.40.2063
utplsql reporters <ConnectionURL>
> 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_COVERALLS_REPORTER: Generates a JSON coverage report providing information on code coverage with line numbers. Designed for [Coveralls](https://coveralls.io/). JSON format conforms with specification: https://docs.coveralls.io/api-introduction 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.
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