Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/pgrange/bash_unit

bash unit testing enterprise edition framework for professionals
https://github.com/pgrange/bash_unit

assertions bash tdd test-driven-development test-framework testing unit-testing unittest xunit

Last synced: 2 months ago
JSON representation

bash unit testing enterprise edition framework for professionals

Host: GitHub
URL: https://github.com/pgrange/bash_unit
Owner: pgrange
License: gpl-3.0
Created: 2011-07-13T08:09:53.000Z (almost 13 years ago)
Default Branch: main
Last Pushed: 2024-03-19T07:26:10.000Z (3 months ago)
Last Synced: 2024-04-14T18:48:35.320Z (2 months ago)
Topics: assertions, bash, tdd, test-driven-development, test-framework, testing, unit-testing, unittest, xunit
Language: Shell
Homepage:
Size: 1.21 MB
Stars: 574
Watchers: 13
Forks: 55
Open Issues: 8
Metadata Files:
- Readme: README.adoc
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE

Lists

awesome-bash - bash_unit - Bash unit testing enterprise edition framework for professionals. (Shell Script Development)
awesome-bash - bash_unit - Bash unit testing enterprise edition framework for professionals. (Applications / Testing)
awesome-stars - pgrange/bash_unit - bash unit testing enterprise edition framework for professionals (testing)
awesome-bash - bash_unit - Bash unit testing enterprise edition framework for professionals. (Shell Script Development)

README

ifdef::backend-manpage[]
= BASH_UNIT(1)

== NAME
endif::[]

ifndef::backend-manpage[]
image::img/bu_50.png[bash_unit]
endif::[]

bash_unit - bash unit testing enterprise edition framework for professionals!

== Synopsis

*bash_unit* [-f tap] [-p ] [-s ] [-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 link:getting_started[how to get started]
before continuing reading this documentation.

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

* `fail [message]`
* `assert [message]`
* `assert_fail [message]`
* `assert_status_code [message]`
* `assert_equals [message]`
* `assert_not_equals [message]`
* `assert_matches [message]`
* `assert_not_matches [message]`
* `assert_within_delta [message]`
* `assert_no_diff [message]`
* `skip_if `
* `fake [replacement code]`

ifndef::backend-manpage[]
image::img/demo.gif[demo]
endif::[]

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

*bash_unit* is free software you may contribute to. See link:CONTRIBUTING.md[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.

ifndef::backend-manpage[]

== How to install *bash_unit*

=== installing on Archlinux

*bash_unit* package is available on Archlinux through AUR. In order to install, issue the following command :

yaourt -Sys bash_unit

=== installing via link:https://nixos.org/[Nix/NixOS]

*bash_unit* package has been added to link:https://github.com/nixos/nixpkgs[nixpkgs]. You can use it with the following command:

nix-shell -p bash_unit

=== installing via link:https://brew.sh[Homebrew]

*bash_unit* is available by invoking brew:

brew install bash_unit

=== other installation

This will install *bash_unit* in your current working directory:

curl -s https://raw.githubusercontent.com/pgrange/bash_unit/master/install.sh | bash

You can also download it from the https://github.com/pgrange/bash_unit/releases[release page].

endif::[]

=== GitHub Actions

Here is an example of how you could integrate *bash_unit* with https://docs.github.com/fr/actions[GitHub 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 https://github.com/pgrange/bash_unit_getting_started[getting started gitlab project] for a working example.

=== GitLab CI

Here is an example of how you could integrate *bash_unit* with https://docs.gitlab.com/ee/ci/[GitLab 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 https://gitlab.com/pgrange/bash_unit_getting_started[getting started gitlab project] for a working example.

=== pre-commit hook

You can run `+bash_unit+` as a https://pre-commit.com[pre-commit] 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$+`.

[.pre-commit-config,yaml]
```
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:

```test
./bash_unit tests/test_core.sh
```

```output
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.

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

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.

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

```output
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 http://testanything.org/[Test Anything Protocol] so you can ask for a tap formatted
output with the _-f_ option.

```test
./bash_unit -f tap tests/test_core.sh
```

```output
# 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
```

== 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 https://github.com/pgrange/bash_unit/issues/43[issue 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
test_can_fail() {
fail "this test failed on purpose"
}
```

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

=== *assert*

assert [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
test_assert_fails() {
assert false "this test failed, obviously"
}
test_assert_succeed() {
assert true
}
```

```output
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.

```test
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"
}
```

```output
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.

```test
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"
}
```

```output
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 [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.

```test
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"
}
```

```output
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 [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.

```test
code() {
exit 23
}

test_code_should_fail_with_code_25() {
assert_status_code 25 code
}
```

```output
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 [message]

Asserts for equality of the two strings _expected_ and _actual_.

```test
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
}

```

```output
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 [message]

Asserts for inequality of the two strings _unexpected_ and _actual_.

```test
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
}

```

```output
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 [message]

Asserts that the string _actual_ matches the regex pattern _expected-regex_.

```test
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"
}

```

```output
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 [message]

Asserts that the string _actual_ does not match the regex pattern _unexpected-regex_.

```test
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"
}

```

```output
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 [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
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
}

```

```output
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 [message]

Asserts that the content of the file _actual_ does not have any differences to the one _expected_.

```test
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
}

```

```output
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

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:

```test
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:

```output
Running test_darwin_proc_does_not_exist ... SKIPPED
Running test_linux_proc_exists ... SUCCESS
```

== *fake* function

fake [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:

```test
fake ps echo hello world
ps
```

will output:

```output
hello world
```

We can do the same using _stdin_ of fake:

```test
fake ps << EOF
hello world
EOF
ps
```

```output
hello world
```

ifndef::backend-manpage[]
It has been asked whether using *fake* results in creating actual fakes or stubs or mocks? or may be spies? or may be they are dummies?
The first answer to this question is: it depends. The second is: read this
https://www.google.fr/search?tbm=isch&q=fake%20mock%20stub[great and detailed literature] on this subject.
endif::[]

=== 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:

```test
code() {
ps a | grep apache
}

test_code_succeeds_if_apache_runs() {
fake ps </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 ...

```output
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_:

```shell
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:

```shell
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:

```shell
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:

```test
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`.

```output
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:

```test
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
}
```

```output
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_:

```test
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]})"
}

```

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