Buildkite

Ghost Inspector test suites can be executed inside your Buildkite pipelines by leveraging the Ghost Inspector API. This tutorial will show you how you can run Ghost Inspector tests against an application running locally on your Buildkite agent.

Note: This example assumes your build agent is running in a Linux-like environment.

Getting started

To get started, we are going to need the following:

Set up an account with Buildkite, a platform for running continuous integration pipelines on your own infrastructure.
Set up an account with ngrok.io, a free utility used for secure local VPN tunneling. You will need the auth token provided in your account.

Setting up the build

Buildkite is a pipeline management tool, but the build agents run on your own infrastructure, so before we run anything you’ll need to make sure you have set up your build agent.

Next we will need to add a build.sh to your repository that Buildkite can execute, a good location is probably ./bin/build.sh, relative to the root of your repo.

Don’t forget to add the execute bit, chmod +x ./bin/build.sh.

./bin/build.sh

The ./bin/build.sh script will handle the actual work of executing the suite in Ghost Inspector by doing the following:

pull down the Ghost Inspector CLI binary,
start the local application,
execute the suite with the CLI.

Variables and secrets

Note that this script relies on having values for GHOST_INSPECTOR_API_KEY, APP_PORT, SUITE_ID, and NGROK_TOKEN in the environment. Check out the Buildkite documentation on how to set up and manage environment variables and secrets.

# Pull down the Ghost Inspector CLI binary
curl -sL https://github.com/ghost-inspector/node-ghost-inspector/releases/latest/download/ghost-inspector-linux \
  --output ./ghost-inspector

# Make the CLI executable
chmod +x ghost-inspector

# Run the local application in the background
node my-application.js &

# Execute the suite
./ghost-inspector suite execute $SUITE_ID \
  --apiKey $GHOST_INSPECTOR_API_KEY \
  --browser firefox
  --ngrokTunnel localhost:$APP_PORT
  --ngrokUrlVariable startUrl
  --ngrokToken $NGROK_TOKEN
  --errorOnFail

For more details on execution options, see the CLI documentation.

Tying it together

Now we can specify the build script location as a step in our pipeline. In your Buildkite pipeline add bin/build.sh in the input for Commands to run and Ghost Inspector Suite under Label:

Add Ghost Inspector step in Buildkite

Click Create Pipeline. Buildkite will now ask you to tie your new pipeline into your SCM system (like Github) or trigger the build via webhook.

Wrapping up

And we’re done! Once your build is triggered you should be able to log into your Buildkite account and follow your pipeline logs. If you encounter any issues with this tutorial or require any other assistance, feel free to drop us a line, we're always happy to help.