Improve documentation how to use the docker image to run tests with bats

[mh182]

The current documentation does not provide enough information so that users could just start working with bats-core using a container runtime instead of a location installation.

This issue is related to #150 (which is quite old and this I created a new ticket since the image has probably changes since 2018).

My goal was to create a test suite for my bash program and execute it with the docker image provided by bats-core.

Since I have no experience with bats I started the tutorial but instead of having a local installation with git submodule I run the test/tutorial with

docker run -it -v "${PWD}:/code" bats/bats:latest tes

I could follow the tutorial until the first helper module was loaded via load 'test_helper/bats-support/load where I got the following error.

➜ docker run -it -v "${PWD}:/code" bats/bats:latest test
test.bats
 ✗ calling without arguments shows usage
   (from function `setup' in test file test/test.bats, line 1)
     `setup() {' failed
   bats_load_safe: Could not find '/code/test/test_helper/bats-support/load'[.bash]

1 test, 1 failure

Solution
The solution to my problem was simple, but it toke me a quite a while to figure it out.

The reason for this error was the location in which the helper libraries are installed in the container image. bats itself is installed in /opt/bats, the helper libraries in /usr/lib/bats.

I had to create a symbolic link in the test directory, which would provide me tha access

ln -sf /usr/lib/bats test/test_helper

It would be nice to improve the tutorial so other users have a better time to get started with bats.

[mh182]

I just found the documentation on https://github.com/bats-core/bats-core/wiki/Docker-Usage-Examples.

Following the instructions lead to an error

➜ docker run -it -v "$(pwd):/opt/bats" --workdir /opt/bats bats/bats:latest test
bash: bats: No such file or directory

[martin-schulze-vireso]

The current documentation does not provide enough information

Please provide a link to the documentation you used and if possible to the offending section.

Since I have no experience with bats I started the tutorial but instead of having a local installation with git submodule I run the test/tutorial with

The tutorial assumes you work with submodules. If you depart from that, the subsequent steps might not work as intended.

The reason for this error was the location in which the helper libraries are installed in the container image. bats itself is installed in /opt/bats, the helper libraries in /usr/lib/bats.

The code in the tutorial assumes the helper libraries are installed in specific subdirectories which the load command will pick up. The docker image has only recently begun to provide these libraries and they should be consumed via bats_load_library instead, which relies on BATS_LIB_PATH, which is already set appropriately in the Dockerfile.

With this in mind, the tutorial might be rewritten to use bats_load_library and mention how to use the Docker image.

Following the instructions lead to an error

➜ docker run -it -v "$(pwd):/opt/bats" --workdir /opt/bats bats/bats:latest test
bash: bats: No such file or directory```

This example needs a rewrite, it only works with bats itself. Please try docker run -it -v "$(pwd):/code" bats/bats:latest test/ (or whatever your test dir is) instead.

[mh182]

The current documentation does not provide enough information

Please provide a link to the documentation you used and if possible to the offending section.

https://bats-core.readthedocs.io/en/stable/tutorial.html#dealing-with-output

The reason for this error was the location in which the helper libraries are installed in the container image. bats itself is installed in /opt/bats, the helper libraries in /usr/lib/bats.

The code in the tutorial assumes the helper libraries are installed in specific subdirectories which the load command will pick up. The docker image has only recently begun to provide these libraries and they should be consumed via bats_load_library instead, which relies on BATS_LIB_PATH, which is already set appropriately in the Dockerfile.

This example needs a rewrite, it only works with bats itself. Please try docker run -it -v "$(pwd):/code" bats/bats:latest test/ (or whatever your test dir is) instead.

I agree. My current solution was to use bats_load_library and setting the environment variable with docker run -it -e BATS_LIB_PATH=/usr/lib/bats -v "${PWD}:/code" bats/bats:latest test.

Setting BATS_LIB_PATH in the container image would make the whole thing easier.

So the tutorial code would look like

setup() {
    load 'test_helper/bats-support/load'
    load 'test_helper/bats-assert/load'
    # ... the remaining setup is unchanged

    # get the containing directory of this file
    # use $BATS_TEST_FILENAME instead of ${BASH_SOURCE[0]} or $0,
    # as those will point to the bats executable's location or the preprocessed file respectively
    DIR="$( cd "$( dirname "$BATS_TEST_FILENAME" )" >/dev/null 2>&1 && pwd )"
    # make executables in src/ visible to PATH
    PATH="$DIR/../src:$PATH"
}

@test "can run our script" {
    run project.sh # notice `run`!
    assert_output 'Welcome to our project!'
}

[arve0]

This works for me with docker run -it -v "$PWD:/code" bats/bats:latest /code/test:

setup() {
    bats_load_library bats-support
    bats_load_library bats-assert
}

@test "Check welcome message" {
    run project
    assert_output --partial 'Welcome to our project!'
}

function project {
    echo "Welcome to our project!"

    echo "NOT IMPLEMENTED!" >&2
    return 1
}

[martin-schulze-vireso]

I think arve0's comment and PR already says everything that needs to be said here. The only thing remaining is changing the tutorial.