Integrate web-testing into CircleCI jobs with Trakr

CircleCI is a popular continuous integration platform that can be used to test and deploy a variety of applications. In this post, we will focus on a simple example of how to integrate Trakr visual testing with CircleCI. This will also be useful if you are looking to perform web-testing with your Circle CI builds.

Before you start, we recommend that:

1. You have a general knowledge of CircleCI and it’s configuration structure, references.
2. You have some basic knowledge with Linux/Debian shell commands, etc.

The steps

The steps to run Trakr tests in CircleCI are:

1. Create your web project build (Assuming you already have this in your CircleCI configuration).
2. Expose your web build to the outside world so it can be accessed by Trakr or other web-testing tools.
3. Run Trakr tests

See the gist below for the complete configuration file for CircleCI (Version 2.1)

https://gist.github.com/xcf33/3d9ccefa5cec031d5fde2caf241103c1

Alternatively, you can reference the configuration file for CircleCI version 2 (slightly different)

Before we start

There are two environment variables that we want to set up (Under project -> build settings in CircleCI) in order to run Trakr tests. We set them in the CircleCI user interface rather than in the configuration file for security purposes.

Project build settings.

• TRAKR_API_TOKEN — You can find this under your user account

API TOKEN

• TRAKR_PROJECT_ID — It should be a numerical ID of the Trakr Project you have created, you can find this under your project settings — developer/API tab

1. Creating the web project build

In this simple example, our project repository is a static website with a number of HTML files and other static assets.

Sample project repository (https://github.com/trakrtest/circle-test)

For our web build, we are using a simple LAMP docker image. You can easily use different images and different web-development technology for your project (e.g. node, ruby, python, etc. See a list of pre-built images from CircleCI https://circleci.com/docs/2.0/circleci-images/) as well as adding other images for database connections, etc depending on your project complexity.

executors:  
  lamp:    
    docker:      
      - image: circleci/php:7.1-apache

We are also declaring some environment variables in the configuration

environment:       
  TRAKR_BASE_ENV: production       
  TUNNEL_PORT: 80

• TRAKR_BASE_ENV — This is the (Trakr) base environment which we test the web build against in Trakr. It normally defaults to a production environment or staging.
• TUNNEL_PORT — The local port which your web build server runs on. For web-based apps, it can be 80, 8080, 443 (https) and in some cases 3000 (for Node JS). We will perform port forwarding in later steps from the local server port to the outside world.

Lastly, our web build is relatively simple, we simply check out the project repository and copy them into the default Webhost root directory and start the webserver so the static website runs locally.

- checkout       
- run: sudo cp -r ~/project/* /var/www/html/       
- run: sudo /etc/init.d/apache2 start

Again, our web build example is extremely simple for illustration purposes, you probably will have a more complex build process. However, the end result should be that you have your web-build running on the localhost at some port.

2. Expose your web build with port forwarding

Port forwarding allows us to “forward” all the web traffic from the specific port within your CircleCI build to the world and temporarily provide access for outside tools to access your web build. This is a common method used for local development and testing of service webhooks.

There are a number of tools available to do this, namely:

• Localtunnel (https://localtunnel.github.io/www/)
• Ngrok (https://ngrok.com/)

In this example, we will be using localtunnel because it is completely free and does not need any signups or registration.

- run: sudo apt-get update       
- run: sudo apt-get install curl software-properties-common       
- run: curl -sL https://deb.nodesource.com/setup_10.x | sudo bash -       - run: sudo apt-get install nodejs       
- run: sudo npm install -g localtunnel

We install Node JS (LTS) and use the node package manager (NPM) to install localtunnel. However, if you are already using a Node JS based environment, you can simply run the last step to install localtunnel directly.

- run: sudo git clone https://github.com/makehero/trakr_circleci.git $HOME/trakr_circleci       
- run: cd $HOME/trakr_circleci && sudo npm install

We also clone the Trakr testing script and other utilities in preparation to start the tunnel.

- run:           
  name: Start tunnel           
  command: sh $HOME/trakr_circleci/start_tunnel.sh             
  background: true

Finally, we start the tunnel and run it in the background so that we can move on to performing the test while the tunnel is established in the background.

Now your web-build will be accessible via trakr-project-$TRAKR_PROJECT_ID.localtunnel.me where the $TRAKR_PROJECT_ID is an environment variable we set in CircleCI user interface (See instruction prior to step 1)

(Note: we are using a shell script to run the tunnel in order to keep it persistent. Due to the unpredictable volume to the localtunnel.me server, the tunnel can error out easily).

3. Run Trakr tests

Finally, we execute our testing script with the exposed URL from our tunnel. The script will run until the test finishes before closing the tunnel and the CircleCI job altogether.

- run:          
  name: Perform test          
  command: BUILD_URL=https://trakr-project-$TRAKR_PROJECT_ID.localtunnel.me node $HOME/trakr_circleci/test.js

Running this workflow in CircleCI

The tunnel fails periodically as we noted earlier. However, we restart the process when it fails in order to keep it persistent.

Running the tests

Our test will query the visual test created on Trakr (every minute) and make sure it is complete before exiting the step.

Finally, when the test is complete, we store a link to the Trakr visual test as part of the job artifacts.

Final thoughts

1. Default localtunnel server sometimes can be unreliable as noted in (https://github.com/localtunnel/localtunnel/issues/258). One of the alternatives could be to set up your own localtunnel server (https://github.com/localtunnel/server)
2. Our port forwarding (tunneling) steps and testing steps are all part of the single “build” job because of the tunnel’s need to access the web-build. At the same time, there is a mutual dependency between the tunnel steps and testing.