Jenkins

Official Jenkins Plugin

Ghost Inspector provides an official plugin that can be installed through Jenkins and used to run tests in your CI build.

Plugin Installation

From the Jenkins dashboard, click “Manage Jenkins” in the left menu, then click “Manage Plugins”. Click on the “Available” tab, then search for “Ghost Inspector”. Check the “Install” checkbox for the Ghost Inspector plugin, then click the “Install without restart” button.

Plugin Setup

Once installed, the Ghost Inspector plugin will add a new build step option for running your tests during the build process. Enter your project and click “Configure” on the left menu. Scroll down to the “Build” section. When you click the “Add build step” button, you'll now see an option labeled “Run Ghost Inspector Test Suite”.

Adding a “Run Ghost Inspector Test Suite” build step allows you to trigger a suite of Ghost Inspector tests. You'll need to enter your account's API key and the ID of the suite that you wish to trigger. An optional “Start URL” field is available. If this field is left blank, the tests will run on their default start URLs. However, if you wish to open a tunnel directly to a running instance of your application during the build process and run the tests there, a tunnel URL can be specified here. (See our documentation on local tunneling to learn more about how this can be achieved.)

Save your configuration changes and the Ghost Inspector suite will be triggering during your next build. You can add as many Ghost Inspector steps as you’d like, allowing you to trigger multiple suites.

Jenkins Pipelines Support

You can also trigger the Ghost Inspector Jenkins plugin within your Jenkins Pipelines script (or Jenkinsfile), here is an example usage:

node {
  stage('Main') {
       step([$class: 'GhostInspectorBuilder', apiKey: 'my-api-key', params: 'additional=parameters&another=one', startUrl: 'my-start-url', suiteId: 'my-suite-id'])
  }
}

Note that you will need to customize the four parameters for apiKey, params, startUrl, and suiteId.

Testing Your Application Directly in the Build Process using a Tunnel

You may wish to run Ghost Inspector tests on an instance of your application that's running within your Jenkins build. We recommend using a tool called ngrok to open a temporary tunnel to your application that Ghost Inspector to test through.

Below is a sample configuration that starts our application, creates an ngrok tunnel, then triggers a Ghost Inspector test suite (using that tunnel). This example follows a similar route to our CircleCI blog post which walks through this process in slightly more detail.

First, we’ll need to setup an ngrok.io account. Make note of your account’s ngrok token.

Now we need to add an “Execute shell” build step. This step is going to launch our application, open an ngrok tunnel to it, then trigger a suite of Ghost Inspector tests on the application through the tunnel. Note that some of these commands will need to be customized, for instance, the command to start the application and the port number of the application. You’ll also need to swap in the proper values for your ngrok token, suite ID and Ghost Inspector API key. (You can store these values in Jenkins variables, if you’d like.)

# Start our application (Command needs to be customized)
node server.js &

# Download ngrok and unzip
if [ ! -f "ngrok" ]; then
    wget https://bin.equinox.io/c/4VmDzA7iaHb/ngrok-stable-linux-amd64.zip
    unzip ngrok-stable-linux-amd64.zip
    chmod +x ngrok
fi

# Download JSON parser for determining ngrok tunnel
if [ ! -f "jq" ]; then
    wget http://stedolan.github.io/jq/download/linux64/jq
    chmod +x jq
fi

# Intialize ngrok and open tunnel to our application (Port 3000 needs to be customized)
./ngrok authtoken [NGROK_TOKEN]
./ngrok http 3000 > /dev/null &
sleep 5

# Execute Ghost Inspector suite via API using the ngrok tunnel and store results in JSON file
curl -s "https://api.ghostinspector.com/v1/suites/[GHOST_SUITE_ID]/execute/?apiKey=[GHOST_API_KEY]&startUrl=$(curl -s 'http://localhost:4040/api/tunnels' | ./jq -r '.tunnels[1].public_url')" > ghostinspector.json

# Check JSON results for failing tests
if [ $(grep -c '"passing":false' ghostinspector.json) -ne 0 ]; then exit 1; else echo "Tests Passed"; fi

Alternative Options

If you prefer to skip the Ghost Inspector plugin and use our API directly, install the Jenkins Notification Plugin and configure it to use the settings below. You will need to swap in your own values for [suite-id] and [api-key].

Protocol:

HTTP

URL:

https://api.ghostinspector.com/v1/suites/[suite-id]/execute/?apiKey=[api-key]