Docker

Table of Contents

• Getting started

• Base Image (node.js)

  • Video Tutorial
  • Dockerfile
  • Environment variables
  • CMD
  • Firing up

• Standalone image

  • Setting up the network
  • Start the application
  • Execute the test suite

• Command Line Interface (CLI) Image

  • Execute a suite
  • Execute with VPN tunnel to local application

• Wrapping up

Getting started

Before we get started we are going to need the following:

• An account with ngrok.io, a free utility used for local tunneling. You will need the auth token provided in your account.
• Docker installed in your local or test environment.

We offer two different Docker images to aide in testing your containerized app:

• Base image (ghostinspector/test-runner-node) - image for testing your application within a single Docker container.
• Standalone image (ghostinspector/test-runner-standalone) - standalone image for testing within an existing Docker cluster.

Base Image (node.js)

Video Tutorial

The base image test runner is designed for you to extend with your source files for the purpose of testing your application. This can be useful if you have a fairly simple Docker setup or are working in a CI environment that does not support multi-container Docker (such as Bitbucket Pipelines). The image includes all the utilities and scripts needed to execute your Ghost Inspector test suite against your Node.js application.

Dockerfile

Let’s have a look at an example Dockerfile:

FROM ghostinspector/test-runner-node

# Copy your source code
COPY . .

# Install your app
RUN npm install .

# Configure the test runner
ENV APP_PORT 3000
ENV GI_API_KEY <ghostinspector-api-key>
ENV GI_SUITE <ghostinspector-suite-id>
ENV GI_PARAM_myVar some-custom-value
ENV NGROK_TOKEN <your-ngrok-token>

# Pass your application entrypoint into our test runner script
CMD ["index.js"]

This Dockerfile simple extends our ghostinspector/test-runner-node image, copies our application files, and installs the application. Next we will need to adjust the environment variables for the test runner to execute properly, and then adjust our CMD accordingly.

Environment variables

In order for this image to successfully interact with your application we will need to provide some configuration at runtime, either for the test running script, or for your Ghost Inspector test suite.

Some of the environment variables are required:

• APP_PORT - tells the test running script which port your application is running on.
• GI_API_KEY - available in your Ghost Inspector account.
• GI_SUITE - the ID of the Ghost Inspector test suite you wish to run against your app.
• NGROK_TOKEN - available from your ngrok account
• STARTUP_DELAY (optional) - seconds to wait for application and ngrok each to start up, defaults to 3 seconds.
• GI_PARAM_myVar (optional) - additional URL parameter to send to our API, the value of which will be accessible in your test under myVar. You may include additional variables required by your tests.

Note that all environment variables will also be available to your application in the process.env object.

CMD

The last line of our Dockerfile is going to be the CMD. This should be the Node.js entrypoint of your application, in our case it looks like:

CMD ["index.js"]

Note that it could be server.js or myapp/start.js or whatever Node.js script fires up your app, as long as it is a Node.js file.

Also, if you require additional parameters on startup, you are not restricted by the number of parameters that you pass into CMD:

CMD ["index.js", "--sky=blue"]

Any additional parameters past the index.js position will be passed to your application when it is started up.

Firing up

Now, assuming everything is configured correctly, we should be able to build and run our container and watch it’s progress:

$ docker build -t my-app .
$ docker run my-app

The container will now start your application, open a tunnel using ngrok, and execute your Ghost Inspector suite via the API using the API key and suite ID you’ve provided, along with any custom parameters defined in the Environment Variables.

Continue to the next section to learn about executing your test suite within a more complex Docker environment.

Standalone image

This Docker image will allow you to execute your Ghost Inspector test suite against another running Docker container within your cluster by using Docker container networking.

First, pull down the ghostinspector/test-runner-standalone image to your local environment:

$ docker pull ghostinspector/test-runner-standalone

Setting up the network

Next we will create a new network in Docker-land so we can link the applications at runtime:

$ docker network create my-test-network

This will create a network that we can attach to our Docker containers at runtime to give them the ability to communicate privately.

Start the application

Then we can start your application in the background (-d), noting that {{my-image}} will need to be changed to the name of your application Docker image:

$ docker run -d --name my-app --network my-test-network {{my-image}}

Here we have named the new container my-app and connected it to the network my-test-network.

Execute the test suite

Once that’s up and running, we can fire up the Ghost Inspector test-runner-standalone image which will run our suite against our running app:

$ docker run \
  -e NGROK_TOKEN={{my-ngrok-token}} \
  -e GI_API_KEY={{my-api-key}} \
  -e GI_SUITE={{my-suite-id}} \
  -e GI_PARAM_myVar=foo \
  -e APP_PORT=my-app:8000 \
  --network my-test-network \
  ghostinspector/test-runner-standalone

Make sure you change out all the environment variables to your own custom values for NGROK_TOKEN, GI_API_KEY, and GI_SUITE. Notice that for APP_PORT we’ve passed in my-app:8000, my-app will resolve to our running docker container that we named my-app and 8000 assumes that is the port that our application is running on. Finally we also connect this new container to the same my-test-network so all the DNS and networking magic can happen. Also note that you can send custom variables to the API call when we execute your test suite by using a custom environment variable named GI_PARAM_varName where varName is the name of your variable. This will be available in your Ghost Inspector tests under {{varName}} at runtime.

Once this container fires up, it will perform the exact same set of actions as before:

• Start the ngrok daemon and open a tunnel to my-app:8000.
• Execute the Ghost Inspector test suite based on GI_SUITE.
• Poll the Ghost Inspector API for passing status until a result is provided.
• Exit with the pass (0) or fail (1) status.

Command Line Interface (CLI) Image

Ghost Inspector provides another convenience image that comes pre-bundled with our Command Line Interace. This is provided as an alternative if you don't have the ability to install Node.js or NPX natively but still want to utilize our CLI.

Here are some example commands:

Execute a suite

This example will execute a suite with a few custom parameters:

$ docker run ghostinspector/cli suite execute {{my-suite-id}} \
  --browser firefox \
  --startUrl "https://my-website.com" \
  --myVariable 12345 \
  --apiKey {{my-api-key}}

In the above command, make sure to substitute the values for {{my-suite-id}} and {{my-api-key}} with your own values from your account. The additional parameters specified are:

• Set the executing --browser to the latest version of firefox.
• Set the --startUrl for this execution to https://my-website.com.
• Set a custom variable --myVariable to the value 12345 for all tests in this execution.

Execute with VPN tunnel to local application

Here's another example of how to utilize the VPN feature of the CLI to execute a test against an application running locally:

$ docker run --network host ghostinspector/cli \
  test execute {{my-test-id}} \
  --ngrokTunnel host.docker.internal:8000 \
  --ngrokUrlVariable startUrl \
  --ngrokToken {{my-ngrok-token}} \
  --apiKey {{my-api-key}}

There are a few details here that are worth studying:

• To enable container to access the host, we set the --network mode to host.
• To configure the VPN we need to provide the parameter --ngrokTunnel and provide the value host.docker.internal which is a special value within your Docker container that will resolve to the host IP address. This example also assumes our application is running locally on port 8000.
• We use --ngrokUrlVariable to tell the VPN config to assign the tunnel URL to the variable startUrl for our test.

Additionally in this example, don't forget to swap out {{my-test-id}}, {{my-ngrok-token}} and {{my-api-key}} with your own values.

Wrapping up

That’s it! If everything went well you should be able to visit your dashboard and check on the status of your test suite.

If you run into issues setting up this tutorial, or any other problems with our product, feel free to drop us a line in support and we’ll be happy to answer any questions for you.