@testdino/playwright 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,779 @@
+import { Reporter, FullConfig, Suite, TestCase, TestResult, TestStep, FullResult, TestError } from '@playwright/test/reporter';
+
+/**
+ * Metadata collection types and interfaces
+ */
+/**
+ * Base interface for all metadata collectors
+ */
+interface MetadataCollector<T = Record<string, unknown>> {
+    /**
+     * Collect metadata asynchronously
+     * Should handle errors gracefully and return partial data
+     */
+    collect(): Promise<T>;
+    /**
+     * Get collector name for debugging
+     */
+    getName(): string;
+}
+/**
+ * Result of metadata collection with error tracking
+ */
+interface MetadataCollectionResult<T = Record<string, unknown>> {
+    /**
+     * Collected data (may be partial on errors)
+     */
+    data: T;
+    /**
+     * Whether collection was successful
+     */
+    success: boolean;
+    /**
+     * Error message if collection failed
+     */
+    error?: string;
+    /**
+     * Collection duration in milliseconds
+     */
+    duration: number;
+    /**
+     * Collector name
+     */
+    collector: string;
+}
+/**
+ * Git metadata structure
+ */
+interface GitMetadata {
+    branch?: string;
+    commit?: {
+        hash?: string;
+        message?: string;
+        author?: string;
+        authorId?: string;
+        email?: string;
+        timestamp?: string;
+        isDirty?: boolean;
+    };
+    repository?: {
+        name?: string;
+        url?: string;
+    };
+    pr?: PRMetadata;
+}
+/**
+ * CI metadata structure
+ */
+interface CIMetadata {
+    provider?: string;
+    pipeline?: {
+        id?: string;
+        name?: string;
+        url?: string;
+    };
+    build?: {
+        number?: string;
+        trigger?: string;
+    };
+    environment?: {
+        name?: string;
+        type?: string;
+        os?: string;
+        node?: string;
+    };
+}
+/**
+ * Pull Request metadata structure
+ */
+interface PRMetadata {
+    title?: string;
+    number?: number;
+    url?: string;
+    status?: string;
+    branch?: string;
+    targetBranch?: string;
+    author?: string;
+    labels?: string[];
+    merged?: boolean;
+    mergeable?: boolean;
+    mergeCommitSha?: string;
+}
+/**
+ * System metadata structure
+ */
+interface SystemMetadata {
+    os?: string;
+    cpu?: string;
+    memory?: string;
+    nodeVersion?: string;
+    platform?: string;
+    hostname?: string;
+}
+/**
+ * Test case metadata in skeleton
+ */
+interface SkeletonTest {
+    testId: string;
+    title: string;
+    location: {
+        file: string;
+        line: number;
+        column: number;
+    };
+    tags?: string[];
+    expectedStatus?: string;
+    annotations?: Array<{
+        type: string;
+        description?: string;
+    }>;
+}
+/**
+ * Suite metadata in skeleton (recursive structure)
+ */
+interface SkeletonSuite {
+    title: string;
+    file?: string;
+    type: 'describe' | 'file';
+    location?: {
+        file: string;
+        line: number;
+        column: number;
+    };
+    tests: SkeletonTest[];
+    suites?: SkeletonSuite[];
+}
+/**
+ * Test run skeleton structure
+ */
+interface RunSkeleton {
+    totalTests: number;
+    suites: SkeletonSuite[];
+}
+/**
+ * Playwright metadata structure
+ */
+interface PlaywrightMetadata {
+    version?: string;
+    parallel?: boolean;
+    workers?: number;
+    shard?: ShardMetadata;
+    projects?: string[];
+    browsers?: string[];
+    configFile?: string;
+    forbidOnly?: boolean;
+    fullyParallel?: boolean;
+    globalTimeout?: number;
+    grep?: string[];
+    maxFailures?: number;
+    metadata?: Record<string, unknown>;
+    reportSlowTests?: {
+        max: number;
+        threshold: number;
+    };
+    rootDir?: string;
+    tags?: string[];
+    webServer?: Record<string, unknown>;
+}
+/**
+ * Shard metadata structure
+ */
+interface ShardMetadata {
+    current?: number;
+    total?: number;
+}
+/**
+ * Complete metadata collection result
+ */
+interface CompleteMetadata {
+    git?: GitMetadata;
+    ci?: CIMetadata;
+    system?: SystemMetadata;
+    playwright?: PlaywrightMetadata;
+    skeleton?: RunSkeleton;
+}
+/**
+ * Metadata collection summary
+ */
+interface MetadataCollectionSummary {
+    /**
+     * Complete collected metadata
+     */
+    metadata: CompleteMetadata;
+    /**
+     * Collection results for each collector
+     */
+    results: MetadataCollectionResult[];
+    /**
+     * Total collection time in milliseconds
+     */
+    totalDuration: number;
+    /**
+     * Number of successful collectors
+     */
+    successCount: number;
+    /**
+     * Number of failed collectors
+     */
+    failureCount: number;
+}
+
+/**
+ * Server error classes for quota and infrastructure errors
+ * These are received from the TestDino server and handled gracefully in the reporter
+ * Follows the same Error class pattern as cli/errors.ts
+ */
+/**
+ * Base class for all TestDino server errors
+ * Extends Error to work with standard error handling
+ */
+declare class TestDinoServerError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Quota exhausted error (session creation)
+ * HTTP 402 response when organization pool is exhausted
+ */
+declare class QuotaExhaustedError extends TestDinoServerError {
+    readonly details: {
+        planName: string;
+        totalLimit: number;
+        used: number;
+        resetDate?: string;
+    };
+    constructor(message: string, details: {
+        planName: string;
+        totalLimit: number;
+        used: number;
+        resetDate?: string;
+    });
+}
+/**
+ * Quota exceeded error (run:begin)
+ * WebSocket NACK when test count exceeds available quota
+ */
+declare class QuotaExceededError extends TestDinoServerError {
+    readonly details: {
+        planName: string;
+        totalTests: number;
+        remaining: number;
+        used: number;
+        total: number;
+        resetDate?: string;
+        canPartialSubmit: boolean;
+        allowedCount: number;
+    };
+    constructor(message: string, details: {
+        planName: string;
+        totalTests: number;
+        remaining: number;
+        used: number;
+        total: number;
+        resetDate?: string;
+        canPartialSubmit: boolean;
+        allowedCount: number;
+    });
+}
+/**
+ * Queue full error (backpressure)
+ * WebSocket NACK when event queue is full
+ */
+declare class QueueFullError extends TestDinoServerError {
+    constructor(message: string);
+}
+/**
+ * Circuit breaker error (Redis unavailable)
+ * WebSocket NACK when circuit breaker is open
+ */
+declare class CircuitBreakerError extends TestDinoServerError {
+    readonly retryAfter?: number;
+    constructor(message: string, retryAfter?: number);
+}
+/**
+ * Union type for all server error classes
+ */
+type ServerError = QuotaExhaustedError | QuotaExceededError | QueueFullError | CircuitBreakerError;
+
+/**
+ * Server response type definitions
+ * These are pure type definitions for server responses (not Error classes)
+ * Error classes are in reporter/errors.ts following the established pattern
+ */
+
+/**
+ * HTTP 402 response from session creation
+ * This is a server response type, not an error class
+ */
+interface SessionCreationQuotaResponse {
+    success: false;
+    message: string;
+    error: 'QUOTA_EXHAUSTED';
+    details: {
+        planName: string;
+        totalLimit: number;
+        used: number;
+        resetDate?: string;
+    };
+}
+/**
+ * WebSocket NACK message structure
+ * This is a server message type, not an error class
+ */
+interface NackMessage {
+    type: 'nack';
+    eventId: string;
+    error: string | ServerError;
+    retryable: boolean;
+    timestamp: number;
+}
+
+/**
+ * Core types for TestDino Playwright integration
+ */
+
+interface TestdinoConfig {
+    /**
+     * Record token for authentication
+     */
+    token?: string;
+    /**
+     * CI build ID for grouping sharded runs
+     */
+    ciBuildId?: string;
+    /**
+     * Server URL (for development/testing)
+     */
+    serverUrl?: string;
+    /**
+     * Enable debug logging
+     */
+    debug?: boolean;
+    /**
+     * Upload artifacts (screenshots, videos, traces) to cloud storage
+     * Default: true (enabled)
+     * Set to false or use --no-artifacts CLI flag to disable
+     */
+    artifacts?: boolean;
+}
+interface EventBuffer {
+    events: TestEvent[];
+    maxSize: number;
+    flush: () => Promise<void>;
+    add: (event: TestEvent) => Promise<void>;
+}
+interface ConnectionConfig {
+    token: string;
+    serverUrl: string;
+    maxRetries?: number;
+    retryDelay?: number;
+}
+type TestEvent = TestRunBeginEvent | TestBeginEvent | TestStepBeginEvent | TestStepEndEvent | TestEndEvent | TestRunEndEvent | TestRunErrorEvent | TestConsoleOutEvent | TestConsoleErrEvent;
+interface BaseEvent {
+    type: string;
+    timestamp: number;
+    runId: string;
+    sequence: number;
+}
+interface TestRunBeginEvent extends BaseEvent {
+    type: 'run:begin';
+    metadata: CompleteMetadata;
+}
+interface TestBeginEvent extends BaseEvent {
+    type: 'test:begin';
+    testId: string;
+    title: string;
+    titlePath: Array<string>;
+    location: {
+        file: string;
+        line: number;
+        column: number;
+    };
+    tags: Array<string>;
+    expectedStatus: 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted';
+    timeout: number;
+    retries: number;
+    annotations: Array<{
+        type: string;
+        description?: string;
+    }>;
+    retry: number;
+    workerIndex: number;
+    parallelIndex: number;
+    repeatEachIndex?: number;
+    parentSuite: {
+        title: string;
+        type: 'root' | 'project' | 'file' | 'describe';
+        location?: {
+            file: string;
+            line: number;
+            column: number;
+        };
+    };
+    startTime: number;
+}
+interface TestStepBeginEvent extends BaseEvent {
+    type: 'step:begin';
+    testId: string;
+    stepId: string;
+    title: string;
+    titlePath: Array<string>;
+    category: string;
+    location?: {
+        file: string;
+        line: number;
+        column: number;
+    };
+    parentStep?: {
+        title: string;
+        category: string;
+        location?: {
+            file: string;
+            line: number;
+            column: number;
+        };
+    };
+    startTime: number;
+    retry: number;
+    workerIndex: number;
+    parallelIndex: number;
+}
+interface TestStepEndEvent extends BaseEvent {
+    type: 'step:end';
+    testId: string;
+    stepId: string;
+    title?: string;
+    titlePath?: string[];
+    duration: number;
+    error?: {
+        message: string;
+        stack?: string;
+        snippet?: string;
+        value?: string;
+        location?: {
+            file: string;
+            line: number;
+            column: number;
+        };
+    };
+    status: 'passed' | 'failed';
+    childSteps: {
+        count: number;
+        steps: Array<{
+            title: string;
+            status: 'passed' | 'failed';
+        }>;
+    };
+    workerIndex: number;
+    parallelIndex: number;
+    attachments: Array<{
+        name: string;
+        contentType: string;
+        path?: string;
+    }>;
+    annotations?: Array<{
+        type: string;
+        description?: string;
+    }>;
+    retry: number;
+}
+interface TestEndEvent extends BaseEvent {
+    type: 'test:end';
+    testId: string;
+    status: 'passed' | 'failed' | 'skipped' | 'timedOut' | 'interrupted';
+    outcome: 'expected' | 'unexpected' | 'flaky' | 'skipped';
+    duration: number;
+    retry: number;
+    workerIndex: number;
+    parallelIndex: number;
+    annotations: Array<{
+        type: string;
+        description?: string;
+    }>;
+    errors: Array<{
+        message: string;
+        stack?: string;
+        snippet?: string;
+        value?: string;
+        location?: {
+            file: string;
+            line: number;
+            column: number;
+        };
+    }>;
+    steps: {
+        total: number;
+        passed: number;
+        failed: number;
+    };
+    attachments: Array<{
+        name: string;
+        contentType: string;
+        path?: string;
+    }>;
+    stdout?: string[];
+    stderr?: string[];
+}
+interface TestRunEndEvent extends BaseEvent {
+    type: 'run:end';
+    status: 'passed' | 'failed' | 'timedout' | 'interrupted';
+    duration: number;
+    startTime: number;
+    shard?: {
+        current: number;
+        total: number;
+    };
+}
+interface TestRunErrorEvent extends BaseEvent {
+    type: 'run:error';
+    error: {
+        message?: string;
+        stack?: string;
+        value?: string;
+        snippet?: string;
+        location?: {
+            file: string;
+            line: number;
+            column: number;
+        };
+        cause?: {
+            message?: string;
+            stack?: string;
+            value?: string;
+            snippet?: string;
+            location?: {
+                file: string;
+                line: number;
+                column: number;
+            };
+        };
+    };
+}
+interface TestConsoleOutEvent extends BaseEvent {
+    type: 'console:out';
+    text: string;
+    testId?: string;
+    retry?: number;
+    truncated?: boolean;
+}
+interface TestConsoleErrEvent extends BaseEvent {
+    type: 'console:err';
+    text: string;
+    testId?: string;
+    retry?: number;
+    truncated?: boolean;
+}
+
+/**
+ * TestDino Playwright Reporter
+ * Streams test execution data in real-time
+ */
+
+declare class TestdinoReporter implements Reporter {
+    private config;
+    private wsClient;
+    private httpClient;
+    private buffer;
+    private runId;
+    private useHttpFallback;
+    private sequenceNumber;
+    private shardInfo?;
+    private runStartTime?;
+    private sigintHandler?;
+    private sigtermHandler?;
+    private isShuttingDown;
+    private quotaExceeded;
+    private sessionId;
+    private artifactUploader;
+    private artifactsEnabled;
+    private initPromise;
+    private initFailed;
+    constructor(config?: TestdinoConfig);
+    /**
+     * Load configuration from CLI temp file if available
+     */
+    private loadCliConfig;
+    /**
+     * Called once before running tests
+     */
+    onBegin(config: FullConfig, suite: Suite): Promise<void>;
+    /**
+     * Perform all async initialization: metadata, auth, WebSocket, artifacts, run:begin
+     *
+     * Buffer's onFlush callback awaits this promise before transmitting events,
+     * ensuring no data is sent before authentication and connection are established.
+     *
+     * @param config - Playwright FullConfig for metadata collection
+     * @param suite - Playwright Suite for skeleton building
+     * @param token - Authentication token
+     * @returns true on success, false on failure
+     */
+    private performAsyncInit;
+    /**
+     * Called for each test before it starts
+     */
+    onTestBegin(test: TestCase, result: TestResult): Promise<void>;
+    /**
+     * Called when a test step begins
+     */
+    onStepBegin(test: TestCase, result: TestResult, step: TestStep): Promise<void>;
+    /**
+     * Called when a test step ends
+     */
+    onStepEnd(test: TestCase, result: TestResult, step: TestStep): Promise<void>;
+    /**
+     * Called after each test completes
+     */
+    onTestEnd(test: TestCase, result: TestResult): Promise<void>;
+    /**
+     * Called after all tests complete
+     */
+    onEnd(result: FullResult): Promise<void>;
+    /**
+     * Called on global errors
+     */
+    onError(error: TestError): Promise<void>;
+    /**
+     * Called when standard output is produced in worker process
+     */
+    onStdOut(chunk: string | Buffer, test?: TestCase, result?: TestResult): Promise<void>;
+    /**
+     * Called when standard error is produced in worker process
+     */
+    onStdErr(chunk: string | Buffer, test?: TestCase, result?: TestResult): Promise<void>;
+    /**
+     * Indicates whether this reporter outputs to stdout/stderr
+     * Returns false to allow Playwright to add its own terminal output
+     */
+    printsToStdio(): boolean;
+    /**
+     * Send events via WebSocket or HTTP fallback
+     */
+    private sendEvents;
+    /**
+     * Get token from config or environment
+     */
+    private getToken;
+    /**
+     * Get server URL from config or environment
+     */
+    private getServerUrl;
+    private getWebSocketUrl;
+    /**
+     * Collect metadata for the test run
+     */
+    private collectMetadata;
+    /**
+     * Get next sequence number and current timestamp
+     */
+    private getEventMetadata;
+    /**
+     * Extract parent suite information for skeleton mapping
+     */
+    private extractParentSuite;
+    /**
+     * Extract parent step information for step hierarchy mapping
+     */
+    private extractParentStep;
+    /**
+     * Extract child steps summary for step:end event
+     */
+    private extractChildSteps;
+    /**
+     * Extract error details from TestError (shared by step:end, test:end, and error events)
+     */
+    private extractError;
+    /**
+     * Extract global error details with cause support (for error events)
+     */
+    private extractGlobalError;
+    /**
+     * Print a prominent configuration error banner
+     */
+    private printConfigurationError;
+    /**
+     * Print quota error with plan details and upgrade information
+     * @param error - Quota error (QUOTA_EXHAUSTED or QUOTA_EXCEEDED)
+     */
+    private printQuotaError;
+    /**
+     * Truncate console chunk to max size and convert Buffer to string
+     */
+    private truncateChunk;
+    /**
+     * Extract attachment metadata for step:end event
+     */
+    private extractAttachments;
+    /**
+     * Extract steps summary for test:end event
+     */
+    private extractTestStepsSummary;
+    /**
+     * Extract console output for test:end event
+     */
+    private extractConsoleOutput;
+    /**
+     * Check if this is a duplicate instance of TestdinoReporter
+     * This happens when the CLI injects our reporter via --reporter flag,
+     * but the user already has TestdinoReporter configured in playwright.config
+     *
+     * @param reporters - The resolved reporters array from FullConfig
+     * @returns true if there are multiple TestdinoReporter instances, false otherwise
+     */
+    private isDuplicateInstance;
+    /**
+     * Count how many TestdinoReporter instances are in the reporters array
+     *
+     * @param reporters - The resolved reporters array from FullConfig
+     * @returns Number of TestdinoReporter instances found
+     */
+    private countTestdinoReporters;
+    /**
+     * Check if a reporter name/path matches TestdinoReporter
+     *
+     * @param value - Reporter name, path, or class reference
+     * @returns true if this is our reporter, false otherwise
+     */
+    private isTestdinoReporter;
+    /**
+     * Register signal handlers for graceful shutdown on interruption
+     */
+    private registerSignalHandlers;
+    /**
+     * Remove signal handlers (called on normal completion or after handling interruption)
+     */
+    private removeSignalHandlers;
+    /**
+     * Handle process interruption by sending run:end event with interrupted status
+     * @param signal - The signal that triggered the interruption (SIGINT or SIGTERM)
+     * @param exitCode - The exit code to use when exiting
+     */
+    private handleInterruption;
+    /**
+     * Send interruption event directly without buffering
+     * Uses optimized path for speed during shutdown
+     */
+    private sendInterruptionEvent;
+    /**
+     * Create a promise that rejects after a timeout
+     * @param ms - Timeout in milliseconds
+     * @param message - Error message for timeout
+     */
+    private timeoutPromise;
+    /**
+     * Initialize artifact uploader by requesting SAS token
+     * Gracefully handles failures - uploads disabled if SAS token request fails
+     */
+    private initializeArtifactUploader;
+    /**
+     * Upload attachments and return with Azure URLs
+     * If uploads disabled or failed, returns attachments with local paths
+     */
+    private uploadAttachments;
+    /**
+     * Get base server URL without /api/reporter suffix
+     */
+    private getBaseServerUrl;
+}
+
+export { type BaseEvent, type CIMetadata, CircuitBreakerError, type ConnectionConfig, type EventBuffer, type GitMetadata, type MetadataCollectionResult, type MetadataCollectionSummary, type MetadataCollector, type NackMessage, type PRMetadata, type PlaywrightMetadata, QueueFullError, QuotaExceededError, QuotaExhaustedError, type CompleteMetadata as RunMetadata, type ServerError, type SessionCreationQuotaResponse, type ShardMetadata, type SystemMetadata, type TestBeginEvent, type TestConsoleErrEvent, type TestConsoleOutEvent, type TestEndEvent, type TestEvent, type TestRunBeginEvent, type TestRunEndEvent, type TestRunErrorEvent, type TestStepBeginEvent, type TestStepEndEvent, type TestdinoConfig, TestdinoReporter as default };