Provided by: bash-unit_2.3.2-1_all bug

NAME

       bash_unit - bash unit testing enterprise edition framework for professionals!

SYNOPSIS

       bash_unit [-f tap] [-p <pattern>] [-s <pattern>] [-r] [test_file]

DESCRIPTION

       bash_unit allows you to write unit tests (functions starting with test), run them and, in case of
       failure, displays the stack trace with source file and line number indications to locate the problem.

       You might want to take a look at how to get started <getting_started> before continuing reading this
       documentation.

       The following functions are available in your tests (see below for detailed documentation):

       •   fail [message]

       •   assert <assertion> [message]

       •   assert_fail <assertion> [message]

       •   assert_status_code <expected_status_code> <assertion> [message]

       •   assert_equals <expected> <actual> [message]

       •   assert_not_equals <unexpected> <actual> [message]

       •   assert_matches <expected-regex> <actual> [message]

       •   assert_not_matches <unexpected-regex> <actual> [message]

       •   assert_within_delta <expected num> <actual num> <max delta> [message]

       •   assert_no_diff <expected> <actual> [message]

       •   skip_if <condition> <pattern>

       •   fake <command> [replacement code]

       (by the way, the documentation you are reading is itself tested with bash-unit)

       bash_unit is free software you may contribute to. See CONTRIBUTING.md.

OPTIONS

       -p pattern
           filters tests to run based on the given pattern. You can specify several patterns by repeating this
           option for each pattern.

       -s pattern
           skip tests which name matches the given pattern. You can specify several patterns by repeating this
           option for each pattern. Tests will appear in bash_unit output as skipped. (see also skip_if)

       -r
           executes test cases in random order. Only affects the order within a test file (files are always
           executed in the order in which they are specified on the command line).

       -f output_format
           specify an alternative output format. The only supported value is tap.

       -q
           quiet mode. Will only output the status of each test with no further information even in case of
           failure.

   GitHub Actions
       Here is an example of how you could integrate bash_unit with GitHub Actions
       <https://docs.github.com/fr/actions>:

           name: bash_unit tests
           on:
             push:
               branches: [ main ]
             pull_request:
               branches: [ main ]

           jobs:
             ubuntu:
               runs-on: ubuntu-latest
               steps:
               - uses: actions/checkout@v4
               - name: Unit testing with bash_unit
                 run: |
                   curl -s https://raw.githubusercontent.com/pgrange/bash_unit/master/install.sh | bash
                   FORCE_COLOR=true ./bash_unit tests/test_*

       See this bash_unit getting started gitlab project <https://github.com/pgrange/bash_unit_getting_started>
       for a working example.

   GitLab CI
       Here is an example of how you could integrate bash_unit with GitLab CI <https://docs.gitlab.com/ee/ci/>:

           test:
             image: debian
             script:
               - apt-get update
               - apt-get install --no-install-recommends -y curl ca-certificates
               - curl -s https://raw.githubusercontent.com/pgrange/bash_unit/master/install.sh | bash
               - FORCE_COLOR=true ./bash_unit tests/test_*

       See this bash_unit getting started gitlab project <https://gitlab.com/pgrange/bash_unit_getting_started>
       for a working example.

   pre-commit hook
       You can run bash_unit as a pre-commit <https://pre-commit.com> hook.

       Add the following to your pre-commit configuration. By default it will run scripts that are identified as
       shell scripts that match the path ^tests/(.*/)?test_.*\.sh$.

           repos:
             - repo: https://github.com/pgrange/bash_unit
               rev: v2.2.0
               hooks:
                 - id: bash-unit
                   always-run: true

HOW TO RUN TESTS

       To run tests, simply call bash_unit with all your tests files as parameter. For instance to run some
       bash_unit tests, from bash_unit directory:

           ./bash_unit tests/test_core.sh

           Running tests in tests/test_core.sh
                   Running test_assert_equals_fails_when_not_equal ... SUCCESS
                   Running test_assert_equals_succeed_when_equal ... SUCCESS
                   Running test_assert_fails ... SUCCESS
                   Running test_assert_fails_fails ... SUCCESS
                   Running test_assert_fails_succeeds ... SUCCESS
                   Running test_assert_matches_fails_when_not_matching ... SUCCESS
                   Running test_assert_matches_succeed_when_matching ... SUCCESS
                   Running test_assert_no_diff_fails_when_diff ... SUCCESS
                   Running test_assert_no_diff_succeeds_when_no_diff ... SUCCESS
                   Running test_assert_not_equals_fails_when_equal ... SUCCESS
                   Running test_assert_not_equals_succeeds_when_not_equal ... SUCCESS
                   Running test_assert_not_matches_fails_when_matching ... SUCCESS
                   Running test_assert_not_matches_succeed_when_not_matching ... SUCCESS
                   Running test_assert_shows_stderr_on_failure ... SUCCESS
                   Running test_assert_shows_stdout_on_failure ... SUCCESS
                   Running test_assert_status_code_fails ... SUCCESS
                   Running test_assert_status_code_succeeds ... SUCCESS
                   Running test_assert_succeeds ... SUCCESS
                   Running test_assert_within_delta_fails ... SUCCESS
                   Running test_assert_within_delta_succeeds ... SUCCESS
                   Running test_fail_fails ... SUCCESS
                   Running test_fail_prints_failure_message ... SUCCESS
                   Running test_fail_prints_where_is_error ... SUCCESS
                   Running test_fake_actually_fakes_the_command ... SUCCESS
                   Running test_fake_can_fake_inline ... SUCCESS
                   Running test_fake_echo_stdin_when_no_params ... SUCCESS
                   Running test_fake_exports_faked_in_subshells ... SUCCESS
                   Running test_fake_transmits_params_to_fake_code ... SUCCESS
                   Running test_fake_transmits_params_to_fake_code_as_array ... SUCCESS
                   Running test_should_pretty_format_even_when_LANG_is_unset ... SUCCESS
           Overall result: SUCCESS

       You might also want to run only specific tests, you may do so with the -p option. This option accepts a
       pattern as parameter and filters test functions against this pattern.

           ./bash_unit -p fail_fails -p assert tests/test_core.sh

           Running tests in tests/test_core.sh
                   Running test_assert_equals_fails_when_not_equal ... SUCCESS
                   Running test_assert_equals_succeed_when_equal ... SUCCESS
                   Running test_assert_fails ... SUCCESS
                   Running test_assert_fails_fails ... SUCCESS
                   Running test_assert_fails_succeeds ... SUCCESS
                   Running test_assert_matches_fails_when_not_matching ... SUCCESS
                   Running test_assert_matches_succeed_when_matching ... SUCCESS
                   Running test_assert_no_diff_fails_when_diff ... SUCCESS
                   Running test_assert_no_diff_succeeds_when_no_diff ... SUCCESS
                   Running test_assert_not_equals_fails_when_equal ... SUCCESS
                   Running test_assert_not_equals_succeeds_when_not_equal ... SUCCESS
                   Running test_assert_not_matches_fails_when_matching ... SUCCESS
                   Running test_assert_not_matches_succeed_when_not_matching ... SUCCESS
                   Running test_assert_shows_stderr_on_failure ... SUCCESS
                   Running test_assert_shows_stdout_on_failure ... SUCCESS
                   Running test_assert_status_code_fails ... SUCCESS
                   Running test_assert_status_code_succeeds ... SUCCESS
                   Running test_assert_succeeds ... SUCCESS
                   Running test_assert_within_delta_fails ... SUCCESS
                   Running test_assert_within_delta_succeeds ... SUCCESS
                   Running test_fail_fails ... SUCCESS
           Overall result: SUCCESS

       You can combine the -p option with -s to skip some of the tests. This option accepts a pattern as
       parameter and mark as skipped any test function which matches this pattern.

           ./bash_unit -p fail_fails -p assert -s no -s status tests/test_core.sh

           Running tests in tests/test_core.sh
                   Running test_assert_equals_fails_when_not_equal ... SKIPPED
                   Running test_assert_matches_fails_when_not_matching ... SKIPPED
                   Running test_assert_no_diff_fails_when_diff ... SKIPPED
                   Running test_assert_no_diff_succeeds_when_no_diff ... SKIPPED
                   Running test_assert_not_equals_fails_when_equal ... SKIPPED
                   Running test_assert_not_equals_succeeds_when_not_equal ... SKIPPED
                   Running test_assert_not_matches_fails_when_matching ... SKIPPED
                   Running test_assert_not_matches_succeed_when_not_matching ... SKIPPED
                   Running test_assert_status_code_fails ... SKIPPED
                   Running test_assert_status_code_succeeds ... SKIPPED
                   Running test_assert_equals_succeed_when_equal ... SUCCESS
                   Running test_assert_fails ... SUCCESS
                   Running test_assert_fails_fails ... SUCCESS
                   Running test_assert_fails_succeeds ... SUCCESS
                   Running test_assert_matches_succeed_when_matching ... SUCCESS
                   Running test_assert_shows_stderr_on_failure ... SUCCESS
                   Running test_assert_shows_stdout_on_failure ... SUCCESS
                   Running test_assert_succeeds ... SUCCESS
                   Running test_assert_within_delta_fails ... SUCCESS
                   Running test_assert_within_delta_succeeds ... SUCCESS
                   Running test_fail_fails ... SUCCESS
           Overall result: SUCCESS

       bash_unit supports the Test Anything Protocol <http://testanything.org/> so you can ask for a tap
       formatted output with the -f option.

           ./bash_unit -f tap tests/test_core.sh

           # Running tests in tests/test_core.sh
           ok - test_assert_equals_fails_when_not_equal
           ok - test_assert_equals_succeed_when_equal
           ok - test_assert_fails
           ok - test_assert_fails_fails
           ok - test_assert_fails_succeeds
           ok - test_assert_matches_fails_when_not_matching
           ok - test_assert_matches_succeed_when_matching
           ok - test_assert_no_diff_fails_when_diff
           ok - test_assert_no_diff_succeeds_when_no_diff
           ok - test_assert_not_equals_fails_when_equal
           ok - test_assert_not_equals_succeeds_when_not_equal
           ok - test_assert_not_matches_fails_when_matching
           ok - test_assert_not_matches_succeed_when_not_matching
           ok - test_assert_shows_stderr_on_failure
           ok - test_assert_shows_stdout_on_failure
           ok - test_assert_status_code_fails
           ok - test_assert_status_code_succeeds
           ok - test_assert_succeeds
           ok - test_assert_within_delta_fails
           ok - test_assert_within_delta_succeeds
           ok - test_fail_fails
           ok - test_fail_prints_failure_message
           ok - test_fail_prints_where_is_error
           ok - test_fake_actually_fakes_the_command
           ok - test_fake_can_fake_inline
           ok - test_fake_echo_stdin_when_no_params
           ok - test_fake_exports_faked_in_subshells
           ok - test_fake_transmits_params_to_fake_code
           ok - test_fake_transmits_params_to_fake_code_as_array
           ok - test_should_pretty_format_even_when_LANG_is_unset
           1..30

HOW TO WRITE TESTS

       Write your test functions in a file. The name of a test function has to start with test. Only functions
       starting with test will be tested.

       Use the bash_unit assertion functions in your test functions, see below.

       You may write a setup function that will be executed before each test is run.

       You may write a teardown function that will be executed after each test is run.

       You may write a setup_suite function that will be executed only once before all the tests of your test
       file.

       You may write a teardown_suite function that will be executed only once after all the tests of your test
       file.

       If you write code outside of any bash function, this code will be executed once at test file loading time
       since your file is a bash script and bash_unit sources it before running your tests. It is suggested to
       write a setup_suite function and avoid any code outside a bash function. you must not use any bash_unit
       assertion in setup_suite or use exit in setup_suite for teardown_suite to be run. See issue 43
       <https://github.com/pgrange/bash_unit/issues/43> for more details.

       If you want to keep an eye on a test not yet implemented, prefix the name of the function by todo instead
       of test. Test to do are not executed and do not impact the global status of your test suite but are
       displayed in bash_unit output.

       bash_unit changes the current working directory to the one of the running test file. If you need to
       access files from your test code, for instance the script under test, use path relative to the test file.

       You may need to change the behavior of some commands to create conditions for your code under test to
       behave as expected. The fake function may help you to do that, see below.

TEST FUNCTIONS

       bash_unit supports several shell oriented assertion functions.

   fail
           fail [message]

       Fails the test and displays an optional message.

           test_can_fail() {
             fail "this test failed on purpose"
           }

                   Running test_can_fail ... FAILURE
           this test failed on purpose
           doc:2:test_can_fail()

   assert
           assert <assertion> [message]

       Evaluates assertion and fails if assertion fails.

       assertion fails if its evaluation returns a status code different from 0.

       In case of failure, the standard output and error of the evaluated assertion is displayed. The optional
       message is also displayed.

           test_assert_fails() {
             assert false "this test failed, obviously"
           }
           test_assert_succeed() {
             assert true
           }

                   Running test_assert_fails ... FAILURE
           this test failed, obviously
           doc:2:test_assert_fails()
                   Running test_assert_succeed ... SUCCESS

       But you probably want to assert less obvious facts.

           code() {
             touch /tmp/the_file
           }

           test_code_creates_the_file() {
             code

             assert "test -e /tmp/the_file"
           }

           test_code_makes_the_file_executable() {
             code

             assert "test -x /tmp/the_file" "/tmp/the_file should be executable"
           }

                   Running test_code_creates_the_file ... SUCCESS
                   Running test_code_makes_the_file_executable ... FAILURE
           /tmp/the_file should be executable
           doc:14:test_code_makes_the_file_executable()

       It may also be fun to use assert to check for the expected content of a file.

           code() {
             echo 'not so cool' > /tmp/the_file
           }

           test_code_write_appropriate_content_in_the_file() {
             code

             assert "diff <(echo 'this is cool') /tmp/the_file"
           }

                   Running test_code_write_appropriate_content_in_the_file ... FAILURE
           out> 1c1
           out> < this is cool
           out> ---
           out> > not so cool
           doc:8:test_code_write_appropriate_content_in_the_file()

   assert_fail
           assert_fail <assertion> [message]

       Asserts that assertion fails. This is the opposite of assert.

       assertion fails if its evaluation returns a status code different from 0.

       If the evaluated expression does not fail, then assert_fail will fail and display the standard output and
       error of the evaluated assertion. The optional message is also displayed.

           code() {
             echo 'not so cool' > /tmp/the_file
           }

           test_code_does_not_write_cool_in_the_file() {
             code

             assert_fails "grep cool /tmp/the_file" "should not write 'cool' in /tmp/the_file"
           }

           test_code_does_not_write_this_in_the_file() {
             code

             assert_fails "grep this /tmp/the_file" "should not write 'this' in /tmp/the_file"
           }

                   Running test_code_does_not_write_cool_in_the_file ... FAILURE
           should not write 'cool' in /tmp/the_file
           out> not so cool
           doc:8:test_code_does_not_write_cool_in_the_file()
                   Running test_code_does_not_write_this_in_the_file ... SUCCESS

   assert_status_code
           assert_status_code <expected_status_code> <assertion> [message]

       Checks for a precise status code of the evaluation of assertion.

       It may be useful if you want to distinguish between several error conditions in your code.

       In case of failure, the standard output and error of the evaluated assertion is displayed. The optional
       message is also displayed.

           code() {
             exit 23
           }

           test_code_should_fail_with_code_25() {
             assert_status_code 25 code
           }

                   Running test_code_should_fail_with_code_25 ... FAILURE
            expected status code 25 but was 23
           doc:6:test_code_should_fail_with_code_25()

   assert_equals
           assert_equals <expected> <actual> [message]

       Asserts for equality of the two strings expected and actual.

           test_obvious_inequality_with_assert_equals(){
             assert_equals "a string" "another string" "a string should be another string"
           }
           test_obvious_equality_with_assert_equals(){
             assert_equals a a
           }

                   Running test_obvious_equality_with_assert_equals ... SUCCESS
                   Running test_obvious_inequality_with_assert_equals ... FAILURE
           a string should be another string
            expected [a string] but was [another string]
           doc:2:test_obvious_inequality_with_assert_equals()

   assert_not_equals
           assert_not_equals <unexpected> <actual> [message]

       Asserts for inequality of the two strings unexpected and actual.

           test_obvious_equality_with_assert_not_equals(){
             assert_not_equals "a string" "a string" "a string should be different from another string"
           }
           test_obvious_inequality_with_assert_not_equals(){
             assert_not_equals a b
           }

                   Running test_obvious_equality_with_assert_not_equals ... FAILURE
           a string should be different from another string
            expected different value than [a string] but was the same
           doc:2:test_obvious_equality_with_assert_not_equals()
                   Running test_obvious_inequality_with_assert_not_equals ... SUCCESS

   assert_matches
           assert_matches <expected-regex> <actual> [message]

       Asserts that the string actual matches the regex pattern expected-regex.

           test_obvious_notmatching_with_assert_matches(){
             assert_matches "a str.*" "another string" "'another string' should not match 'a str.*'"
           }
           test_obvious_matching_with_assert_matches(){
             assert_matches "a[nN].t{0,1}.*r str.*" "another string"
           }

                   Running test_obvious_matching_with_assert_matches ... SUCCESS
                   Running test_obvious_notmatching_with_assert_matches ... FAILURE
           'another string' should not match 'a str.*'
            expected regex [a str.*] to match [another string]
           doc:2:test_obvious_notmatching_with_assert_matches()

   assert_not_matches
           assert_not_matches <unexpected-regex> <actual> [message]

       Asserts that the string actual does not match the regex pattern unexpected-regex.

           test_obvious_matching_with_assert_not_matches(){
             assert_not_matches "a str.*" "a string" "'a string' should not match 'a str.*'"
           }
           test_obvious_notmatching_with_assert_not_matches(){
             assert_not_matches "a str.*" "another string"
           }

                   Running test_obvious_matching_with_assert_not_matches ... FAILURE
           'a string' should not match 'a str.*'
            expected regex [a str.*] should not match but matched [a string]
           doc:2:test_obvious_matching_with_assert_not_matches()
                   Running test_obvious_notmatching_with_assert_not_matches ... SUCCESS

   assert_within_delta
           assert_within_delta <expected num> <actual num> <max delta> [message]

       Asserts that the expected num matches the actual num up to a given max delta. This function only support
       integers. Given an expectation of 5 and a delta of 2 this would match 3, 4, 5, 6, and 7:

           test_matches_within_delta(){
             assert_within_delta 5 3 2
             assert_within_delta 5 4 2
             assert_within_delta 5 5 2
             assert_within_delta 5 6 2
             assert_within_delta 5 7 2
           }
           test_does_not_match_within_delta(){
             assert_within_delta 5 2 2
           }

                   Running test_does_not_match_within_delta ... FAILURE
            expected value [5] to match [2] with a maximum delta of [2]
           doc:9:test_does_not_match_within_delta()
                   Running test_matches_within_delta ... SUCCESS

   assert_no_diff
           assert_no_diff <expected> <actual> [message]

       Asserts that the content of the file actual does not have any differences to the one expected.

           test_obvious_notmatching_with_assert_no_diff(){
             assert_no_diff <(echo foo) <(echo bar)
           }
           test_obvious_matching_with_assert_assert_no_diff(){
             assert_no_diff bash_unit bash_unit
           }

                   Running test_obvious_matching_with_assert_assert_no_diff ... SUCCESS
                   Running test_obvious_notmatching_with_assert_no_diff ... FAILURE
            expected 'doc' to be identical to 'doc' but was different
           out> 1c1
           out> < foo
           out> ---
           out> > bar
           doc:2:test_obvious_notmatching_with_assert_no_diff()

SKIP_IF FUNCTION

           skip_if <condition> <pattern>

       If condition is true, will skip all the tests in the current file which match the given pattern.

       This can be useful when one has tests that are dependent on system environment, for instance:

           skip_if "uname | grep Darwin" linux
           skip_if "uname | grep Linux" darwin

           test_linux_proc_exists() {
             assert "ls /proc/" "there should exist /proc on Linux"
           }
           test_darwin_proc_does_not_exist() {
             assert_fail "ls /proc/" "there should not exist /proc on Darwin"
           }

       will output, on a Linux system:

                   Running test_darwin_proc_does_not_exist ... SKIPPED
                   Running test_linux_proc_exists ... SUCCESS

FAKE FUNCTION

           fake <command> [replacement code]

       Fakes command and replaces it with replacement code (if code is specified) for the rest of the execution
       of your test. If no replacement code is specified, then it replaces command by one that echoes stdin of
       fake. This may be useful if you need to simulate an environment for you code under test.

       For instance:

           fake ps echo hello world
           ps

       will output:

           hello world

       We can do the same using stdin of fake:

           fake ps << EOF
           hello world
           EOF
           ps

           hello world

   Using stdin
       Here is an example, parameterizing fake with its stdin to test that code fails when some process does not
       run and succeeds otherwise:

           code() {
             ps a | grep apache
           }

           test_code_succeeds_if_apache_runs() {
             fake ps <<EOF
             PID TTY          TIME CMD
           13525 pts/7    00:00:01 bash
           24162 pts/7    00:00:00 ps
            8387 ?            0:00 /usr/sbin/apache2 -k start
           EOF

             assert code "code should succeed when apache is running"
           }

           test_code_fails_if_apache_does_not_run() {
             fake ps <<EOF
             PID TTY          TIME CMD
           13525 pts/7    00:00:01 bash
           24162 pts/7    00:00:00 ps
           EOF

             assert_fails code "code should fail when apache is not running"
           }

                   Running test_code_fails_if_apache_does_not_run ... SUCCESS
                   Running test_code_succeeds_if_apache_runs ... SUCCESS

   Using a function
       In a previous example, we faked ps by specifying code inline:

           fake ps echo hello world
           ps

           hello world

       If you need to write more complex code to fake your command, you may abstract this code in a function:

           _ps() {
             echo hello world
           }
           fake ps _ps
           ps

           hello world

       Be careful however that your _ps function is not exported to sub-processes. It means that, depending on
       how your code under test works, _ps may not be defined in the context where ps will be called. For
       instance:

           _ps() {
             echo hello world
           }
           fake ps _ps

           bash -c ps

           environment: line 1: _ps: command not found

       It depends on your code under test but it is safer to just export functions needed by your fake so that
       they are available in sub-processes:

           _ps() {
             echo hello world
           }
           export -f _ps
           fake ps _ps

           bash -c ps

           hello world

       fake is also limited by the fact that it defines a bash function to override the actual command. In some
       context the command can not be overridden by a function. For instance if your code under test relies on
       exec to launch ps, fake will have no effect.

       fake may also imply strange behaviors from bash_unit when you try to fake really basic stuff. bash_unit
       tries to be as much immune to this as possible but there are some limits. Especially and as surprising as
       it might seem, bash allows creating functions named after builtin commands and bash_unit won’t resist
       that kind of situation. So, for instance, do not try to fake: exit; local; trap; eval; export; if; then;
       else; fi; while; do; done; $; echo; [ (I know, this is not a builtin but don’t).

   fake parameters
       fake stores parameters given to the fake in the global variable FAKE_PARAMS so that you can use them
       inside your fake.

       It may be useful if you need to adapt the behavior on the given parameters.

       It can also help in asserting the values of these parameters ... but this may be quite tricky.

       For instance, in our previous code that checks apache is running, we have an issue since our code does
       not use ps with the appropriate parameters. So we will try to check that parameters given to ps are ax.

       To do that, the first naive approach would be:

           code() {
             ps a | grep apache
           }

           test_code_gives_ps_appropriate_parameters() {
             _ps() {
               cat <<EOF
             PID TTY          TIME CMD
           13525 pts/7    00:00:01 bash
           24162 pts/7    00:00:00 ps
            8387 ?            0:00 /usr/sbin/apache2 -k start
           EOF
               assert_equals ax "${FAKE_PARAMS[@]}"
             }
             export -f _ps
             fake ps _ps

             code >/dev/null
           }

       This test calls code, which calls ps, which is actually implemented by _ps. Since code does not use ax
       but only a as parameters, this test should fail. But ...

                   Running test_code_gives_ps_appropriate_parameters ... SUCCESS

       The problem here is that ps fail (because of the failed assert_equals assertion). But ps is piped with
       grep:

           code() {
             ps a | grep apache
           }

       With bash, the result code of a pipeline equals the result code of the last command of the pipeline. The
       last command is grep and since grep succeeds, the failure of _ps is lost and our test succeeds. We have
       only succeeded in messing with the test output, nothing more.

       An alternative may be to activate bash pipefail option but this may introduce unwanted side effects. We
       can also simply not output anything in _ps so that grep fails:

           code() {
             ps a | grep apache
           }

           test_code_gives_ps_appropriate_parameters() {
             _ps() {
               assert_equals ax "${FAKE_PARAMS[@]}"
             }
             export -f _ps
             fake ps _ps

             code >/dev/null
           }

       The problem here is that we use a trick to make the code under test fail but the failure has nothing to
       do with the actual assert_equals failure. This is really bad, don’t do that.

       Moreover, assert_equals output is captured by ps and this just messes with the display of our test
       results:

                   Running test_code_gives_ps_appropriate_parameters ...

       The only correct alternative is for the fake ps to write FAKE_PARAMS in a file descriptor so that your
       test can grab them after code execution and assert their value. For instance by writing to a file:

           code() {
             ps a | grep apache
           }

           test_code_gives_ps_appropriate_parameters() {
             _ps() {
               echo ${FAKE_PARAMS[@]} > /tmp/fake_params
             }
             export -f _ps
             fake ps _ps

             code || true

             assert_equals ax "$(head -n1 /tmp/fake_params)"
           }

           setup() {
             rm -f /tmp/fake_params
           }

       Here our fake writes to /tmp/fake. We delete this file in setup to be sure that we do not get
       inappropriate data from a previous test. We assert that the first line of /tmp/fake equals ax. Also, note
       that we know that code will fail and write this to ignore the error: code || true.

                   Running test_code_gives_ps_appropriate_parameters ... FAILURE
            expected [ax] but was [a]
           doc:14:test_code_gives_ps_appropriate_parameters()

       We can also compact the fake definition:

           code() {
             ps a | grep apache
           }

           test_code_gives_ps_appropriate_parameters() {
             fake ps 'echo ${FAKE_PARAMS[@]} >/tmp/fake_params'

             code || true

             assert_equals ax "$(head -n1 /tmp/fake_params)"
           }

           setup() {
             rm -f /tmp/fake_params
           }

                   Running test_code_gives_ps_appropriate_parameters ... FAILURE
            expected [ax] but was [a]
           doc:10:test_code_gives_ps_appropriate_parameters()

       Finally, we can avoid the /tmp/fake_params temporary file by using coproc:

           code() {
             ps a | grep apache
           }

           test_get_data_from_fake() {
             #Fasten you seat belt ...
             coproc cat
             exec {test_channel}>&${COPROC[1]}
             fake ps 'echo ${FAKE_PARAMS[@]} >&$test_channel'

             code || true

             assert_equals ax "$(head -n1 <&${COPROC[0]})"
           }

                   Running test_get_data_from_fake ... FAILURE
            expected [ax] but was [a]
           doc:13:test_get_data_from_fake()

                                                   2025-02-15                                       BASH_UNIT(1)