Executing Tests on Local and Firewalled Websites

Table of Contents

• Test manually
• Using our CLI
• Using Docker locally
• Using Docker with a hostname

Test manually

Ghost Inspector can access local and firewalled websites through the use of ngrok. ngrok is a tool that exposes a local port to the internet via a secure tunnel. That tunnel can be used to allow Ghost Inspector to access your website and test it. You will need to sign up for a free ngrok account, then download and unzip the program.

Once you have ngrok downloaded and unzipped, you will need to set your authentication token which is available in your ngrok account. (You’ll only need to do this once.)

$ ./ngrok authtoken {{my-ngrok-token}}

Now, there are two difference scenarios. Either the website is running locally on your machine (localhost), or it’s running on a private server (with it’s own URL).

If the website is running locally on your machine, you will need to know which port it’s being served on. This is typically port 80, but may be something different (for instance, if your website is visible at http://localhost:3000, then the port is 3000). To open the tunnel, execute this command (with the port number swapped in):

$ ./ngrok http 3000

If the website is running on a private server then you are likely using a URL like http://private.mycompany.com to access it. In this case, you’ll create a tunnel to that URL using this command (with the private server URL swapped in):

$ ./ngrok http -host-header=rewrite private.mycompany.com:80

Once ngrok opens the tunnel, it’ll provide a public ngrok.io URL (ex: https://0b99c72f.ngrok.io) which can be used for your test(s) start URL. If you open this ngrok.io URL in your browser, you’ll see the website. However, this copy is accessible to Ghost Inspector. Simply record your tests using this ngrok.io URL and Ghost Inspector will be able to access your website and execute them.

You can exit the ngrok process at anytime to disconnect the tunnel. When you wish to run your Ghost Inspector tests again, start ngrok back up using the same command above.

Using our CLI

We also offer a Command Line Interface (CLI) that can simplify the process of interacting with Ghost Inspector services. Visit the CLI documentation for different installation options.

Once you have your CLI installed, grab your API key (Settings > User Account > Details) and your ngrok token and run the following command to execute your suite:

ghost-inspector suite execute {{suite-id}} \
  --apiKey {{my-api-key}} \
  --ngrokTunnel localhost:3000 \
  --ngrokUrlVariable startUrl \
  --ngrokToken {{my-ngrok-token}}

This example includes a couple options:

• Your Ghost Inspector API key is set with --apiKey.
• The local application is running on localhost:3000.
• The parameter --ngrokUrlVariable sets the tunnel URL to the variable startUrl (ngrokUrl by default).

Using Docker locally

It is possible to execute a test suite against your local application using our standalone Docker image ghostinspector/test-runner-standalone. This is accomplished through the use of the --network host flag when running the container. This flag will instruct Docker that the new container should be run using the host network which will allow ngrok to properly access your application. Assuming you are running your app locally on port 3000, your Docker command should look like this:

$ docker run \
    -e NGROK_TOKEN={{my-ngrok-token}} \
    -e GI_API_KEY={{my-api-key}} \
    -e GI_SUITE={{my-gi-suite}} \
    -e APP_PORT=3000 \
    --add-host "localhost:{{my-local-ip-address}}" \
    --network host \
    ghostinspector/test-runner-standalone

Make note to replace the values for my-ngrok-token, my-api-key, my-gi-suite, and make sure my-local-ip-address is the IP of your computer. Once executed, the Docker container will establish a tunnel using ngrok to the local computer on port 3000 and execute your Ghost Inspector test suite.

Using Docker with a hostname

Sometimes you have a scenario where your application is configured to only listen on a specific hostname, for instance if you're using a specific Nginx config such as:

server {
    listen       80;
    server_name  www.example.org  www.example.local;
    ...
}

This can be used sometimes to allow the server to respond to requests in both production and local environments. In this case, simply forwarding a ngrok tunnel to the IP of the host will only result in a blank response (or an error). We can still utilize ghostinspector/test-runner-standalone with a little extra configuration at runtime:

$ docker run \
    -e NGROK_TOKEN={{my-ngrok-token}} \
    -e GI_API_KEY={{my-api-key}} \
    -e GI_SUITE={{my-gi-suite}} \
    -e APP_PORT="--host-header=rewrite www.example.local:80" \
    --add-host "www.example.local:{{target-ip-address}}" \
    --network host \
    ghostinspector/test-runner-standalone

Here we utilize the --network host setting again, and we also have a couple customizations:

• -e APP_PORT="--host-header=rewrite www.example.local:80" - here we're actually injecting a little bit of extra information into the parameters we pass to ngrok which tell it to pass along a host header of www.example.local with each request.
• --add-host "www.example.local:{{target-ip-address}}" - here we tell Docker to add a host entry for www.example.local as well as specify the IP where that host can be found. Make sure you customize the IP to the address of the machine serving the application, whether it be your local IP or otherwise.

Once executed, the Docker container will establish a tunnel using ngrok to www.example.local:80 and execute your Ghost Inspector test suite.