For AI agents and developers
Connect your AI agent to TestCollab
Give Claude Code, Codex, Cursor, or any coding agent the prompt on this page. It reads our agent guide, writes automated tests for your app, runs them, and reports every result to TestCollab with the evidence.
No credit card required. The agent guide is one Markdown file that any agent can read.
Trusted by QA teams at
Paste this into your agent
Read https://testcollab.com/agents.md, then help me use TestCollab from this project. First ask me what I want to do: document test cases, write automated tests, run them, and report the results with evidence; run a test plan that my team curated; or sync my BDD feature files. Use the tc CLI as the guide describes. Take my API token from the TESTCOLLAB_TOKEN environment variable and never ask me to paste it here. Ask me for the project ID when you need it.
Works in any agent that can run shell commands. A chat assistant without a shell reads the same guide and gives you the commands to run.
Why connect an agent
One test record for people, pipelines, and agents
Tests your agent writes
The agent writes test automation code in your repository and runs it with your test runner.
Results with evidence
Each result lands in TestCollab next to your manual runs, with the screenshot, video, or trace attached.
One connection, the CLI
The agent runs the tc command in its own shell. One npm package, no server to host.
Your team stays in control
The agent works with a token that a person creates. It gets that person's role and project access, nothing more.
Ways to connect
Three ways to connect
The same CLI serves an agent on your laptop and a pipeline in CI. Assistants without a shell use the MCP server.
For a coding agent
Claude Code, Codex, Cursor, OpenCode, and other agents with a shell. The agent writes the tests, runs them, and reports the results.
- Write: test code in your repository
- Run: with your test runner
- Report: results and evidence to TestCollab
For CI pipelines
Put the same commands in your pipeline. Each build reports its results, and one more command can gate the build.
- Report: tc report after the test job
- Trace: --build links the version under test
- Gate: tc gate fails the build on your rule
For chat and IDE assistants
An assistant that cannot run a shell uses the MCP server to work with your test library.
- Create and update test cases
- Organize suites
- Build and query test plans
What it can do
What an agent can do today
The main job: your agent writes test automation code, runs it, and reports the results straight to TestCollab as evidence.
1. Write the tests
You describe the flow to test. The agent writes the test automation code in your repository, for example Playwright tests, where you review it like any other code.
2. Run them
The agent runs the tests with your test runner. It sets the runner to keep a screenshot, a video, and a trace for each test that fails.
3. Report the evidence
tc report --auto-create sends the results to TestCollab. It creates the suites, the test cases, and a test plan, and attaches each file to its executed case.
More commands
More an agent can do
The same CLI covers the rest of the test cycle.
Run a curated test plan
tc getTestPlan gives the agent the cases, the steps, and the expected results of a plan your team wrote. The agent performs each case and reports the result. How it works.
Gate a release
tc gate exits non-zero when the results miss your rule: failing statuses, pass rate, or an incomplete run. --wait holds a deployment until manual QA finishes.
Sync BDD feature files
tc sync turns the committed Gherkin .feature files of your repository into suites and test cases. The results of those scenarios report back to the same cases.
Human review, by design
Your team decides. The agent executes.
An agent can write, run, and report the tests. Three things stay with your team.
The token
A person creates the API token in TestCollab. The agent acts as that user, with the same role and project access. Revoke the token and the access ends.
The scope
You say what to test. The agent writes the tests in your repository, where you review them. For a curated plan, your team picks the cases and the steps.
The verdict
Each result arrives with its evidence. Agent runs can vary, so review a failure before you act on it. tc gate --wait can hold a deployment until manual QA finishes.
Get started
Start in three steps
From a new account to the first results in TestCollab.
1. Create a token
In TestCollab, open My Profile Settings and the API token tab. Create a token. It is shown once.
# in your agent's shell,
# never in the chat
export TESTCOLLAB_TOKEN=...2. Install the CLI
One npm package gives your agent the tc command. There is no server to set up.
# needs Node.js 18 or later
npm i -g @testcollab/cli
tc --version3. Report the first results
Run your tests, then send the result file. --auto-create builds the suites, the test cases, and the test plan.
tc report --project 123 \
--format junit \
--auto-create \
--result-file results.xmlAlso for machines
Reading this as an agent?
These are the shortest paths.
This guide in Markdown, with the command sequence for each loop.
A summary of the site and the links that matter, in the llms.txt convention. The long version is llms-full.txt.
The CLI source and README are on GitHub under the MIT license. For other operations, use the REST API reference.
FAQ
Frequently asked questions
Which AI agents work with TestCollab?
Any agent that can run shell commands: Claude Code, Codex, Cursor, OpenCode, Hermes Agent, and others. The agent needs Node.js 18 or later to run the tc CLI. An assistant without a shell can use the MCP server for test cases, suites, and test plans.
How does the agent run the tests?
With its own tools. TestCollab does not start a browser or a test runner. For automated tests, the agent writes the test code and runs it with your test runner, for example Playwright. For a curated test plan, it reads each step and expected result and performs it. TestCollab records the results and the evidence.
Which test frameworks work?
Any runner that writes JUnit XML or Mochawesome JSON: Playwright, Cypress, Jest, pytest, and others. Evidence files attach from JUnit XML. Playwright's JUnit reporter lists its screenshots, videos, and traces in the result file, so they attach with no extra code.
Does my agent need the MCP server?
No. The CLI is the main connection. It reports results, attaches evidence, fetches plans, and gates builds. The MCP server is for chat and IDE assistants that cannot run a shell. It creates, reads, and updates test cases, suites, and test plans. It does not execute tests or report results.
How does the agent authenticate?
With a TestCollab API token in the TESTCOLLAB_TOKEN environment variable. A person creates the token under My Profile Settings. The agent gets the same role and project access as that person. Set the token in the environment. Do not paste it into a chat.
Can an agent write test cases?
Yes, in three ways. tc report --auto-create turns each automated test the agent wrote into a test case with its result. With BDD, the agent writes Gherkin .feature files in your repository and tc sync turns each scenario into a test case. With the MCP server, an assistant creates and updates test cases directly.
Can I use an agent's results for a release decision?
Treat them like the results of a new tester. Agent runs can vary from one run to the next. Each result carries its evidence, so a person can check a failure quickly. Put tc gate on a plan only when your team has agreed to that rule.
What is agents.md?
A Markdown file at testcollab.com/agents.md, written for AI agents. It lists the commands, the options, and the rules an agent needs to work with TestCollab. Give your agent the link, or use the prompt at the top of this page.
Let your agent write, run, and report your tests
Start a free trial, create a token, and paste the prompt into your agent.
