Executing Tests on Local and Firewalled Websites

Want to use Ghost Inspector locally? Here are some options.

Search our documentation:

Toggle Documentation Menu

Executing Tests on Local and Firewalled Websites

Note: The method for local testing below involves a 3rd party tool that opens up a public URL to your website. Ghost Inspector is not directly associated with this tool. Before implementing this approach at your company, we recommend consulting your network administrator.
Jump to...

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 [TOKEN-HERE]

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 80

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.

Note: Each time you restart ngrok, a new URL will be provided. You can use the “Run with Custom Settings…” option in our application to quickly override your test(s) start URL with this new ngrok.io URL:
Run Test with Custom Settings... Run Test with Custom Settings...

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:

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