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.
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:
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 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
Example:
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:
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).
-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]]
--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 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 3.1.2.1913
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
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.
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