NAME

       bats - Bash Automated Testing System

SYNOPSIS

       Usage: bats [OPTIONS] tests bats [-h | -v]

       tests  is  the  path  to a Bats test file, or the path to a directory containing Bats test
       files (ending with ".bats")

DESCRIPTION

       Bats is a TAP-compliant testing framework for Bash. It provides a  simple  way  to  verify
       that the UNIX programs you write behave as expected.

       A  Bats  test file is a Bash script with special syntax for defining test cases. Under the
       hood, each test case is just a function with a description.

       Test cases consist of standard shell commands. Bats makes use of Bash´s errexit  (set  -e)
       option  when  running  test cases. If every command in the test case exits with a 0 status
       code (success), the test passes. In this way, each line is an assertion of truth.

       See bats(7) for more information on writing Bats tests.

RUNNING TESTS

       To run your tests, invoke the bats interpreter with a path to a test file. The file´s test
       cases are run sequentially and in isolation. If all the test cases pass, bats exits with a
       0 status code. If there are any failures, bats exits with a 1 status code.

       You can invoke the bats interpreter with multiple test file arguments, or with a path to a
       directory  containing  multiple .bats files. Bats will run each test file individually and
       aggregate the results. If any test case fails, bats exits with a 1 status code.

FILTERING TESTS

       There are multiple mechanisms to filter which tests to execute:

       ○   --filter <regex> to filter by test name

       ○   --filter-status <status> to filter by the test´s status in the last run

       ○   --filter-tags <tag-list> to filter by the tags of a test

--FILTER-TAGS <var>TAG-LIST</var>

       Tags can be used for finegrained filtering of which tests to run via  --filter-tags.  This
       accepts  a  comma  separated list of tags. Only tests that match all of these tags will be
       executed. For example, bats --filter-tags a,b,c will pick up tests with  tags  a,b,c,  but
       not tests that miss one or more of those tags.

       Additionally, you can specify negative tags via bats --filter-tags a,!b,c, which now won´t
       match tests with tags a,b,c, due to the b, but will select a,c. To put it  more  formally,
       --filter-tags is a boolean conjunction.

       To  allow for more complex queries, you can specify multiple --filter-tags. A test will be
       executed, if it matches at least one of them. This means  multiple  --filter-tags  form  a
       boolean disjunction.

       A  query  of --filter-tags a,!b --filter-tags b,c can be translated to: Execute only tests
       that (have tag a, but not tag b) or (have tag b and c).

       An empty tag list matches tests without tags.

OPTIONS

       -c, --count
              Count the number of test cases without running any tests

       --code-quote-style <style>
              A two character string of code quote delimiters or custom  which  requires  setting
              $BATS_BEGIN_CODE_QUOTE    and   $BATS_END_CODE_QUOTE.   Can   also   be   set   via
              $BATS_CODE_QUOTE_STYLE.

       -f, --filter <regex>
              Filter test cases by names matching the regular expression

       -F, --formatter <type>
              Switch between formatters: pretty (default), tap (default w/o term), tap13,  junit,
              /<absolute path to formatter>

       --filter-status <status>
              Only  run tests with the given status in the last completed (no CTRL+C/SIGINT) run.
              Valid status values are: failed - runs tests that failed or were not present in the
              last run missed - runs tests that were not present in the last run

       --filter-tags <comma-separated-tag-list>
              Only  run  tests that match all the tags in the list (&&). You can negate a tag via
              prepending !. Specifying this flag multiple  times  allows  for  logical  or  (||):
              --filter-tags A,B --filter-tags A,!C matches tags (A && B) || (A && !C)

       --gather-test-outputs-in <directory>
              Gather the output of failing and passing tests as files in directory

       -h, --help
              Display this help message

       -j, --jobs <jobs>
              Number of parallel jobs (requires GNU parallel)

       --no-tempdir-cleanup
              Preserve test output temporary directory

       --no-parallelize-across-files
              Serialize  test file execution instead of running them in parallel (requires --jobs
              >1)

       --no-parallelize-within-files
              Serialize test execution within files instead of running them in parallel (requires
              --jobs >1)

       --report-formatter <type>
              Switch between reporters (same options as --formatter)

       -o, --output <dir>
              Directory to write report files

       -p, --pretty
              Shorthand for "--formatter pretty"

       --print-output-on-failure
              Automatically print the value of $output on failed tests

       -r, --recursive
              Include tests in subdirectories

       --show-output-of-passing-tests
              Print output of passing tests

       -t, --tap
              Shorthand for "--formatter tap"

       -T, --timing
              Add timing information to tests

       -x, --trace
              Print test commands as they are executed (like set -x)

       --verbose-run
              Make run print $output by default

       -v, --version
              Display the version number

OUTPUT

       When  you  run  Bats  from a terminal, you´ll see output as each test is performed, with a
       check-mark next to the test´s name if it passes or an "X" if it fails.

           $ bats addition.bats
            ✓ addition using bc
            ✓ addition using dc

           2 tests, 0 failures

       If Bats is not connected to a terminal--in other words, if you run it  from  a  continuous
       integration  system  or  redirect  its  output  to  a  file--the  results are displayed in
       human-readable, machine-parsable TAP format. You can force TAP output from a  terminal  by
       invoking Bats with the --tap option.

           $ bats --tap addition.bats
           1..2
           ok 1 addition using bc
           ok 2 addition using dc

EXIT STATUS

       The  bats  interpreter exits with a value of 0 if all test cases pass, or 1 if one or more
       test cases fail.

SEE ALSO

       Bats wiki: https://github.com/bats-core/bats-core/wiki/

       bash(1), bats(7)

COPYRIGHT

       (c) 2017-2022 bats-core organization
       (c) 2011-2016 Sam Stephenson

       Bats is released under the terms of an MIT-style license.