1.4.1 Procedures

Procedure: main args ¶

Entry point suitable for a launcher or a Guile -c invocation.

args is the list of user arguments (typically (cdr (command-line))). Exits the process with the status returned by run-cli.

Procedure: run-cli args ¶

Parse args and run the Veritas runner.

args is a list of command-line strings without the program name. Returns an exit status: 0 on success, 1 on failure.

(run-cli '("--test-type" "unit" "--no-benchmarks"))

Procedure: show-help ¶

Print the full Veritas CLI help page to standard output.

1.4.2 Variables

Variable: veritas-help-text ¶

"veritas 1.4.0 - test runner for the Veritas framework\n\nusage: veritas [OPTIONS]\n\nDiscover and run the test suites, tests and benchmarks of a project.\nEvery option is mapped to the corresponding VERITAS_* environment\nvariable, so the command line is only syntactic sugar over the exact\nsame configuration used programmatically and in CI.\n\noptions:\n  -d, --scan-dir DIR       root directory to scan for tests (VERITAS_SCAN_DIR)\n  -T, --test-top-dir DIR   directory holding the test hierarchy (VERITAS_TEST_TOP_DIR)\n  -t, --test-type TYPE     test category / sub-directory to load (VERITAS_TEST_TYPE)\n  -e, --entrypoint NAME    no-argument function to call per file (VERITAS_ENTRYPOINT)\n  -m, --test-module NAME   top level module prefix of the tests (VERITAS_TEST_MODULE)\n  -r, --reporter NAME      reporter to use, e.g. emoji-reporter,\n                           monotone-reporter, json-reporter,\n                           junit-reporter or github-reporter (VERITAS_REPORTER)\n      --only-test SUBSTR   only run tests whose name contains SUBSTR (VERITAS_ONLY_TEST)\n      --only-suite SUBSTR  only run suites whose name contains SUBSTR (VERITAS_ONLY_SUITE)\n      --only-tag TAG       only run tests/suites carrying TAG (VERITAS_ONLY_TAG)\n      --only-failed        rerun only what failed in the previous run\n                           (VERITAS_ONLY_FAILED)\n      --no-only-failed     ignore the recorded failures (the default)\n      --seed N             seed every shuffle of this run (VERITAS_SEED)\n      --partition I/T      run slice I of the T slices of the test files\n                           (VERITAS_PARTITION)\n  -j, --jobs N             run the test files in N worker processes, one\n                           file per process (VERITAS_JOBS)\n      --changed            run only the test files the working tree change\n                           reaches (VERITAS_CHANGED)\n      --no-changed         run every test file (the default)\n      --since REF          run only the test files the change since REF\n                           reaches (VERITAS_SINCE)\n      --src-dir DIR        source root the change graph is read from\n                           (VERITAS_SRC_DIR, default src)\n      --retries N          rerun a failing test up to N extra times\n                           (VERITAS_RETRIES)\n      --trace              record every step of the run, to\n                           reports/traces/last.scm (VERITAS_TRACE)\n      --no-trace           do not record a trace (the default)\n      --show-trace         print the timeline of the last run and exit\n      --list               print the test files this run would run, one\n                           per line, and run none of them (VERITAS_LIST)\n      --coverage           measure code coverage and write the reports\n                           (VERITAS_COVERAGE)\n      --no-coverage        do not measure coverage (the default)\n      --coverage-dir DIR   where the LCOV trace and the JSON summary go\n                           (VERITAS_COVERAGE_DIR, default reports/lcov)\n      --coverage-html-dir DIR\n                           where the HTML report goes, or \"false\" to skip\n                           it (VERITAS_COVERAGE_HTML_DIR, default reports/html)\n      --coverage-include DIRS\n                           colon-separated source roots the report covers\n                           (VERITAS_COVERAGE_INCLUDE, default the current\n                           directory)\n      --coverage-exclude DIRS\n                           colon-separated source roots left out\n                           (VERITAS_COVERAGE_EXCLUDE)\n  -s, --shuffle            shuffle the order of discovered files (default)\n      --no-shuffle         keep the discovered file order (VERITAS_SHUFFLE_FILES=false)\n  -b, --benchmarks         run benchmarks (default) (VERITAS_RUN_BENCHMARKS=true)\n      --no-benchmarks      skip benchmarks (VERITAS_RUN_BENCHMARKS=false)\n  -h, --help               show this help and exit\n  -V, --version            show version information and exit\n\nenvironment variables:\n  VERITAS_ENTRYPOINT        entry-point function name, defaults to \"spec\"\n  VERITAS_SCAN_DIR          directory to scan, defaults to \"./\"\n  VERITAS_TEST_TYPE         test type directory, defaults to \"unit\"\n  VERITAS_TEST_TOP_DIR      test hierarchy root, defaults to \"test\"\n  VERITAS_TEST_MODULE       module prefix, defaults to \"veritas\"\n  VERITAS_SHUFFLE_FILES     \"true\" or \"false\", defaults to \"true\"\n  VERITAS_RUN_BENCHMARKS    \"true\" or \"false\", defaults to \"true\"\n  VERITAS_ONLY_TEST         optional test-name substring filter\n  VERITAS_ONLY_SUITE        optional suite-name substring filter\n  VERITAS_ONLY_TAG          optional tag filter\n  VERITAS_ONLY_FAILED       \"true\" to rerun only the tests that failed last time\n  VERITAS_REPORTER          reporter symbol, defaults to emoji-reporter\n  VERITAS_SEED              seed for every shuffle, printed by a shuffled run\n  VERITAS_PARTITION         \"INDEX/TOTAL\" slice of the discovered test files\n  VERITAS_JOBS              whole number of worker processes for the files,\n                            defaults to 1 and then they run in this process\n  VERITAS_CHANGED           \"true\" to run only the tests the change reaches\n  VERITAS_SINCE             revision the change is read against, for example\n                            origin/trunk\n  VERITAS_SRC_DIR           source root of the change graph, defaults to src\n  VERITAS_RETRIES           extra attempts for a failing test, defaults to 0\n  VERITAS_TRACE             \"true\" to record a trace of the run\n  VERITAS_LIST              \"true\" to print the selected files and run none\n  VERITAS_COVERAGE          \"true\" to measure code coverage\n  VERITAS_COVERAGE_DIR      where the LCOV trace is written, defaults to\n                            reports/lcov\n  VERITAS_COVERAGE_HTML_DIR where the HTML report is written, defaults to\n                            reports/html, and \"false\" turns it off\n  VERITAS_COVERAGE_INCLUDE  colon-separated source roots to report on,\n                            defaults to the current directory\n  VERITAS_COVERAGE_EXCLUDE  colon-separated source roots to leave out\n  VERITAS_COBERTURA_PATH    where the Cobertura XML is written, defaults to\n                            cobertura.xml in the coverage directory\n  VERITAS_JACOCO_PATH       where the JaCoCo XML is written, defaults to\n                            jacoco.xml in the coverage directory\n  VERITAS_LAST_FAILED_PATH  where the failing names are recorded, defaults\n                            to reports/last-failed.scm\n  VERITAS_JUNIT_PATH        where junit-reporter writes, defaults to\n                            reports/junit/veritas-junit.xml\n\nexamples:\n  veritas                          run unit tests with the project defaults\n  veritas --test-type integration  run the integration test suite\n  veritas --no-shuffle --reporter monotone-reporter\n  veritas --only-suite auth        run only the suites mentioning \"auth\"\n  veritas --only-tag slow          run only tests/suites tagged \"slow\"\n  veritas --no-benchmarks          fast feedback loop, skip benchmarks\n  veritas --only-failed            rerun what failed in the previous run\n  veritas --seed 42                repeat a shuffled order exactly\n  veritas --partition 1/3          run one third of the test files\n  veritas --jobs 4                 run the files in four worker processes\n  veritas --changed                run only the tests this change can reach\n  veritas --since origin/trunk     run only the tests a branch touches\n  veritas --retries 2              ride out an intermittent failure\n  veritas --trace                  record the run, then\n  veritas --show-trace             print the recorded timeline\n  veritas --changed --list         show what --changed would run\n  veritas --coverage               measure coverage and write LCOV and HTML\n  veritas --coverage --coverage-exclude test\n                                   measure the sources, not the tests\n  veritas --reporter junit-reporter  write a JUnit XML report\n\ninteractive use:\n  The same runner is available from a Guile REPL.  Load the CLI module and\n  call (run-cli '(\"--help\")) or (show-help) to inspect the options, and\n  ((@@ (veritas runner) run-tests)) to run with the current environment.\n"

Variable: veritas-man-page-name ¶

"veritas(1)"

Variable: veritas-option-grammar ¶

((scan-dir (single-char #\d) (value #t)) (test-top-dir (single-char #\T) (value #t)) (test-type (single-char #\t) (value #t)) (entrypoint (single-char #\e) (value #t)) (test-module (single-char #\m) (value #t)) (reporter (single-char #\r) (value #t)) (only-test (value #t)) (only-suite (value #t)) (only-tag (value #t)) (only-failed (value #f)) (no-only-failed (value #f)) (seed (value #t)) (partition (value #t)) (jobs (single-char #\j) (value #t)) (changed (value #f)) (no-changed (value #f)) (since (value #t)) (src-dir (value #t)) (list (value #f)) (trace (value #f)) (no-trace (value #f)) (show-trace (value #f)) (retries (value #t)) (coverage (value #f)) (no-coverage (value #f)) (coverage-dir (value #t)) (coverage-html-dir (value #t)) (coverage-include (value #t)) (coverage-exclude (value #t)) (shuffle (single-char #\s) (value #f)) (no-shuffle (value #f)) (benchmarks (single-char #\b) (value #f)) (no-benchmarks (value #f)) (help (single-char #\h) (value #f)) (version (single-char #\V) (value #f)))

Variable: veritas-version ¶

"1.4.0"