Bamboo Server

Ghost Inspector test suites can be executed inside your Bamboo Server builds by leveraging the Ghost Inspector CLI. This tutorial will show you how you can run Ghost Inspector suite against an application running on your Bamboo Server.

Table of Contents

Environment configuration

Before getting started you should set up a few environment variables for your plan. At a minimum you should have:

Bamboo Server job environment configuration

Note that we've prepended SECRET_ to the first two environment variables to let Bamboo know that they should be treated as sensitive.

Node.js Example

Note: This example assumes your build agent has the Node.js capability.

The simplest way to execute a suite from your build step is with our CLI. To do this, add a Script task to your build stage:

Add a Script task to Bamboo Server build stage

Give your task a description and set the intepreter to Shell. Here's an example script that will install our CLI and execute a suite, drop this into the Script body:

# Install the CLI
npm install ghost-inspector

# Execute the suite
npx ghost-inspector suite execute ${bamboo.SUITE_ID} \
  --apiKey ${bamboo.SECRET_apiKey} \
  --region ap-northeast-2
  --errorOnFail

If you are executing against an application already running Bamboo agent from an earlier step, you can also create a local VPN tunnel using --ngrokTunnel. See our CLI docs for more details.

Linux Example

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

If you do not have Node.js installed but you are building within a Linux-like environment, you can still download and execute a suite using our standalone CLI binary. Again use the Script task type for this build example.

This example script will pull down the latest release of our CLI binary for Linux systems and execute the same suite in Ghost Inspector:

# Download the CLI
curl -sL https://github.com/ghost-inspector/node-ghost-inspector/releases/latest/download/ghost-inspector-linux \
  --output ./ghost-inspector

# Make it executable
chmod +x ghost-inspector

# Execute the suite
./ghost-inspector suite execute ${bamboo.SUITE_ID} \
  --apiKey ${bamboo.SECRET_apiKey} \
  --browser firefox
  --ngrokTunnel localhost:8080
  --ngrokUrlVariable startUrl
  --ngrokToken ${bamboo.SECRET_ngrokToken}
  --errorOnFail

Note that this example includes the VPN parameter --ngrokTunnel and related details required to test against a locally-running application.

Docker Example

Note: This example assumes your build agent has the Docker capability

This example will demonstrate how to add a build task running a detached application, and then execute a Ghost Inspector suite against that application in a subsequent step.

Running the application

The first task in the build process is going to start the application under test. For this example the application is already containerized using Docker, so add the Docker task to your build:

Add the Docker build task

Here are the details of the task configuration:

Docker run application task configuration

Let's break this down since there's so much going on:

Task description
Name this something simple, but descriptive to the task like Run my app.

Give the task a description for your application

Command
For the Docker command use Run a Docker container.

Select the Docker command - Run a Docker container

Docker image
This example is using a test image ghostinspector/standalone-app, but you will likely be using the name of the image that you've built in a previous step. It is also important to select the option Detach container. This will instruct Bamboo to run the container in the background so that it will still be accessible from a later build step.

Set the Docker image to run

Container name
Set the container name to something appropriate. This example uses the built-in variable ${bamboo.buildNumber} to make the container name unique.

Give this new container a unique name

Port mappings
This option is not necessary in order to execute your Ghost Inspector suite, however you can use it with the next option to ensure that your application is responding to requests prior to starting the test suite. Without this step you may have mixed results when attempting to start the local VPN tunnel.

Here the port 8080 is bound to the host:

Set a port mapping to test for requests

Wait for service to start
This is useful if you have an application that needs a moment to fire up and will prevent the build task from continuing until it responds at the specified location.

With the port for your application opened with the last option, check the option for Wait for the service to start. Bamboo provides the shortcut variable ${docker.port} for accessing the first opened port, so the application should now be accessible at the location http://localhost:${docker.port}, add that to the field Service URL pattern.

Also set the Service timeout to an approprite value.

Set a port mapping to test for requests

Working directory
Bamboo also sets a default working directory of /data, so adjust that value or remove it according to your application.

Executing the suite

To execute your suite, add another Docker task. Here is an example configuration that will execute a suite against the application running in the previous task:

Docker execute suite task configuration

Again, here is the breakdown:

Task description
Name this task Execute suite.

Give the execute suite task a description

Command
Again for the Docker command use Run a Docker container.

Select the Docker command - Run a Docker container

Docker image
To make utilizing our CLI more convenient, we provide the ghostinspector/cli image for use within a Docker environment, specify that for the Docker image input.

Set the Docker image to run

Link to detached containers
Check this box to show the list of available detached containers. You should see the previous container my-app-${bamboo.buildNumber} in the list. You will need this value shortly for the CLI configuration (below).

Select link to detached containers

Container environment variables
Pass in the variable GHOST_INSPECTOR_API_KEY=${bamboo.SECRET_apiKey}. This can also optionally be set in the next step using --apiKey.

Select link to detached containers

Container command
Use the following example for the Container command field. This is the parameters that will be passed to the CLI on execution:

suite execute ${bamboo.suiteId}
  --ngrokTunnel my-app-${bamboo.buildNumber}:8000
  --ngrokUrlVariable startUrl
  --ngrokToken ${bamboo.SECRET_ngrokToken}
  --errorOnFail

Note that --ngrokTunnel points to the location of the previous container my-app-${bamboo.buildNumber}:8000. The VPN tunnel by default will send in the variable {{ ngrokUrl }} which represents the location of the tunnel, however here the value has been changed with --ngrokUrlVariable to {{ startUrl }}. The secret --ngrokToken is passed in, and lastly --errorOnFail is specified to instruct the command to return a non-zero status code if the suite fails which will signal Bamboo to fail the build task.

Wrapping up

From here, execute your first build by clicking Run > Run plan and wait for your build status to update or check out your build log to follow status updates.