README.md

Buildkite Plugin Tester

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

• bats-core
• bats-support
• bats-assert
• 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.7'
services:
  tests:
    image: buildkite/plugin-tester:v4.1.1
    volumes:
      - ".:/plugin"

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

#!/usr/bin/env bats

setup() {
  load "$BATS_PLUGIN_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

Releasing

1. Create a new GitHub Release. Docker Hub images are automatically pushed when the new tag is created.
2. Update the README.md example line’s version number (image: buildkite/plugin-tester#vX.Y.Z)

License

MIT (see LICENSE)