diff --git a/CONTRIBUTING.md b/docs/about/CONTRIBUTING.md similarity index 100% rename from CONTRIBUTING.md rename to docs/about/CONTRIBUTING.md diff --git a/authors.md b/docs/about/authors.md similarity index 100% rename from authors.md rename to docs/about/authors.md diff --git a/docs/about/project-details.md b/docs/about/project-details.md index 56e216f00..53bc1bedb 100644 --- a/docs/about/project-details.md +++ b/docs/about/project-details.md @@ -8,8 +8,7 @@ utPLSQL is hosted on [hosted on GitHub](https://github.com/utPLSQL/utPLSQL) and open source project. -Community help on this project is always appreciated, if your interested in helping please read our [guide to contributing](https://github.com/utPLSQL/utPLSQL/blob/master/CONTRIBUTING.md) +Community help on this project is always appreciated, if your interested in helping please read our [guide to contributing](CONTRIBUTING.md) - \ No newline at end of file diff --git a/docs/images/3_steps_to_run_utPLSQL.gif b/docs/images/3_steps_to_run_utPLSQL.gif new file mode 100644 index 000000000..ec99033e9 Binary files /dev/null and b/docs/images/3_steps_to_run_utPLSQL.gif differ diff --git a/docs/userguide/images/coverage_html_details.png b/docs/images/coverage_html_details.png similarity index 100% rename from docs/userguide/images/coverage_html_details.png rename to docs/images/coverage_html_details.png diff --git a/docs/userguide/images/coverage_html_summary.png b/docs/images/coverage_html_summary.png similarity index 100% rename from docs/userguide/images/coverage_html_summary.png rename to docs/images/coverage_html_summary.png diff --git a/docs/images/documentation_reporter.png b/docs/images/documentation_reporter.png new file mode 100644 index 000000000..d4f485164 Binary files /dev/null and b/docs/images/documentation_reporter.png differ diff --git a/docs/images/documentation_reporter_color.png b/docs/images/documentation_reporter_color.png new file mode 100644 index 000000000..9cacb5e3f Binary files /dev/null and b/docs/images/documentation_reporter_color.png differ diff --git a/docs/images/running_from_command_line.gif b/docs/images/running_from_command_line.gif new file mode 100644 index 000000000..9701ebd03 Binary files /dev/null and b/docs/images/running_from_command_line.gif differ diff --git a/docs/images/running_with_coverage_line.gif b/docs/images/running_with_coverage_line.gif new file mode 100644 index 000000000..eed184752 Binary files /dev/null and b/docs/images/running_with_coverage_line.gif differ diff --git a/docs/images/teamcity_report_example.png b/docs/images/teamcity_report_example.png new file mode 100644 index 000000000..b00ea44a8 Binary files /dev/null and b/docs/images/teamcity_report_example.png differ diff --git a/docs/images/teamcity_report_example_errors.png b/docs/images/teamcity_report_example_errors.png new file mode 100644 index 000000000..fe4523894 Binary files /dev/null and b/docs/images/teamcity_report_example_errors.png differ diff --git a/docs/images/xunit_reporter_jenkins.png b/docs/images/xunit_reporter_jenkins.png new file mode 100644 index 000000000..5032ecc5c Binary files /dev/null and b/docs/images/xunit_reporter_jenkins.png differ diff --git a/docs/images/xunit_reporter_jenkins_errors.png b/docs/images/xunit_reporter_jenkins_errors.png new file mode 100644 index 000000000..3796d27db Binary files /dev/null and b/docs/images/xunit_reporter_jenkins_errors.png differ diff --git a/docs/index.md b/docs/index.md index 5733633dd..4bce7f092 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,11 +1,56 @@ # Introduction to utPLSQL - utPLSQL is a powerful unit testing library for Oracle PL/SQL. +utPLSQL is a Unit Testing framework for Oracle PL/SQL. +The framework follows industry standards and best patterns of modern Unit Testing frameworks like [JUnit](http://junit.org/junit4/) and [RSpec](http://rspec.info/) - TODO: Sales pitch of utPLSQL with links to documentation areas that support discussed features. + - User Guide + - [Installation](userguide/install.md) + - [Getting Started](userguide/getting-started.md) + - [Annotations](userguide/annotations.md) + - [Expectations](userguide/expectations.md) + - [Running unit tests](userguide/running-unit-tests.md) + - [Using the ut_run script](userguide/ut_run-script.md) + - [Testing best pracitces](userguide/best-practices.md) + - [Upgrade utPLSQL](userguide/upgrade.md) + - Reporting + - [Using reporters](userguide/reporters.md) + - [Reporting errors](userguide/exception-reporting.md) + - [Code coverage](userguide/coverage.md) + - About + - [Project Details](about/project-details.md) + - [License](about/license.md) + - [Support](about/support.md) + - [Authors](about/authors.md) + - [Contributing](about/CONTRIBUTING.md) - TODO: Table of Contents / Index of the docs +#Three steps +With just three simple steps you can define and run your unit tests for PLSQL code. + +1. Install the utPLSQL framework +2. Create Unit Tests to for the code +3. Run the tests + +Here is how you can simply create tested code, unit tests and execute the tests using SQL Developer + +![3_steps](images/3_steps_to_run_utPLSQL.gif) + +Check out the sections on [annotations](userguide/annotations.md) and [expectations](userguide/expectations.md) to see how to define your tests. + + +# Command line +The `ut_run.sql` script is a powerful thing - it can provide output from the tests on the fly. +You can also use it to have coloured output from the test, and if you try to test code that was dropper, all of unit tests related to that code will fail. + +![colors_and_failures](images/running_from_command_line.gif) + +Look into [ut_run.sql script options](userguide/ut_run-script.md) to see more. + +# Coverage +If you want to have code coverage gathered on your code , it's best to use `ut_run.sql` to execute your tests with multiple reporters and have both test execution report as well as coverage report saved to a file. +Check out the [coverage documentation](userguide/coverage.md) for options of coverage reporting + +![coverage](images/running_with_coverage_line.gif) diff --git a/docs/userguide/coverage.md b/docs/userguide/coverage.md index 37859caf1..a7915267f 100644 --- a/docs/userguide/coverage.md +++ b/docs/userguide/coverage.md @@ -44,11 +44,11 @@ The `ut_coverage_html_reporter` will produce a interactive HTML report. You may The report provides a summary information with list of source code that was expected to be covered. -![Coverage Summary page](images/coverage_html_summary.png) +![Coverage Summary page](../images/coverage_html_summary.png) The report allow to navigate to every source and inspect line by line coverage. -![Coverage Details page](images/coverage_html_details.png) +![Coverage Details page](../images/coverage_html_details.png) ##Coverage reporting options diff --git a/docs/userguide/expectations.md b/docs/userguide/expectations.md index ae1adc7a6..b5a3f48db 100644 --- a/docs/userguide/expectations.md +++ b/docs/userguide/expectations.md @@ -1,4 +1,4 @@ -# Concept of expectation and matcher +# Concepts Validation of the code under test (the tested logic of procedure/function etc.) is performed by comparing the actual data against the expected data. To do that we use concept of expectation and a matcher to perform the check on the data. @@ -12,68 +12,237 @@ end; Expectation is a set of the expected value(s), actual values(s) and the matcher(s) to run on those values. -Matcher is defining the comparison operation to be performed on expected and actual values. +Matcher is defining the comparison operation to be performed on expected and actual values. +Pseudo-code: +```sql + ut.expect( a_actual {data-type} ).to_( {matcher} ); + ut.expect( a_actual {data-type} ).not_to( {matcher} ); +``` -# List of currently build-in matchers -- `match` -- `equal` -- `be_true` -- `be_null` -- `be_not_null` -- `be_like` -- `be_less_than` -- `be_less_or_equal` -- `be_greater_than` -- `be_greater_or_equal` -- `be_false` + +# Matchers +utPLSQL provides following matchers to perform checks on the expected and actual values. - `be_between` - `be_empty` +- `be_false` +- `be_greater_than` +- `be_greater_or_equal` +- `be_less_or_equal` +- `be_less_than` +- `be_like` +- `be_not_null` +- `be_null` +- `be_true` +- `equal` +- `match` -## match -Allows regexp_like validations to be executed against the following datatypes: -- `clob` -- `varchar2` +## be_between +Validates that the actual value is between the lower and upper bound. + +Example: +```sql + exec ut.expect( a_actual => 3 ).to_( be_between( a_lower_bound => 1, a_upper_bound => 3 ) ); + exec ut.expect( 3 ).to_( be_between( 1, 3 ) ); +``` + +## be_empty +Unary matcher that validates if the provided data-set is empty. + +Usage: +```sql +declare + l_cursor sys_refcursor; +begin + open l_cursor for select * from dual where 1 = 0; + ut.expect( l_cursor ).to_( be_empty() ); +end; +``` + +When used with anydata, it is only valid for collection data types. + +## be_false +Unary matcher that validates if the provided value is false. + +Usage: +```sql + exec ut.expect( ( 1 = 0 ) ).to_( be_false() ); +``` + +## be_greater_or_equal +Allows to check if the actual value is greater or equal than the expected. + +Usage: +```sql + exec ut.expect( sysdate ).to_( be_greater_or_equal( sysdate - 1 ) ); +``` + +## be_greater_than +Allows to check if the actual value is greater than the expected. + +Usage: +```sql + exec ut.expect( 2 ).to_( be_greater_than( 1 ) ); +``` + +## be_less_or_equal +Allows to check if the actual value is less or equal than the expected. + +Usage: +```sql + exec ut.expect( 3 ).to_( be_less_or_equal( 3 ) ); +``` + +## be_less_than +Allows to check if the actual value is less than the expected. Usage: ```sql - ut.expect( a_actual ).to_( match( a_pattern in varchar2, a_modifiers in varchar2 := null) ) + exec ut.expect( 3 ).to_( be_less_than( 2 ) ); ``` -Parameters `a_pattern` and `a_modifiers` represent a valid regexp pattern accepted by [Oracle regexp_like function](http://docs.oracle.com/database/121/SQLRF/conditions007.htm#SQLRF00501) + +## be_like +Validates that the actual value is like the expected expression. + +Usage: +```sql + exec ut.expect( 'Lorem_impsum' ).to_( be_like( a_mask => '%rem\_%', a_escape_char => '\' ) ); + exec ut.expect( 'Lorem_impsum' ).to_( be_like( '%rem\_%', '\' ) ); +``` + +Parameters `a_mask` and `a_escape_char` represent a valid parameters of the [Oracle like function](https://docs.oracle.com/database/121/SQLRF/conditions007.htm#SQLRF52142) + + +## be_not_null +Unary matcher that validates if the actual value is not null. + +Usage: +```sql + exec ut.expect( to_clob('ABC') ).to_( be_not_null() ); +``` + +## be_null +Unary matcher that validates if the actual value is null. + +Usage: +```sql + exec ut.expect( cast(null as varchar2(100)) ).to_( be_null() ); +``` + +## be_true +Unary matcher that validates if the provided value is false. +- `boolean` + +Usage: +```sql + exec ut.expect( ( 1 = 1 ) ).to_( be_true() ); +``` ## equal -The equal matcher is a very restrictive matcher. -It only returns true, if compared data-types. +The equal matcher is a very restrictive matcher. It only returns true, if compared data-types. That means, that comparing varchar2 to a number will fail even if the varchar2 contains the same number. This matcher is designed to capture changes of data-type, so that if you expect your variable to be number and is now something else, the test will fail and give you early indication of potential problem. Usage: ```sql - ut.expect( a_actual ).to_( equal( a_expected {mulitple data-types}, a_nulls_are_equal boolean := null) ) +declare + x ref_cursor; + y ref_cursor; +begin + ut.expect( 'a dog' ).to_( equal( 'a dog' ) ); + ut.expect( a_actual => y ).to_( equal( a_expected => x, a_nulls_are_equal => true ) ); +end; ``` +The `a_nulls_are_equal` parameter decides on the behavior of `null=null` comparison (**this comparison by default is true!**) +The `anydata` data type is used to compare user defined object and collections. + +Example usage of anydata to compare user defined types. +```sql +create type department as object(name varchar2(30)); +/ +create or replace package demo_dept as + -- %suite(demo) -The equal matcher accepts a_expected of following data-types. -- `anydata` -- `blob` -- `boolean` -- `clob` -- `date` -- `number` -- `sys_refcursor` -- `timestamp_unconstrained` -- `timestamp_tz_unconstrained` -- `timestamp_ltz_unconstrained` -- `varchar2` -- `yminterval_unconstrained` -- `dsinterval_unconstrained` + --%test(demo_dept) + procedure test_department; +end; +/ + +create or replace package body demo_dept as + procedure test_department is + v_expected department; + v_actual department; + begin + v_expected := department('HR'); + ut.expect( anydata.convertObject(v_expected) ).to_( equal( anydata.convertObject(v_actual) ) ); + end; +end; +/ +``` + +This test will fail as the `v_acutal` is not equal `v_expected`. + +## match +Validates that the actual value is matching the expected regular expression. + +Usage: +```sql + exec ut.expect( a_actual => '123-456-ABcd' ).to_( match( a_pattern => '\d{3}-\d{3}-[a-z]', a_modifiers => 'i' ) ); + exec ut.expect( 'some value' ).to_( match( '^some.*' ) ); +``` + +Parameters `a_pattern` and `a_modifiers` represent a valid regexp pattern accepted by [Oracle regexp_like function](https://docs.oracle.com/database/121/SQLRF/conditions007.htm#SQLRF00501) + + + +# Supported data types + +Below matrix illustrates the data types supported by different matchers. + +| | be_between | be_empty | be_false | be_greater_than | be_greater_or_equal | be_less_or_equal | be_less_than | be_like | be_not_null | be_null | be_true | equal | match | +|:------------------------------|:----------:|:--------:|:--------:|:---------------:|:-------------------:|:----------------:|:------------:|:-------:|:-----------:|:-------:|:-------:|:-----:|:-----:| +| anydata | | X | | | | | | | X | X | | X | | +| blob | | | | | | | | | X | X | | X | | +| boolean | | | X | | | | | | X | X | X | X | | +| clob | | | | | | | | X | X | X | | X | X | +| date | X | | | X | X | X | X | | X | X | | X | | +| number | X | | | X | X | X | X | | X | X | | X | | +| refcursor | | X | | | | | | | X | X | | X | | +| timestamp | X | | | X | X | X | X | | X | X | | X | | +| timestamp with timezone | X | | | X | X | X | X | | X | X | | X | | +| timestamp with local timezone | X | | | X | X | X | X | | X | X | | X | | +| varchar2 | X | | | | | | | X | X | X | | X | X | +| interval year to month | X | | | X | X | X | X | | X | X | | X | | +| interval day to second | X | | | X | X | X | X | | X | X | | X | | -The second parameter decides on the behavior of `null=null` comparison (**this comparison by default is true!**) - - A test procedure will contain one or more checks to verify the the test performed as expected. These checks are called assertion. utPLSQL provides a robust and extensible assertion library. + +# Negating the matcher +Expectations provide a very convenient way to check for a negative of the expectation. + +Syntax of check for matcher evaluating to true: +```sql + exec ut.expect( a_actual {data-type} ).to_( {matcher} ); +``` + +Syntax of check for matcher evaluating to false: +```sql + exec ut.expect( a_actual {data-type} ).not_to( {matcher} ); +``` + +If a matcher evaluated to NULL, then both `to_` and `not_to` will cause the expectation to report failure. + +Example: +```sql +begin + ut.expect( null ).to_( be_true() ); + ut.expect( null ).not_to( be_true() ); +end; +``` + +Since NULL is neither true not it is not true, both expectations will report failure. -TODO: Finish Expectations concepts diff --git a/docs/userguide/install.md b/docs/userguide/install.md index b9a58f860..bb92c785c 100644 --- a/docs/userguide/install.md +++ b/docs/userguide/install.md @@ -25,7 +25,12 @@ The installation user/schema must have the following Oracle system permissions d In addition it must be granted execute to the following system packages. - - DBMS_LOCK + - DBMS_LOCK + +The utPLSQL is using Oracle [DBMS_PROFILER tables](https://docs.oracle.com/cd/E18283_01/appdev.112/e16760/d_profil.htm#i999476). The tables will be created in the installation schema if they do not exist. +The uninstall process however will not drop those tables, as they can potentially be shared and reused for profiling PLSQL code. +It is up to DBA to maintain the storage of the profiler tables. + # Installation Procedure diff --git a/docs/userguide/reporters.md b/docs/userguide/reporters.md index 5d8983b99..bb506d389 100644 --- a/docs/userguide/reporters.md +++ b/docs/userguide/reporters.md @@ -1,2 +1,94 @@ -#Unit Test reporters -TODO +utPLSQL provides the following reporting formats. + +#Documentation reporter + +The `ut_documentation_reporter` is the default reporting format used by the framework. +It provides a human readable test results. + +To invoke tests with documentation reporter use one of following calls from sql console (SQLPlus) + +`exec ut.run();` + +`exec ut.run(ut_documentation_reporter());` + +You may also invoke unit tests directly from command line by calling. + +`sqlplus /nolog @ut_run %user%/%pass%@%dbsid%` + +Invoking tests from command line tool `ut_run.sql` allows you to track progress of test execution. +In that case, the documentation reporter will provide information about each test that was executed as soon as it's execution finishes. +For more details on using the `ut_run.sql` script look into [ut_run.sql](ut_run-script.md) documentation. + +The `ut_documentation_reporter` doesn't accept any arguments. + +Example outputs from documentation reporter. + +![doc_reporter_outputs](../images/documentation_reporter.png) + +The documentation report provides the following information. +- Test suite name or test package name (nested with suitepath if suitepath is used) +- Test description name or test procedure name +- Information about test failing `(FAILED - n)` +- Information about disabled test `(IGNORED)` +- List of all errors and failures +- Summary with total number of tests, number of tests with status and timing for the execution + + +##Color output from documentation reporter + +When invoking tests with documentation reporter and your command line supports ANSICONSOLE (default on Unix), you can obtain the coloured outputs from the documentation reporter. + +To invoke tests with documentation reporter in color mode use one of following calls. + +`exec ut.run(a_color_console=>true);` + +`exec ut.run(ut_documentation_reporter(), a_color_console=>true);` + +Example outputs from documentation reporter. + +![doc_reporter_outputs](../images/documentation_reporter_color.png) + + +#XUnit reporter + +Most of continuous integration servers (like Jenkins) are capable of consuming unit test execution results in [XUnit/JUnit](https://en.wikipedia.org/wiki/XUnit) format. +The `ut_xunit_reporter` is producing outcomes as XUnit-compatible XML unit test report, that can be used by CI servers to display their custom reports and provide metrics (like tests execution trends). + +Invocation of tests with XUnit reporter. + +`exec ut.run(ut_xunit_reporter());` + +The `ut_xunit_reporter` doesn't accept any arguments. + +Example of xunit report integrated with [Jenkins CI](https://jenkins.io/) + +![xunit_reporter_outputs](../images/xunit_reporter_jenkins.png) + +Example of failure report details + +![xunit_reporter_outputs](../images/xunit_reporter_jenkins_errors.png) + + +#Teamcity reporter + +[Teamcity](https://www.jetbrains.com/teamcity/) is a CI server by Jetbrains. It supports XUnit reporting and additionally has it's own format of reporting that allows tracking of progress of a CI step/task as it executes. +The TeamCity format developed by Jetbrains is supported by utPLSQL with `ut_teamcity_reporter`. + +Invocation of tests with Teamcity reporter. + +`exec ut.run(ut_teamcity_reporter());` + +The `ut_teamcity_reporter` doesn't accept any arguments. + +Example of unit test report from Teamcity CI server. + +![xunit_reporter_outputs](../images/teamcity_report_example.png) + +Example of failure report details + +![xunit_reporter_outputs](../images/teamcity_report_example_errors.png) + + +# Coverage reporters + +utPLSQL comes with a set of build-in coverage reporters. Have a look into the [coverage documentation](coverage.md) to learn more about them. diff --git a/docs/userguide/running-unit-tests.md b/docs/userguide/running-unit-tests.md index 10c5af46e..49f05a654 100644 --- a/docs/userguide/running-unit-tests.md +++ b/docs/userguide/running-unit-tests.md @@ -1,2 +1,112 @@ -#Running unit tests -TODO +utPLSQL framework provides two main entry points to run unit tests from within database: +- `ut.run` procedures and functions +- `ut_runner.run` procedures + +Those two entry points differ in purpose and behavior. + +# ut.run +Package `ut` contains overloaded procedures and functions `run`. +The `run` API is designed to be called directly by developer, when using IDE/SQL console to execute unit tests. +The main benefit of using this API is it's simplicity. +One-line call is enough to execute a set of tests form one or multiple schemes. + +The **procedures** execute specified tests and produces outputs to DBMS_OUTPUT using specified reporter +The **functions** can only be used in SELECT statements. They execute specified tests and produce outputs as a pipelined data stream to be consumed by select satement. + +## ut.run procedures + +Examples: +```sql +alter session set current_schema=hr; +begin + ut.run(); +end; +``` +Execute all tests in current schema (_HR_). + + +```sql +begin + ut.run('HR'); +end; +``` +Execute all tests in specified schema (_HR_). + + +```sql +begin + ut.run('hr:com.my_org.my_project'); +end; +``` + +Execute all tests from all packages that are on the _COM.MY_ORG.MY_PROJECT_ suitepath. +Check the [annotations documentation](annotations.md) to find out about suitepaths and how they can be used to group test packages. + + +```sql +begin + ut.run('hr.test_apply_bonus'); +end; +``` +Execute all tests from package _HR.TEST_APPLY_BONUS_. + + +```sql +begin + ut.run('hr.test_apply_bonus.bonus_cannot_be_negative'); +end; +``` +Execute single test procedure _HR.TEST_APPLY_BONUS.BONUS_CANNOT_BE_NEGATIVE_. + + +```sql +begin + ut.run(ut_varcahr2_list('hr.test_apply_bonus','cust')); +end; +``` +Execute all tests from package _HR.TEST_APPLY_BONUS_ and all tests from schema _CUST_. +Using a list of items to execute allows you to execute a fine-grained set of tests. + + +**Note:** +`ut_documentation_reporter` is default reporter for all API's defined for running unit tests. + +The `ut.run` procedures and functions accept `a_reporter` attribute that defines the reporter to be used in the run. +You can execute any set of tests with any of the predefined reporters. + +```sql +begin + ut.run('hr.test_apply_bonus', ut_xunit_reporter()); +end; +``` +Execute all tests from package _HR.TEST_APPLY_BONUS_ and provide outputs to DBMS_OUTPUT using the XUnit reporter. + + +For details on build-in reporters look at [reporters documentation](reporters.md). + +## ut.run functions + +The `ut.run` functions provide exactly the same functionality as the procedures. You may use the same sets of parameters with both functions and procedures. The only difference is the output of the results. +Functions provide outputs as pipelined stream and therefore need to be executed as select statements. + +Example. +```sql +select * from table(ut.run('hr.test_apply_bonus', ut_xunit_reporter())); +``` + +# ut_runner.run + +The `ut_runner` provides API for integrating utPLSQL with other products. Maven, Jenkins, SQL Develper, PL/SQL Developer, TOAD and others can leverage this API to call utPLSQL. + +The main difference as compared to `ut.run` API is that the `ut_runner.run` does not print outputs to the screen. + +`ut_runner.run` accepts multiple reporters. Each reporter produces outputs into a separate output (uniquely identified by output_id). +Outputs of multiple reporters can be consumed in parallel. This allows for live reporting of test execution progress with threads and several database sessions. + +The concept is pretty simple. + +- in the main thread (session), define the reporters to be used. Each reporter has it's output_id and so you need to extract and store those output_id's. +- as a separate thread, start the `ut_runner.run` and pass reporters with previously defined output_id's +- for each reporter start a separate thread and read outputs from `ut_output_buffer.get_lines` table function by providing the output_id defined in the main thread. + +`ut_runner.run` is internally used by the [`ut_run.sql` script](ut_run-script.md) which is a utility for running tests with multiple reporters and provides parameters to save reporters results into individual files on the local file system. diff --git a/docs/userguide/ut_run-script.md b/docs/userguide/ut_run-script.md new file mode 100644 index 000000000..9e635037b --- /dev/null +++ b/docs/userguide/ut_run-script.md @@ -0,0 +1,52 @@ +The `ut_run.sql` script is designed to allow invocation of utPLSQL with multiple reporters. +It allows saving of outcomes into multiple output files. +It also facilitates displaying on screen unit test results while the execution is still ongoing. +Current limit of script parameters is 39 + +#Scrip invocation + ut_run.sql user/password@database [-p=(ut_path|ut_paths)] [-c] [-f=format [-o=output] [-s] ...] + +#Parameters +``` + user - username to connect as + password - password of the user + database - database to connect to + -p=ut_path(s)- A path or a comma separated list of paths to unit test to be executed. + The path can be in one of the following formats: + schema[.package[.procedure]] + schema:suite[.suite[.suite][...]][.procedure] + Both formats can be mixed in the comma separated list. + If only schema is provided, then all suites owner by that schema (user) are executed. + If -p is omitted, the current schema is used. + -f=format - A reporter to be used for reporting. + Available options: + -f=ut_documentation_reporter + A textual pretty-print of unit test results (usually use for console output) + -f=ut_teamcity_reporter + A teamcity Unit Test reporter, that can be used to visualize progress of test execution as the job progresses. + -f=ut_xunit_reporter + A XUnit xml format (as defined at: http://stackoverflow.com/a/9691131 and at https://gist.github.com/kuzuha/232902acab1344d6b578) + Usually used by Continuous Integration servers like Jenkins/Hudson or Teamcity to display test results. + If no -f option is provided, the ut_documentation_reporter will be used. + + -o=output - file name to save the output provided by the 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. + -c - If specified, enables printing of test results in colors as defined by ANSICONSOLE standards +``` + +Parameters -f, -o, -s are correlated. That is parameters -o and -s are defining outputs for -f. + +Examples of invocation using sqlplus from command line: + +`sqlplus /nolog @ut_run hr/hr@xe -p=hr_test -f=ut_documentation_reporter -o=run.log -s -f=ut_teamcity_reporter -o=teamcity.xml` + +All Unit tests from schema/package "hr_test" will be be invoked with two reporters: + - ut_documentation_reporter - will output to screen and save it's output to file "run.log" + - ut_teamcity_reporter - will save it's output to file "teamcity.xml" + +`sqlplus /nolog @ut_run hr/hr@xe` + +All Unit tests from schema "hr" will be be invoked with ut_documentation_reporter as a format and the results will be printed to screen diff --git a/mkdocs.yml b/mkdocs.yml index 0ae687e2e..401100c47 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,7 +4,7 @@ site_name: utPLSQL site_description: utPLSQL Documenation Powerful Unit Testing Framework for Oracle PL/SQL copyright: Copyright © 2016 - utPLSQL Team -repo_url: https://github.com/utplsql/utplsql/ +repo_url: https://github.com/utPLSQL/utPLSQL theme: mkdocs use_directory_urls: false strict: true @@ -16,9 +16,17 @@ pages: - Getting Started: userguide/getting-started.md - Annotations: userguide/annotations.md - Expectations: userguide/expectations.md - - Testing Best Pracitces: userguide/best-practices.md - - Upgrade utPLSQL : userguide/upgrade.md + - Running unit tests: userguide/running-unit-tests.md + - Using the ut_run script: userguide/ut_run-script.md + - Testing best pracitces: userguide/best-practices.md + - Upgrade utPLSQL: userguide/upgrade.md + - Reporting: + - Using reporters: userguide/reporters.md + - Reporting errors: userguide/exception-reporting.md + - Code coverage: userguide/coverage.md - About: - Project Details: about/project-details.md - License: about/license.md - Support: about/support.md + - Authors: about/authors.md + - Contributing: about/CONTRIBUTING.md diff --git a/readme.md b/readme.md index 0ff69a258..b6e7f48c2 100644 --- a/readme.md +++ b/readme.md @@ -17,15 +17,18 @@ utPLSQL version 3 is a complete rewrite of utPLSQL v2 from scratch. Version 2 still supports older versions of Oracle that are no longer available. The community that had developed on GitHub, decided that a new internal architecture was needed, from that version 3 was born. -We welcome new developers to join our community and contribute to the utPLSQL project. +# Introduction +utPLSQL is a Unit Testing framework for Oracle PL/SQL and SQL. +The framework follows industry standards and best patterns of modern Unit Testing frameworks like [JUnit](http://junit.org/junit4/) and [RSpec](http://rspec.info/) + -Primary features: - - Support for all basic scalar data-types +# Primary features + - Support for all basic scalar data-types except ROWID and RAW - Support for User Defined Object Types and Collections - Support for native cursors both strong and weak - - Data-type aware testing - - [Annotations](docs/userguide/annotations.md) based test definitions - - Extensible [matchers](docs/userguide/expectations.md) + - Data-type aware testing - number 1 is not equal to string '1' + - [Annotations](docs/userguide/annotations.md) are used to define and configure tests + - Extensible [expectations](docs/userguide/expectations.md) - Extensible reporting formats - Extensible output providers - Support for multi-reporting @@ -43,6 +46,16 @@ __Download__ Published releases are available for download on the [utPLSQL GitHub Releases Page.](https://github.com/utPLSQL/utPLSQL/releases) +# Contributing to the project + +We welcome new developers to join our community and contribute to the utPLSQL project. +If you are interested in helping please read our [guide to contributing](docs/about/CONTRIBUTING.md) +The best place to start is to read the documentation and get familiar existing with code base. +A [slack chat](https://utplsql.slack.com/) is the place to go isf you want to talk with team members. +To sign up to the chat use [this link](http://utplsql-slack-invite.herokuapp.com/) + + +[__Authors__](docs/about/authors.md) __Version 2 to Version 3 Comparison__ @@ -194,19 +207,12 @@ c:\my_work\>sqlplus /nolog @ut_run hr/hr@xe Will run all the suites in the current schema (hr) and provide documentation report into screen. Invoking this script will show the progress after each test. - -__Primary Directories__ +__Project Directories__ * .travis - contains files needed for travis-ci integration * client_source - Sources to be used on the client-side. Developer workstation or CI platform to run the tests. * development - Set of useful scripts and utilities for development and debugging of utPLSQL -* docs - Markdown version of the documentation +* docs/md - Markdown version of the documentation * examples - contains example unit tests. * source - contains the installation code for utPLSQL -* tests - contains the tests written to test utPLSQL - - - - - - +* tests - contains the tests for utPLSQL framework