@specwright/plugin 0.1.0 → 0.1.1
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.
- package/README.md +255 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
# @specwright/plugin
|
|
2
|
+
|
|
3
|
+
AI-powered E2E test automation framework. Drop into any web app — get Playwright BDD tests, Claude Code agents, and self-healing test execution.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@specwright/plugin)
|
|
6
|
+
[](https://github.com/SanthoshDhandapani/specwright/blob/main/LICENSE)
|
|
7
|
+
|
|
8
|
+
## Install
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
npx @specwright/plugin init
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Then:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
pnpm install # Install dependencies
|
|
18
|
+
npx playwright install # Install browsers
|
|
19
|
+
pnpm test:bdd:auth # Verify setup (runs 7 auth tests)
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## What You Get
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
your-project/
|
|
26
|
+
├── playwright.config.ts Multi-project BDD configuration
|
|
27
|
+
├── e2e-tests/
|
|
28
|
+
│ ├── instructions.js Pipeline config (your test definitions)
|
|
29
|
+
│ ├── instructions.example.js Example configs (text, Jira, CSV, workflow)
|
|
30
|
+
│ ├── playwright/
|
|
31
|
+
│ │ ├── fixtures.js Custom test fixtures (Given/When/Then/Before/After)
|
|
32
|
+
│ │ ├── auth.setup.js Authentication state creation
|
|
33
|
+
│ │ ├── global.setup.js Cleanup marker strategy
|
|
34
|
+
│ │ └── generated/seed.spec.js Validated selectors from exploration
|
|
35
|
+
│ ├── features/playwright-bdd/
|
|
36
|
+
│ │ ├── @Modules/ Single-module test features
|
|
37
|
+
│ │ │ └── @Authentication/ Pre-built auth tests (7 scenarios)
|
|
38
|
+
│ │ ├── @Workflows/ Cross-module workflow tests
|
|
39
|
+
│ │ └── shared/ Global step definitions
|
|
40
|
+
│ ├── utils/
|
|
41
|
+
│ │ ├── stepHelpers.js processDataTable + validateExpectations
|
|
42
|
+
│ │ └── testDataGenerator.js Faker-based data generation
|
|
43
|
+
│ └── data/
|
|
44
|
+
│ ├── authenticationData.js Login form locators + credentials
|
|
45
|
+
│ └── testConfig.js Routes, timeouts, base URL
|
|
46
|
+
└── .claude/
|
|
47
|
+
├── agents/ 8 AI agent system prompts
|
|
48
|
+
├── skills/ 7 Claude Code skills (/e2e-automate, etc.)
|
|
49
|
+
└── rules/ Architecture + conventions docs
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Quick Start
|
|
53
|
+
|
|
54
|
+
### 1. Configure Authentication
|
|
55
|
+
|
|
56
|
+
Update `e2e-tests/data/authenticationData.js` to match your app's login form:
|
|
57
|
+
|
|
58
|
+
```javascript
|
|
59
|
+
locators: {
|
|
60
|
+
emailInput: { testId: 'your-email-input' },
|
|
61
|
+
emailSubmitButton: { testId: 'your-submit-button' },
|
|
62
|
+
passwordInput: { testId: 'your-password-input' },
|
|
63
|
+
loginSubmitButton: { testId: 'your-login-button' },
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### 2. Configure Routes
|
|
68
|
+
|
|
69
|
+
Update `e2e-tests/data/testConfig.js`:
|
|
70
|
+
|
|
71
|
+
```javascript
|
|
72
|
+
routes: {
|
|
73
|
+
Home: '/',
|
|
74
|
+
Dashboard: '/dashboard',
|
|
75
|
+
SignIn: '/signin',
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### 3. Set Environment Variables
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
# .env
|
|
83
|
+
BASE_URL=http://localhost:5173
|
|
84
|
+
TEST_USER_EMAIL=your-email@example.com
|
|
85
|
+
TEST_USER_PASSWORD=your-password
|
|
86
|
+
HEADLESS=true
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### 4. Run Tests
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
pnpm test:bdd # All tests
|
|
93
|
+
pnpm test:bdd:auth # Authentication tests only
|
|
94
|
+
pnpm test:bdd:debug # Debug mode
|
|
95
|
+
pnpm report:playwright # View HTML report
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## Generate Tests with AI
|
|
99
|
+
|
|
100
|
+
### Option 1: Full Pipeline
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
# Configure what to test
|
|
104
|
+
cp e2e-tests/instructions.example.js e2e-tests/instructions.js
|
|
105
|
+
# Edit instructions.js with your pages and test descriptions
|
|
106
|
+
|
|
107
|
+
# Run the 10-phase pipeline
|
|
108
|
+
claude
|
|
109
|
+
/e2e-automate
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### Option 2: Step by Step
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
/e2e-plan /dashboard # Explore a page, discover selectors
|
|
116
|
+
/e2e-generate plan.md # Generate .feature + steps.js
|
|
117
|
+
/e2e-heal # Auto-fix failing tests
|
|
118
|
+
/e2e-run # Execute tests
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### Option 3: Specwright Desktop App
|
|
122
|
+
|
|
123
|
+
Use the [Specwright desktop app](https://github.com/SanthoshDhandapani/specwright) for a visual UI — configure tests, see real-time progress, approve plans before generation.
|
|
124
|
+
|
|
125
|
+
## The 10-Phase Pipeline
|
|
126
|
+
|
|
127
|
+
```
|
|
128
|
+
Phase 1: Read Config instructions.js
|
|
129
|
+
Phase 2: Detect & Route Jira / File / Text input
|
|
130
|
+
Phase 3: Process Input Convert to parsed test plan
|
|
131
|
+
Phase 4: Explore App Playwright browser exploration
|
|
132
|
+
Phase 5: Validate Seeds Run discovered selectors (optional)
|
|
133
|
+
Phase 6: User Approval Review plan before generation
|
|
134
|
+
Phase 7: Generate BDD Create .feature + steps.js
|
|
135
|
+
Phase 8: Execute & Heal Run tests + auto-fix failures
|
|
136
|
+
Phase 9: Cleanup Aggregate results
|
|
137
|
+
Phase 10: Quality Review Score (0-100) + summary
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
## Key Features
|
|
141
|
+
|
|
142
|
+
### Playwright BDD
|
|
143
|
+
|
|
144
|
+
Gherkin `.feature` files compiled to Playwright specs via [playwright-bdd](https://github.com/nicolo-ribaudo/playwright-bdd). Write tests in natural language:
|
|
145
|
+
|
|
146
|
+
```gherkin
|
|
147
|
+
@authentication @smoke
|
|
148
|
+
Feature: User Authentication
|
|
149
|
+
|
|
150
|
+
Scenario: Successful login flow
|
|
151
|
+
Given I navigate to "Sign In"
|
|
152
|
+
When I enter my email "user@example.com"
|
|
153
|
+
And I click the proceed button
|
|
154
|
+
And I enter my password
|
|
155
|
+
And I click the login button
|
|
156
|
+
Then I should be redirected to the home page
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### 8 AI Agents
|
|
160
|
+
|
|
161
|
+
| Agent | Purpose |
|
|
162
|
+
|-------|---------|
|
|
163
|
+
| `input-processor` | Convert Jira/Excel/CSV/text to test plans |
|
|
164
|
+
| `jira-processor` | Fetch and parse Jira tickets |
|
|
165
|
+
| `playwright-test-planner` | Explore apps, discover selectors |
|
|
166
|
+
| `bdd-generator` | Create .feature files + step skeletons |
|
|
167
|
+
| `code-generator` | Fill in Playwright implementation code |
|
|
168
|
+
| `execution-manager` | Run tests, investigate source code |
|
|
169
|
+
| `playwright-test-healer` | Auto-fix failing tests |
|
|
170
|
+
| `playwright-test-generator` | Direct Playwright code generation |
|
|
171
|
+
|
|
172
|
+
### 3-Layer Data Persistence
|
|
173
|
+
|
|
174
|
+
```
|
|
175
|
+
Layer 1: page.testData Scenario-scoped (cleared each scenario)
|
|
176
|
+
Layer 2: featureDataCache In-memory (survives scenario boundaries)
|
|
177
|
+
Layer 3: test-data/{scope}.json File-backed (survives worker restarts)
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### processDataTable
|
|
181
|
+
|
|
182
|
+
Declarative form filling with `<gen_test_data>` (faker generation) and `<from_test_data>` (cache reading):
|
|
183
|
+
|
|
184
|
+
```gherkin
|
|
185
|
+
When I fill the form with:
|
|
186
|
+
| Field Name | Value | Type |
|
|
187
|
+
| Name | <gen_test_data> | SharedGenerated |
|
|
188
|
+
| Email | <gen_test_data> | SharedGenerated |
|
|
189
|
+
| Phone | <gen_test_data> | SharedGenerated |
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### Cross-Module Workflows
|
|
193
|
+
|
|
194
|
+
Precondition features create shared data, consumer features use it:
|
|
195
|
+
|
|
196
|
+
```
|
|
197
|
+
@Workflows/@UserJourney/
|
|
198
|
+
├── @0-Precondition/ Create test data (serial, runs first)
|
|
199
|
+
├── @1-Favorites/ Consumer (parallel, loads precondition data)
|
|
200
|
+
└── @2-Watchlist/ Consumer (parallel, loads precondition data)
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
## Instructions Format
|
|
204
|
+
|
|
205
|
+
`e2e-tests/instructions.js` defines what to test:
|
|
206
|
+
|
|
207
|
+
```javascript
|
|
208
|
+
export default [
|
|
209
|
+
{
|
|
210
|
+
moduleName: '@Dashboard',
|
|
211
|
+
category: '@Modules',
|
|
212
|
+
fileName: 'dashboard',
|
|
213
|
+
pageURL: 'http://localhost:5173/dashboard',
|
|
214
|
+
instructions: [
|
|
215
|
+
'Navigate to the dashboard',
|
|
216
|
+
'Verify summary cards are displayed',
|
|
217
|
+
'Click on a card and verify detail view',
|
|
218
|
+
],
|
|
219
|
+
explore: true,
|
|
220
|
+
runExploredCases: false,
|
|
221
|
+
runGeneratedCases: false,
|
|
222
|
+
},
|
|
223
|
+
];
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
## Prerequisites
|
|
227
|
+
|
|
228
|
+
- **Node.js** 20+
|
|
229
|
+
- **pnpm** (or npm/yarn)
|
|
230
|
+
- **Claude Code CLI** — [Get it here](https://claude.ai/code)
|
|
231
|
+
|
|
232
|
+
## Options
|
|
233
|
+
|
|
234
|
+
```bash
|
|
235
|
+
# Install with authentication module (default)
|
|
236
|
+
npx @specwright/plugin init
|
|
237
|
+
|
|
238
|
+
# Skip authentication module
|
|
239
|
+
npx @specwright/plugin init --skip-auth
|
|
240
|
+
|
|
241
|
+
# Install to a specific directory
|
|
242
|
+
npx @specwright/plugin init /path/to/project
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
## Links
|
|
246
|
+
|
|
247
|
+
- [GitHub Repository](https://github.com/SanthoshDhandapani/specwright)
|
|
248
|
+
- [Desktop App](https://github.com/SanthoshDhandapani/specwright/tree/main/apps/desktop)
|
|
249
|
+
- [ShowBuff Demo App](https://github.com/SanthoshDhandapani/specwright/tree/main/apps/examples/show-buff)
|
|
250
|
+
- [Plugin Documentation](https://github.com/SanthoshDhandapani/specwright/blob/main/packages/plugin/PLUGIN.md)
|
|
251
|
+
- [Testing Guide](https://github.com/SanthoshDhandapani/specwright/blob/main/packages/plugin/README-TESTING.md)
|
|
252
|
+
|
|
253
|
+
## License
|
|
254
|
+
|
|
255
|
+
MIT
|