fair-playwright 1.0.0 → 1.2.0

package/README.md

@@ -1,19 +1,22 @@
-# fair-playwright
+<div align="center">
+  <img src="resources/fair-playwright-logo.png" alt="fair-playwright" width="500" />
 
-> AI-optimized Playwright test reporter with progressive terminal output and hierarchical step management
+  #
 
-[![npm version](https://img.shields.io/npm/v/fair-playwright.svg)](https://www.npmjs.com/package/fair-playwright)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+AI-optimized Playwright test reporter with progressive terminal output and hierarchical step management
+
+  [![npm version](https://img.shields.io/npm/v/fair-playwright.svg)](https://www.npmjs.com/package/fair-playwright)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+</div>
 
 ## Features
 
-- 🤖 **AI-First Design** - Structured output optimized for LLM context and AI code assistants
-- 📊 **MAJOR/MINOR Step Hierarchy** - Track test flows at two levels for better organization
+- 🤖 **AI-First Design** - Structured output optimized for LLM context
+- 📊 **MAJOR/MINOR Step Hierarchy** - Two-level test organization
 - ⚡ **Progressive Terminal Output** - Live updates with smart compression
-- 🎯 **Zero Config** - Sensible defaults, works out of the box
-- 🪶 **Lightweight** - Minimal dependencies, <100KB bundle size
-- 🔒 **Type Safe** - Full TypeScript support with exported types
-- 🔌 **MCP Server** - Built-in integration for AI coding assistants
+- 🎯 **Zero Config** - Works out of the box
+- 🔌 **MCP Server** - Built-in AI assistant integration
 
 ## Installation
 
@@ -34,229 +37,97 @@ export default defineConfig({
 });
 ```
 
-### 2. Write Tests with Step Hierarchy
+### 2. Write Tests
 
-**Inline Mode (Quick tests):**
+**Quick Mode** (v1.1.0+) - Compact syntax:
 
 ```typescript
 import { test } from '@playwright/test';
 import { e2e } from 'fair-playwright';
 
 test('user login', async ({ page }) => {
-  await e2e.minor('Open login page', async () => {
-    await page.goto('/login');
-  }, { success: 'Page opened', failure: 'Failed to open' });
-
-  await e2e.minor('Fill credentials', async () => {
-    await page.getByLabel('Email').fill('test@example.com');
-    await page.getByLabel('Password').fill('password123');
-  }, { success: 'Filled', failure: 'Failed to fill' });
-
-  await e2e.minor('Submit form', async () => {
-    await page.getByRole('button', { name: 'Login' }).click();
-  }, { success: 'Submitted', failure: 'Failed to submit' });
-});
-```
-
-**Declarative Mode (Complex flows):**
-
-```typescript
-await e2e.major('User login flow', {
-  success: 'User logged in successfully',
-  failure: 'Login failed',
-  steps: [
-    {
-      title: 'Open login page',
-      success: 'Page opened',
-      failure: 'Failed to open',
-      action: async () => {
-        await page.goto('/login');
-      }
-    },
-    {
-      title: 'Fill credentials',
-      success: 'Credentials filled',
-      failure: 'Failed to fill',
-      action: async () => {
-        await page.getByLabel('Email').fill('test@example.com');
-        await page.getByLabel('Password').fill('password123');
-      }
-    },
-    {
-      title: 'Submit form',
-      success: 'Form submitted',
-      failure: 'Failed to submit',
-      action: async () => {
-        await page.getByRole('button', { name: 'Login' }).click();
-      }
-    }
-  ]
+  await e2e.quick('User login flow', [
+    ['Open login page', async () => {
+      await page.goto('/login');
+    }],
+    ['Submit credentials', async () => {
+      await page.getByLabel('Email').fill('user@example.com');
+      await page.getByLabel('Password').fill('password');
+      await page.getByRole('button', { name: 'Login' }).click();
+    }]
+  ]);
 });
 ```
 
-## Configuration
+**Declarative Mode** - Full control:
 
 ```typescript
-// playwright.config.ts
-export default defineConfig({
-  reporter: [
-    ['fair-playwright', {
-      mode: 'progressive',          // 'progressive' | 'full' | 'minimal'
-      aiOptimized: true,
-      output: {
-        console: true,
-        ai: './test-results/ai-summary.md',
-        json: './test-results/results.json'
-      },
-      stepClassification: {
-        durationThreshold: 1000,    // Steps > 1s are MAJOR
-        autoDetect: true
+test('user login', async ({ page }) => {
+  await e2e.major('User login flow', {
+    success: 'User logged in successfully',
+    failure: 'Login failed',
+    steps: [
+      {
+        title: 'Open login page',
+        success: 'Page opened',
+        action: async () => {
+          await page.goto('/login');
+        }
       },
-      progressive: {
-        clearCompleted: true,
-        updateInterval: 100         // ms
+      {
+        title: 'Submit credentials',
+        success: 'Form submitted',
+        action: async () => {
+          await page.getByLabel('Email').fill('user@example.com');
+          await page.getByLabel('Password').fill('password');
+          await page.getByRole('button', { name: 'Login' }).click();
+        }
       }
-    }]
-  ]
+    ]
+  });
 });
 ```
 
-## MAJOR vs MINOR Steps
-
-- **MAJOR steps**: High-level user flows (e.g., "User logs in", "Checkout process")
-- **MINOR steps**: Detailed actions within a major step (e.g., "Fill email", "Click submit")
-
-This two-level hierarchy helps both humans and AI understand test structure at a glance.
-
-## MCP Server Integration
-
-Fair-playwright includes a full **Model Context Protocol (MCP)** server for AI assistant integration.
+### 3. Run Tests
 
-### Features
-
-The MCP server exposes:
-- **3 Resources**: Test results, summary, and failure details
-- **5 Tools**: Query tests, filter by status, get step details, and more
-- **Streaming Support**: Real-time test result updates
-
-### Setup with Claude Desktop
-
-Add to `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "fair-playwright": {
-      "command": "npx",
-      "args": ["fair-playwright-mcp"],
-      "env": {
-        "FAIR_PLAYWRIGHT_RESULTS": "./test-results/results.json"
-      }
-    }
-  }
-}
+```bash
+npx playwright test
 ```
 
-### Available Resources
+## Documentation
 
-- `fair-playwright://test-results` - Complete test execution data (JSON)
-- `fair-playwright://test-summary` - AI-optimized summary (Markdown)
-- `fair-playwright://failures` - Detailed failure information (Markdown)
+📚 **Full Documentation**: https://baranaytass.github.io/fair-playwright/
 
-### Available Tools
+- [Getting Started](https://baranaytass.github.io/fair-playwright/guide/getting-started)
+- [API Reference](https://baranaytass.github.io/fair-playwright/api/)
+- [Configuration](https://baranaytass.github.io/fair-playwright/guide/configuration)
+- [MCP Integration](https://baranaytass.github.io/fair-playwright/guide/mcp)
+- [Examples](https://baranaytass.github.io/fair-playwright/examples/)
 
-- `get_test_results` - Get all test results with full details
-- `get_failure_summary` - Get AI-optimized failure summary
-- `query_test` - Search for specific test by title
-- `get_tests_by_status` - Filter tests by passed/failed/skipped
-- `get_step_details` - Get MAJOR/MINOR step details for a test
+## MCP Server
 
-### CLI Options
+Fair-playwright includes a Model Context Protocol server for AI assistants:
 
 ```bash
 npx fair-playwright-mcp --help
-npx fair-playwright-mcp --results-path ./custom-results.json --verbose
 ```
 
-## Output Examples
+See [MCP Guide](https://baranaytass.github.io/fair-playwright/guide/mcp) for details.
 
-### Terminal (Progressive Mode)
+## Examples
 
-```
-✓ Authentication (2/2 tests, 1.2s)
-
-⏳ Payment Processing (1/3 tests)
-  ✓ Validate cart (234ms)
-  ⟳ Process payment (running 2.1s)
-    Step 1/4: Navigate to checkout ✓
-    Step 2/4: Fill payment form ✓
-    Step 3/4: Submit payment ⟳
-
-⏸ Remaining: Order Confirmation (0/2 tests)
-```
-
-### AI-Optimized Output (Markdown)
-
-Generates structured markdown summaries perfect for AI analysis:
-
-```markdown
-# Test Results: E2E Payment Flow
-
-**Status**: ❌ FAILED (2/3 test suites passed)
-**Duration**: 15.4s
-
-## ✅ Authentication Suite (2/2 tests, 1.2s)
-All tests passed.
-
-## ❌ Payment Processing (1/2 tests, 8.3s)
-
-### ❌ Payment Submission (5.1s - FAILED)
-
-**Error**: Timeout waiting for element
-**Location**: tests/payment.spec.ts:45:12
-
-**Steps Executed**:
-1. ✅ Navigate to /checkout (189ms)
-2. ✅ Fill payment form (456ms)
-3. ❌ Click submit button - Element not found
+Check out the [examples](./examples) directory for complete working examples.
 
-**Artifacts**:
-- Screenshot: ./test-results/payment-fail-001.png
-- Trace: ./test-results/trace.zip
-```
-
-## Why fair-playwright?
-
-- **For Developers**: Progressive output keeps you focused on what matters
-- **For AI**: Structured markdown summaries help AI understand test failures instantly
-- **For Teams**: Hierarchical steps document test flows automatically
-
-## Development
-
-```bash
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Run tests
-npm test
+## Contributing
 
-# Run integration tests
-npm run test:integration
-```
+Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## License
 
 MIT © [Baran Aytas](https://github.com/baranaytass)
 
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
 ## Links
 
-- [GitHub Repository](https://github.com/baranaytass/fair-playwright)
-- [Issue Tracker](https://github.com/baranaytass/fair-playwright/issues)
+- [Documentation](https://baranaytass.github.io/fair-playwright/)
 - [npm Package](https://www.npmjs.com/package/fair-playwright)
+- [GitHub Issues](https://github.com/baranaytass/fair-playwright/issues)

package/dist/index.cjs

@@ -925,6 +925,26 @@ var E2EHelperImpl = class {
       }
     });
   }
+  /**
+   * Execute a quick workflow with simplified tuple syntax (v1.1.0+)
+   * Converts compact syntax to declarative mode internally
+   */
+  async quick(title, steps, options) {
+    const stepDefinitions = steps.map((step) => {
+      const [stepTitle, action, stepOptions] = step;
+      return {
+        title: stepTitle,
+        action,
+        success: stepOptions?.success,
+        failure: stepOptions?.failure
+      };
+    });
+    return this.majorDeclarative(title, {
+      success: options?.success,
+      failure: options?.failure,
+      steps: stepDefinitions
+    });
+  }
   /**
    * Inline mode for major steps
    */

package/dist/index.d.cts

@@ -287,6 +287,16 @@ interface MajorStepOptions {
      */
     steps?: StepDefinition[];
 }
+/**
+ * Quick step definition - simplified tuple syntax
+ * [title, action] or [title, action, options]
+ */
+type QuickStepDefinition = [string, () => Promise<void>] | [string, () => Promise<void>, StepOptions];
+/**
+ * Options for quick mode execution
+ */
+interface QuickModeOptions extends StepOptions {
+}
 /**
  * E2E test helper interface
  */
@@ -303,6 +313,22 @@ interface E2EHelper {
      * Execute a minor step
      */
     minor(title: string, action: () => Promise<void>, options?: StepOptions): Promise<void>;
+    /**
+     * Execute a quick workflow with simplified syntax (v1.1.0+)
+     * Compact API for simple test cases
+     *
+     * @param title - Major step title
+     * @param steps - Array of [title, action] or [title, action, options] tuples
+     * @param options - Optional success/failure messages for major step
+     *
+     * @example
+     * await e2e.quick('User login', [
+     *   ['Open page', async () => { await page.goto('/login') }],
+     *   ['Fill form', async () => { await page.fill('#email', 'test@example.com') }],
+     *   ['Submit', async () => { await page.click('button[type="submit"]') }]
+     * ])
+     */
+    quick(title: string, steps: QuickStepDefinition[], options?: QuickModeOptions): Promise<void>;
 }
 
 /**

package/dist/index.d.ts

@@ -287,6 +287,16 @@ interface MajorStepOptions {
      */
     steps?: StepDefinition[];
 }
+/**
+ * Quick step definition - simplified tuple syntax
+ * [title, action] or [title, action, options]
+ */
+type QuickStepDefinition = [string, () => Promise<void>] | [string, () => Promise<void>, StepOptions];
+/**
+ * Options for quick mode execution
+ */
+interface QuickModeOptions extends StepOptions {
+}
 /**
  * E2E test helper interface
  */
@@ -303,6 +313,22 @@ interface E2EHelper {
      * Execute a minor step
      */
     minor(title: string, action: () => Promise<void>, options?: StepOptions): Promise<void>;
+    /**
+     * Execute a quick workflow with simplified syntax (v1.1.0+)
+     * Compact API for simple test cases
+     *
+     * @param title - Major step title
+     * @param steps - Array of [title, action] or [title, action, options] tuples
+     * @param options - Optional success/failure messages for major step
+     *
+     * @example
+     * await e2e.quick('User login', [
+     *   ['Open page', async () => { await page.goto('/login') }],
+     *   ['Fill form', async () => { await page.fill('#email', 'test@example.com') }],
+     *   ['Submit', async () => { await page.click('button[type="submit"]') }]
+     * ])
+     */
+    quick(title: string, steps: QuickStepDefinition[], options?: QuickModeOptions): Promise<void>;
 }
 
 /**

package/dist/index.js

@@ -885,6 +885,26 @@ var E2EHelperImpl = class {
       }
     });
   }
+  /**
+   * Execute a quick workflow with simplified tuple syntax (v1.1.0+)
+   * Converts compact syntax to declarative mode internally
+   */
+  async quick(title, steps, options) {
+    const stepDefinitions = steps.map((step) => {
+      const [stepTitle, action, stepOptions] = step;
+      return {
+        title: stepTitle,
+        action,
+        success: stepOptions?.success,
+        failure: stepOptions?.failure
+      };
+    });
+    return this.majorDeclarative(title, {
+      success: options?.success,
+      failure: options?.failure,
+      steps: stepDefinitions
+    });
+  }
   /**
    * Inline mode for major steps
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fair-playwright",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "AI-optimized Playwright test reporter with progressive terminal output and hierarchical step management",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,6 +18,7 @@
   },
   "files": [
     "dist",
+    "resources",
     "README.md",
     "LICENSE"
   ],
@@ -34,7 +35,10 @@
     "typecheck": "tsc --noEmit",
     "changeset": "changeset",
     "release": "changeset publish",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "keywords": [
     "playwright",
@@ -58,7 +62,7 @@
   "bugs": {
     "url": "https://github.com/baranaytass/fair-playwright/issues"
   },
-  "homepage": "https://github.com/baranaytass/fair-playwright#readme",
+  "homepage": "https://baranaytass.github.io/fair-playwright/",
   "author": "Baran Aytas",
   "license": "MIT",
   "peerDependencies": {
@@ -80,6 +84,7 @@
     "prettier": "^3.4.2",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
+    "vitepress": "^1.6.4",
     "vitest": "^2.1.8"
   },
   "engines": {