BATS / Buildkite Plugin Tester

A base docker image for testing Buildkite plugins with BATS. It includes:

• A non-root user/group at 1000:1000. A docker group is located at gid 900.
• Docker compose v2 and compose-switch for v1 support.
• bats-core
• bats-support
• bats-assert
• @lox's fork of bats-mock
• bats-file

Your plugin’s code is expected to be mounted to /plugin, and by default the image will run the command bats tests/.

Usage

For example, say you had a plugin called git-logger, which took a commit option, and called git log via a command hook:

steps:
  - plugins:
      - foo/git-logger#v1.0.0:
          commit: "abc123"

To test this, you'd add the following docker-compose.yml file:

version: '3.4'
services:
  tests:
    image: buildkite/plugin-tester
    volumes:
      - ".:/plugin"

And you'd create the following test in tests/command.bats:

#!/usr/bin/env bats

load "$BATS_PATH/load.bash"

# Uncomment to enable stub debugging
# export GIT_STUB_DEBUG=/dev/tty

@test "calls git log" {
  export BUILDKITE_PLUGIN_GIT_LOGGER_COMMIT="abc123"

  stub git "log abc123 : echo git log output"

  run $PWD/hooks/command

  assert_output --partial "git log output"
  assert_success
  unstub git
}

Now you can run your tests locally:

docker compose run --rm tests

To set up it up in Buildkite, create a .buildkite/pipeline.yml file that uses the docker-compose Buildkite Plugin to run that same command on CI, for example:

steps:
  - plugins:
      - docker-compose#x.y.z:
          run: tests

Developing

To test plugin-tester itself, use the following command:

docker compose run --rm tests

License

MIT (see LICENSE)