bkahlert/bats-wrapper

About

Bats Wrapper is a self-contained wrapper to run tests based on the Bash testing framework Bats with some differences:

• To facilitate testing of Dockerfiles the Docker command line tools is pre-installed and
  docker buildx bake is called if $DOCKER_BAKE is set (with its contents as the arguments).
• The environment variable TESTING is set to 1 while running tests.
• The following arguments are set by default:
  • --jobs (with the number of processors or 4 or they cannot be determined)
  • --no-parallelize-within-files
  • --no-tempdir-cleanup
  • --recursive
  • --timing
• The following extensions are loaded by default (and patched to support the nounset shell option):
  • bats-support
  • bats-assert
  • bats-file
• Helper script with the name _setup.sh are automatically sourced
  (with the _setup.sh located in the same directory as the bats test file sourced last)

  📁work             ⬅︎ you are here  
  ├─📁src
  └─📁test
    ├─🔧_setup.sh    … automatically sourced
    ├─📄foo.bats
    └─📁bar
      ├─🔧_setup.sh  … automatically sourced
      └─📄baz.bats
  

• The working directory for each test is $BATS_TEST_TMPDIR.
• To focus on a single or a couple of tests an alternative to the --filter option is to prefix a test name with x or X:

  @test "foo" {
    ...
  }
  
  @test "Xbar" {
    ...
  }

  The above example will only execute Xbar without you having to change the command line.
• Several extensions are provided:
  • copy_fixture to handle fixtures
  • expect for tests that require interaction
  • Check wrapper.sh for all extensions.

Bats Wrapper Demo

Docker image

Build locally

git clone https://github.com/bkahlert/bats-wrapper.git
cd bats-wrapper

# Build image and output to docker (default)
docker buildx bake

# Build multi-platform image
docker buildx bake image-all

Image

• Docker Hub bkahlert/bats-wrapper
• GitHub Container Registry ghcr.io/bkahlert/bats-wrapper

Following platforms for this image are available:

• linux/amd64
• linux/arm64/v8

Usage

The Docker container passes all arguments to the wrapped Bash testing framework Bats and therefore inherits all its supported options.

Docker image

docker run -it --rm \
  -e TERM="$TERM" \
  -v "$PWD":"$PWD" \
  -w "$PWD" \
  bkahlert/bats-wrapper [OPTIONS] TEST [TEST...]

Wrapper

The Bats Wrapper batsw needs nothing but a working Docker installation and either curl , wget, or wget2:

curl

curl -LfsS https://git.io/batsw | "$SHELL" -s -- [OPTIONS] TEST [TEST...]

wget

wget -qO- https://git.io/batsw | "$SHELL" -s -- [OPTIONS] TEST [TEST...]

wget2

wget2 -nv -O- https://git.io/batsw | "$SHELL" -s -- [OPTIONS] TEST [TEST...]

GitHub Action

The Bats Wrapper can also be used to run your Bats based tests right inside your GitHub workflow.

Usage Example

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Run Bats tests
        id: bats
        uses: bkahlert/bats-wrapper@v0.1.4
        with:
          tests: test

All described options can be used to customize the test run. Please consult action.yml for detailed information.

Image Configuration

This image can be configured using the following options of which all but APP_USER and APP_GROUP exist as both—build argument and environment variable.
You should go for build arguments if you want to set custom defaults you don't intend to change (often). Environment variables will overrule any existing configuration on each container start.

• APP_USER Name of the main user (default: bats)
• APP_GROUP Name of the main user's group (default: bats)
• DEBUG Whether to log debug information (default: 0)
• TZ Timezone the container runs in (default: UTC)
• LANG Language/locale to use (default: C.UTF-8)
• PUID User ID of the libguestfs user (default: 1000)
• PGID Group ID of the libguestfs group (default: 1000)

# Build single image with build argument TZ
docker buildx bake --build-arg TZ="$(date +"%Z")"

# Build multi-platform image with build argument TZ
docker buildx bake image-all --build-arg TZ="$(date +"%Z")"

# Start container with environment variable TZ
docker run --rm \
  -e TZ="$(date +"%Z")" \
  -v "$(pwd):$(pwd)" \
  -w "$(pwd)" \
  bats-wrapper:local

Testing

git clone https://github.com/bkahlert/bats-wrapper.git
cd bats-wrapper

# Use Bats wrapper to build the Docker image and run the tests
chmod +x ./batsw
DOCKER_BAKE="--set '*.tags=test'" BATSW_IMAGE=test:latest \
  ./batsw --batsw:-e --batsw:BUILD_TAG=test test

Troubleshooting

• To avoid permission problems with generated files, you can use your local user/group ID (see PUID/PGID).
• If you need access to Docker, its command line interface is already installed.
  You can control your host instance by mounting /var/run/docker.sock.

docker run -it --rm \
  -e PUID="$(id -u)" \
  -e PGID="$(id -g)" \
  -e TERM="$TERM" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$PWD":"$PWD" \
  -w "$PWD" \
  bkahlert/bats-wrapper:edge

Contributing

Want to contribute? Awesome! The most basic way to show your support is to star the project, or to raise issues. You can also support this project by making a Paypal donation to ensure this journey continues indefinitely!

Thanks again for your support, it is much appreciated! 🙏

License

MIT. See LICENSE for more details.