Why You Should run TestProject agent inside Docker container?

Why You Should run TestProject agent inside Docker container?

Play this article

Docker with TestProject

Gone are the days when applications & it’s dependencies needed to be set up on different physical systems for developing, testing & making them available for the end users. The introduction of virtualizing hardware inside the same system broke away these constraints that had yet locked us in. But that too came at a price & many resources left untouched finally gave in to the concept of containerization.

In layman’s terms it’s simply the process of packing the software & its dependencies so the application runs quickly and reliably from one computing environment to another for Development, Shipment and Deployment.

Build, Ship & Share

Docker is the de facto standard to build, run and share containerized apps — from desktop, to the cloud. Docker uses a client-server architecture in the following way :

  • The Docker client talks to the Docker daemon, which does the heavy lifting of building, running, and distributing your Docker containers.
  • The Docker client and daemon can run on the same system, or you can connect a Docker client to a remote Docker daemon.
  • The Docker client and daemon communicate using a REST API, over UNIX sockets or a network interface.

Docker Objects :

When you use Docker, you are creating and using images, containers, networks, volumes, plugins, and other objects. This section is a brief overview of some of those objects.

  • images : An image is a read-only template with instructions for creating a Docker container. You can create your own image, using a Dockerfile with a simple syntax for defining the steps needed to create the image and run it, or build an image based on another image, with some additional customization.
  • containers : A container is a runnable instance of an image. You can create, start, stop, move, or delete a container using the Docker API or CLI. You can connect a container to one or more networks, attach storage to it, or even create a new image based on its current state.
  • services : Services allow you to scale containers across multiple Docker daemons, which all work together as a swarm with multiple managers and workers.

Docker Hub :

A Docker registry stores Docker images. Docker Hub is a public registry that anyone can use, and Docker is configured to look for images on Docker Hub by default. You can even run your own private registry.

Docker Compose

Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration. Compose is great for development, testing, and staging environments, as well as CI workflows. We will be leveraging Docker Compose towards the end of this tutorial where we will be starting a TestProject agent with headless Chrome and Firefox browsers.

Setting up a Docker Environment

Follow the instructions appropriate for your operating system to download and install Docker Desktop:

After you’ve successfully installed Docker Desktop, you can verify the Docker version by clicking on whale-icon on the top left of the screen and selecting “About Docker Desktop”.

Open a terminal and run docker — version to check the version of Docker installed on your machine.

  • $ docker version

Test that your installation works by running the hello-world Docker image:

  • $ docker run hello-world

Why do I need TestProject Agents running inside Docker containers?

Containers are a perfect companion to the agile movement. Organizations today need fast paced & efficient software teams & with that comes the hefty practice of continuous pushing of source code from development to testing & production multiple times. With Docker’s ability to isolate environments with specific dependencies & the flexibility to ship them from or to different environments makes the work more efficient & reliable.

Docker containers can accelerate your test automation platform using “dockerized” TestProject Agents. What makes the docker agent useful is that it saves a bunch of resources & provides the ability to run tests with just a simple command. For most cases you’ll need to set up the TP_API_KEY from the web console which is a way of authorizing the docker agent to an account. Optionally, you’ll need a Job id TP_JOB_ID if you want the containers to execute directly instead of waiting for instructions from the web UI.

You can set up the agent in two ways:

  • Giving signals to execute jobs right from the web UI.
  • Or providing dedicated tokens beforehand for seamless execution of jobs without the need for manual intervention.

Setting up TestProject Agents in Docker


  • All you need is a TestProject account, that’s it! If you don’t already have one, you can sign up and open your free account here.

The TestProject Agent docker container can be used in two distinct ways, as also described in our DockerHub page:

  • Permanent Execution Engine — The agent is registered once, and then can be used to execute tests and jobs from the TestProject web application
  • Ephemeral Instances — In this scenario the agent is started up in order to perform a specific task, and will self terminate upon completion of said task.

The operation mode of the agent is controlled by environment variables that are passed to the container upon creation.

Permanent Execution Engine

Let’s say you want to run multiple jobs & don’t want a fresh container for each test run. Your test capitalizes on a cache previously saved from a test run to continue further execution. Running tests from the start is a bit of an overkill even when using containers.

This is where instances that have saved states come into the picture.

The flexibility to resume or carry on jobs with the ability to save data can become crucial for any testing environment as the testing phase matures.

The Docker agent of TestProject comes with this feature built in. You can easily start images that run for indefinite time & you can save the data with the help of attached volumes in case a running container fails. To get started aforementioned we need the TP_API_KEY to grant access to the project & an TP_AGENT_ALIAS to set a custom name for the agent.

When starting an instance with these variables, the agent is automatically registered to the account. This name can be referred to if you want to view the agent in your account.

TestProject Agents

In order to run tests in a container we need an API key for authorization & a JOB ID to perform the specific tests. We can generate API keys through the console in the Integrations tab from the top bar.

Click on Integration > API > Create API key as shown below:

Click Create & enter a name. Clicking Next gives us the option to either allow access to all or particular projects. For now we’ll go for unrestricted.

Click “Finish”.

Copy the key, because we’ll need it when we’re creating the containers.

Next, it’s time to open a terminal and run the below command:

docker run — name testproject-agent \


-e TP_AGENT_ALIAS=”My First Agent” \

-v :/var/testproject/agent \


In the above CLI, one needs to pass the correct API_KEY. A volume can also be set up to store the images data for the persistence.Once you execute the above command, you will see the below output which depicts successful initialization of the TestProject agent.

By now, you should be able to get a TestProject agent registered. The is the IP address of Docker container running the agent.

Go to Docker Desktop UI > Dashboard > Select testproject-agent

TestProject Agent runs an Alpine based Docker container which you can verify by clicking on the “>_” option as shown above in the UI.

Running Test Jobs using Docker

One important aspect of test automation is being able to run the tests on a regular cadence. Often teams are interested in how the product quality looks as the code changes and so tests need to be run on some kind of schedule. TestProject provides you with the tools that you need to schedule and run tests by adding a job to your project.

To create a job, navigate to the project you want to add a job for and in the right hand panel click on the Add a job button.

Click on “Add a Job”. This will bring up the job creation wizard. Enter in a name and description for the job and click next. On the next page you can choose where you want the job to run. You can either run a mobile or web test and you can pick which agent you want to use to run the job. Make sure that you are selecting compatible agents for the kind of testing that you want to do. For example, if you want to run the job as a mobile android test, be sure to pick an agent that will have an android device attached.

For this example, I selected “Web”.

Enter a Name & Description followed by selecting the browser you want to run on. Since we’re running it on containers we’ll select headless.

Add the test you created earlier to the JOB & also copy it’s ID.

You can find Job ID by clicking on dots as shown in the below window.

In its current state the agent is idle & is waiting for a job to run. Let’s bring the container into action by sending it the job signal using Testproject’s Jenkins plugin.

The plugins available for installation from Manage Jenkins > Manage Plugins.

Using the API_KEY, you can link the plugin to your TestProject account seamlessly. All you need to do is to navigate to Manage Jenkins > Configure System & scroll down to TestProject Global Configuration, enter the APi_KEY & you’re good to go.

Create a Freestyle project under the build section add a build step with Run Testproject Job selected. The id’s can be found from the testproject’s web console.

2.Ephemeral Instances & Jenkins:

In order to have test environments that resemble production environments we can either configure it at the source code level, or have tests run on actual servers with the dependencies like db etc. installed.

The story at the source code level brings unwanted configurations to the code making it hard to maintain with newer updates & bug fixes. However running it on an actual hardware is also a burnout as stuff can get overwhelmed pretty quick, & comes with a lot of setup and maintenance overheads. Also since resources are shared among tests we can only run them one at a time to ensure they don’t interfere with each other’s executions.

Let’s have a look at Docker Compose which enables us to get the best of both worlds. It makes it easier to replicate the parts we have in environments & create them in the form of containerized solutions.We get the freedom to test in a real physical environment. Firstly the TestProject agent is responsible for handling the test cases with the given api_key & job_id. The Docker compose file also sets up multiple browsers to run the tests on. After running the test it exits so that any cache left is cleared. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration.

Create a File with the .yaml extension with the following configuration :

version: “3.1”
image: testproject/agent:latest
container_name: testproject-agent3
 — chrome
 — firefox
TP_AGENT_ALIAS: “Docker Agent”
TP_JOB_PARAMS: ‘“jobParameters” : { “browsers”: [ “chrome”, “firefox” ] }’

CHROME: “chrome:4444”
FIREFOX: “firefox:4444”
image: selenium/standalone-chrome
 — /dev/shm:/dev/shm
image: selenium/standalone-firefox
 — /dev/shm:/dev/shm

You can download YAML file directly from https://gist.github.com/ajeetraina/57334e044d1d6bf5af28b502010618e2

This docker-compose snippet spins up 3 containers:

  1. TestProject Agent
  2. Standalone selenium with pre-installed Chrome
  3. Standalone selenium with pre-installed Firefox

The TestProject Agent will automatically detect the Chrome & Firefox containers.By setting the TP_API_KEY & TP_JOB_ID environment variables we instruct the Agent to automatically start executing the requested job on startup. By setting the TP_JOB_PARAMS environment variable we override the execution targets for this job to include both Chrome & Firefox browsers.

In a nutshell the above configuration starts a container(testproject/agent) that is connected to your testProject.io account & with the help of the browser containers runs the test-jobs.

[Captains-Bay]🚩 > docker-compose ps

Name Command State Ports

— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — — -

testproj_chrome_1 /opt/bin/entry_point.sh Up 4444/tcp

testproj_firefox_1 /opt/bin/entry_point.sh Up 4444/tcp

testproject-agent3 /bin/sh /opt/testproject/a … Up

[Captains-Bay]🚩 >

Let’s set up a Docker compose file to run from a Jenkins pipeline. With the Docker testproject jenkins plugin we can run tests directly from the pipeline enabling a seamless CI set up. Here’s a sample jenkinsfile that pulls & runs a nodejs application that initiates the test on the containers via the testproject plugin & cleans up in the end.

I assume you have already installed NodeJS plugin for this specific scenario.

pipeline {

agent any

stages {

stage(‘Build’) {

steps {

// Get some code from a GitHub repository

git ‘github.com/collabnix/testproject.git'



stage(‘Run’) {

steps {

sh “node index.js &”



stage(‘Test’) {

steps {

tpJobRun agentId: ‘ph3CXXXXXXXX’, jobId: ‘o7wS4nXXXXXXX’, projectId: ‘DzkGyzxkMXXXXXXXX’, waitJobFinishSeconds: 180

sh “killall -9 node”





Link: https://github.com/collabnix/testproject/blob/master/Jenkinsfile


Hence we saw that Docker makes it quite simple to start a TestProject Agent with headless Chrome & Firefox browsers using a simple Docker compose file. In our next blog post, we will see how TestProject can be integrated with Kubernetes in a much easier way.


[ This blog was originally published under https://blog.testproject.io/2020/05/30/the-ultimate-docker-tutorial-for-automation-testing-using-testproject/]

Did you find this article valuable?

Support Collabnix by becoming a sponsor. Any amount is appreciated!