TestChimp Local

Agentic Testing, From your CLI

 

Introduction

When you trigger an exploration from testchimp site, the agent runs on TestChimp cloud. testchimp-local enables you to run TestChimp’s autonomous testing agent locally. This enables the following:

  • Test your localhost version (during development phase, before even pushing to staging envs)
  • Reuse your signed-in sessions for testing sites with complex logins (eg: SSO, 2FA etc.)
  • When your site under test is not open to public internet access (behind firewalls etc.)
  • For human-in-the-loop hybrid exploration with the agent.

The Local Agent also doubles up as an MCP server that your MCP-compliant IDEs (such as Cursor) can collaborate with to get access to your webapps’ runtime behaviour context. For more information on setting up the local agent server as an MCP server, refer here.

 

Prerequisites

Python 3.11 or above should be installed.

 

How to Run

 

1. Install:

pip install --upgrade testchimp-local

2.Create an exploration configuration file

Refer Configuration section below for guide and examples.

Here is a minimal config file to get started:

{
    "browserContext": {
        "mode": "launch",
    },
    "appReleaseLabel": "local_default",
    "explorationConfig": {
         "promptConfig": {
               "url": "https://example.com",
               "explorePrompt": "Explore the website and find any issues",
               "testDataPrompt": "Login with test@example.com password1"
         },
         "maxCredits": 50,
         "maxJourneys": 2,
         "bugCaptureSettings": {
              "sources": ["dom", "screenshot", "network", "console"]
         },
         "viewportConfig": {
               "viewports": [
                   {
                    "nickname": "laptop"
                   }
               ]
         },
         "urlRegexToCapture": ".*\\.example\\.com.*"
     }
}

3. Set Environment Variables

Following environment variables are used for authenticating your local agent client and syncing with TestChimp platform:

  • TESTCHIMP_PAT: Sign in to your TestChimp account. Go to user settings (click on your name at side bar bottom). Copy Personal Access Token value.
  • TESTCHIMP_PROJECT_ID: The project id for which the results will be synced. Go to project settings -> General. Copy project id.
  • TESTCHIMP_EMAIL: Email address used for signing-up with TestChimp

 

4. Run

testchimp-local --config_file=<path to your exploration_config.json>
By default, the local service is started at port 43449. You can change it be passing –port argument.
 

 

Configuration

For detailed configuration guidance, refer documentation here.

 

Reusing an existing browser session

To reuse your existing signed-in sessions (to circumvent 2FA, SSO limitation etc.) for agentic testing, follow the steps below:

  1. Close your existing chrome browser instances.
  2. Start chrome in CDP mode (below command):

 

In MacOS:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-cdp

In Windows:

"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir=C:\chrome-cdp

In Linux:

google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-cdp
  1. In your exploration config json file, specify the browser_context section as below, and it will connect to the browser instance via CDP, and reuse the existing sessions:
 "browserContext": {
     "mode": "cdp",
     "cdpUrl": "http://localhost:9222",
     "headless": false
 }