TurnSignal
# TurnSignal for Playwright
Source of the [`turnsignal`](https://www.npmjs.com/package/turnsignal) npm package: the Playwright reporter, the `turnsignal` CLI and the TurnSignal **MCP server** for coding agents. MIT licensed.
[TurnSignal](https://turnsignal.ai) keeps every Playwright test's results across CI runs and branches, and labels each failure as a *new failure*, *also failing on main* or *known flaky*. Package docs: [packages/turnsignal/README.md](packages/turnsignal/README.md).
## MCP server
Read-only Playwright CI results for coding agents (Claude Code, Cursor, Copilot, ...). Before an agent "fixes" a failing test, it can check whether the failure is new in this pull request, already failing on main, or known flaky.
| Tool | What it returns |
|---|---|
| `turnsignal_recent_runs` | Recent CI runs: verdict, status, branch, commit, counts, run id |
| `turnsignal_run` | One run's results: new failures, already failing, flaky, missing tests, with errors |
| `turnsignal_test_history` | One test's recent outcomes across runs |
| `turnsignal_flaky_tests` | Tests that were flaky in the last N days, most flaky first |
```json
{
"mcpServers": {
"turnsignal": {
"command": "npx",
"args": ["-y", "turnsignal", "mcp"],
"env": { "TURNSIGNAL_TOKEN": "<project token from https://app.turnsignal.ai>" }
}
}
}
```
Claude Code: `claude mcp add turnsignal -e TURNSIGNAL_TOKEN=<token> -- npx -y turnsignal mcp`
The server talks JSON-RPC over stdio and only reads data the project token can see. It is listed in the official MCP Registry as `ai.turnsignal/turnsignal`.
## Layout
| Path | What |
|---|---|
| `packages/shared` | Wire format, test identity, secret redaction |
| `packages/playwright-reporter` | The Playwright reporter (crash-safe local copy, never changes your exit code) |
| `packages/cli` | `turnsignal upload`, `comment`, `governance`, `doctor`, `mcp` ([src/mcp.ts](packages/cli/src/mcp.ts)) |
| `packages/turnsignal` | The published package: an esbuild bundle of the three above |
```bash
npm ci
npm test # build + unit tests
npm run package # builds packages/turnsignal/dist
```
The hosted service (API and web app) is not part of this repository; `ADR-NNN` references in code comments point to its internal design records. This repository is a mirror: changes land upstream and are synced here, so please report issues to hello@turnsignal.ai or open an issue. Questions: hello@turnsignal.ai.
TDQS
Scored across 4 tools
Each tool targets a clearly distinct scope: recent_runs lists runs, run details a single run, test_history tracks one test across runs, and flaky_tests aggregates flaky tests over a time window. The descriptions explicitly state the progression (find a run, inspect it, drill into a test) so an agent can pick the right tool without overlap confusion.
All names use a consistent turnsignal_ prefix with snake_case, giving a predictable pattern. The only minor wrinkle is the noun-phrase style (run vs recent_runs, test_history, flaky_tests) with a singular/plural pair that could momentarily blur, but it remains readable and coherent.
Four tools is a tight, well-scoped set for a read-only CI test inspection domain, with each tool covering a distinct layer (runs, run detail, test history, flaky aggregation). No tool feels redundant or missing at this scale.
The surface covers the core diagnostic lifecycle: find runs, explain a run, trace a single test over time, and surface flaky tests. Minor gaps exist (e.g. no way to list all tests in a run, compare runs, or fetch raw logs), but agents can work around these via the run detail tool.