Integration: Buildkite

Integrate Ghost Inspector with Buildkite

Search our documentation:

Toggle Documentation Menu

Integration: 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:

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 test suite in Ghost Inspector. It will launch your application locally, set up an ngrok tunnel to that application, execute our test suite, and then poll the Ghost Inspector API for the suite results.

Note that you will need to modify the values for API_KEY, APP_PORT, GI_SUITE, and NGROK_TOKEN at the top of the script.

Note: You may not want to commit your API_KEY or NGROK_TOKEN into your repository, in that case you can specify environment variables in your Buildkite pipeline configuration and remove the associated definitions at the top of the script below.
################################
##### CUSTOMIZE BELOW HERE #####

# note: if you specify any of these env vars in your pipeline config,
# you will want to remove them from here
API_KEY='<your-api-key>'
APP_PORT='<your-application-port>'
GI_SUITE='<your-suite-id>'
NGROK_TOKEN='<your-ngrok-auth-token>'

# Tailor this command to suit your application, *must* have the trailing '&'
node server.js &

##### CUSTOMIZE ABOVE HERE #####
################################

# Save the application process ID so we can clean up later
APP_PID=$!
echo "Local application started with PID: $APP_PID"

# unzip may not be available on docker image atlassian/bamboo-base-agent
which unzip
if [ $? -ne 0 ]; then
  wget -qO- https://oss.oracle.com/el4/unzip/unzip.tar | tar -x -C /bin/
fi

# Download ngrok and unzip
wget -qN https://bin.equinox.io/c/4VmDzA7iaHb/ngrok-stable-linux-amd64.zip
unzip ngrok-stable-linux-amd64.zip
chmod +x ngrok

# Download JSON parser for determining ngrok tunnel
wget -qN -Ojq https://stedolan.github.io/jq/download/linux64/jq
chmod +x jq

# Intialize ngrok and open tunnel to our application
./ngrok authtoken $NGROK_TOKEN
./ngrok http $APP_PORT > /dev/null &
NGROK_PID=$!

# give ngrok a second to register URLs
sleep 5

# Grab the ngrok url to send to the API
START_URL=$(curl -s 'http://localhost:4040/api/tunnels' | ./jq -r '.tunnels[1].public_url')
echo "Using start URL: $START_URL"

# Set up a couple variables to monitor result state
STATUS='null'
SUITE_RESULT=
PASSING=

# Execute Ghost Inspector suite via API and grab the result ID
EXECUTE_URL="https://api.ghostinspector.com/v1/suites/$GI_SUITE/execute/?apiKey=$API_KEY&startUrl=$START_URL&immediate=1"
echo "Executing suite: $EXECUTE_URL"
RESULT_ID=$(curl -s $EXECUTE_URL | ./jq -r '.data._id')

# for the suite result, sleep for a few seconds if it hasn't changed
echo "Polling for suite results (ID: $RESULT_ID)"
while [ "$STATUS" = 'null' ]; do
  sleep 5
  SUITE_RESULT=$(curl -s "https://api.ghostinspector.com/v1/suite-results/$RESULT_ID/?apiKey=$API_KEY")
  STATUS=$(echo $SUITE_RESULT | ./jq -r '.data.passing')
  echo " - status: $STATUS"
done

# status has been updated, check results for "passing"
if [ "$(echo $SUITE_RESULT | ./jq -r '.data.passing')" != 'true' ]; then
  echo "Suite failed! ¯\_(ツ)_/¯"
  PASSING=1
else 
  echo "Suite passed! \o/"
  PASSING=0
fi

# clean up our processes
kill -9 $APP_PID
kill -9 $NGROK_PID

# return our passing status
exit $PASSING

Don't forget to add and commit the script to your repo.

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.