Writing Tests

Batspp is a testing framework that allows users to write tests in a format resembling shell commands. Tests consist of commands followed by expected outputs, facilitating easy verification.

$ [command]
[expected output]

Your first Batspp test

To write your first Batspp test, create a new file example.batspp with the following content:

$ echo "this is a test" | wc -c
15

Running $ batspp ./example.batspp you should see the result of the test:

$ batspp /path/to/test.batspp
1..1
ok 1 test of line 1

When the assertion fails, you will see something like this:

$ batspp /path/to/test.batspp
1..1
not ok 1 test of line 1
# (in test file /tmp/main-8zolvc_v, line 21)
#   '[ "$actual" == "$expected" ]' failed
# ========== actual ==========
# 15
# ========= expected =========
# 23
# ============================

Naming your tests

You can replace the assigned title test of line [number] with a better title using the test directive # Test [some better title]:

# Test testing batspp titles
$ echo "here we will use a title for this test" | wc -c
39

Running it you will see:

$ batspp /path/to/test.batspp
1..1
ok 1 testing batspp titles

Grouping commands into a single test

Tests directives also are used to group multiple assertions and setups commands, for example:

# Test multiple setup and assertions
$ filepath=$(echo $TMP/testfile-"$$")
$ echo -e "in this test\nwe are using\nmultiple assertions" | sudo tee $filepath
$ cat $filepath | wc -l
3
$ cat $filepath | wc -c
46

Splitting tests into multiple parts

If you want to split a test into multiple parts, you can first write the test directive and then use the continuation directive # Continue of [some test title]:

# Test multiple setups and assertions
$ filepath=$(echo $TMP/testfile-"$$")
$ echo -n "this is a file content to run an example test" | sudo tee $filepath
$ cat $filepath
this is a file content to run an example test

...

# Continue of multiple setups and assertions
$ echo -n " using setup" >> $filepath
$ echo -n " and continue directives" >> $filepath
$ cat $filepath
this is a file content to run an example test using setup and continue directives

1..1
ok 1 multiple setups and assertions

Continuation directives without a specific title assigned, for example # Continue, are assigned to the last found test directive. If there are no previous tests, it throws an exception.

Arrow assertions

Also, you can write assertions with arrows; => (assert equals) and =/> (assert not equals):

# This test should work fine:
fibonacci 9 => 0 1 1 2 3 5 8 13 21 34

# This is a negative test:
fibonacci 3 =/> 8 2 45 34 3 5

Writing setups

You can write setups for assertions as standalone commands $ command,

For example, the first two commands are setup and the last one an assertion, note that setup commands do not have text after the command:

# Test setup and title
$ filepath=$(echo $TMP/testfile-"$$")
$ echo -n "this is a file content to run an example test" | sudo tee $filepath
$ cat $filepath
this is a file content to run an example test

You can specify a test target of the setup with `` of `` followed by the title of that test # Setup of [some test]:

# Test some important test
$ filepath=$(echo $TMP/testfile-"$$")
$ echo -n "this is a file content to run an example test" | sudo tee $filepath

...

# Setup of some important test
$ echo -n " using setup" >> $filepath
$ echo -n " and continue directives" >> $filepath

Writing global setups

You can write global setups for all tests writing setups commands without previous test:

# Setup
$ shopt -s expand_aliases
$ source ./bash_example.bash

If a previous test/assertion is found before, the setup will be interpreted as local.

Also you can use the Global Setup directive to specify that the setup is global for all tests:

# Global Setup
$ alias count-words='wc -w'

Writing teardowns

The equivalent directive of setups but for teardowns is # Teardown:

# Teardown
echo "this will be run when the test finishes"

Writing global teardowns

As with setups, you can write global teardowns for all tests writing teardowns commands without previous test:

# Global Teardown
echo "this will be run when the test finishes"

Coverage Reports

Section work in progress…

Mote test examples!

On examples, you can find several Batspp full examples and their related generated Bats files.