GitHub Actions

Table of Contents

• Prerequisites

• Test against public URL

• Docker configurations

  • Base image example (ghostinspector/test-runner-node)
  • Standalone image example (ghostinspector/test-runner-standalone)

• Manual script configuration

Prerequisites

It is generally recommended to set up your test execution parameters as GitHub secrets, which can then be used environment variables in your actions. The examples below will be using the GitHub secrets syntax (${{ secrets.[SECRET_NAME] }}) for sensitive information like the following:

• GI_API_KEY - available in your Ghost Inspector account.
• GI_SUITE or GI_TEST - the ID of the Ghost Inspector suite/test you wish to run against your app.
• NGROK_TOKEN - (optional) Ngrok is a free service that can provide secure SSH tunnels to our local environment. Your Ngrok token is available from your ngrok account

The examples below start at the jobs portion of a GitHub Action workflow. If this is your first action, be sure to include something like the following at the top of your workflow:

.github/workflows/main.yml

name: GI
on:
  push:
    branches: [stable]
  pull_request:
    branches: [stable]

Read more about Configuring a workflow in the official GitHub Help.

Test against public URL

If your GitHub action deploys to a publicly available URL, the simplest way to integrate Ghost Inspector is to use curl to execute a test or a suite.

.github/workflows/main.yml

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: deploy to staging
        run: npm run deploy
      - name: execute Ghost Inspector test
        env:
          GI_API_KEY: ${{ secrets.GI_API_KEY }}
          GI_TEST: ${{ secrets.GI_TEST }}
          START_URL: https://your-staging-url
        run: curl "https://api.ghostinspector.com/v1/tests/$GI_TEST/execute/?apiKey=$GI_API_KEY&startUrl=$START_URL"

Docker configurations

There are 2 different Docker images available for use with GitHub, ghostinspector/test-runner-node and ghostinspector/test-runner-standalone. Use the node image if you have a simple Node.js application that you would like to test using Ghost Inspector. Use 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)

.github/workflows/main.yml

jobs:
  test:
    runs-on: ubuntu-latest
    container: ghostinspector/test-runner-node
    steps:
      - uses: actions/checkout@v2
      - name: install dependencies
        run: npm install
      - name: execute Ghost Inspector suite
        env:
          GI_API_KEY: ${{ secrets.GI_API_KEY }}
          GI_SUITE: ${{ secrets.GI_SUITE }}
          NGROK_TOKEN: ${{ secrets.NGROK_TOKEN }}
          APP_PORT: 3000
        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.

.github/workflows/main.yml

jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: node:12-alpine
      # this will be used by the Ghost Inspector container
      options: --network-alias node-app
    steps:
      - uses: actions/checkout@v2
      - name: install, build, and run app
        run: |
          npm install
          npm run build
          npm start &
      - name: execute Ghost Inspector suite
        env:
          GI_API_KEY: ${{ secrets.GI_API_KEY }}
          GI_SUITE: ${{ secrets.GI_SUITE }}
          NGROK_TOKEN: ${{ secrets.NGROK_TOKEN }}
          # this uses the network-alias defined in the container options
          APP_PORT: node-app:3000
        uses: docker://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 a build script that interfaces with the ngrok and Ghost Inspector APIs directly. Use the example build script in our CircleCI integration docs as a starting point. Below is an example of how you would use the build script in GitHub actions specifically.

.github/workflows/main.yml

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Execute test
        run: bash build.sh