fair-playwright 1.0.0 → 1.1.0

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.
Files changed (3) hide show
  1. package/README.md +53 -201
  2. package/package.json +8 -3
  3. package/resources/fair-playwright-logo.png +0 -0
package/README.md CHANGED
@@ -1,19 +1,22 @@
1
- # fair-playwright
1
+ <div align="center">
2
+ <img src="resources/fair-playwright-logo.png" alt="fair-playwright" width="200" />
2
3
 
3
- > AI-optimized Playwright test reporter with progressive terminal output and hierarchical step management
4
+ # fair-playwright
4
5
 
5
- [![npm version](https://img.shields.io/npm/v/fair-playwright.svg)](https://www.npmjs.com/package/fair-playwright)
6
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
+ > AI-optimized Playwright test reporter with progressive terminal output and hierarchical step management
7
+
8
+ [![npm version](https://img.shields.io/npm/v/fair-playwright.svg)](https://www.npmjs.com/package/fair-playwright)
9
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
10
+
11
+ </div>
7
12
 
8
13
  ## Features
9
14
 
10
- - ðŸĪ– **AI-First Design** - Structured output optimized for LLM context and AI code assistants
11
- - 📊 **MAJOR/MINOR Step Hierarchy** - Track test flows at two levels for better organization
15
+ - ðŸĪ– **AI-First Design** - Structured output optimized for LLM context
16
+ - 📊 **MAJOR/MINOR Step Hierarchy** - Two-level test organization
12
17
  - ⚡ **Progressive Terminal Output** - Live updates with smart compression
13
- - ðŸŽŊ **Zero Config** - Sensible defaults, works out of the box
14
- - ðŸŠķ **Lightweight** - Minimal dependencies, <100KB bundle size
15
- - 🔒 **Type Safe** - Full TypeScript support with exported types
16
- - 🔌 **MCP Server** - Built-in integration for AI coding assistants
18
+ - ðŸŽŊ **Zero Config** - Works out of the box
19
+ - 🔌 **MCP Server** - Built-in AI assistant integration
17
20
 
18
21
  ## Installation
19
22
 
@@ -34,229 +37,78 @@ export default defineConfig({
34
37
  });
35
38
  ```
36
39
 
37
- ### 2. Write Tests with Step Hierarchy
38
-
39
- **Inline Mode (Quick tests):**
40
+ ### 2. Write Tests
40
41
 
41
42
  ```typescript
42
43
  import { test } from '@playwright/test';
43
44
  import { e2e } from 'fair-playwright';
44
45
 
45
46
  test('user login', async ({ page }) => {
46
- await e2e.minor('Open login page', async () => {
47
- await page.goto('/login');
48
- }, { success: 'Page opened', failure: 'Failed to open' });
49
-
50
- await e2e.minor('Fill credentials', async () => {
51
- await page.getByLabel('Email').fill('test@example.com');
52
- await page.getByLabel('Password').fill('password123');
53
- }, { success: 'Filled', failure: 'Failed to fill' });
54
-
55
- await e2e.minor('Submit form', async () => {
56
- await page.getByRole('button', { name: 'Login' }).click();
57
- }, { success: 'Submitted', failure: 'Failed to submit' });
58
- });
59
- ```
60
-
61
- **Declarative Mode (Complex flows):**
62
-
63
- ```typescript
64
- await e2e.major('User login flow', {
65
- success: 'User logged in successfully',
66
- failure: 'Login failed',
67
- steps: [
68
- {
69
- title: 'Open login page',
70
- success: 'Page opened',
71
- failure: 'Failed to open',
72
- action: async () => {
73
- await page.goto('/login');
74
- }
75
- },
76
- {
77
- title: 'Fill credentials',
78
- success: 'Credentials filled',
79
- failure: 'Failed to fill',
80
- action: async () => {
81
- await page.getByLabel('Email').fill('test@example.com');
82
- await page.getByLabel('Password').fill('password123');
83
- }
84
- },
85
- {
86
- title: 'Submit form',
87
- success: 'Form submitted',
88
- failure: 'Failed to submit',
89
- action: async () => {
90
- await page.getByRole('button', { name: 'Login' }).click();
91
- }
92
- }
93
- ]
94
- });
95
- ```
96
-
97
- ## Configuration
98
-
99
- ```typescript
100
- // playwright.config.ts
101
- export default defineConfig({
102
- reporter: [
103
- ['fair-playwright', {
104
- mode: 'progressive', // 'progressive' | 'full' | 'minimal'
105
- aiOptimized: true,
106
- output: {
107
- console: true,
108
- ai: './test-results/ai-summary.md',
109
- json: './test-results/results.json'
47
+ await e2e.major('User login flow', {
48
+ success: 'User logged in successfully',
49
+ failure: 'Login failed',
50
+ steps: [
51
+ {
52
+ title: 'Open login page',
53
+ success: 'Page opened',
54
+ action: async () => {
55
+ await page.goto('/login');
56
+ }
110
57
  },
111
- stepClassification: {
112
- durationThreshold: 1000, // Steps > 1s are MAJOR
113
- autoDetect: true
114
- },
115
- progressive: {
116
- clearCompleted: true,
117
- updateInterval: 100 // ms
58
+ {
59
+ title: 'Submit credentials',
60
+ success: 'Form submitted',
61
+ action: async () => {
62
+ await page.getByLabel('Email').fill('user@example.com');
63
+ await page.getByLabel('Password').fill('password');
64
+ await page.getByRole('button', { name: 'Login' }).click();
65
+ }
118
66
  }
119
- }]
120
- ]
67
+ ]
68
+ });
121
69
  });
122
70
  ```
123
71
 
124
- ## MAJOR vs MINOR Steps
125
-
126
- - **MAJOR steps**: High-level user flows (e.g., "User logs in", "Checkout process")
127
- - **MINOR steps**: Detailed actions within a major step (e.g., "Fill email", "Click submit")
128
-
129
- This two-level hierarchy helps both humans and AI understand test structure at a glance.
72
+ ### 3. Run Tests
130
73
 
131
- ## MCP Server Integration
132
-
133
- Fair-playwright includes a full **Model Context Protocol (MCP)** server for AI assistant integration.
134
-
135
- ### Features
136
-
137
- The MCP server exposes:
138
- - **3 Resources**: Test results, summary, and failure details
139
- - **5 Tools**: Query tests, filter by status, get step details, and more
140
- - **Streaming Support**: Real-time test result updates
141
-
142
- ### Setup with Claude Desktop
143
-
144
- Add to `claude_desktop_config.json`:
145
-
146
- ```json
147
- {
148
- "mcpServers": {
149
- "fair-playwright": {
150
- "command": "npx",
151
- "args": ["fair-playwright-mcp"],
152
- "env": {
153
- "FAIR_PLAYWRIGHT_RESULTS": "./test-results/results.json"
154
- }
155
- }
156
- }
157
- }
74
+ ```bash
75
+ npx playwright test
158
76
  ```
159
77
 
160
- ### Available Resources
78
+ ## Documentation
161
79
 
162
- - `fair-playwright://test-results` - Complete test execution data (JSON)
163
- - `fair-playwright://test-summary` - AI-optimized summary (Markdown)
164
- - `fair-playwright://failures` - Detailed failure information (Markdown)
80
+ 📚 **Full Documentation**: https://baranaytass.github.io/fair-playwright/
165
81
 
166
- ### Available Tools
82
+ - [Getting Started](https://baranaytass.github.io/fair-playwright/guide/getting-started)
83
+ - [API Reference](https://baranaytass.github.io/fair-playwright/api/)
84
+ - [Configuration](https://baranaytass.github.io/fair-playwright/guide/configuration)
85
+ - [MCP Integration](https://baranaytass.github.io/fair-playwright/guide/mcp)
86
+ - [Examples](https://baranaytass.github.io/fair-playwright/examples/)
167
87
 
168
- - `get_test_results` - Get all test results with full details
169
- - `get_failure_summary` - Get AI-optimized failure summary
170
- - `query_test` - Search for specific test by title
171
- - `get_tests_by_status` - Filter tests by passed/failed/skipped
172
- - `get_step_details` - Get MAJOR/MINOR step details for a test
88
+ ## MCP Server
173
89
 
174
- ### CLI Options
90
+ Fair-playwright includes a Model Context Protocol server for AI assistants:
175
91
 
176
92
  ```bash
177
93
  npx fair-playwright-mcp --help
178
- npx fair-playwright-mcp --results-path ./custom-results.json --verbose
179
- ```
180
-
181
- ## Output Examples
182
-
183
- ### Terminal (Progressive Mode)
184
-
185
- ```
186
- ✓ Authentication (2/2 tests, 1.2s)
187
-
188
- âģ Payment Processing (1/3 tests)
189
- ✓ Validate cart (234ms)
190
- âŸģ Process payment (running 2.1s)
191
- Step 1/4: Navigate to checkout ✓
192
- Step 2/4: Fill payment form ✓
193
- Step 3/4: Submit payment âŸģ
194
-
195
- âļ Remaining: Order Confirmation (0/2 tests)
196
94
  ```
197
95
 
198
- ### AI-Optimized Output (Markdown)
199
-
200
- Generates structured markdown summaries perfect for AI analysis:
201
-
202
- ```markdown
203
- # Test Results: E2E Payment Flow
204
-
205
- **Status**: ❌ FAILED (2/3 test suites passed)
206
- **Duration**: 15.4s
207
-
208
- ## ✅ Authentication Suite (2/2 tests, 1.2s)
209
- All tests passed.
210
-
211
- ## ❌ Payment Processing (1/2 tests, 8.3s)
212
-
213
- ### ❌ Payment Submission (5.1s - FAILED)
96
+ See [MCP Guide](https://baranaytass.github.io/fair-playwright/guide/mcp) for details.
214
97
 
215
- **Error**: Timeout waiting for element
216
- **Location**: tests/payment.spec.ts:45:12
98
+ ## Examples
217
99
 
218
- **Steps Executed**:
219
- 1. ✅ Navigate to /checkout (189ms)
220
- 2. ✅ Fill payment form (456ms)
221
- 3. ❌ Click submit button - Element not found
100
+ Check out the [examples](./examples) directory for complete working examples.
222
101
 
223
- **Artifacts**:
224
- - Screenshot: ./test-results/payment-fail-001.png
225
- - Trace: ./test-results/trace.zip
226
- ```
227
-
228
- ## Why fair-playwright?
229
-
230
- - **For Developers**: Progressive output keeps you focused on what matters
231
- - **For AI**: Structured markdown summaries help AI understand test failures instantly
232
- - **For Teams**: Hierarchical steps document test flows automatically
233
-
234
- ## Development
235
-
236
- ```bash
237
- # Install dependencies
238
- npm install
239
-
240
- # Build
241
- npm run build
242
-
243
- # Run tests
244
- npm test
102
+ ## Contributing
245
103
 
246
- # Run integration tests
247
- npm run test:integration
248
- ```
104
+ Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md).
249
105
 
250
106
  ## License
251
107
 
252
108
  MIT ÂĐ [Baran Aytas](https://github.com/baranaytass)
253
109
 
254
- ## Contributing
255
-
256
- Contributions are welcome! Please feel free to submit a Pull Request.
257
-
258
110
  ## Links
259
111
 
260
- - [GitHub Repository](https://github.com/baranaytass/fair-playwright)
261
- - [Issue Tracker](https://github.com/baranaytass/fair-playwright/issues)
112
+ - [Documentation](https://baranaytass.github.io/fair-playwright/)
262
113
  - [npm Package](https://www.npmjs.com/package/fair-playwright)
114
+ - [GitHub Issues](https://github.com/baranaytass/fair-playwright/issues)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fair-playwright",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "AI-optimized Playwright test reporter with progressive terminal output and hierarchical step management",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -18,6 +18,7 @@
18
18
  },
19
19
  "files": [
20
20
  "dist",
21
+ "resources",
21
22
  "README.md",
22
23
  "LICENSE"
23
24
  ],
@@ -34,7 +35,10 @@
34
35
  "typecheck": "tsc --noEmit",
35
36
  "changeset": "changeset",
36
37
  "release": "changeset publish",
37
- "prepublishOnly": "npm run build"
38
+ "prepublishOnly": "npm run build",
39
+ "docs:dev": "vitepress dev docs",
40
+ "docs:build": "vitepress build docs",
41
+ "docs:preview": "vitepress preview docs"
38
42
  },
39
43
  "keywords": [
40
44
  "playwright",
@@ -58,7 +62,7 @@
58
62
  "bugs": {
59
63
  "url": "https://github.com/baranaytass/fair-playwright/issues"
60
64
  },
61
- "homepage": "https://github.com/baranaytass/fair-playwright#readme",
65
+ "homepage": "https://baranaytass.github.io/fair-playwright/",
62
66
  "author": "Baran Aytas",
63
67
  "license": "MIT",
64
68
  "peerDependencies": {
@@ -80,6 +84,7 @@
80
84
  "prettier": "^3.4.2",
81
85
  "tsup": "^8.3.5",
82
86
  "typescript": "^5.7.2",
87
+ "vitepress": "^1.6.4",
83
88
  "vitest": "^2.1.8"
84
89
  },
85
90
  "engines": {