@testdriverai/mcp 7.9.155-test → 7.9.156-test
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -8,6 +8,10 @@ Start by exploring your app. This is where tests begin: you describe a flow in p
|
|
|
8
8
|
|
|
9
9
|
There are two ways to explore: chatting interactively with your AI assistant through the TestDriver MCP server, or handing a coding agent our instructions file and prompting it to generate a test.
|
|
10
10
|
|
|
11
|
+
<Info>
|
|
12
|
+
Both paths need an MCP-capable AI coding assistant. If you don't have one yet, start with **GitHub Copilot** — there's a [free tier](https://github.com/features/copilot/plans), no credit card required. See [Run → Setup](/v7/copilot/running-tests#setup) for the full install and sign-in walkthrough.
|
|
13
|
+
</Info>
|
|
14
|
+
|
|
11
15
|
## Instructions for Coding Agents
|
|
12
16
|
|
|
13
17
|
We recommend starting with [our quickstart](./quickstart), then supplying your coding agent with our agent instructions file.
|
|
@@ -86,6 +86,265 @@ TestDriver makes it easy to write automated computer-use tests for web browsers,
|
|
|
86
86
|
</Step>
|
|
87
87
|
</Steps>
|
|
88
88
|
</Tab>
|
|
89
|
+
<Tab title="AI Setup" icon="robot">
|
|
90
|
+
|
|
91
|
+
Plug TestDriver into your AI client so you can write, run, and debug real end-to-end tests right from chat. There are three pieces, and `testdriverai init` installs all of them for you:
|
|
92
|
+
|
|
93
|
+
- **The agent** — an expert test-creator that drives a live sandbox, writes code after each step, and reruns the test until it passes.
|
|
94
|
+
- **Skills** — small instruction files that teach the agent the exact syntax for each TestDriver capability (`find`, `click`, `type`, `assert`, …).
|
|
95
|
+
- **The MCP server** — exposes TestDriver's computer-use tools over the [Model Context Protocol](https://modelcontextprotocol.io) so any MCP-capable client can use them.
|
|
96
|
+
|
|
97
|
+
### Quick install (recommended)
|
|
98
|
+
|
|
99
|
+
`testdriverai init` wires up the agent, skills, and MCP server for you, writing each client's config in the exact format and location it expects:
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
# interactive — pick your client(s)
|
|
103
|
+
npx testdriverai init
|
|
104
|
+
|
|
105
|
+
# one client
|
|
106
|
+
npx testdriverai init --client claude-code
|
|
107
|
+
|
|
108
|
+
# several
|
|
109
|
+
npx testdriverai init --client claude-code,cursor,vscode
|
|
110
|
+
|
|
111
|
+
# everything
|
|
112
|
+
npx testdriverai init --client all
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
<Info>
|
|
116
|
+
`init` detects clients already present in your project and pre-selects them in the picker. Re-running `init` is safe — it merges the TestDriver entry into existing config without overwriting your other servers.
|
|
117
|
+
</Info>
|
|
118
|
+
|
|
119
|
+
You'll need a TestDriver API key. Create one at [console.testdriver.ai/team](https://console.testdriver.ai/team) and `init` will save it to `.env` as `TD_API_KEY`.
|
|
120
|
+
|
|
121
|
+
### The agent
|
|
122
|
+
|
|
123
|
+
The **TestDriver agent** is an expert test-creator that runs inside your AI client (Claude Code, Cursor, VS Code, and others). It writes, runs, and debugs real end-to-end tests by driving your app the same way a person would — using AI vision to find elements, click, type, and assert — through the TestDriver MCP server.
|
|
124
|
+
|
|
125
|
+
Unlike a chat assistant that only suggests code, the agent works **iteratively against a live sandbox**: it starts a session, performs each action, writes the generated code to your test file, verifies the result with a screenshot, and reruns the test until it passes.
|
|
126
|
+
|
|
127
|
+
During init you'll be asked which AI client(s) to install into. The agent is written to the location each client expects:
|
|
128
|
+
|
|
129
|
+
| Client | Agent location |
|
|
130
|
+
| --- | --- |
|
|
131
|
+
| Claude Code | `.claude/agents/testdriver.md` |
|
|
132
|
+
| VS Code (Copilot) | `.github/agents/testdriver.agent.md` |
|
|
133
|
+
| Cursor | `.cursor/rules/testdriver.mdc` |
|
|
134
|
+
| Windsurf | `.windsurf/rules/testdriver.md` |
|
|
135
|
+
| Codex | `AGENTS.md` |
|
|
136
|
+
| Zed | `.rules` |
|
|
137
|
+
|
|
138
|
+
Once installed, invoke it from your client's chat:
|
|
139
|
+
|
|
140
|
+
```text
|
|
141
|
+
@testdriver write a test that logs in and verifies the dashboard loads
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
The agent will spin up a sandbox, perform the steps live, write them into a test file under `tests/`, and run it for you.
|
|
145
|
+
|
|
146
|
+
### Skills
|
|
147
|
+
|
|
148
|
+
**Skills** are small, focused instruction files — one per TestDriver capability — that teach your AI client exactly how to use each part of the TestDriver SDK and MCP tools. They follow the [Anthropic `SKILL.md` format](https://code.claude.com/docs/en/skills): a folder per skill, each containing a `SKILL.md` with YAML frontmatter and a markdown body.
|
|
149
|
+
|
|
150
|
+
There are **106 skills**, generated directly from the TestDriver documentation, covering every action and concept: `find`, `click`, `type`, `assert`, `check`, `scroll`, `press-keys`, `provision`, caching, secrets, CI/CD, and more. They're written to the directory each client expects:
|
|
151
|
+
|
|
152
|
+
| Client | Skills location |
|
|
153
|
+
| --- | --- |
|
|
154
|
+
| Claude Code | `.claude/skills/<name>/SKILL.md` |
|
|
155
|
+
| Zed | `.agents/skills/<name>/SKILL.md` |
|
|
156
|
+
| Codex | referenced from `AGENTS.md` |
|
|
157
|
+
| VS Code · Cursor · Windsurf | folded into the agent rules/instructions |
|
|
158
|
+
|
|
159
|
+
<Note>
|
|
160
|
+
Skills are **generated, not hand-edited** — each is built from a `.mdx` docs page and carries a `DO NOT EDIT` marker. To change a skill, edit the corresponding documentation page and run `node docs/_scripts/generate-skills.js`.
|
|
161
|
+
</Note>
|
|
162
|
+
|
|
163
|
+
### MCP server
|
|
164
|
+
|
|
165
|
+
The **TestDriver MCP server** exposes TestDriver's computer-use tools — `session_start`, `find`, `click`, `type`, `assert`, `check`, `screenshot`, and more — over the [Model Context Protocol](https://modelcontextprotocol.io). It runs as a local stdio process:
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
npx -p testdriverai testdriverai-mcp
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
and authenticates with your `TD_API_KEY`. `testdriverai init` configures it for you, but you can also wire it up by hand:
|
|
172
|
+
|
|
173
|
+
| Client | Auto-install | MCP config file | Config key |
|
|
174
|
+
| --- | --- | --- | --- |
|
|
175
|
+
| Claude Code | ✅ | `.mcp.json` | `mcpServers` |
|
|
176
|
+
| Claude Desktop | ✅ | OS-specific | `mcpServers` |
|
|
177
|
+
| Cursor | ✅ | `.cursor/mcp.json` | `mcpServers` |
|
|
178
|
+
| VS Code (Copilot) | ✅ | `.vscode/mcp.json` | `servers` |
|
|
179
|
+
| Windsurf | ✅ | `~/.codeium/windsurf/mcp_config.json` | `mcpServers` |
|
|
180
|
+
| Codex | ✅ | `~/.codex/config.toml` | `[mcp_servers]` |
|
|
181
|
+
| Zed | ✅ | `.zed/settings.json` | `context_servers` |
|
|
182
|
+
| Lovable | ⚙️ partial | GitHub `AGENTS.md` + UI | — |
|
|
183
|
+
| Replit | ⚙️ partial | `replit.md` + UI | — |
|
|
184
|
+
| v0 (Vercel) | 📝 manual | web UI only | — |
|
|
185
|
+
|
|
186
|
+
<Note>
|
|
187
|
+
Each client uses a **different top-level key** for MCP servers. The most common mistake when configuring by hand is using `mcpServers` for VS Code (it wants `servers`), Codex (TOML `[mcp_servers]`), or Zed (`context_servers`).
|
|
188
|
+
</Note>
|
|
189
|
+
|
|
190
|
+
<Tabs>
|
|
191
|
+
<Tab title="Claude Code">
|
|
192
|
+
Add to `.mcp.json` at your project root (or `~/.claude.json` for all projects):
|
|
193
|
+
|
|
194
|
+
```json
|
|
195
|
+
{
|
|
196
|
+
"mcpServers": {
|
|
197
|
+
"testdriver": {
|
|
198
|
+
"type": "stdio",
|
|
199
|
+
"command": "npx",
|
|
200
|
+
"args": ["-p", "testdriverai", "testdriverai-mcp"],
|
|
201
|
+
"env": { "TD_API_KEY": "${TD_API_KEY}" }
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
```
|
|
206
|
+
</Tab>
|
|
207
|
+
|
|
208
|
+
<Tab title="Claude Desktop">
|
|
209
|
+
Edit the Claude Desktop config file:
|
|
210
|
+
|
|
211
|
+
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
212
|
+
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
|
|
213
|
+
- **Linux:** `~/.config/Claude/claude_desktop_config.json`
|
|
214
|
+
|
|
215
|
+
```json
|
|
216
|
+
{
|
|
217
|
+
"mcpServers": {
|
|
218
|
+
"testdriver": {
|
|
219
|
+
"command": "npx",
|
|
220
|
+
"args": ["-p", "testdriverai", "testdriverai-mcp"],
|
|
221
|
+
"env": { "TD_API_KEY": "your_api_key" }
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
Restart Claude Desktop after saving.
|
|
228
|
+
</Tab>
|
|
229
|
+
|
|
230
|
+
<Tab title="Cursor">
|
|
231
|
+
Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
|
|
232
|
+
|
|
233
|
+
```json
|
|
234
|
+
{
|
|
235
|
+
"mcpServers": {
|
|
236
|
+
"testdriver": {
|
|
237
|
+
"type": "stdio",
|
|
238
|
+
"command": "npx",
|
|
239
|
+
"args": ["-p", "testdriverai", "testdriverai-mcp"],
|
|
240
|
+
"env": { "TD_API_KEY": "${TD_API_KEY}" }
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
```
|
|
245
|
+
</Tab>
|
|
246
|
+
|
|
247
|
+
<Tab title="VS Code">
|
|
248
|
+
Add to `.vscode/mcp.json`. VS Code uses the `servers` key and an `inputs` prompt for secrets:
|
|
249
|
+
|
|
250
|
+
```json
|
|
251
|
+
{
|
|
252
|
+
"servers": {
|
|
253
|
+
"testdriver": {
|
|
254
|
+
"type": "stdio",
|
|
255
|
+
"command": "npx",
|
|
256
|
+
"args": ["-p", "testdriverai", "testdriverai-mcp"],
|
|
257
|
+
"env": { "TD_API_KEY": "${input:testdriver-api-key}" }
|
|
258
|
+
}
|
|
259
|
+
},
|
|
260
|
+
"inputs": [
|
|
261
|
+
{
|
|
262
|
+
"type": "promptString",
|
|
263
|
+
"id": "testdriver-api-key",
|
|
264
|
+
"description": "TestDriver API Key From https://console.testdriver.ai/team",
|
|
265
|
+
"password": true
|
|
266
|
+
}
|
|
267
|
+
]
|
|
268
|
+
}
|
|
269
|
+
```
|
|
270
|
+
</Tab>
|
|
271
|
+
|
|
272
|
+
<Tab title="Windsurf">
|
|
273
|
+
Windsurf reads MCP config globally. Add to `~/.codeium/windsurf/mcp_config.json`:
|
|
274
|
+
|
|
275
|
+
```json
|
|
276
|
+
{
|
|
277
|
+
"mcpServers": {
|
|
278
|
+
"testdriver": {
|
|
279
|
+
"command": "npx",
|
|
280
|
+
"args": ["-p", "testdriverai", "testdriverai-mcp"],
|
|
281
|
+
"env": { "TD_API_KEY": "${TD_API_KEY}" }
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
}
|
|
285
|
+
```
|
|
286
|
+
</Tab>
|
|
287
|
+
|
|
288
|
+
<Tab title="Codex">
|
|
289
|
+
Codex uses TOML. Add to `~/.codex/config.toml`:
|
|
290
|
+
|
|
291
|
+
```toml
|
|
292
|
+
[mcp_servers.testdriver]
|
|
293
|
+
command = "npx"
|
|
294
|
+
args = ["-p", "testdriverai", "testdriverai-mcp"]
|
|
295
|
+
env = { TD_API_KEY = "${TD_API_KEY}" }
|
|
296
|
+
```
|
|
297
|
+
</Tab>
|
|
298
|
+
|
|
299
|
+
<Tab title="Zed">
|
|
300
|
+
Zed calls them "context servers". Add to `.zed/settings.json` (project) or `~/.config/zed/settings.json` (global):
|
|
301
|
+
|
|
302
|
+
```json
|
|
303
|
+
{
|
|
304
|
+
"context_servers": {
|
|
305
|
+
"testdriver": {
|
|
306
|
+
"command": "npx",
|
|
307
|
+
"args": ["-p", "testdriverai", "testdriverai-mcp"],
|
|
308
|
+
"env": { "TD_API_KEY": "${TD_API_KEY}" }
|
|
309
|
+
}
|
|
310
|
+
}
|
|
311
|
+
}
|
|
312
|
+
```
|
|
313
|
+
</Tab>
|
|
314
|
+
</Tabs>
|
|
315
|
+
|
|
316
|
+
**Web-based clients** — Lovable, Replit, and v0 run in the browser, so the MCP server can't be launched as a local process. Configure them through each product's UI:
|
|
317
|
+
|
|
318
|
+
<AccordionGroup>
|
|
319
|
+
<Accordion title="Lovable">
|
|
320
|
+
1. Connect your GitHub repo and run `npx testdriverai init --client lovable` — this writes `AGENTS.md` and the skills into the repo so Lovable's agent picks them up.
|
|
321
|
+
2. In Lovable, open **Settings → MCP** and add the TestDriver server.
|
|
322
|
+
</Accordion>
|
|
323
|
+
|
|
324
|
+
<Accordion title="Replit">
|
|
325
|
+
1. Run `npx testdriverai init --client replit` to write `replit.md` with the TestDriver agent guidance.
|
|
326
|
+
2. In Replit, open **Tools → Integrations → MCP** and add a custom MCP server.
|
|
327
|
+
</Accordion>
|
|
328
|
+
|
|
329
|
+
<Accordion title="v0 (Vercel)">
|
|
330
|
+
v0 is fully UI-driven and does not read repo files.
|
|
331
|
+
|
|
332
|
+
1. Open **[v0.app/chat/settings/mcp-connections](https://v0.app/chat/settings/mcp-connections)** and add the TestDriver MCP connection.
|
|
333
|
+
2. Paste the agent guidance into **Instructions** (the **+** in the prompt bar).
|
|
334
|
+
</Accordion>
|
|
335
|
+
</AccordionGroup>
|
|
336
|
+
|
|
337
|
+
### Verifying the install
|
|
338
|
+
|
|
339
|
+
Open your client's chat and ask the agent to write a test:
|
|
340
|
+
|
|
341
|
+
```text
|
|
342
|
+
@testdriver write a test that opens the homepage and asserts the title
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
If the MCP server is wired up correctly, the agent will start a session and you'll see screenshots come back as it works. If tools don't appear, check that `TD_API_KEY` is set and restart the client.
|
|
346
|
+
|
|
347
|
+
</Tab>
|
|
89
348
|
<Tab title="Manual" icon="wrench">
|
|
90
349
|
|
|
91
350
|
Install TestDriver and manually create the files yourself.
|