utPLSQL-cli

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.
• 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. (Comming Soon)

Downloading

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

You can also download all development versions from Bintray.

Requirements

• Java SE Runtime Environment 8
• When using reporters for Sonar or Coveralls client needs to be invoked from project's root directory.
• Due to Oracle license we can't ship the necessary oracle libraries directly with utPLSQL-cli. Please download the libraries directly from oracle website and put the jars into the "lib" folder of your utPLSQL-cli installation
  • Oracle ojdbc8 driver
  • If you are on a 11g database with non standard NLS settings, you will also need the orai18n library.
  • All of the above can be downloaded from Oracle download site

Compatibility

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

Usage

utplsql run <ConnectionURL> [-p=(ut_path|ut_paths)] [-f=format [-o=output_file] [-s] ...]

<ConnectionURL>     - 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. 
-p=suite_path(s)    - A suite path or a comma separated list of suite paths for unit test to be executed.     
                      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.
-f=format           - A reporter to be used for reporting.
                      If no -f option is provided, the default ut_documentation_reporter is used.
                      Available options:
                          -f=ut_documentation_reporter
                             A textual pretty-print of unit test results (usually use for console output)
                          -f=ut_teamcity_reporter
                             For reporting live progress of test execution with Teamcity CI. 
                          -f=ut_xunit_reporter
                             Used for reporting test results with CI servers like Jenkins/Hudson/Teamcity.
                          -f=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.
                          -f=ut_coveralls_reporter
                             Generates a JSON coverage report providing information on code coverage with line numbers.
                             Designed for [Coveralls](https://coveralls.io/).
                          -f=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.
                          -f=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.
  
    -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. 
                      Works only on reporeters that support colors (ut_documentation_reporter).
--failure-exit-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.
                      If you skip compatibility-check, CLI will expect the most actual framework version

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.

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.

Enabling Color Outputs on Windows

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