Integration: CircleCI

Integrate Ghost Inspector with CircleCI

Search our documentation:

Toggle Documentation Menu

Integration: CircleCI

Jump to...

Prerequisites

For both the Docker image configuration and the Manual script configuration, we will need the following:

CircleCI environment variables

The following environment variables will need to be set up in CircleCI:

Add environment variables for CircleCI build

Docker configurations

There are 2 different Docker images available for use with CircleCI, ghostinspector/test-runner-node and ghostinspector/test-runner-standalone. Use the ghostinspector/test-runner-node image if you just have a simple Node.js application that you would like to test using Ghost Inspector. Use ghostinspector/test-runner-standalone if you are already building your own Docker image or need to run your tests against a more complex Docker cluster configuration. More details on our Docker images can be found here.

Base image example (ghostinspector/test-runner-node)

The base Docker image can be used to test your Node.js application on CircleCI by extending the ghostinspector/test-runner-node image.

.circleci/config.yml

version: 2
jobs:
  build:
    docker:
      # extend the test runner base image
      - image: ghostinspector/test-runner-node
    steps:
      - checkout
      # add any dependencies/installation steps here
      # - run: npm install .
      # run the test suite against our application
      - run: /bin/runghostinspectorsuite server.js

You will want to customize the example to install any system or application dependencies that you require. Also customize the last line of the example to point to the entrypoint of your application, so for example if your app runs from app/index.js then you will want the last line to read:

      - run: /bin/runghostinspectorsuite app/index.js

When the container starts, it will run your application using node app/index.js before attempting to execute your Ghost Inspector test suite.

Standalone image example (ghostinspector/test-runner-standalone)

The standalone Docker image can be used to test your existing Docker application without the need to modify your existing container(s). The following example will build and start the application under test in the background, and then use ghostinspector/test-runner-standalone to create a temporary tunnel to your Docker app and execute your test suite against it.

.circleci/config.yml

version: 2
jobs:
  build:
    docker:
      - image: docker:17.05.0-ce-git
    steps:
      # required to run multiple containers
      - setup_remote_docker
      # check out our code
      - checkout
      # build our app, tag it 'my-app.0.1.x'
      - run:
          name: Build my application
          # build our app and call it 
          command: |
            docker build -t my-app:0.1.$CIRCLE_BUILD_NUM .
      # NOTE: when we run the second container we *must* specify
      # the network name (my-app) as well as the port for APP_PORT
      # so the test-runner-standalone points the tunnel to the right
      # place, eg: 'APP_PORT=my-app:$APP_PORT'
      - run:
          name: Execute test
          command: |
            docker network create temp-network
            docker run -d \
              --network temp-network \
              --name my-app \
              my-app:0.1.$CIRCLE_BUILD_NUM --sha=$CIRCLE_SHA1
            docker run \
              -e APP_PORT=my-app:$APP_PORT \
              -e GI_API_KEY=$GI_API_KEY \
              -e GI_SUITE=$GI_SUITE \
              -e NGROK_TOKEN=$NGROK_TOKEN \
              --network temp-network \
              ghostinspector/test-runner-standalone

Manual script configuration

If you are not using Docker (or do not wish to), you can still perform the same operations as our Docker containers manually with the following:

.circleci/config.yml

version: 2
jobs:
  build:
    docker:
      - image: circleci/node:8.11.1-stretch
    steps:
      - checkout
      - run:
          name: Execute test
          command: bash build.sh

Here we are referencing a build.sh script in the root of our project which looks like this:

build.sh

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

# 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 &

# 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=$GI_API_KEY&startUrl=$START_URL&immediate=1" 
echo "Executing suite: $EXECUTE_URL"
RESULT_ID=$(curl -s $EXECUTE_URL | ./jq -r '.data._id')

# Poll 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=$GI_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

# return our passing status
exit $PASSING

Note you will need to modify the first line of the script to suit your application, so if your Node.js app starts with bin/start.js then you will want line 1 to look like node bin/start.js &. Customize the rest of the script to suit.

Simple notification configration

This option is available if you simply want to trigger your Ghost Inspector test suite at the end of your CircleCI build. While not officially documented in the CircleCI 2.0 configuration documentation this still appears to work: simply add the notify key at the end of your .circleci/config.yml file:

version: 2
jobs:
  build:
    docker:
      - image: docker:17.05.0-ce-git
    steps:
      - checkout
      - run:
          name: Deploy to staging
          command: ./deploy.sh

notify:
  webhooks:
    - url: https://api.ghostinspector.com/v1/suites/<suite-id>/execute/?apiKey=<api-key>&startUrl=<start-url>&immediate=1

Note that you will need to replace the values for suite-id, api-key, and start-url to match your settings as the webhook will not pick them up from your environment.