# End-to-end tests from Claude Code, Cursor and Codex: a setup walk-through

> Connect Claude Code, Cursor or Codex to FlowQA so the agent writes end-to-end tests, runs them in a browser and reads the failing step and its screenshot. Every command and config file, a first prompt, and what to do when a step does not work.

Published 2026-11-18, about FlowQA.

To get end-to-end tests from Claude Code, Cursor or Codex, connect the agent to a service that runs tests in a browser, then ask it for a test.
An end-to-end test opens your running app, does what a person would do, and checks what the page shows.
With FlowQA by TestFinch the setup is a token, one command or config file for your agent, and a first prompt.
Only the second step differs between the three agents.

## What you need before you start

- A TestFinch account with a project pointed at your site.
  Start free with your site's address, and the first project is created for you with its tests set up at that address.
- A site a cloud browser can reach: a deployed staging, preview or production address.
  An app that runs only on your computer is covered further down, with the CLI.
- Your product's repository open in the agent's session, so the agent can read the code it is testing.

## 1. Create a token

In TestFinch, open Agents and create a token.
The page makes a read and write token for every project or for one.
Treat the token like a password: it goes in your agent's configuration and never in the conversation.

## 2. Add the TestFinch server to your agent

The server's address is `https://api.testfinch.com/mcp`, and the token goes in an `Authorization: Bearer` header.

### Claude Code

Run this in your repository:

```sh
claude mcp add --transport http testfinch https://api.testfinch.com/mcp --header "Authorization: Bearer <token>"
```

`claude mcp list` then shows `testfinch` as connected.

### Cursor

Put this in `.cursor/mcp.json`:

```json
{ "mcpServers": { "testfinch": { "url": "https://api.testfinch.com/mcp", "headers": { "Authorization": "Bearer <token>" } } } }
```

The file now holds your token, so keep it out of git.

### Codex

```sh
codex mcp add testfinch -- npx -y mcp-remote https://api.testfinch.com/mcp --header "Authorization: Bearer <token>"
```

Any other MCP client takes the same address and header, or bridges over stdio with `mcp-remote`.

## 3. Start a new session and check the tools

Start a new agent session after adding the server, so the tools load.
The agent's tool list now has the TestFinch tools, such as `list_projects`, `get` and `flowqa_guide`.
If the list has no tool whose name starts with `flowqa_`, see "When a step does not work".

## What should the first prompt be?

Ask for one test of one journey, and name the outcome that proves the journey worked:

```text
Read the flowqa_guide tool. Then call list_projects and pick the project for this repository.
Write one test: a new person signs up and lands on the dashboard.
End it by checking that the dashboard shows the heading "Your projects".
Save it with verify on, and if it fails, show me the failing step and its screenshot before you change anything.
```

The agent then works through these tools, in this order:

| Tool | What the agent does with it |
|---|---|
| `flowqa_guide` | Reads how tests are written. Every save is checked against this guide. |
| `list_projects` | Finds your project and its `project_id`. |
| `flowqa_get_project` | Reads the environments, modules, openings and variable names. An opening is a reusable start, such as signing in. |
| `flowqa_list_tests` | Makes sure the test does not exist already. |
| `flowqa_save_tests` with `verify: true` | Saves the test and runs it once on a cloud browser in the same call. |
| `flowqa_wait_for_run` | Waits up to 55 seconds a call for a run that has not finished. |
| `flowqa_get_artifact` | Fetches the failing step's screenshot. |

The verdict from a verify run says passed or failed, the failing step and its error, the failing screenshot's path and a link to the run.
A saved test is published at once: it shows in Tests in TestFinch, written by you through your agent, and you can run, edit, rename or delete it.

Each save also comes back with findings, such as a test with no check or a typed password.
When a save has open findings, the verify run does not start.
The agent resolves the findings and saves again.

## How do I test the app on my own computer?

A cloud browser cannot open `localhost`.
For the app on your computer, the agent uses the TestFinch CLI from its terminal.
The CLI needs Node.js 20.11 or newer.

```sh
npm install -g @testfinch/cli
testfinch login
testfinch init
testfinch browsers install
testfinch test http://localhost:3000
```

- `testfinch login` opens your browser on TestFinch.
  The approval page asks you to allow **Run tests on this computer**, and runs on your computer need it.
  With it allowed, the CLI receives each project's test values, secret ones included, and so can anything that runs commands as you on this computer, a coding agent included.
- `testfinch init` asks which project and default environment the repository uses and writes `testfinch.json` at the repository root.
  Commit that file.
- `testfinch browsers install` downloads Chromium once.
- `testfinch test http://localhost:3000` runs every recorded test of the project against that address.
  `--test <id>` runs one, and `--start "pnpm dev"` starts your dev server first and stops it after.

After a run, the agent reads `.testfinch/runs/<run-id>/results.json`, which names each test's verdict and the step that failed.
The screenshots of failing steps are in the same folder.
The exit code is 0 when every test passed and 1 when a test failed or was blocked.
`testfinch guide` prints what an agent should read before it uses the CLI, and the same text is at [the CLI guide for agents](https://testfinch.com/docs/testfinch-cli-agent-guide/).

Run the login yourself, so that no token is pasted into the conversation.
Site passwords and sign-ins are sent only to the environment's own address.
A test that needs one stops and says so when you point it at `localhost`.

The connector writes and edits tests, and the CLI does not.
Both work on the same projects, tests and runs, so the agent writes a test through the connector and runs it against `localhost` with the CLI.

## When a step does not work

| What you see | What to do |
|---|---|
| The agent has no TestFinch tools | Start a new session. In Claude Code, run `claude mcp list` and look for `testfinch` as connected. |
| The agent has `list_projects` and no `flowqa_` tools | Your account is a reporter. A reporter sees no FlowQA tools. |
| The agent can read tests and cannot save | The token is read-only. Create a read and write token under Agents. |
| A save is refused and nothing is saved | One test in the batch does not parse, or names a module, an environment or an opening the project does not have. The error names each one. |
| A run is refused with the plan's limit | Runs the agent starts count against your plan as if you started them. The save itself still lands. |
| `testfinch test` exits 2 | A configuration problem: no linked project, no browser installed, or an address that matches no environment. The message says which. |
| `testfinch test` exits 3 | Not signed in, or the sign-in does not allow runs on this computer. Run `testfinch login` again and approve it. |

## What this setup does not do

The TestFinch connector does not give your agent a live page to click around in.
Its tools save, run and read tests.
For looking at a page while building, add a browser automation server such as Playwright MCP beside it; [Playwright MCP for testing](https://testfinch.com/blog/flowqa-vs-playwright-mcp/) compares the two.

Runs on your computer use Chromium, or the Google Chrome installed there with `--browser chrome`.
FlowQA tests web apps, and phone and tablet sizes are emulated in a desktop browser.
A flow the agent cannot read from the code, such as a third-party payment widget or a link in an email, is handed to you as a recording to make in FlowQA Desktop.

## Keep the tests running after the session ends

The tests the agent saved can run with no agent session open.
Once the first tests pass, put them on a schedule or run them after every deploy: [Schedules and CI](https://testfinch.com/docs/flowqa-ci/) covers both, and [GitHub deploy hooks](https://testfinch.com/docs/flowqa-github/) report a check on each commit.
The free plan covers 1 project, up to 100 tests, 1,000 cloud test runs a month, 1 schedule and a CI trigger.
Runs on your own computer through the CLI never count against your plan.
