Setting Up Testsigma Agent Locally

With Testsigma Agent you can run tests on local machines/devices in addition to Testsigma Cloud. This article discusses how to set up the Testsigma agent on your local machine.

Download Formats Available

The Testsigma Agents are available in the following forms:

1. ZIP files
2. Executable files
3. DMG files
4. Docker image

Steps to Download Testsigma Agent as a ZIP File

1. Navigate to Agents and click Download Agent.
2. From the dropdown that appears, download the ZIP file as per your machine.

3. After downloading the agent ZIP file, extract the Testsigma Agent ZIP file to a location of your choice. Some suggested locations to place the Testsigma agent folder are mentioned in the table below:
   

   Operating System	Preferred Agent location
   Windows	C:\Users<your_username>\
   Mac	/Users/<your_username>/
   Linux	/Users/<your_username>/

   Replace the <your_username> part with your account username.

   The home directory is recommended so as to avoid hassles of setting file permissions and ownership and also to avoid file corruption due to syncing with iCloud or Google Drive.

You can either start the Testsigma agent server as a process via the command line or terminal when needed. Or, you can run the Testsigma agent server as a server. For more information, refer to the below sections to see how to start the Testsigma Agent as a process or as a service.

Steps to Download Testsigma Agent as Executable File

1. Navigate to Agents and click Download Agent.

2. From the dropdown that appears, select the executable file supported by your machine.

   • For Windows, select exe,
   • For mac, select dmg,
   • For Linux, select bin to download the latest version of Testsigma Agent.
3. Double click on the downloaded file.
4. Choose the path where you would like to install the agent.
5. Let the installer run till completion.

Once the installation is complete, you can either run the Testsigma Agent server as a process via the command line/terminal when needed.

Start the Testsigma Agent Server as a Process

For Windows

1. Navigate to the Testsigma Agent installation folder and double click the start.bat or run start.bat in the command line file to start the Testsigma Agent.
2. Wait for a few minutes for the Testsigma Agent to start up.
3. After starting up you will be directed to the agent registration page.

For Mac/Linux

1. Navigate to the Testsigma Agent installation folder and drag start.sh to a new terminal window and click on Return.
2. Wait for a few minutes for the Testsigma Agent to start up.
3. After starting up you will be directed to the agent registration page.

For more information on how to register Testsigma Agent, see Register the Testsigma Agent.

Start the Testsigma Agent Server as a Service

1. For Windows: Go to the command line. For Mac/Linux: Go to the terminal.
2. Navigate to the Testsigma Agent installation folder.
3. Inside the Testsigma Agent installation folder, navigate to Wrapper > Bin.
4. For Mac/Linux, if you want to install the agent as a service, use the command TestsigmaAgent start.
5. For Windows, if you want to install the agent as a service, use the command TestsigmaAgent install.

6. To stop the service, run the command - TestsigmaAgent stop from the same location.

Commands that work with TestsigmaAgent:

console      Launch in the current console.
start        Start in the background as a daemon process.
stop         Stop if running as a daemon or in another console.
restart      Stop if running and then start.
condrestart  Restart only if already running.
status       Query the current status.
install      Install to start automatically when system boots.
installstart Install and start running as a daemon process.
remove       Uninstall.
dump         Request a Java thread dump if running.

Register the Testsigma Agent

1. Once your Testsigma agent is up and running, you will be directed to the Agent Registration page. Click Register to start the registration process.

2. On the Add new Agent dialog,

   • Enter a Name for your machine.
   • Specify the maximum sessions in the textbox provided.
   • To set your agent’s visibility, select either the Public or Private radio button.
   • For agent activation, choose either Activate now or Activate later.
   • Click on Register & Activate
3. Once the agent registration is successful, the dialog will display a success message..
4. On the Agents page, the agent you registered will be displayed along with all the available browsers on that agent machine.

It might take a couple of minutes for the operating system version and the browser names to appear. Refer to the troubleshooting guide if the details does not show up after 10 minutes.

Run Testsigma Agent Using Docker

There are two ways of starting the testsigma local agent using docker:

• Create an Agent in Testsigma application, obtain the Activation Key, and use it to register the agent while the Docker container is booting.
• Create and register a New Agent entirely while booting the Docker container.

1. Once the Agent is registered, navigate to Agents > select the agent > Config, and copy the Activation Key.
2. Create a docker-compose.yml file with TS_ACTIVATION_KEY environment variables.

The following docker-compose snippet can be used to start a Testsigma Agent with headless Chrome, Firefox & Edge browsers:

version: "3.9"
services:
  testsigma-agent:
    image: testsigmainc/testsigma-agent:latest
    container_name: testsigma-agent
    depends_on:
      - chrome
      - firefox
      - edge
    volumes:
      - ./data/agent_data:/var/ts/agent
      - ./data/agent_temp:/tmp/agent_temp
      - ./<foldername>:/root/.testsigma/agent/logs
    environment:
      TS_ACTIVATION_KEY: "REPLACE_WITH_YOUR_ACTIVATION_KEY"
      CHROME: "http://chrome:4444"
      FIREFOX: "http://firefox:4444"
      EDGE: "http://edge:4444"
      
  chrome:
    image: selenium/standalone-chrome:latest
    shm_size: 1gb
    ports:
      - "4444:4444"
    volumes:
      - ./data/agent_temp:/tmp/agent_temp

  firefox:
    image: selenium/standalone-firefox:latest
    shm_size: 1gb
    ports:
      - "4445:4444"
    volumes:
      - ./data/agent_temp:/tmp/agent_temp
     
  edge:
    image: selenium/standalone-edge:latest
    shm_size: 1gb
    ports:
      - "4446:4444"
    volumes:
      - ./data/agent_temp:/tmp/agent_temp

This docker-compose snippet spins up four containers:

1. Testsigma Agent
   
2. Standalone Selenium with pre-installed Chrome
   
3. Standalone Selenium with pre-installed Firefox
   
4. Standalone Selenium with pre-installed Edge

Testsigma Agent will detect browser versions through the Environment Variables CHROME, FIREFOX, and EDGE. Note that these Environment Variables are all optional.


If you plan to run your test solely on the Chrome browser, there's no need to specify the FIREFOX and EDGE environment variables. Here's an example docker-compose file:

version: "3.9"
services:
  testsigma-agent:
    image: testsigmainc/testsigma-agent:latest
    container_name: testsigma-agent
    depends_on:
      - chrome
    volumes:
      - ./data/agent_data:/var/ts/agent
      - ./data/agent_temp:/tmp/agent_temp
      - ./<foldername>:/root/.testsigma/agent/logs
    environment:
      TS_ACTIVATION_KEY: "REPLACE_WITH_YOUR_ACTIVATION_KEY"
      CHROME: "http://chrome:4444"

  chrome:
    image: selenium/standalone-chrome:latest
    shm_size: 1gb
    ports:
      - "4444:4444"
    volumes:
      - ./data/agent_temp:/tmp/agent_temp

If your system lacks sufficient resources, you can distribute browser containers across multiple systems and specify a remote debugging URL. Here's an example docker-compose file:

version: "3.9"
services:
  testsigma-agent:
    image: testsigmainc/testsigma-agent:latest
    container_name: testsigma-agent
    volumes:
      - ./data/agent_data:/var/ts/agent
      - ./data/agent_temp:/tmp/agent_temp
      - ./<foldername>:/root/.testsigma/agent/logs
    environment:
      TS_ACTIVATION_KEY: "REPLACE_WITH_YOUR_ACTIVATION_KEY"
      CHROME: "<REMOTE_CHROME_URL>"
      FIREFOX: "<REMOTE_FIREFOX_URL>"
      EDGE: "<REMOTE_EDGE_URL>"          

Testsigma Agent container allows controlling minimum and maximum heap memory settings using MIN and MAX environment variables. The default values for MIN and MAX will be 1GB and 8GB, respectively. Here's an example docker-compose file:

version: "3.9"
services:
  testsigma-agent:
    image: testsigmainc/testsigma-agent:latest
    container_name: testsigma-agent
    volumes:
      - ./data/agent_data:/var/ts/agent
      - ./data/agent_temp:/tmp/agent_temp
      - ./<foldername>:/root/.testsigma/agent/logs
    environment:
      TS_ACTIVATION_KEY: "REPLACE_WITH_YOUR_ACTIVATION_KEY"
      MIN: "-Xms1g"
      MAX: "-Xmx8g"
      CHROME: "<CHROME_URL>"
      FIREFOX: "<FIREFOX_URL>"
      EDGE: "<EDGE_URL>"

For ARM-based Systems (Mac M1 processors):
Google does not build Chrome for Linux ARM platforms. Instead, docker-seleniarm uses the open-source Chromium browser built for ARM. Here's an example docker-compose file:

version: "3.9"
services:
  testsigma-agent:
    image: testsigmainc/testsigma-agent:latest
    container_name: testsigma-agent
    depends_on:
      - chrome
      - firefox
    volumes:
      - ./data/agent_data:/var/ts/agent
      - ./data/agent_temp:/tmp/agent_temp
      - ./<foldername>:/root/.testsigma/agent/logs
    environment:
      TS_ACTIVATION_KEY: "REPLACE_WITH_YOUR_ACTIVATION_KEY"
      CHROME: "http://chrome:4444"
      FIREFOX: "http://firefox:4444"
      EDGE: "<REMOTE_EDGE_URL>"
  chrome:
    image: seleniarm/standalone-chrome:latest
    shm_size: 1gb
    ports:
      - "4444:4444"
    volumes:
      - ./data/agent_temp:/tmp/agent_temp

  firefox:
    image: seleniarm/standalone-firefox:latest
    shm_size: 1gb
    ports:
      - "4445:4444"
    volumes:
      - ./data/agent_temp:/tmp/agent_temp

1. Save the docker-compose.yml file in an appropriate directory.
2. Open a command-line interface and navigate to the directory. Execute the command docker-compose up, which will download the necessary images and start the Testsigma Agent.

Register a New Agent While Booting the Docker Container.

To create and register the Agent Automatically in one step, you must specify the environment variables below instead of TS_ACTIVATION_KEY.

TS_AUTO_REGISTRATION_KEY - Testsigma API key
TS_AUTO_REGISTRATION_TITLE - Title of the Agent
TS_AUTO_REGISTRATION_HTTP_PORT - HTTP Port for internal communication between Agent and Testsigma TS_AUTO_REGISTRATION_HTTPS_PORT - HTTPS Port for internal communication between Agent and Testsigma

Here's an example docker-compose file:

version: "3.9"
services:
  testsigma-agent:
    image: testsigmainc/testsigma-agent:latest
    container_name: testsigma-agent
    depends_on:
      - chrome
      - firefox
      - edge
    volumes:
      - ./data/agent_data:/var/ts/agent
      - ./data/agent_temp:/tmp/agent_temp
      - ./<foldername>:/root/.testsigma/agent/logs
    environment:
      TS_AUTO_REGISTRATION_KEY: "REPLACE_WITH_API_KEY"
      TS_AUTO_REGISTRATION_TITLE: "REPLACE_WITH_TITLE"
      TS_AUTO_REGISTRATION_HTTP_PORT: "REPLACE_WITH_ANY_AVAILABLE_PORT_NUMBER"
      TS_AUTO_REGISTRATION_HTTPS_PORT: "REPLACE_WITH_ANY_AVAILABLE_PORT_NUMBER"
      CHROME: "http://chrome:4444"
      FIREFOX: "http://firefox:4444"
      EDGE: "http://edge:4444"

  chrome:
    image: selenium/standalone-chrome:latest
    shm_size: 1gb
    ports:
      - "4444:4444"
    volumes:
      - ./data/agent_temp:/tmp/agent_temp

  firefox:
    image: selenium/standalone-firefox:latest
    shm_size: 1gb
    ports:
      - "4445:4444"
    volumes:
      - ./data/agent_temp:/tmp/agent_temp
  
  edge:
    image: selenium/standalone-edge:latest
    shm_size: 1gb
    ports:
      - "4446:4444"    
    volumes:
      - ./data/agent_temp:/tmp/agent_temp