From 8f238007d29cf0cb15e05f5d79a66ba74bf14d81 Mon Sep 17 00:00:00 2001 From: Jacek Date: Wed, 17 May 2017 21:51:52 +0100 Subject: [PATCH] Moved client_source to separate project. - the main project no longer contains client - client_source is mover to [utPLSQL-sql-cli](https://github.com/utPLSQL/utPLSQL-sql-cli/) - initial [release v1.0.0](https://github.com/utPLSQL/utPLSQL-sql-cli/releases/tag/V1.0.0) for utPLSQL-sql-cli is done --- client_source/sqlplus/file_list | 39 --- client_source/sqlplus/file_list.bat | 44 --- client_source/sqlplus/ut_run | 17 - client_source/sqlplus/ut_run.bat | 16 - client_source/sqlplus/ut_run.sql | 459 --------------------------- docs/index.md | 8 +- docs/userguide/install.md | 12 +- docs/userguide/reporters.md | 6 +- docs/userguide/running-unit-tests.md | 21 +- docs/userguide/ut_run-script.md | 85 ----- mkdocs.yml | 1 - readme.md | 12 +- 12 files changed, 34 insertions(+), 686 deletions(-) delete mode 100755 client_source/sqlplus/file_list delete mode 100644 client_source/sqlplus/file_list.bat delete mode 100755 client_source/sqlplus/ut_run delete mode 100644 client_source/sqlplus/ut_run.bat delete mode 100644 client_source/sqlplus/ut_run.sql delete mode 100644 docs/userguide/ut_run-script.md diff --git a/client_source/sqlplus/file_list b/client_source/sqlplus/file_list deleted file mode 100755 index 4afea9299..000000000 --- a/client_source/sqlplus/file_list +++ /dev/null @@ -1,39 +0,0 @@ -#!/bin/bash -set -e - -# All parameters are required. This way, users can't pass empty string as parameter. -invalidArgs=0 -[ -z "$1" ] && invalidArgs=1 -[ -z "$2" ] && invalidArgs=1 -[ -z "$3" ] && invalidArgs=1 - -if [ $invalidArgs -eq 1 ]; then - echo Usage: ut_run.sh "project_path" "sql_param_name" "output_file" "scan_path" - exit 1 -fi - -# Remove trailing slashes. -projectPath=${1%/} -sqlParamName=$2 -outputFile=$3 -scanPath=$4 - -fullScanPath="$projectPath/$scanPath" - -if [ ! -d "$fullScanPath" ] || [ -z "$4" ]; then - echo "begin" > $outputFile - echo " open :$sqlParamName for select null from dual where 1= 0;" >> $outputFile - echo "end;" >> $outputFile - echo "/" >> $outputFile - exit 0 -fi - -echo "declare" > $outputFile -echo " l_list ut_varchar2_list := ut_varchar2_list();" >> $outputFile -echo "begin" >> $outputFile -for f in $(find $fullScanPath/* -type f | sed "s|$projectPath/||"); do - echo " l_list.extend; l_list(l_list.last) := '$f';" >> $outputFile -done -echo " open :$sqlParamName for select * from table(l_list);" >> $outputFile -echo "end;" >> $outputFile -echo "/" >> $outputFile diff --git a/client_source/sqlplus/file_list.bat b/client_source/sqlplus/file_list.bat deleted file mode 100644 index 5bb22fe30..000000000 --- a/client_source/sqlplus/file_list.bat +++ /dev/null @@ -1,44 +0,0 @@ -@echo off -setlocal EnableDelayedExpansion - -REM All parameters are required. This way, users can't pass empty string as parameter. -set invalidArgs=0 -set pathNotProvided=0 -if [%1] == "" set invalidArgs=1 -if [%2] == "" set invalidArgs=1 -if [%3] == "" set invalidArgs=1 - -if %invalidArgs% == 1 ( - echo Usage: ut_run.bat "project_path" "sql_param_name" "output_file" "scan_path" - exit /b 1 -) -REM Expand relative path from parameter to be a full path -set projectPath=%~f1 -set sqlParamName=%~2 -set outputFile=%~3 -set scanPath=%~4 - -REM Remove trailing slashes. -if %projectPath:~-1%==\ set projectPath=%projectPath:~0,-1% -if [%scanPath%] == [] (set pathNotProvided=1) else (set "fullScanPath=%projectPath%\%scanPath%") -if not exist "%fullScanPath%\*" set pathNotProvided=1 - -if %pathNotProvided% == 1 ( - echo begin>%outputFile% - echo ^ open :%sqlParamName% for select null from dual where 1 = 0;>>%outputFile% - echo end;>>%outputFile% - echo />>%outputFile% - exit /b 0 -) - -echo declare>%outputFile% -echo ^ l_list ut_varchar2_list := ut_varchar2_list();>>%outputFile% -echo begin>>%outputFile% -for /f "tokens=* delims= " %%a in ('dir %fullScanPath%\* /B /S /A:-D') do ( - set "filePath=%%a" - set filePath=!filePath:%projectPath%\=! - echo ^ l_list.extend; l_list^(l_list.last^) := '!filePath!^';>>%outputFile% -) -echo ^ open :%sqlParamName% for select * from table(l_list);>>%outputFile% -echo end;>>%outputFile% -echo />>%outputFile% diff --git a/client_source/sqlplus/ut_run b/client_source/sqlplus/ut_run deleted file mode 100755 index 09bbd1950..000000000 --- a/client_source/sqlplus/ut_run +++ /dev/null @@ -1,17 +0,0 @@ -#!/bin/bash -set -e - -clientDir="$(dirname "$(readlink -f "$0")")" -projectDir="$(pwd)" - -if [[ "$clientDir" != "${clientDir% *}" ]]; then - echo "Error: ut_run script path cannot have spaces." - exit 1 -fi - -if [[ "$#" -eq 0 ]] ; then - echo "Usage: ut_run user/password@database [options...]" - exit 1 -fi - -sqlplus /nolog @"$clientDir/ut_run.sql" "$clientDir" "$projectDir" "$@" diff --git a/client_source/sqlplus/ut_run.bat b/client_source/sqlplus/ut_run.bat deleted file mode 100644 index afcf25ab7..000000000 --- a/client_source/sqlplus/ut_run.bat +++ /dev/null @@ -1,16 +0,0 @@ -@echo off - -set clientDir=%~dp0 -set projectDir=%__CD__% - -if not "%clientDir%" == "%clientDir: =%" ( - echo Error: ut_run script path cannot have spaces. - exit /b 1 -) - -if "%1" == "" ( - echo Usage: ut_run user/password@database [options...] - exit /b 1 -) - -sqlplus /nolog @"%clientDir%\ut_run.sql" '%clientDir%' '%projectDir%' %* diff --git a/client_source/sqlplus/ut_run.sql b/client_source/sqlplus/ut_run.sql deleted file mode 100644 index 9207522db..000000000 --- a/client_source/sqlplus/ut_run.sql +++ /dev/null @@ -1,459 +0,0 @@ -/* - utPLSQL - Version X.X.X.X - Copyright 2016 - 2017 utPLSQL Project - - Licensed under the Apache License, Version 2.0 (the "License"): - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. -*/ - -/** - This 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 "client_Path" "project_path" user/password@database [-p=(ut_path|ut_paths)] [-c] [-f=format [-o=output] [-s] ...] [-source_path=path] [-test_path=path] - -Parameters: - client_path - The path where this script is installed. Will be used to find auxiliary scripts and to save temp files. - project_path - The path from where this script is being called. - 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. - -f=ut_coverage_html_reporter - Generates a HTML coverage report providing summary and detailed information on code coverage. - The html reporter is based on open-source simplecov-html reporter for Ruby. - It includes source code of the code that was covered (if possible). - -f=ut_coveralls_reporter - Generates a JSON coverage report providing detailed information on code coverage with line numbers. - This coverage report is designed to be consumed by cloud services like https://coveralls.io/. - -f=ut_coverage_sonar_reporter - Generates a JSON coverage report providing detailed information on code coverage with line numbers. - This report is designed to be consumed by SonarQube to report code coverage. - -f=ut_sonar_test_reporter - Generates a JSON report providing detailed information on test specifications. - This report is designed to be consumed by SonarQube to report test files. - 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. - -source_path=path - Source files path to be used by coverage reporters. - -test_path=path - Test files path to be used by coverage reporters. - -c - If specified, enables printing of test results in colors as defined by ANSICONSOLE standards - - To make coverage reporters work source_path and/or test_path cannot be empty, and ut_run need to be executed from your project's path. - - 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 ~/ut_run_path ~/project/source 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 - - 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_coverage_html_reporter - will read file structure from source folder, and save it's output to file "coverage.html" - - 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. - - */ - -whenever sqlerror exit failure -whenever oserror exit failure - -define client_path="&1" -define project_path="&2" -define conn_str="&3" - -conn &conn_str - -set serveroutput on size unlimited format truncated -set trimspool on -set echo off -set termout off -set feedback off -set pagesize 0 -set linesize 30000 -set long 30000 -set longchunksize 30000 -set verify off -set heading off - -column param_list new_value param_list noprint; -/* -* Prepare script to make SQLPlus parameters optional and pass parameters call to param_list variable -*/ -set define # -spool ##client_path/define_params_variable.sql.tmp -declare - l_sql_columns varchar2(4000); - l_params varchar2(4000); -begin - for i in 1 .. 100 loop - dbms_output.put_line('column '||i||' new_value '||i); - l_sql_columns := l_sql_columns ||'null as "'||i||'",'; - l_params := l_params || '''''&&'||i||''''','; - end loop; - dbms_output.put_line('select '||rtrim(l_sql_columns, ',') ||' from dual where rownum = 0;'); - dbms_output.put_line('select '''||rtrim(l_params, ',')||''' as param_list from dual;' ); -end; -/ -spool off -set define & - - -/* -* Make SQLPlus parameters optional and pass parameters call to param_list variable -*/ -@&&client_path/define_params_variable.sql.tmp - - -var l_paths varchar2(4000); -var l_color_enabled varchar2(5); -var l_source_path varchar2(4000); -var l_test_path varchar2(4000); -var l_source_files refcursor; -var l_test_files refcursor; -var l_run_params_cur refcursor; -var l_out_params_cur refcursor; -/* -* Parse parameters and return them as variables -*/ -set termout on -declare - - type t_call_param is record ( - ut_reporter_name varchar2(4000) := 'ut_documentation_reporter', - output_file_name varchar2(4000), - output_to_screen varchar2(3) := 'on', - reporter_id varchar2(250) - ); - - type tt_call_params is table of t_call_param; - - l_input_params ut_varchar2_list := ut_varchar2_list(&¶m_list); - l_call_params tt_call_params; - - l_run_cursor_sql varchar2(32767); - l_out_cursor_sql varchar2(32767); - - function is_reporter(a_reporter_name varchar2) return varchar2 is - l_reporter_name varchar2(4000); - l_dummy integer; - l_owner varchar2(4000); - e_invalid_object exception; - e_not_a_reporter exception; - pragma exception_init (e_invalid_object,-44002); - pragma exception_init (e_not_a_reporter,-6550); - begin - l_reporter_name := upper(dbms_assert.simple_sql_name(a_reporter_name)); - -- a report is a valid reporter if it can be assigned as element of ut_reporters collection - execute immediate - 'declare - r ut_reporters; - begin - r := ut_reporters('||l_reporter_name||'()); - end;'; - return l_reporter_name; - exception - when e_not_a_reporter or e_invalid_object then - raise_application_error(-20000, 'Invalid reporter name specified: '||a_reporter_name); - end; - - function parse_reporting_params(a_params ut_varchar2_list) return tt_call_params is - l_default_call_param t_call_param; - l_call_params tt_call_params := tt_call_params(); - l_force_out_to_screen boolean; - l_param_regex varchar2(20) := '^-([fos])(\=(.*))?$'; - begin - for param in( - select regexp_substr(column_value,l_param_regex,1,1,'c',1) param_type, - regexp_substr(column_value,l_param_regex,1,1,'c',3) param_value - from table(a_params) - where column_value is not null - and regexp_like(column_value,l_param_regex) - ) loop - if param.param_type = 'f' or l_call_params.last is null then - l_call_params.extend; - l_call_params(l_call_params.last) := l_default_call_param; - if param.param_type = 'f' then - l_call_params(l_call_params.last).ut_reporter_name := is_reporter(param.param_value); - end if; - l_force_out_to_screen := false; - end if; - if param.param_type = 'o' then - l_call_params(l_call_params.last).output_file_name := param.param_value; - if not l_force_out_to_screen then - l_call_params(l_call_params.last).output_to_screen := 'off'; - end if; - elsif param.param_type = 's' then - l_call_params(l_call_params.last).output_to_screen := 'on'; - l_force_out_to_screen := true; - end if; - end loop; - if l_call_params.count = 0 then - l_call_params.extend; - l_call_params(1) := l_default_call_param; - end if; - for i in 1 .. cardinality(l_call_params) loop - l_call_params(i).reporter_id := sys_guid(); - end loop; - return l_call_params; - end; - - function parse_suite_paths_param(a_params ut_varchar2_list) return varchar2 is - l_paths varchar2(4000); - begin - begin - select ''''||replace(ut_paths,',',''',''')||'''' - into l_paths - from (select regexp_substr(column_value,'-p\=(.*)',1,1,'c',1) as ut_paths from table(a_params) ) - where ut_paths is not null; - exception - when no_data_found then - l_paths := 'user'; - when too_many_rows then - raise_application_error(-20000, 'Parameter "-p=ut_path(s)" defined more than once. Only one "-p=ut_path(s)" parameter can be used.'); - end; - return l_paths; - end; - - function parse_color_enabled(a_params ut_varchar2_list) return varchar2 is - begin - for i in 1 .. cardinality(a_params) loop - if a_params(i) = '-c' then - return 'true'; - end if; - end loop; - return 'false'; - end; - - function parse_source_files_path_param(a_params ut_varchar2_list, a_param_name varchar2) return varchar2 is - l_path varchar2(4000); - begin - begin - select param_value - into l_path - from (select regexp_substr(column_value,'-'||a_param_name||'\=(.*)',1,1,'c',1) as param_value from table(a_params) ) - where param_value is not null; - exception - when no_data_found then - null; - when too_many_rows then - raise_application_error(-20000, 'Parameter "-'||a_param_name||'='||a_param_name||'" defined more than once. Only one "-'||a_param_name||'='||a_param_name||'" parameter can be used.'); - end; - return l_path; - end; - -begin - l_call_params := parse_reporting_params(l_input_params); - for i in l_call_params.first .. l_call_params.last loop - l_run_cursor_sql := - l_run_cursor_sql || - 'select '''||l_call_params(i).reporter_id||''' as reporter_id,' || - ' '''||l_call_params(i).ut_reporter_name||''' as reporter_name' || - ' from dual'; - l_out_cursor_sql := - l_out_cursor_sql || - 'select '''||l_call_params(i).reporter_id||''' as reporter_id,' || - ' '''||l_call_params(i).output_to_screen||''' as output_to_screen,' || - ' '''||l_call_params(i).output_file_name||''' as output_file_name' || - ' from dual'; - if i < l_call_params.last then - l_run_cursor_sql := l_run_cursor_sql || ' union all '; - l_out_cursor_sql := l_out_cursor_sql || ' union all '; - end if; - end loop; - - :l_paths := parse_suite_paths_param(l_input_params); - :l_color_enabled := parse_color_enabled(l_input_params); - - :l_source_path := parse_source_files_path_param(l_input_params,'source_path'); - :l_test_path := parse_source_files_path_param(l_input_params,'test_path'); - - if l_run_cursor_sql is not null then - open :l_run_params_cur for l_run_cursor_sql; - end if; - if l_out_cursor_sql is not null then - open :l_out_params_cur for l_out_cursor_sql; - end if; - dbms_output.put_line(:l_source_path); -end; -/ -set termout off - - -/** - * Convert paths to substitution variable - */ -column source_path new_value source_path noprint; -select :l_source_path as source_path from dual; -column test_path new_value test_path noprint; -select :l_test_path as test_path from dual; - ---try running on windows -$ "&&client_path\file_list.bat" "&&project_path" "l_source_files" "&&client_path\source_file_list.sql.tmp" "&&source_path" -$ "&&client_path\file_list.bat" "&&project_path" "l_test_files" "&&client_path\test_file_list.sql.tmp" "&&test_path" ---try running on linux/unix -! "&&client_path/file_list" "&&project_path" "l_source_files" "&&client_path/source_file_list.sql.tmp" "&&source_path" -! "&&client_path/file_list" "&&project_path" "l_test_files" "&&client_path/test_file_list.sql.tmp" "&&test_path" - -undef source_path -undef test_path - -/* - * Generate the project source and tests files, saving it into the l_source_files and l_test_files bind variables - */ -@&&client_path/source_file_list.sql.tmp -@&&client_path/test_file_list.sql.tmp - - -/* -* Generate runner script -*/ -spool &&client_path/run_in_background.sql.tmp -declare - l_reporter_id varchar2(250); - l_reporter_name varchar2(250); - l_file_path varchar2(32767); - procedure p(a_text varchar2) is begin dbms_output.put_line(a_text); end; -begin - p('set serveroutput on size unlimited format truncated'); - p('set trimspool on'); - p('set pagesize 0'); - p('set linesize 4000'); - p('spool ut_run.dbms_output.log'); - p('declare'); - p(' v_reporter ut_reporter_base;'); - p(' v_reporters_list ut_reporters := ut_reporters();'); - p(' v_source_files ut_varchar2_list := ut_varchar2_list();'); - p(' v_test_files ut_varchar2_list := ut_varchar2_list();'); - p('begin'); - if :l_run_params_cur%isopen then - loop - fetch :l_run_params_cur into l_reporter_id, l_reporter_name; - exit when :l_run_params_cur%notfound; - p(' v_reporter := '||l_reporter_name||'();'); - p(' v_reporter.reporter_id := '''||l_reporter_id||''';'); - p(' v_reporters_list.extend; v_reporters_list(v_reporters_list.last) := v_reporter;'); - end loop; - close :l_run_params_cur; - end if; - - loop - fetch :l_source_files into l_file_path; - exit when :l_source_files%notfound or l_file_path is null; - p(' v_source_files.extend; v_source_files(v_source_files.last) := '''||l_file_path||''';'); - end loop; - - loop - fetch :l_test_files into l_file_path; - exit when :l_test_files%notfound or l_file_path is null; - p(' v_test_files.extend; v_test_files(v_test_files.last) := '''||l_file_path||''';'); - end loop; - - p(' ut_runner.run( '); - p(' a_paths => ut_varchar2_list('||:l_paths||'),'); - p(' a_reporters => v_reporters_list,'); - p(' a_source_files => v_source_files,'); - p(' a_test_files => v_test_files,'); - p(' a_color_console => '||:l_color_enabled||' );'); - p('end;'); - p('/'); - p('spool off'); - p('exit'); -end; -/ -spool off - - -/* -* Generate output retrieval script -*/ -spool &&client_path/gather_data_from_outputs.sql.tmp -declare - l_reporter_id varchar2(250); - l_output_file_name varchar2(250); - l_output_to_screen varchar2(250); - l_need_spool boolean; - procedure p(a_text varchar2) is begin dbms_output.put_line(a_text); end; -begin - if :l_out_params_cur%isopen then - loop - fetch :l_out_params_cur into l_reporter_id, l_output_to_screen, l_output_file_name; - exit when :l_out_params_cur%notfound; - l_need_spool := (l_output_file_name is not null); - p( 'set termout '||l_output_to_screen); - if l_need_spool then - p( 'spool '||l_output_file_name); - end if; - p( 'select * from table( ut_output_buffer.get_lines('''||l_reporter_id||''') );'); - if l_need_spool then - p('spool off'); - end if; - end loop; - end if; -end; -/ -spool off - - -/* -* Execute runner script in background process -*/ -set define # ---try running on windows -$ start /min sqlplus ##conn_str @##client_path/run_in_background.sql.tmp ---try running on linux/unix -! sqlplus ##conn_str @##client_path/run_in_background.sql.tmp & -set define & -set termout on - - ---make sure we fetch row by row to indicate the progress -set arraysize 1 -/* -* Gather outputs from reporters one by one while runner script executes. -*/ -@&&client_path/gather_data_from_outputs.sql.tmp - -set termout off -/* -* cleanup temporary sql files -*/ ---try running on windows -$ del &&client_path\*.sql.tmp ---try running on linux/unix -! rm &&client_path/*.sql.tmp - -exit diff --git a/docs/index.md b/docs/index.md index 5d66026a5..08998381c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,7 +9,6 @@ The framework follows industry standards and best patterns of modern Unit Testin - [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 @@ -31,6 +30,7 @@ Have a look at our [demo project](https://github.com/utPLSQL/utPLSQL-demo-projec It uses [Travis CI](https://travis-ci.org/utPLSQL/utPLSQL-demo-project) to build on every commit, runs all tests, publishes test results and code coverage to [SonarQube](https://sonarqube.com/dashboard?id=utPLSQL%3AutPLSQL-demo-project%3Adevelop). # Three steps + With just three simple steps you can define and run your unit tests for PLSQL code. 1. Install the utPLSQL framework @@ -44,15 +44,17 @@ Here is how you can simply create tested code, unit tests and execute the tests Check out the sections on [annotations](userguide/annotations.md) and [expectations](userguide/expectations.md) to see how to define your tests. -# Command line +# Command line + The `ut_run` (for linux/unix) and `ut_run.bat` (for windows) are simple yet powerful. They can provide output from the tests on the fly. You can also use it to have coloured outputs. -Look into [ut_run.sql script options](userguide/ut_run-script.md) to see more. +Look into [utPLSQL-sql-cli](https://github.com/utPLSQL/utPLSQL-sql-cli) project to see more. # Coverage + If you want to have code coverage gathered on your code , it's best to use `ut_run` 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 diff --git a/docs/userguide/install.md b/docs/userguide/install.md index a687efecf..ba24adf22 100644 --- a/docs/userguide/install.md +++ b/docs/userguide/install.md @@ -5,15 +5,11 @@ Here is a little snippet that can be handy for downloading latest version. ```bash #!/bin/bash # Get the url to latest release "zip" file -UTPLSQL_DOWNLOAD_URL=$(curl --silent https://api.github.com/repos/utPLSQL/utPLSQL/releases/latest | awk '/browser_download_url/ { print $2 }' | grep ".zip" | sed 's/"//g') -# Extract file name from the URL -UTPLSQL_DOWNLOAD_FILE="${UTPLSQL_DOWNLOAD_URL##*/}" -# Extract the output directory from URL -UTPLSQL_DIR="${UTPLSQL_DOWNLOAD_FILE%.*}" -# Download the latest utPLSQL release "zip" file -curl -LOk "${UTPLSQL_DOWNLOAD_URL}" +DOWNLOAD_URL=$(curl --silent https://api.github.com/repos/utPLSQL/utPLSQL/releases/latest | awk '/browser_download_url/ { print $2 }' | grep ".zip" | sed 's/"//g') +# Download the latest release "zip" file +curl -Lk "${UTPLSQL_DOWNLOAD_URL}" -o utPLSQL.zip # Extract downloaded "zip" file -unzip -q "${UTPLSQL_DOWNLOAD_FILE}" +unzip -q utPLSQL.zip ``` You may download with a one-liner if that is more convenient. diff --git a/docs/userguide/reporters.md b/docs/userguide/reporters.md index f77de9c91..6a2c9bc74 100644 --- a/docs/userguide/reporters.md +++ b/docs/userguide/reporters.md @@ -13,11 +13,11 @@ To invoke tests with documentation reporter use one of following calls from sql You may also invoke unit tests directly from command line by calling. -`sqlplus /nolog @ut_run %user%/%pass%@%dbsid%` +`ut_run user/pass@dbsid` -Invoking tests from command line tool `ut_run.sql` allows you to track progress of test execution. +Invoking tests from command line tool `ut_run` 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. +For more details on using the `ut_run` script look into [utPLSQL-sql-cli](https://github.com/utPLSQL/utPLSQL-sql-cli) project. The `ut_documentation_reporter` doesn't accept any arguments. diff --git a/docs/userguide/running-unit-tests.md b/docs/userguide/running-unit-tests.md index de1053b4e..8fd5d28c4 100644 --- a/docs/userguide/running-unit-tests.md +++ b/docs/userguide/running-unit-tests.md @@ -1,12 +1,30 @@ # Running tests + 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. +Most of the times, you will want to use `ut.run` as the `ut_runner` is designed for API integration and does not output the results to the screen directly. + +# utPLSQL-sql-cli + +If you are thinking about running you tests from a command line or from a CI server like Jenkins/Temcity the best way is to use the [utPLSQL-sql-cli](https://github.com/utPLSQL/utPLSQL-sql-cli) +You may download the latest release of the command line client automatically by using the below command (Unix). + +```bash +#!/bin/bash +# Get the url to latest release "zip" file +DOWNLOAD_URL=$(curl --silent https://api.github.com/repos/utPLSQL/utPLSQL-sql-cli/releases/latest | awk '/zipball_url/ { print $2 }' | sed -r 's/"|,//g') +# Download the latest release "zip" file +curl -Lk "${DOWNLOAD_URL}" -o utplsql-sql-cli.zip +# Extract downloaded "zip" file +unzip -q utplsql-sql-cli.zip +``` # 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. @@ -115,5 +133,4 @@ 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` scripts](ut_run-script.md). + diff --git a/docs/userguide/ut_run-script.md b/docs/userguide/ut_run-script.md deleted file mode 100644 index bdfeddaa7..000000000 --- a/docs/userguide/ut_run-script.md +++ /dev/null @@ -1,85 +0,0 @@ -# ut_run scripts - -The `ut_run` (for linux/unix) and `ut_run.bat` (for windows) are designed to allow invocation of utPLSQL from Windows/Unix command line with multiple reporters. - -They provide display of test execution progress on screen and also allow saving of reporters outcomes into multiple output files. - -# Requirements - -The scripts require `sqlplus` to be installed and configured to be in your PATH. - -When using reporters for Sonar or Coveralls the the `ut_run.bat`/`ut_run` script needs to be invoked from project's root directory. - -Number of script parameters cannot exceed 39. - -# Script Invocation - ut_run user/password@database [-p=(ut_path|ut_paths)] [-c] [-f=format [-o=output] [-s] ...] [-source_path=path] [-test_path=path] - -# Parameters -``` - user - username to connect as - password - password of the user - database - database to connect to - -p=ut_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=path - Path to project source files. Used by coverage reporters. The path needs to be relative to the projects root directory. - -test_path=path - Path to unit test source files. Used by test reporters. The path needs to be relative to the projects root directory. - -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) -``` - -**Sonar and Coveralls reporters 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.** - -Parameters -f, -o, -s are correlated. That is parameters -o and -s are specifying outputs for reporter specified by the -f parameter. - -Examples: - -`ut_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 on database objects that are mapping to file structure from "source" folder, and save output to file "coverage.html" - - -`ut_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 from SQLPlus on winddows you need to install an open-source utility called [ANSICON](http://adoxa.altervista.org/ansicon/) diff --git a/mkdocs.yml b/mkdocs.yml index 8c2739c6a..22c0fe04c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -17,7 +17,6 @@ pages: - Annotations: userguide/annotations.md - Expectations: userguide/expectations.md - Running unit tests: userguide/running-unit-tests.md - - Using ut_run scrips: userguide/ut_run-script.md - Testing best pracitces: userguide/best-practices.md - Upgrade utPLSQL: userguide/upgrade.md - Reporting: diff --git a/readme.md b/readme.md index d7a5cd35b..54e2bbfb9 100644 --- a/readme.md +++ b/readme.md @@ -32,7 +32,7 @@ The framework follows industry standards and best patterns of modern Unit Testin - 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](docs/userguide/ut_run-script.md) +- multi-reporting from test-run from [command line](https://github.com/utPLSQL/utPLSQL-sql-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) @@ -210,17 +210,11 @@ Finished in .036027 seconds ``` To execute your tests from command line, you will need a oracle sql client like SQLPlus or [SQLcl](http://www.oracle.com/technetwork/developer-tools/sqlcl/overview/index.html) -You may benefit from using the [ut_run.sql](client_source/sqlplus/ut_run.sql) to execute your tests if you want to achieve one of the following: + +You may benefit from using the [ut_run](https://github.com/utPLSQL/utPLSQL-sql-cli) script to execute your tests if you want to achieve one of the following: * see the progress of test execution for long-running tests * have output to screen with one output format (text) and at the same time have output to file in other format (xunit) -Example: -``` -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. - __Project Directories__ * .travis - contains files needed for travis-ci integration