fair-playwright 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,429 @@
+import { Reporter, FullConfig, Suite, TestCase, TestResult, TestStep, FullResult, TestError } from '@playwright/test/reporter';
+export { FullConfig, FullResult, Reporter, Suite, TestCase, TestResult, TestStep } from '@playwright/test/reporter';
+
+/**
+ * Type definitions for fair-playwright reporter
+ */
+
+/**
+ * Step level in the hierarchy
+ */
+type StepLevel = 'major' | 'minor';
+/**
+ * Step status
+ */
+type StepStatus = 'pending' | 'running' | 'passed' | 'failed' | 'skipped';
+/**
+ * Output mode for the reporter
+ */
+type OutputMode = 'progressive' | 'full' | 'minimal';
+/**
+ * Configuration for the Fair Playwright reporter
+ */
+interface FairReporterConfig {
+    /**
+     * Output mode: progressive (live updates), full (all details), minimal (summary only)
+     * @default 'progressive'
+     */
+    mode?: OutputMode;
+    /**
+     * Enable AI-optimized markdown output
+     * @default true
+     */
+    aiOptimized?: boolean;
+    /**
+     * Output file configurations
+     */
+    output?: {
+        /**
+         * Enable console output
+         * @default true
+         */
+        console?: boolean;
+        /**
+         * AI-optimized markdown output file path, or true for default location
+         * @default false
+         */
+        ai?: boolean | string;
+        /**
+         * JSON output file path, or true for default location
+         * @default false
+         */
+        json?: boolean | string;
+    };
+    /**
+     * Step classification settings
+     */
+    stepClassification?: {
+        /**
+         * Duration threshold in ms - steps longer than this are considered MAJOR
+         * @default 1000
+         */
+        durationThreshold?: number;
+        /**
+         * Auto-detect step level based on context and duration
+         * @default true
+         */
+        autoDetect?: boolean;
+    };
+    /**
+     * Progressive mode settings
+     */
+    progressive?: {
+        /**
+         * Clear completed tests from terminal
+         * @default true
+         */
+        clearCompleted?: boolean;
+        /**
+         * Update interval in milliseconds
+         * @default 100
+         */
+        updateInterval?: number;
+    };
+    /**
+     * Compression settings for output
+     */
+    compression?: {
+        /**
+         * How to display passed tests: summary, hide, or full
+         * @default 'summary'
+         */
+        passedTests?: 'summary' | 'hide' | 'full';
+        /**
+         * Failure context settings
+         */
+        failureContext?: {
+            /**
+             * Number of steps to show before failure
+             * @default 3
+             */
+            steps?: number;
+            /**
+             * Include screenshot in failure context
+             * @default true
+             */
+            screenshot?: boolean;
+            /**
+             * Include trace in failure context
+             * @default true
+             */
+            trace?: boolean;
+            /**
+             * Include console logs in failure context
+             * @default true
+             */
+            logs?: boolean;
+        };
+    };
+}
+/**
+ * Step metadata for tracking
+ */
+interface StepMetadata {
+    /**
+     * Unique identifier for the step
+     */
+    id: string;
+    /**
+     * Step title/description
+     */
+    title: string;
+    /**
+     * Step level (major or minor)
+     */
+    level: StepLevel;
+    /**
+     * Current status
+     */
+    status: StepStatus;
+    /**
+     * Start timestamp
+     */
+    startTime: number;
+    /**
+     * End timestamp (undefined if not finished)
+     */
+    endTime?: number;
+    /**
+     * Duration in milliseconds
+     */
+    duration?: number;
+    /**
+     * Success message
+     */
+    successMessage?: string;
+    /**
+     * Failure message
+     */
+    failureMessage?: string;
+    /**
+     * Error details if failed
+     */
+    error?: {
+        message: string;
+        stack?: string;
+        location?: string;
+    };
+    /**
+     * Parent step ID (for nested steps)
+     */
+    parentId?: string;
+    /**
+     * Child step IDs
+     */
+    childIds: string[];
+}
+/**
+ * Test metadata for tracking
+ */
+interface TestMetadata {
+    /**
+     * Unique identifier
+     */
+    id: string;
+    /**
+     * Test title
+     */
+    title: string;
+    /**
+     * Test file path
+     */
+    file: string;
+    /**
+     * Test status
+     */
+    status: StepStatus;
+    /**
+     * Start timestamp
+     */
+    startTime: number;
+    /**
+     * End timestamp
+     */
+    endTime?: number;
+    /**
+     * Duration in milliseconds
+     */
+    duration?: number;
+    /**
+     * Steps in this test
+     */
+    steps: StepMetadata[];
+    /**
+     * Error details if failed
+     */
+    error?: {
+        message: string;
+        stack?: string;
+        location?: string;
+    };
+    /**
+     * Attachments (screenshots, traces, etc.)
+     */
+    attachments: Array<{
+        name: string;
+        path?: string;
+        contentType: string;
+    }>;
+    /**
+     * Browser console errors captured during test execution
+     */
+    consoleErrors?: Array<{
+        type: string;
+        message: string;
+        location?: string;
+        timestamp: number;
+    }>;
+}
+/**
+ * Options for e2e step execution (inline mode)
+ */
+interface StepOptions {
+    /**
+     * Success message to display
+     */
+    success?: string;
+    /**
+     * Failure message to display
+     */
+    failure?: string;
+}
+/**
+ * Step definition for declarative mode
+ */
+interface StepDefinition {
+    /**
+     * Step title
+     */
+    title: string;
+    /**
+     * Success message
+     */
+    success?: string;
+    /**
+     * Failure message
+     */
+    failure?: string;
+    /**
+     * Action to execute
+     */
+    action: () => Promise<void>;
+}
+/**
+ * Options for major step execution (declarative mode)
+ */
+interface MajorStepOptions {
+    /**
+     * Success message for the major step
+     */
+    success?: string;
+    /**
+     * Failure message for the major step
+     */
+    failure?: string;
+    /**
+     * Child steps to execute
+     */
+    steps?: StepDefinition[];
+}
+/**
+ * E2E test helper interface
+ */
+interface E2EHelper {
+    /**
+     * Execute a major step (inline mode)
+     */
+    major(title: string, action: () => Promise<void>, options?: StepOptions): Promise<void>;
+    /**
+     * Execute a major step with child steps (declarative mode)
+     */
+    major(title: string, options: MajorStepOptions): Promise<void>;
+    /**
+     * Execute a minor step
+     */
+    minor(title: string, action: () => Promise<void>, options?: StepOptions): Promise<void>;
+}
+
+/**
+ * Fair Playwright Reporter
+ * AI-optimized reporter with progressive terminal output and hierarchical step management
+ */
+declare class FairReporter implements Reporter {
+    private config;
+    private stepTracker;
+    private consoleFormatter?;
+    private aiFormatter?;
+    private jsonFormatter?;
+    private stepIdMap;
+    constructor(config?: FairReporterConfig);
+    /**
+     * Called once before running tests
+     */
+    onBegin(_config: FullConfig, suite: Suite): void;
+    /**
+     * Called when a test begins
+     */
+    onTestBegin(test: TestCase, result: TestResult): void;
+    /**
+     * Called when a test step begins
+     */
+    onStepBegin(test: TestCase, result: TestResult, step: TestStep): void;
+    /**
+     * Called when a test step ends
+     */
+    onStepEnd(test: TestCase, result: TestResult, step: TestStep): void;
+    /**
+     * Called when a test ends
+     */
+    onTestEnd(test: TestCase, result: TestResult): void;
+    /**
+     * Called once after all tests have finished
+     */
+    onEnd(result: FullResult): Promise<void>;
+    /**
+     * Optional: Called on error
+     */
+    onError(error: TestError): void;
+}
+
+/**
+ * Global e2e helper instance
+ * Usage:
+ * import { e2e } from 'fair-playwright'
+ * await e2e.major('User login', ...)
+ */
+declare const e2e: E2EHelper;
+
+/**
+ * MCP (Model Context Protocol) Server for AI integration
+ * Provides test results and progress to AI coding assistants
+ *
+ * Full MCP protocol implementation using @modelcontextprotocol/sdk
+ */
+interface MCPServerConfig {
+    /**
+     * Path to test results JSON file
+     * Default: './test-results/results.json'
+     */
+    resultsPath?: string;
+    /**
+     * Server name
+     */
+    name?: string;
+    /**
+     * Server version
+     */
+    version?: string;
+    /**
+     * Enable verbose logging
+     */
+    verbose?: boolean;
+}
+/**
+ * MCP Server for exposing test results to AI assistants
+ */
+declare class MCPServer {
+    private server;
+    private config;
+    private testResults;
+    constructor(config?: MCPServerConfig);
+    /**
+     * Setup MCP protocol handlers
+     */
+    private setupHandlers;
+    /**
+     * Load test results from JSON file
+     */
+    private loadTestResults;
+    /**
+     * Start the MCP server with stdio transport
+     */
+    start(): Promise<void>;
+    /**
+     * Get current test results
+     */
+    private getTestResults;
+    /**
+     * Get test summary in markdown format
+     */
+    private getTestSummary;
+    /**
+     * Get AI-optimized summary of failures
+     */
+    private getFailureSummary;
+    /**
+     * Query specific test by title
+     */
+    private queryTest;
+    /**
+     * Get tests by status
+     */
+    private getTestsByStatus;
+}
+/**
+ * Create and start MCP server
+ */
+declare function createMCPServer(config?: MCPServerConfig): Promise<MCPServer>;
+
+export { type E2EHelper, FairReporter, type FairReporterConfig, MCPServer, type MCPServerConfig, type MajorStepOptions, type OutputMode, type StepDefinition, type StepLevel, type StepMetadata, type StepOptions, type StepStatus, type TestMetadata, createMCPServer, FairReporter as default, e2e };