https://github.com/pgrange/bash_unit

Skip to content
 
Sign up

  * Why GitHub?
    Features -
      + Mobile -
      + Actions -
      + Codespaces -
      + Packages -
      + Security -
      + Code review -
      + Project management -
      + Integrations -
      + GitHub Sponsors -
      + Customer stories-
      + Security -
  * Team
  * Enterprise
  * Explore
      + Explore GitHub -

    Learn and contribute

      + Topics -
      + Collections -
      + Trending -
      + Learning Lab -
      + Open source guides -

    Connect with others

      + The ReadME Project -
      + Events -
      + Community forum -
      + GitHub Education -
      + GitHub Stars program -
  * Marketplace
  * Pricing
    Plans -
      + Compare plans -
      + Contact Sales -
      + Nonprofit -
      + Education -

[                    ] [search-key]

  *  
    #
    In this repository All GitHub |
    Jump to |

  * No suggested jump to results

  *  
    #
    In this repository All GitHub |
    Jump to |
  *  
    #
    In this user All GitHub |
    Jump to |
  *  
    #
    In this repository All GitHub |
    Jump to |

Sign in Sign up
{{ message }}

pgrange / bash_unit

  * Notifications
  * Star 315
  * Fork 36

bash unit testing enterprise edition framework for professionals

GPL-3.0 License
315 stars 36 forks
Star
Notifications

  * Code
  * Issues 7
  * Pull requests 2
  * Actions
  * Projects 0
  * Security
  * Insights

More

  * Code
  * Issues
  * Pull requests
  * Actions
  * Projects
  * Security
  * Insights

master
Switch branches/tags
[                    ]
Branches Tags
Nothing to show
{{ refName }} default View all branches
Nothing to show
{{ refName }} default
View all tags
1 branch 15 tags
Go to file Code
 
Clone
HTTPS GitHub CLI
[https://github.com/p]

Use Git or checkout with SVN using the web URL.

[gh repo clone pgrang]

Work fast with our official CLI. Learn more.

  * Open with GitHub Desktop
  * Download ZIP

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Go back

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Go back

Launching Xcode

If nothing happens, download Xcode and try again.

Go back

Launching Visual Studio

If nothing happens, download the GitHub extension for Visual Studio
and try again.

Go back

Latest commit

@Httqm Matthieu FOURNET
Httqm and Matthieu FOURNET FIX typo (#62)
...
ca58fc3 Sep 11, 2020
FIX typo (#62)

Co-authored-by: Matthieu FOURNET <matthieu.fournet@orange.com>

ca58fc3

Git stats

  * 188 commits

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
docs/man/man1
FIX typo (#62)
Sep 11, 2020
getting_started
FIX #18: bash_unit changes current working directory to current test
...
Sep 14, 2016
img
ADD logo and icon in two size each (#30)
Nov 16, 2016
tests
Fixes #54 (#59)
Jan 18, 2020
.gitattributes
bash_unit -v will display bash_unit current version.
Dec 1, 2016
.gitignore
ADD tool to release bash_unit quickly.
Sep 14, 2016
CONTRIBUTING.md
There are other ways than just code to contribute to bash_unit.
Jun 1, 2017
CONTRIBUTING_CODE.md
Release includes up to date man page.
Jun 27, 2017
LICENSE
FIX #9 expliciting GNU General Public Licence for bash_unit.
Mar 31, 2016
README.adoc
FIX typo (#62)
Sep 11, 2020
bash_unit
Try to handle syntax error in tests the best we can
Jan 18, 2020
install.sh
Remove warning with find command (#41)
Jul 7, 2017
release
Improve release script usage
Sep 1, 2017
View code

README.adoc

bash_unit

bash_unit - bash unit testing enterprise edition framework for
professionals !

 Synopsis

bash_unit [-f tap] [-p <pattern>] [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 before continuing
reading this documentation.

(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.

-f output_format

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

 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 Nix/NixOS

bash_unit package has been added to nixpkgs. You can use it with the
following command:

nix-shell -p bash_unit

 other installation

This will install bash_unit in your current working directory:

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

You can also download it from the release page.

 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_not_equals_fails_when_equal... SUCCESS
Running test_assert_not_equals_succeeds_when_not_equal... 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_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

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_not_equals_fails_when_equal... SUCCESS
Running test_assert_not_equals_succeeds_when_not_equal... 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_fail_fails... SUCCESS

bash_unit supports the Test Anything Protocol 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_not_equals_fails_when_equal
ok - test_assert_not_equals_succeeds_when_not_equal
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_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

 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.

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 bellow.

 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, obvioulsy"
}
test_assert_succeed() {
  assert true
}

Running test_assert_fails... FAILURE
this test failed, obvioulsy
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

 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

It has been asked wether 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 great and detailed literature on this subjet.

 Using stdin

Here is an exemple, 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 exemple, 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 carefull 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
overriden 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 approch 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 inapropriate 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()

About

bash unit testing enterprise edition framework for professionals

Topics

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

Resources

Readme

License

GPL-3.0 License

Releases 15

 
v1.7.1 Latest
Jan 18, 2020
+ 14 releases

Packages 0

No packages published

Contributors 12

  * @pgrange
  * @guillaumevincent
  * @mbeko
  * @lmazardo
  * @n0vember
  * @Potherca
  * @MichaelBitard
  * @Httqm
  * @rcastagnet
  * @g2g
  * @Pamplemousse
  * @markeissler

Languages

  * Shell 100.0%

  * (c) 2021 GitHub, Inc.
  * Terms
  * Privacy
  * Security
  * Status
  * Docs

 

  * Contact GitHub
  * Pricing
  * API
  * Training
  * Blog
  * About

You can't perform that action at this time.
You signed in with another tab or window. Reload to refresh your
session. You signed out in another tab or window. Reload to refresh
your session.