NAME

logtalk_tester - Logtalk script for automating running unit tests

SYNOPSIS

logtalk_tester -v
logtalk_tester [-o output] [-p prolog] [-m mode] [-f format] [-d results] [-t timeout] [-n driver] [-s prefix] [-c report] [-l level] [-i options] [-g goal] [-r seed] [-w] [-- arguments]
logtalk_tester -h

DESCRIPTION

logtalk_tester is a script for automating running Logtalk unit tests. This script runs unit tests found on the current directory and recursively in its sub-directories by scanning by default for tester.lgt and tester.logtalk source files. The script returns a non-zero exit status in case of failed tests or test set errors. When a tester.sh file exists in the tests directory, the file is sourced before running the tests. The tester.sh file is sourced with all the parameters passed to the script.

OPTIONS

-v Print script version.

-o Output verbosity. Default is verbose. Valid values are verbose and minimal.

-p Backend Prolog compiler. Default is SWI-Prolog. The following identifiers are used: B-Prolog - b, Ciao Prolog - ciao, CxProlog - cx, ECLiPSe - eclipse, GNU Prolog - gnu, JIProlog - ji, LVM - lvm, Qu-Prolog - qp, SICStus Prolog - sicstus, SWI-Prolog - swi, SWI-Prolog with Logtalk pack - swipack, Tau Prolog - tau, XSB - xsb, XSB-MT - xsbmt, YAP - yap.

-m Compilation mode. Default is normal. Valid values are optimal, normal, debug, and all.

-f Format for writing the test results. Default is default. Valid values are default, tap, and xunit.

-d Directory to store the test results. Default is the local ./logtalk_tester_logs directory.

-t Timeout in seconds for running each test set. Default is 0 (i.e. disabled).

-n Name of the test driver and sourced files (minus file name extensions). Default is tester.

-s Path prefix to suppress when printing test suite and test result paths. Default is the user home directory.

-c Code coverage report. Default is none. Valid values are xml and none.

-l Directory depth level to look for test sets. Level 1 means current directory only. Default is to recurse into all sub-directories.

-i Integration script command-line options (no default).

-g Initialization goal. Default is true. Called after loading the Logtalk compiler and runtime.

-r Random generator starting seed (no default).

-w Wipe test set default scratch directories (./.lgt_tmp and ./lgt_tmp) before running it.

-- Arguments to be passed to the tests (no default).

-h Provide help on script usage.

EXIT STATUS

0 All non-skipped tests pass and there are no broken, timed out, or crashed test sets.

1 Some tests fail but there are no broken, timed out, or crashed test sets.

3 One or more test sets timed out while executing but there are no broken or crashed test sets.

5 One or more test sets are broken and thus could not be executed but there are no crashed test sets.

7 One or more test sets crashed the process running them.

9 The sourced tester.sh file returned a non-zero code.

EXAMPLES

Run all tests on the current directory and sub-directories using the GNU Prolog backend, with results in TAP format, code coverage reports in XML format, and passing arguments foo, bar, and baz to the tests: logtalk_tester -p gnu -tap -c xml -- foo bar baz

Run all tests on the current directory only using the ECLiPSe backend, with a timeout of 4 minutes per test set: logtalk_tester -p eclipse -l 1 -t 240

Run all tests on the current directory and sub-directories using the SICStus Prolog backend and a random generator starting seed: logtalk_tester -p sicstus -r "seed(3172,9814,20125)"

Run all tests on the current directory and sub-directories using the Tau Prolog backend, caching the compilation of the testing tool for better performance, but wiping the test set default scratch directories before running it: logtalk_tester -p tau -g "set_logtalk_flag(clean,off)" -w

IMPLEMENTATION NOTES

When the script detects either a timeout or a gtimeout command (provided by the GNU coreutils package), it will use it to run each test set if the timeout option is set to a value greater than zero. On Windows operating-systems, the native timeout command is not usable for this purpose.

Installation of the GNU sed command, when not available by default, is strongly recommended.

ENVIRONMENT

LOGTALKHOME Specifies the location of the Logtalk installation.

LOGTALKUSER Specifies the location of the Logtalk user directory.

FILES

$LOGTALKUSER/library/tester_versions.lgt Logtalk source file used for printing the Logtalk and backend Prolog compiler versions.

$LOGTALKUSER/library/parallel_logtalk_processes_setup.pl Logtalk source file used for parallel Logtalk processes with selected backend Prolog compilers.

$LOGTALKUSER/tools/lgtunit/automation_report.lgt Logtalk source file that intercepts unit test execution messages and generates report files that are parsed by this script.

SEE ALSO

The Logtalk website at https://logtalk.org/

The Logtalk User and Reference Manuals at $LOGTALKHOME/manuals/index.html

AUTHOR

Paulo Moura <pmoura@logtalk.org>

COPYRIGHT

Copyright (c) 1998-2020 Paulo Moura.

This HTML page was made with roffit.