Integration: Jenkins

Integrate Ghost Inspector with Jenkins

Search our documentation:

Toggle Documentation Menu

Integration: Jenkins

Ghost Inspector provides an official plugin for running Ghost Inspector tests inside of your Jenkins CI build process. We're working on getting the plugin hosted in the official Jenkins plugin repository. In the mean time, we offer a direct download of the ghost-inspector.hpi plugin file as well as access to the full plugin source code, if you wish to build it yourself.

Note: If you're interested in tunneling directly to your application during the build process for testing, we recommend using the shell step below instead of the plugin.

Official Jenkins Plugin

Plugin Installation

From the Jenkins dashboard, click "Manage Jenkins" in the left menu, then click "Manage Plugins". Click on the "Advanced" tab, then scroll down to the "Upload Plugin" section. Upload the the ghost-inspector.hpi plugin file.

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".

Add Ghost Inspector step in Jenkins

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.)

Configure Ghost Inspector step in Jenkins

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.

 

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]
Note: These settings assume that you want to execute a suite after your project has been built. For other options, please see our API.