- The user performing the installation must have the `ADMINISTER DATABASE TRIGGER` privilege. This is required for installation of trigger that is responsible for parsing annotations at at compile-time of a package.
- When installed with DDL trigger, utPLSQL will not be registering unit tests for any of oracle-maintained schemas.
- - For Oracle 11g following users are excluded:
- ANONYMOUS, APPQOSSYS, AUDSYS, DBSFWUSER, DBSNMP, DIP, GGSYS, GSMADMIN_INTERNAL, GSMCATUSER, GSMUSER, ORACLE_OCM, OUTLN, REMOTE_SCHEDULER_AGENT, SYS, SYS$UMF, SYSBACKUP, SYSDG, SYSKM, SYSRAC, SYSTEM, WMSYS, XDB, XS$NULL
- - For Oracle 12c and above the users returned by below query are excluded by utPLSQL:
`select username from all_users where oracle_maintained='Y';`
### Installation without DDL trigger @@ -179,7 +166,7 @@ If the installing user and utPLSQL owner is one and the same, the user must have In addition, the user must be granted the execute privilege on `DBMS_LOCK` and `DBMS_CRYPTO` packages. -utPLSQL is using [DBMS_PROFILER tables](https://docs.oracle.com/cd/E18283_01/appdev.112/e16760/d_profil.htm#i999476) for code coverage. The tables required by DBMS_PROFILER will be created in the installation schema unless they already exist. +utPLSQL is using [DBMS_PROFILER tables](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_PROFILER.html) for code coverage. The tables required by DBMS_PROFILER will be created in the installation schema unless they already exist. It is up to DBA to maintain the storage of the profiler tables. @@ -274,7 +261,7 @@ select ## Additional requirements In order to use the Code Coverage functionality of utPLSQL, users executing the tests must have the CREATE privilege on the PLSQL code that the coverage is gathered on. -This is a requirement of [DBMS_PROFILER package](https://docs.oracle.com/cd/E18283_01/appdev.112/e16760/d_profil.htm#i999476). +This is a requirement of [DBMS_PROFILER package](https://docs.oracle.com/en/database/oracle/oracle-database/19/arpls/DBMS_PROFILER.html#GUID-DEE5EA97-14AA-4AF2-A5F7-4AB1D004B99F). In practice, user running tests for PLSQL code that he does not own, needs to have CREATE ANY PROCEDURE/CREATE ANY TRIGGER privileges. Running code coverage on objects that the user does not own will **not produce any coverage information** without those privileges. diff --git a/docs/userguide/querying_suites.md b/docs/userguide/querying_suites.md index 0cdc2d7fa..e9d8d7ad7 100644 --- a/docs/userguide/querying_suites.md +++ b/docs/userguide/querying_suites.md @@ -1,4 +1,4 @@ - + ## Obtaining information about suites diff --git a/docs/userguide/reporters.md b/docs/userguide/reporters.md index b417ba25c..36b7e8932 100644 --- a/docs/userguide/reporters.md +++ b/docs/userguide/reporters.md @@ -1,4 +1,4 @@ - + utPLSQL provides several reporting formats. The sections below describe most of them. diff --git a/docs/userguide/running-unit-tests.md b/docs/userguide/running-unit-tests.md index 28e02d5b8..324e97602 100644 --- a/docs/userguide/running-unit-tests.md +++ b/docs/userguide/running-unit-tests.md @@ -1,4 +1,4 @@ - + utPLSQL framework provides two main entry points to run unit tests from within the database: diff --git a/docs/userguide/upgrade.md b/docs/userguide/upgrade.md index 818a592bc..e69998a46 100644 --- a/docs/userguide/upgrade.md +++ b/docs/userguide/upgrade.md @@ -1,4 +1,4 @@ - + # Upgrading from version 2 diff --git a/examples/annoation_parser_testing/annotation_parser_test.sql b/examples/annoation_parser_testing/annotation_parser_test.sql new file mode 100644 index 000000000..d1ff43fcd --- /dev/null +++ b/examples/annoation_parser_testing/annotation_parser_test.sql @@ -0,0 +1,298 @@ +-- Annotation Manager Volume Benchmark +-- 1000 generated packages, cold cache per iteration + +set serveroutput on size unlimited +set timing off +set feedback off + +declare + c_packages constant pls_integer := 1000; + c_procs_per_pkg constant pls_integer := 20; + c_contexts_per_pkg constant pls_integer := 4; + c_pkg_prefix constant varchar2(20) := 'TST_GEN_PKG_'; + c_iterations constant pls_integer := 4; + c_perf_threshold constant number := 0.80; + + l_baseline_total_ms number := 0; + l_new_total_ms number := 0; + l_start timestamp; + l_elapsed interval day to second; + + -- Source holders + l_source_lines dbms_preprocessor.source_lines_t; + l_source_clob clob; + l_result ut_annotations; + + -- Correctness tracking + l_missing_from_cache pls_integer := 0; + l_count_mismatches pls_integer := 0; + l_mismatch_detail varchar2(32767); + + -- Cache check + l_cursor sys_refcursor; + l_annotated_obj ut_annotated_object; + l_name varchar2(128); + l_annotations ut_annotations; + l_cache_count pls_integer := 0; + + -- Per-package timing + l_pkg_baseline_ms number; + l_pkg_new_ms number; + l_pkg varchar2(30); + l_ratio number; + + -- Expected annotation count β mirrors generator logic exactly + function expected_annotation_count( + a_pkg_number pls_integer, + a_procs pls_integer, + a_contexts pls_integer + ) return pls_integer is + l_count pls_integer := 0; + begin + l_count := l_count + 2; -- %suite + %suitepath + l_count := l_count + 2; -- %beforeall + %afterall + l_count := l_count + 2; -- %beforeeach + %aftereach + + -- package level conditional + if mod(a_pkg_number, 3) = 0 then l_count := l_count + 1; end if; -- %displayname + if mod(a_pkg_number, 5) = 0 then l_count := l_count + 1; end if; -- %rollback + + -- contexts: each contributes %context + %endcontext + l_count := l_count + (a_contexts * 2); + + -- per procedure + for i in 1 .. a_procs loop + l_count := l_count + 1; -- %test + if mod(i, 3) = 0 then l_count := l_count + 1; end if; -- %tags + if mod(i, 6) = 0 then l_count := l_count + 1; end if; -- %throws + if mod(i, 8) = 0 then l_count := l_count + 1; end if; -- %disabled + if mod(i, 5) = 0 then l_count := l_count + 2; end if; -- %beforetest + %aftertest + end loop; + + return l_count; + end expected_annotation_count; + +begin + dbms_output.put_line('Packages : ' || c_packages); + dbms_output.put_line('Procs/pkg : ' || c_procs_per_pkg); + dbms_output.put_line('Contexts/pkg: ' || c_contexts_per_pkg); + dbms_output.put_line('Iterations : ' || c_iterations); + dbms_output.put_line('Started : ' || to_char(systimestamp,'YYYY-MM-DD HH24:MI:SS.FF3')); + + -- Phase 1: Performance benchmark (cold cache per package per iteration) + dbms_output.put_line(chr(10) || '-- Phase 1: Performance --'); + dbms_output.put_line( + rpad('package', 20) || ' | ' || + lpad('baseline_ms', 11) || ' | ' || + lpad('new_ms', 6) || ' | ' || + lpad('ratio', 5) || ' | ' || + 'status' + ); + dbms_output.put_line(rpad('-', 70, '-')); + + for p in 1 .. c_packages loop + l_pkg := c_pkg_prefix || lpad(p, 4, '0'); + + -- load source once per package + l_source_lines := dbms_preprocessor.get_post_processed_source( + object_type => 'PACKAGE', + schema_name => user, + object_name => l_pkg + ); + + dbms_lob.createtemporary(l_source_clob, true); + for i in 1 .. l_source_lines.count loop + dbms_lob.writeappend(l_source_clob, length(l_source_lines(i)), l_source_lines(i)); + end loop; + + -- baseline: clob version + l_pkg_baseline_ms := 0; + for iter in 1 .. c_iterations loop + ut_annotation_manager.purge_cache(user, 'PACKAGE'); + l_start := systimestamp; + l_result := ut_annotation_parser.parse_object_annotations(l_source_clob); + l_elapsed := systimestamp - l_start; + l_pkg_baseline_ms := l_pkg_baseline_ms + + extract(second from l_elapsed) * 1000; + end loop; + l_pkg_baseline_ms := l_pkg_baseline_ms / c_iterations; + + -- new: source_lines_t version + l_pkg_new_ms := 0; + for iter in 1 .. c_iterations loop + ut_annotation_manager.purge_cache(user, 'PACKAGE'); + l_start := systimestamp; + l_result := ut_annotation_parser.parse_object_annotations(l_source_lines); + l_elapsed := systimestamp - l_start; + l_pkg_new_ms := l_pkg_new_ms + + extract(second from l_elapsed) * 1000; + end loop; + l_pkg_new_ms := l_pkg_new_ms / c_iterations; + + -- accumulate + l_baseline_total_ms := l_baseline_total_ms + l_pkg_baseline_ms; + l_new_total_ms := l_new_total_ms + l_pkg_new_ms; + + l_ratio := round(l_pkg_new_ms / nullif(l_pkg_baseline_ms, 0), 3); + + -- print every 100 packages to avoid flooding output + if mod(p, 100) = 0 or p = 1 then + dbms_output.put_line( + rpad(l_pkg, 20) || ' | ' || + lpad(round(l_pkg_baseline_ms, 3), 11) || ' | ' || + lpad(round(l_pkg_new_ms, 3), 6) || ' | ' || + lpad(l_ratio, 5) || ' | ' || + case when l_ratio <= c_perf_threshold + then 'PASS (' || round((1-l_ratio)*100,1) || '% faster)' + else 'SLOW (ratio=' || l_ratio || ')' + end + ); + end if; + + dbms_lob.freetemporary(l_source_clob); + end loop; + + -- ------------------------------------------------------------------------- + -- Phase 1 summary + -- ------------------------------------------------------------------------- + l_ratio := round(l_new_total_ms / nullif(l_baseline_total_ms, 0), 3); + + dbms_output.put_line(rpad('-', 70, '-')); + dbms_output.put_line('Baseline total ms : ' || round(l_baseline_total_ms, 3)); + dbms_output.put_line('New total ms : ' || round(l_new_total_ms, 3)); + dbms_output.put_line('Overall ratio : ' || l_ratio); + dbms_output.put_line('Improvement : ' || round((1 - l_ratio) * 100, 1) || '%'); + + -- Phase 2: Cache presence check + dbms_output.put_line(chr(10) || '-- Phase 2: Cache presence --'); + + ut_annotation_manager.purge_cache(user, 'PACKAGE'); + ut_annotation_manager.rebuild_annotation_cache(user, 'PACKAGE'); + + -- query cache tables directly to avoid validate_annotation_cache side effects + open l_cursor for + select ut_annotated_object( + i.object_owner, i.object_name, i.object_type, i.parse_time, + cast( + collect( + ut_annotation( + c.annotation_position, c.annotation_name, + c.annotation_text, c.subobject_name + ) order by c.annotation_position + ) as ut_annotations + ) + ) + from ut_annotation_cache_info i + join ut_annotation_cache c on i.cache_id = c.cache_id + where i.object_owner = user + and i.object_type = 'PACKAGE' + and i.object_name like c_pkg_prefix || '%' + group by i.object_owner, i.object_type, i.object_name, i.parse_time; + + loop + fetch l_cursor into l_annotated_obj; + exit when l_cursor%notfound; + l_cache_count := l_cache_count + 1; + end loop; + close l_cursor; + + dbms_output.put_line('Expected in cache : ' || c_packages); + dbms_output.put_line('Found in cache : ' || l_cache_count); + dbms_output.put_line('Cache check : ' || + case when l_cache_count = c_packages + then 'PASS β all ' || c_packages || ' packages found in cache' + else 'FAIL β missing ' || (c_packages - l_cache_count) || ' packages from cache' + end + ); + + -- Phase 3: Annotation count correctness + dbms_output.put_line(chr(10) || '-- Phase 3: Annotation count correctness --'); + + -- reopen same direct cache query for correctness check + open l_cursor for + select ut_annotated_object( + i.object_owner, i.object_name, i.object_type, i.parse_time, + cast( + collect( + ut_annotation( + c.annotation_position, c.annotation_name, + c.annotation_text, c.subobject_name + ) order by c.annotation_position + ) as ut_annotations + ) + ) + from ut_annotation_cache_info i + join ut_annotation_cache c on i.cache_id = c.cache_id + where i.object_owner = user + and i.object_type = 'PACKAGE' + and i.object_name like c_pkg_prefix || '%' + group by i.object_owner, i.object_type, i.object_name, i.parse_time; + + loop + fetch l_cursor into l_annotated_obj; + exit when l_cursor%notfound; + l_name := l_annotated_obj.object_name; + l_annotations := l_annotated_obj.annotations; + + declare + l_pkg_number pls_integer; + l_expected pls_integer; + begin + l_pkg_number := to_number(substr(l_name, length(c_pkg_prefix) + 1)); + l_expected := expected_annotation_count( + l_pkg_number, + c_procs_per_pkg, + c_contexts_per_pkg + ); + + if l_annotations.count != l_expected then + l_count_mismatches := l_count_mismatches + 1; + if l_count_mismatches <= 10 then + l_mismatch_detail := l_mismatch_detail || chr(10) || + ' ' || l_name || + ': expected=' || l_expected || + ' actual=' || l_annotations.count; + end if; + end if; + end; + end loop; + close l_cursor; + + dbms_output.put_line('Packages checked : ' || c_packages); + dbms_output.put_line('Count mismatches : ' || l_count_mismatches); + if l_count_mismatches > 0 then + dbms_output.put_line('Mismatch detail (first 10):' || l_mismatch_detail); + end if; + dbms_output.put_line('Count check : ' || + case when l_count_mismatches = 0 + then 'PASS β all annotation counts match expected' + else 'FAIL β ' || l_count_mismatches || ' packages have wrong annotation count' + end + ); + + dbms_output.put_line(chr(10) || '================================================='); + dbms_output.put_line('FINAL RESULTS'); + dbms_output.put_line('================================================='); + dbms_output.put_line('Performance : ' || + case when l_ratio <= c_perf_threshold then 'PASS' else 'FAIL' end); + dbms_output.put_line('Cache : ' || + case when l_cache_count = c_packages then 'PASS' else 'FAIL' end); + dbms_output.put_line('Counts : ' || + case when l_count_mismatches = 0 then 'PASS' else 'FAIL' end); + dbms_output.put_line('Overall : ' || + case when l_ratio <= c_perf_threshold + and l_cache_count = c_packages + and l_count_mismatches = 0 + then 'PASS' + else 'FAIL' + end + ); + dbms_output.put_line('Finished : ' || + to_char(systimestamp, 'YYYY-MM-DD HH24:MI:SS.FF3')); + dbms_output.put_line('================================================='); + + -- cleanup + ut_annotation_manager.purge_cache(user, 'PACKAGE'); + +end; +/ diff --git a/examples/annoation_parser_testing/create_test_packages.sql b/examples/annoation_parser_testing/create_test_packages.sql new file mode 100644 index 000000000..94a7f3de2 --- /dev/null +++ b/examples/annoation_parser_testing/create_test_packages.sql @@ -0,0 +1,185 @@ +declare + c_packages constant pls_integer := 1000; + c_procs_per_pkg constant pls_integer := 20; + + l_spec varchar2(32767); + l_body varchar2(32767); + l_pkg varchar2(30); + l_errors pls_integer := 0; + + procedure append_to_source(a_source in out nocopy varchar2, a_text varchar2) is + begin + a_source := a_source || a_text; + end; + + procedure append_line(a_source in out nocopy varchar2, a_text varchar2 default null) is + begin + a_source := a_source || a_text || chr(10); + end; + +begin + + for r in ( + select object_name + from user_objects + where object_name like 'TST_GEN_PKG_%' + and object_type = 'PACKAGE' + order by object_name + ) loop + begin + execute immediate 'drop package ' || r.object_name; + exception + when others then + dbms_output.put_line('ERROR dropping ' || r.object_name || ': ' || sqlerrm); + end; + end loop; + dbms_output.put_line('Existing packages dropped.'); + + for p in 1 .. c_packages loop + l_pkg := 'TST_GEN_PKG_' || lpad(p, 4, '0'); + l_spec := null; + l_body := null; + + -- Package spec + append_line(l_spec, 'create or replace package ' || l_pkg || ' as'); + append_line(l_spec); + append_line(l_spec, ' --%suite(Generated suite ' || p || ')'); + append_line(l_spec, ' --%suitepath(generated.vol_test)'); + + if mod(p, 3) = 0 then + append_line(l_spec, ' --%displayname(Suite display name for pkg ' || p || ')'); + end if; + if mod(p, 5) = 0 then + append_line(l_spec, ' --%rollback(manual)'); + end if; + + append_line(l_spec); + append_line(l_spec, ' --%beforeall'); + append_line(l_spec, ' procedure setup_suite;'); + append_line(l_spec); + append_line(l_spec, ' --%afterall'); + append_line(l_spec, ' procedure teardown_suite;'); + append_line(l_spec); + append_line(l_spec, ' --%beforeeach'); + append_line(l_spec, ' procedure setup_test;'); + append_line(l_spec); + append_line(l_spec, ' --%aftereach'); + append_line(l_spec, ' procedure teardown_test;'); + append_line(l_spec); + + for i in 1 .. c_procs_per_pkg loop + declare + l_proc varchar2(30) := 'test_proc_' || lpad(i, 3, '0'); + begin + if mod(i - 1, 5) = 0 then + append_line(l_spec, ' --%context(context_' || ceil(i/5) || ')'); + append_line(l_spec); + end if; + + if mod(i, 4) = 0 then + append_line(l_spec, ' /* multi-line comment for ' || l_proc || ' */'); + end if; + + append_line(l_spec, ' --%test(Test ' || i || ' in pkg ' || p || ')'); + + if mod(i, 3) = 0 then + append_line(l_spec, ' --%tags(tag_' || mod(i,5) || ',smoke)'); + end if; + if mod(i, 6) = 0 then + append_line(l_spec, ' --%throws(-20001)'); + end if; + if mod(i, 8) = 0 then + append_line(l_spec, ' --%disabled(generated disabled test ' || i || ')'); + end if; + if mod(i, 5) = 0 then + append_line(l_spec, ' --%beforetest(setup_test)'); + append_line(l_spec, ' --%aftertest(teardown_test)'); + end if; + + append_line(l_spec, ' -- regular comment'); + append_line(l_spec, ' procedure ' || l_proc || ';'); + append_line(l_spec); + + if mod(i, 5) = 0 then + append_line(l_spec, ' --%endcontext'); + append_line(l_spec); + end if; + end; + end loop; + + append_line(l_spec, 'end ' || l_pkg || ';'); + + -- ----------------------------------------------------------------------- + -- Package body + -- ----------------------------------------------------------------------- + append_line(l_body, 'create or replace package body ' || l_pkg || ' as'); + append_line(l_body); + + for stub in ( + select column_value as proc_name + from table(ut_varchar2_list( + 'setup_suite','teardown_suite', + 'setup_test','teardown_test' + )) + ) loop + append_line(l_body, ' procedure ' || stub.proc_name || ' is'); + append_line(l_body, ' begin'); + append_line(l_body, ' null;'); + append_line(l_body, ' end ' || stub.proc_name || ';'); + append_line(l_body); + end loop; + + for i in 1 .. c_procs_per_pkg loop + declare + l_proc varchar2(30) := 'test_proc_' || lpad(i, 3, '0'); + begin + append_line(l_body, ' procedure ' || l_proc || ' is'); + append_line(l_body, ' begin'); + if mod(i, 4) = 0 then + append_line(l_body, ' ut.expect(''/* not a comment */'').to_equal(''/* not a comment */'');'); + elsif mod(i, 4) = 1 then + append_line(l_body, ' ut.expect(' || i || ').to_be_greater_than(0);'); + elsif mod(i, 4) = 2 then + append_line(l_body, ' ut.expect(q''[-- not a comment]'').to_equal(q''[-- not a comment]'');'); + else + append_line(l_body, ' ut.expect(''test_' || i || ''').not_to_be_null();'); + end if; + append_line(l_body, ' end ' || l_proc || ';'); + append_line(l_body); + end; + end loop; + + append_line(l_body, 'end ' || l_pkg || ';'); + + -- Execute DDL β with error capture so one bad package doesn't stop all + begin + execute immediate l_spec; + execute immediate l_body; + exception + when others then + l_errors := l_errors + 1; + dbms_output.put_line('ERROR on ' || l_pkg || ': ' || sqlerrm); + end; + + if mod(p, 100) = 0 then + dbms_output.put_line('Created ' || p || ' packages...'); + end if; + + end loop; + + dbms_output.put_line('----------------------------------------'); + dbms_output.put_line('Done. packages=' || c_packages || + ' errors=' || l_errors); + + -- quick sanity check + declare + l_count pls_integer; + begin + select count(*) into l_count + from user_objects + where object_name like 'TST_GEN_PKG_%' + and object_type = 'PACKAGE'; + dbms_output.put_line('Packages in user_objects: ' || l_count); + end; +end; +/ diff --git a/readme.md b/readme.md index 1ca252558..bba640d17 100644 --- a/readme.md +++ b/readme.md @@ -1,102 +1,47 @@  ----------- - -[](https://www.apache.org/licenses/LICENSE-2.0) [](https://github.com/utPLSQL/utPLSQL/releases) -[](http://gra.caldis.me/?url=https://github.com/utPLSQL/utPLSQL) +[](https://www.apache.org/licenses/LICENSE-2.0) [](https://github.com/utPLSQL/utPLSQL/discussions) -[](https://twitter.com/utPLSQL) - +[](https://twitter.com/utPLSQL) [](https://github.com/utPLSQL/utPLSQL/actions/workflows/build.yml) [](https://sonarcloud.io/summary/new_code?id=utPLSQL_utPLSQL) [](https://sonarcloud.io/summary/new_code?id=utPLSQL_utPLSQL) ----------- -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. - -# 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/) - - -# Key features - -- multiple ways to compare data with [matchers](docs/userguide/expectations.md) -- native comparison of complex types (objects/collections/cursors) -- in-depth and consistent reporting of failures and errors for tests -- tests identified and configured by [annotations](docs/userguide/annotations.md) -- hierarchies of test suites configured with annotations -- automatic (configurable) transaction control -- Build-in [coverage](docs/userguide/coverage.md) reporting -- Integration with SonarQube, Coveralls, Jenkins and Teamcity with [reporters](docs/userguide/reporters.md) -- plugin architecture for reporters and matchers -- flexible and simple test invocation -- multi-reporting from test-run from [command line](https://github.com/utPLSQL/utPLSQL-cli) - -Requirements: - - Version of Oracle under [extended support](http://www.oracle.com/us/support/library/lifetime-support-technology-069183.pdf) (Currently 11.2 and above) - -# Download - -Published releases are available for download on the [utPLSQL GitHub Releases Page.](https://github.com/utPLSQL/utPLSQL/releases) - -# Documentation - -Full documentation of the project is automatically published on [utPLSQL github pages](https://utplsql.github.io/utPLSQL/) - -[Cheat-sheets](https://www.cheatography.com/jgebal/lists/utplsql-v3-cheat-sheets/) - -# Installation +utPLSQL is a unit testing framework for Oracle PL/SQL and SQL, following industry standards and best practices of modern testing frameworks like [JUnit](http://junit.org/junit4/) and [RSpec](http://rspec.info/). -To install the utPLSQL into a new database schema and grant it to public, execute the script `install_headless.sql`. -This will create a new user `UT3`, grant all required privileges to that user and create PUBLIC synonyms needed. - -For detailed instructions on other install options see the [Install Guide](docs/userguide/install.md) - - -# Running tests - -To execute using development IDE (TOAD/SQLDeveloper/PLSQLDeveloper/other) use one of following commands. -```sql -begin - ut.run(); -end; -/ -``` -```sql -exec ut.run(); -``` -```sql -select * from table(ut.run()); -``` +## Key Features -The above commands will run all the suites in the current schema and provide report to dbms_output or as a select statement. +- Multiple ways to compare data with [matchers](docs/userguide/expectations.md) +- Native comparison of complex types (objects, collections, cursors) +- In-depth and consistent reporting of failures and errors +- Tests identified and configured by [annotations](docs/userguide/annotations.md) +- Hierarchies of test suites configured with annotations +- Automatic (configurable) transaction control +- Built-in [coverage](docs/userguide/coverage.md) reporting +- Integration with SonarQube, Jenkins and TeamCity via [reporters](docs/userguide/reporters.md) +- Plugin architecture for reporters and matchers +- Flexible and simple test invocation +- Multi-format reporting from the [command line client](https://github.com/utPLSQL/utPLSQL-cli) -# Command line client +## Requirements -You can use the utPLSQL command line client [utPLSQL-cli](https://github.com/utPLSQL/utPLSQL-cli) to run tests without the need for Oracle Client or any IDE like SQLDeveloper/TOAD etc. +- Oracle Database 19c or newer -Amongst many benefits it provides ability to: -* see the progress of test execution for long-running tests - real-time reporting -* use many reporting formats simultaneously and save reports to files (publish) -* map your project source files and test files into database objects +## Installation -Download the [latest client](https://github.com/utPLSQL/utPLSQL-cli/releases/latest) and are good to go. -See [project readme](https://github.com/utPLSQL/utPLSQL-cli/blob/develop/README.md) for details. +Published releases are available for download on the [utPLSQL GitHub Releases page](https://github.com/utPLSQL/utPLSQL/releases). +To install utPLSQL into a new database schema and grant it to public, execute the script `install_headless.sql`. +This creates a new user `UT3`, grants all required privileges, and creates PUBLIC synonyms. -# Example unit test packages +For all install options see the [Install Guide](docs/userguide/install.md). -**For examples of using Continuous Integration Server & SonarCloud with utPLSQL see the [utPLSQL demo project](https://github.com/utPLSQL/utPLSQL-demo-project/).** +## Quick Start +**1. Write a test package** -The below test package is a fully-functional Unit Test package for testing a [`betwnstr` function](examples/between_string/betwnstr.sql). -The package specification is [annotated](docs/userguide/annotations.md) with special comments. -The annotations define that a package is a unit test suite, they also allow defining a description for the suite as well as the test itself. -The package body consists of procedures containing unit test code. To validate [an expectation](docs/userguide/expectations.md) in test, use `ut.expect( actual_data ).to_( ... )` syntax. +Annotate a package specification to define a test suite and its tests, then implement each test procedure in the package body: ```sql create or replace package test_between_string as @@ -106,12 +51,6 @@ create or replace package test_between_string as -- %test(Returns substring from start position to end position) procedure normal_case; - -- %test(Returns substring when start position is zero) - procedure zero_start_position; - - -- %test(Returns string until end if end position is greater than string length) - procedure big_end_position; - -- %test(Returns null for null input string value) procedure null_string; end; @@ -124,16 +63,6 @@ create or replace package body test_between_string as ut.expect( betwnstr( '1234567', 2, 5 ) ).to_( equal('2345') ); end; - procedure zero_start_position is - begin - ut.expect( betwnstr( '1234567', 0, 5 ) ).to_( equal('12345') ); - end; - - procedure big_end_position is - begin - ut.expect( betwnstr( '1234567', 0, 500 ) ).to_( equal('1234567') ); - end; - procedure null_string is begin ut.expect( betwnstr( null, 2, 5 ) ).to_( be_null ); @@ -143,60 +72,83 @@ end; / ``` -Outputs from running the above tests +**2. Run your tests** + +```sql +exec ut.run(); +``` + +**3. See the results** + ``` Between string function Returns substring from start position to end position - Returns substring when start position is zero - Returns string until end if end position is greater than string length Returns null for null input string value Finished in .036027 seconds -4 tests, 0 failures +2 tests, 0 failures +``` + +For complete working examples see [examples/](examples/). + +## Running Tests + +From any Oracle-compatible IDE (SQL Developer, TOAD, PL/SQL Developer): + +```sql +begin + ut.run(); +end; +/ ``` +```sql +exec ut.run(); +``` +```sql +select * from table(ut.run()); +``` + +These commands run all suites in the current schema and report test results to `DBMS_OUTPUT` or as a result set. +## Command Line Client -# Contributing to the project +[utPLSQL-cli](https://github.com/utPLSQL/utPLSQL-cli) lets you run tests without an Oracle Client or IDE. It provides: -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](CONTRIBUTING.md) -The best place to start is to read the documentation and get familiar with the existing code base. -[Github discussions](https://github.com/utPLSQL/utPLSQL/discussions) is the place to go if you want to talk with team members. +- Real-time test reporting +- Simultaneous output of multiple report formats into different files +- Source files and test files mapping for coverage reports +Download the [latest release](https://github.com/utPLSQL/utPLSQL-cli/releases/latest) and see the [CLI readme](https://github.com/utPLSQL/utPLSQL-cli/blob/develop/README.md) for details. ----------- -[__Authors__](docs/about/authors.md) +## Documentation +Full documentation is published at [https://www.utplsql.org/utPLSQL/](https://www.utplsql.org/utPLSQL/). ----------- -__Project Directories__ +[Cheat-sheets](https://www.cheatography.com/jgebal/lists/utplsql-v3-cheat-sheets/) are available for quick reference. -* .github - contains files needed for github Actions integration -* .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 - Documentation of the project -* examples - Example source code and unit tests -* source - The installation code for utPLSQL -* tests - Tests for utPLSQL framework +See the [Changelog](CHANGELOG.md) for the full version history. ----------- +Migrating from legacy utPLSQL v2? See the [version 2 to version 3 comparison](docs/compare_version2_to_3.md). +## Contributing -# Version 2 to Version 3 Comparison +We welcome contributions of all kinds. Please read the [contributing guide](CONTRIBUTING.md) and the [code of conduct](CODE_OF_CONDUCT.md) before getting started. -[Version 2 to Version 3 Comparison](docs/compare_version2_to_3.md) +[GitHub Discussions](https://github.com/utPLSQL/utPLSQL/discussions) is the place to ask questions and connect with the team. -# Supporters +## Supporters -The utPLSQL project is community-driven and is not commercially motivated. Nonetheless, donations and other contributions are always welcome, and are detailed below. +utPLSQL is community-driven and not commercially motivated. Donations and contributions are always welcome.
 |
-utPLSQL has been supported by Redgate in the form of sponsored stickers and t-shirts. Thank you for helping us spreading the word! | +utPLSQL has been supported by Redgate in the form of sponsored stickers and t-shirts. Thank you for helping us spread the word! |