@specwright/plugin 0.1.4 → 0.1.5
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.
|
@@ -0,0 +1,269 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: e2e-desktop-automate
|
|
3
|
+
description: Run the E2E test automation pipeline from Claude Desktop — configure, explore pages via Playwright MCP, generate seed files and test plans using the e2e-automation MCP server.
|
|
4
|
+
argument-hint: <page-url-or-feature>
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# E2E Desktop Automation Pipeline
|
|
8
|
+
|
|
9
|
+
Automate E2E test planning from Claude Desktop by combining two MCP servers:
|
|
10
|
+
|
|
11
|
+
- **e2e-automation** — project config, seed file generation, test plans
|
|
12
|
+
- **microsoft-playwright** — live browser exploration
|
|
13
|
+
|
|
14
|
+
## Pipeline Overview
|
|
15
|
+
|
|
16
|
+
```
|
|
17
|
+
Phase 1: Initialize — get project config + base URL
|
|
18
|
+
Phase 2: Configure — add module entry (or use existing)
|
|
19
|
+
Phase 3: Explore — browse the page, discover selectors
|
|
20
|
+
Phase 4: Plan — generate seed file + test plan from discoveries
|
|
21
|
+
Phase 5: Review — present plan for user approval
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## MCP Tools Used
|
|
25
|
+
|
|
26
|
+
### e2e-automation MCP (project orchestration)
|
|
27
|
+
|
|
28
|
+
| Tool | Purpose |
|
|
29
|
+
| ------------------------------------ | ------------------------------------------------------------------------------ |
|
|
30
|
+
| `mcp__e2e-automation__e2e_configure` | Init setup, read/add config, get base URL + credentials |
|
|
31
|
+
| `mcp__e2e-automation__e2e_explore` | Get exploration instructions (auth status, known selectors, step-by-step plan) |
|
|
32
|
+
| `mcp__e2e-automation__e2e_plan` | Write seed.spec.js + plan markdown from discovered selectors |
|
|
33
|
+
| `mcp__e2e-automation__e2e_status` | Check pipeline state (config, seed, plans, test results) |
|
|
34
|
+
|
|
35
|
+
### microsoft-playwright MCP (browser exploration)
|
|
36
|
+
|
|
37
|
+
| Tool | Purpose |
|
|
38
|
+
| ----------------------------------------------------- | ----------------------------------------------------- |
|
|
39
|
+
| `mcp__microsoft-playwright__browser_navigate` | Navigate to page URL |
|
|
40
|
+
| `mcp__microsoft-playwright__browser_snapshot` | Capture accessibility tree (primary exploration tool) |
|
|
41
|
+
| `mcp__microsoft-playwright__browser_take_screenshot` | Visual screenshot capture |
|
|
42
|
+
| `mcp__microsoft-playwright__browser_click` | Click elements by ref |
|
|
43
|
+
| `mcp__microsoft-playwright__browser_fill_form` | Fill form fields |
|
|
44
|
+
| `mcp__microsoft-playwright__browser_type` | Type text into elements |
|
|
45
|
+
| `mcp__microsoft-playwright__browser_evaluate` | Run JS on page |
|
|
46
|
+
| `mcp__microsoft-playwright__browser_select_option` | Select dropdown options |
|
|
47
|
+
| `mcp__microsoft-playwright__browser_press_key` | Press keyboard keys |
|
|
48
|
+
| `mcp__microsoft-playwright__browser_hover` | Hover over elements |
|
|
49
|
+
| `mcp__microsoft-playwright__browser_console_messages` | Check console errors |
|
|
50
|
+
| `mcp__microsoft-playwright__browser_network_requests` | Check network activity |
|
|
51
|
+
|
|
52
|
+
## Execution Steps
|
|
53
|
+
|
|
54
|
+
### Phase 1: Initialize
|
|
55
|
+
|
|
56
|
+
Call `mcp__e2e-automation__e2e_automate` to read `instructions.js` and get the full pipeline plan:
|
|
57
|
+
|
|
58
|
+
```json
|
|
59
|
+
{}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
This returns all config entries with their module names, page URLs, instructions, and the exact sequence of tool calls to execute for each.
|
|
63
|
+
|
|
64
|
+
If `instructions.js` doesn't exist or is empty, fall back to `mcp__e2e-automation__e2e_configure` with `action: "init"` to get setup info and ask the user for page URL + instructions.
|
|
65
|
+
|
|
66
|
+
### Phase 2: Configure
|
|
67
|
+
|
|
68
|
+
Determine the module name and page URL:
|
|
69
|
+
|
|
70
|
+
- If user provided a URL (e.g., `http://localhost:5173/home`): derive module name as `@HomePage`
|
|
71
|
+
- If user provided a feature name (e.g., "user form"): ask for the URL, derive `@UserForm`
|
|
72
|
+
- Ask the user for test instructions, or proceed with auto-explore
|
|
73
|
+
|
|
74
|
+
Call `mcp__e2e-automation__e2e_configure` with `action: "add"`:
|
|
75
|
+
|
|
76
|
+
```json
|
|
77
|
+
{
|
|
78
|
+
"action": "add",
|
|
79
|
+
"config": {
|
|
80
|
+
"moduleName": "@HomePage",
|
|
81
|
+
"pageURL": "http://localhost:5173/home",
|
|
82
|
+
"instructions": ["user-provided instructions or empty for auto-explore"]
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### Phase 3: Explore
|
|
88
|
+
|
|
89
|
+
#### Step 3a: Get Exploration Plan
|
|
90
|
+
|
|
91
|
+
Call `mcp__e2e-automation__e2e_explore` to get the exploration plan:
|
|
92
|
+
|
|
93
|
+
```json
|
|
94
|
+
{
|
|
95
|
+
"pageURL": "http://localhost:5173/home",
|
|
96
|
+
"moduleName": "@HomePage",
|
|
97
|
+
"instructions": [],
|
|
98
|
+
"authRequired": true
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
This returns: auth status, known selectors from memory, step-by-step exploration instructions, selector discovery rules, and the output format for Phase 4.
|
|
103
|
+
|
|
104
|
+
#### Step 3b: Authenticate (if required)
|
|
105
|
+
|
|
106
|
+
If the page redirects to a login page, or AUTH_STATUS says NOT_FOUND:
|
|
107
|
+
|
|
108
|
+
1. Use `mcp__microsoft-playwright__browser_snapshot` to identify the login form fields
|
|
109
|
+
2. Use the **auth data** from the `e2e_explore` AUTH_STATUS response (email, password, etc.)
|
|
110
|
+
3. Fill fields and submit using Playwright MCP tools
|
|
111
|
+
4. If prompted for 2FA or verification, use the additional auth data provided (e.g., twoFactorCode)
|
|
112
|
+
5. If auth instructions are included in the response, follow them
|
|
113
|
+
|
|
114
|
+
**CRITICAL:** Use the EXACT credentials from the `e2e_explore` response. Do NOT guess or generate passwords. Claude handles the login flow — no step-by-step instructions are needed, just the data.
|
|
115
|
+
|
|
116
|
+
If AUTH_STATUS is NOT_REQUIRED, skip this step entirely.
|
|
117
|
+
If no auth data is configured, ask the user for credentials.
|
|
118
|
+
|
|
119
|
+
#### Step 3c: Navigate & Explore
|
|
120
|
+
|
|
121
|
+
1. **Navigate to target page:**
|
|
122
|
+
|
|
123
|
+
```
|
|
124
|
+
mcp__microsoft-playwright__browser_navigate → { url: "<pageURL>" }
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
2. **Capture initial state:**
|
|
128
|
+
|
|
129
|
+
```
|
|
130
|
+
mcp__microsoft-playwright__browser_snapshot → full accessibility tree
|
|
131
|
+
mcp__microsoft-playwright__browser_take_screenshot → { type: "png", fullPage: true }
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
3. **Explore interactive elements systematically:**
|
|
135
|
+
|
|
136
|
+
For each element visible in the snapshot:
|
|
137
|
+
- **Buttons/Links** — Record ref, text, role. Click to discover state changes:
|
|
138
|
+
|
|
139
|
+
```
|
|
140
|
+
mcp__microsoft-playwright__browser_click → { ref: "<ref>", element: "<description>" }
|
|
141
|
+
mcp__microsoft-playwright__browser_snapshot → capture new state
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
- **Form fields** — Record ref, label, type. Try filling with test data:
|
|
145
|
+
|
|
146
|
+
```
|
|
147
|
+
mcp__microsoft-playwright__browser_fill_form → { fields: [{ name, type, ref, value }] }
|
|
148
|
+
mcp__microsoft-playwright__browser_snapshot → capture validation state
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
- **Dropdowns/Selects** — Record options:
|
|
152
|
+
|
|
153
|
+
```
|
|
154
|
+
mcp__microsoft-playwright__browser_select_option → { ref, element, values }
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
- **Tables/Lists** — Record structure, headers, row count
|
|
158
|
+
|
|
159
|
+
- **Navigation** — Check tabs, menus, pagination:
|
|
160
|
+
```
|
|
161
|
+
mcp__microsoft-playwright__browser_click → menu items
|
|
162
|
+
mcp__microsoft-playwright__browser_snapshot → capture sub-pages
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
4. **Check for errors:**
|
|
166
|
+
|
|
167
|
+
```
|
|
168
|
+
mcp__microsoft-playwright__browser_console_messages → { level: "error" }
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
5. **Final screenshot:**
|
|
172
|
+
```
|
|
173
|
+
mcp__microsoft-playwright__browser_take_screenshot → { type: "png" }
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
#### Step 3d: Collect Discovered Selectors
|
|
177
|
+
|
|
178
|
+
As you explore, build a selectors array. For each element:
|
|
179
|
+
|
|
180
|
+
```json
|
|
181
|
+
{
|
|
182
|
+
"name": "submitButton",
|
|
183
|
+
"selector": "getByRole('button', { name: 'Submit' })",
|
|
184
|
+
"type": "role",
|
|
185
|
+
"tag": "BUTTON",
|
|
186
|
+
"text": "Submit",
|
|
187
|
+
"description": "Form submit button",
|
|
188
|
+
"validated": true
|
|
189
|
+
}
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
**Selector priority** (derive from snapshot):
|
|
193
|
+
|
|
194
|
+
1. `getByTestId('...')` — if element has `data-testid` attribute
|
|
195
|
+
2. `getByRole('...', { name: '...' })` — from accessibility role + name
|
|
196
|
+
3. `getByText('...')` — from visible text
|
|
197
|
+
4. `getByLabel('...')` — from associated label
|
|
198
|
+
5. `getByPlaceholder('...')` — from placeholder text
|
|
199
|
+
6. CSS selector — last resort
|
|
200
|
+
|
|
201
|
+
Also identify **test scenarios** from the interactions:
|
|
202
|
+
|
|
203
|
+
- Happy path flows
|
|
204
|
+
- Form validation (required fields, format errors)
|
|
205
|
+
- Edge cases (empty state, boundary values)
|
|
206
|
+
- Negative cases (invalid input, error handling)
|
|
207
|
+
|
|
208
|
+
### Phase 4: Generate Plan
|
|
209
|
+
|
|
210
|
+
Call `mcp__e2e-automation__e2e_plan` with all discoveries:
|
|
211
|
+
|
|
212
|
+
```json
|
|
213
|
+
{
|
|
214
|
+
"moduleName": "@HomePage",
|
|
215
|
+
"pageURL": "http://localhost:5173/home",
|
|
216
|
+
"category": "@Modules",
|
|
217
|
+
"selectors": [ ... all discovered selectors ... ],
|
|
218
|
+
"behaviors": {
|
|
219
|
+
"description": "Page with navigation menu, search form, data table",
|
|
220
|
+
"forms": [ ... ],
|
|
221
|
+
"tables": [ ... ]
|
|
222
|
+
},
|
|
223
|
+
"scenarios": [
|
|
224
|
+
{
|
|
225
|
+
"name": "Verify page loads with correct title",
|
|
226
|
+
"steps": ["Navigate to /home", "See heading 'Home'"],
|
|
227
|
+
"type": "happy-path"
|
|
228
|
+
}
|
|
229
|
+
],
|
|
230
|
+
"instructions": [ ... original instructions ... ]
|
|
231
|
+
}
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
This writes:
|
|
235
|
+
|
|
236
|
+
- `e2e-tests/playwright/generated/seed.spec.js` — validated selectors
|
|
237
|
+
- `e2e-tests/plans/{module}-plan.md` — full test plan
|
|
238
|
+
|
|
239
|
+
### Phase 5: Review & Approve
|
|
240
|
+
|
|
241
|
+
Present the plan summary to the user:
|
|
242
|
+
|
|
243
|
+
1. Number of selectors discovered
|
|
244
|
+
2. Scenario count and names
|
|
245
|
+
3. File paths to seed file and plan
|
|
246
|
+
4. Ask:
|
|
247
|
+
- **Approve** — plan is ready for BDD generation (Phase 2 of MCP, future)
|
|
248
|
+
- **View Full Plan** — show the plan markdown content
|
|
249
|
+
- **Modify** — adjust scenarios or re-explore
|
|
250
|
+
|
|
251
|
+
Call `mcp__e2e-automation__e2e_status` to confirm pipeline state.
|
|
252
|
+
|
|
253
|
+
## Error Handling
|
|
254
|
+
|
|
255
|
+
- **Browser not installed:** Call `mcp__microsoft-playwright__browser_install`
|
|
256
|
+
- **Page load timeout:** Retry once, then report to user
|
|
257
|
+
- **Auth failure:** Report credentials issue, ask user to verify
|
|
258
|
+
- **No interactive elements found:** Take screenshot, ask user if page loaded correctly
|
|
259
|
+
- **Console errors on page:** Report them but continue exploration
|
|
260
|
+
|
|
261
|
+
## CRITICAL: Sequential Execution
|
|
262
|
+
|
|
263
|
+
Execute phases ONE BY ONE. Never skip Phase 3 (exploration) — the selectors must come from a live browser session.
|
|
264
|
+
|
|
265
|
+
Always close the browser when done:
|
|
266
|
+
|
|
267
|
+
```
|
|
268
|
+
mcp__microsoft-playwright__browser_close
|
|
269
|
+
```
|
package/e2e-tests/.env.testing
CHANGED
package/install.sh
CHANGED
|
@@ -112,6 +112,15 @@ echo "📦 Step 5: Installing documentation..."
|
|
|
112
112
|
cp "$PLUGIN_DIR/README-TESTING.md" "$TARGET_DIR/"
|
|
113
113
|
echo " ✅ README-TESTING.md installed"
|
|
114
114
|
|
|
115
|
+
# ── Step 5b: Install .mcp.json (MCP server config for Claude Code) ──
|
|
116
|
+
if [ ! -f "$TARGET_DIR/.mcp.json" ]; then
|
|
117
|
+
echo "📦 Step 5b: Installing .mcp.json (MCP server config)..."
|
|
118
|
+
cp "$PLUGIN_DIR/mcp.json.template" "$TARGET_DIR/.mcp.json"
|
|
119
|
+
echo " ✅ .mcp.json installed — Claude Code will discover e2e-automation tools"
|
|
120
|
+
else
|
|
121
|
+
echo "⏭️ Step 5b: .mcp.json already exists — skipping"
|
|
122
|
+
fi
|
|
123
|
+
|
|
115
124
|
# ── Step 6: Merge dependencies + scripts into package.json ──
|
|
116
125
|
echo "📦 Step 6: Merging dependencies and scripts into package.json..."
|
|
117
126
|
if [ -f "$TARGET_DIR/package.json" ]; then
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@specwright/plugin",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.5",
|
|
4
4
|
"description": "Drop-in E2E test automation framework plugin — Playwright BDD + Claude Code agents",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"bin": {
|
|
@@ -17,6 +17,7 @@
|
|
|
17
17
|
".gitignore.snippet",
|
|
18
18
|
".claude_agents/",
|
|
19
19
|
".claude_skills/",
|
|
20
|
+
"mcp.json.template",
|
|
20
21
|
".claude_rules/",
|
|
21
22
|
".claude_agent-memory/",
|
|
22
23
|
".claude_memory_MEMORY.md",
|