CircleCI Integration With TestGrid

Overview

Integrating CircleCI with TestGrid enables teams to execute automated tests seamlessly as part of their CI/CD pipelines. With this integration your existing Selenium and Appium test suites or testgrids Codeless test suites can be triggered automatically on request, providing rapid feedback and ensuring application quality across web and mobile platforms.

This guide provides a step-by-step approach to configuring CircleCI to trigger TestGrid test executions and view results directly in the TestGrid dashboard.

Benefits of CircleCI–TestGrid Integration

• Enable continuous testing in CI/CD pipelines
• Execute tests on real devices and browsers hosted on TestGrid
• Centralized test reporting with logs, screenshots, and videos
• Faster feedback and improved release confidence

Prerequisites

Before proceeding, ensure the following requirements are met:

• Active CircleCI account
• A project configured in CircleCI (GitHub or Bitbucket repository)
• Active TestGrid account
• TestGrid application, version, and test suites already created
• Valid TestGrid user token and application token
• Basic familiarity with YAML and CI/CD concepts

High-Level Integration Flow

1. Configure environment variables in CircleCI
2. Create or update CircleCI configuration file
3. Trigger TestGrid execution using CLI or API
4. Monitor execution status and view results in TestGrid

Step 1: Configure Environment Variables in CircleCI

To securely authenticate with TestGrid, required tokens must be added as environment variables in CircleCI.

Required Environment Variables

Variable Name	Description
TESTGRID_USER_TOKEN	TestGrid user authentication token
TESTGRID_APP_TOKEN	Token identifying the TestGrid application
TESTGRID_VERSION_TOKEN	Token for the application version
TESTGRID_PROCESS_TYPE	Execution type (web / app)
TESTGRID_DEVICE	Target device or browser

Add these variables in CircleCI → Project Settings → Environment Variables.

Step 2: Configure CircleCI Pipeline & Trigger Execution

Create or update the .circleci/config.yml file in your repository.

Edit your .circleci/config.yml file.

version: 2.1

jobs:
  testgrid-execution:
     docker:
       - image: cimg/node:18.0
     steps:
       - checkout


       - run:
           name: Install TestGrid CLI
           command: npm install -g @testgrid/cli

       - run:
           name: Execute TestGrid Tests
           command: |
             testgrid run \
               --user-token $TESTGRID_USER_TOKEN \
               --app-token $TESTGRID_APP_TOKEN \
               --version-token $TESTGRID_VERSION_TOKEN \
               --process-type $TESTGRID_PROCESS_TYPE \
               --device $TESTGRID_DEVICE

workflows:
  version: 2
  testgrid-workflow:
    jobs:
      - testgrid-execution

This configuration installs the TestGrid CLI and triggers test execution during the pipeline run.

Below is the list of configuration references:

Determine the user’s capabilities.

a. Go to the Dashboard and then click on “Codeless.”
b. Click on “Test Case Writer” and then click on Versions. On the same screen, look for the “i” button in the upper right corner. Click on the “i” button icon.
c. You can see keys like user tokens, application tokens, etc. You need to choose ‘process_type’ as appropriate for your web or mobile for the CI CD API, which we will discuss below.

Selenium Web With Website URL

• Syntax:

curl --location 'https://{your_domain}.testgrid.io/ci/app_build_run' \
--form 'application_token='{application_token}'' \
--form 'user_token='{user_token}'' \
--form 'version_token='{version_token}'' \
--form 'version_module_id='{module_suite_id}'' \
--form 's_device='{s_devices}'' \
--form 'process_type='{process_type}'' \
--form 'test_website_url='{website_url}''

Appium With Mobile Application File and Bundle Identifier

1. process_type (Android – Appium) –> oaa
2. process_type (Web)  –> ow
3. process_type (iOS-Appium). –>  oia

• Syntax with Build_id:

curl --location 'https://{your_domain}.testgrid.io/ci/app_build_run' \
--form 'application_token='{application_token}'' \
--form 'user_token='{user_token}'' \
--form 'version_token='{version_token}'' \
--form 'version_module_id='{module_id}'' \
--form 's_device='{s_devices}'' \
--form 'process_type='{proccess_type}'' \
--form 'app_build_id='{build_id}'' \

• Syntax with Bundle Identifier:

curl --location 'https://{your_domain}.testgrid.io/ci/app_build_run' \
--form 'application_token='{application_token}'' \
--form 'user_token='{user_token}'' \
--form 'version_token='{version_token}'' \
--form 'version_module_id='{module_id}'' \
--form 's_device='{s_devices}'' \
--form 'process_type='{proccess_type}'' \
--form 'bundle_identifier='{build_id}''

The location of the configuration command is referenced.

Step 3: Monitor Execution and View Results

Once the CircleCI job is triggered:

• Navigate to CircleCI → Pipelines to monitor job status
• Open the execution link generated in the job logs
• Access detailed results in the TestGrid Dashboard, including:
  • Pass/Fail status
  • Step-wise execution logs
  • Screenshots
  • Video recordings (if enabled)
  • Network logs and performance insights

Once you have the build_id, you must check the execution of our platform.
Ex:  https://{your_domain}.testgrid.io/build/apps/907
On the TestGrid Automation Dashboard, keep an eye on and analyze your test results.
To give all of your visitors a seamless user experience, dependably deploy your code at scale using CircleCI integration with TestGrid and make sure it looks robust across all browsers and devices.

Troubleshooting

Common Issues and Resolutions

• Authentication Errors (401/403)
  • Verify TestGrid tokens are correctly set in CircleCI environment variables
• CLI Not Found
  • Ensure the TestGrid CLI installation step is executed successfully
• Execution Not Triggered
  • Validate application, version, and device values
• Timeout Issues
  • Increase CircleCI job timeout settings

Best Practices

• Store all sensitive tokens as environment variables
• Use separate TestGrid applications or versions for different environments
• Monitor flaky tests and stabilize before production runs

Conclusion

Integrating CircleCI with TestGrid enables robust, scalable, and enterprise-ready continuous testing. By embedding TestGrid test execution directly into CI/CD pipelines, teams can improve test coverage, accelerate release cycles, and maintain high-quality standards across applications.