@checkly/playwright-reporter 0.1.10 → 1.0.0

package/dist/index.d.ts

@@ -1,308 +1,384 @@
-export { Asset, AssetCollector, ZipEntry, ZipResult, Zipper, ZipperOptions } from '@checkly/reporter-utils';
-import { FullConfig, Suite, JSONReport as JSONReport$1, JSONReportSuite as JSONReportSuite$1, JSONReportSpec as JSONReportSpec$1, JSONReportTest as JSONReportTest$1, JSONReportTestResult as JSONReportTestResult$1, Reporter, TestCase, TestResult, TestError } from '@playwright/test/reporter';
+import { Reporter, FullConfig, Suite as Suite$1, TestCase, TestResult as TestResult$1, TestStep as TestStep$1, TestError as TestError$1, FullResult } from '@playwright/test/reporter';
 
 /**
- * Checkly environment for API endpoints
- */
-type ChecklyEnvironment = 'local' | 'development' | 'staging' | 'production';
-/**
- * Context passed to sessionName callback function
+ * Output Contract Schema
+ *
+ * This defines the JSON structure that our reporter MUST produce.
+ * It is designed to be compatible with Playwright 1.40 through 1.57+.
+ *
+ * Fields are categorized as:
+ * - REQUIRED: Must always be present (exist in all versions 1.40+)
+ * - OPTIONAL: May be present (added in newer versions, older consumers ignore them)
  */
-interface SessionNameContext {
-    /**
-     * The directory name where tests are running
-     */
-    directoryName: string;
-    /**
-     * Playwright's full configuration object
-     */
-    config: FullConfig;
-    /**
-     * The root test suite containing all tests
-     */
-    suite: Suite;
-}
 /**
- * Session name can be a static string or a function that returns a string
+ * Individual test run status
  */
-type SessionNameOption = string | ((context: SessionNameContext) => string);
+type TestStatus = 'passed' | 'failed' | 'skipped' | 'timedOut' | 'interrupted';
 /**
- * Configuration options for ChecklyReporter
+ * Overall test outcome (aggregated across retries)
  */
-interface ChecklyReporterOptions {
-    /**
-     * Checkly account ID for uploading test results
-     * Required for Phase 2 (upload functionality)
-     */
-    accountId?: string;
-    /**
-     * Checkly API key for authentication
-     * Required for Phase 2 (upload functionality)
-     */
-    apiKey?: string;
-    /**
-     * Checkly environment to use
-     * Can also be set via CHECKLY_ENV environment variable
-     * @default 'production'
-     */
-    environment?: ChecklyEnvironment;
-    /**
-     * Output path for the generated ZIP file (for testing/debugging)
-     * @default 'checkly-report.zip'
-     * @internal
-     */
-    outputPath?: string;
-    /**
-     * Path to the JSON report file generated by Playwright's json reporter
-     * @default 'test-results/playwright-test-report.json'
-     * @internal
-     */
-    jsonReportPath?: string;
-    /**
-     * Directory containing test results and assets
-     * @default 'test-results'
-     * @internal
-     */
-    testResultsDir?: string;
-    /**
-     * Dry run mode - skips API calls and only creates local ZIP file
-     * @default false
-     */
-    dryRun?: boolean;
-    /**
-     * Custom name for the test session
-     * Can be a string or a callback function for dynamic names
-     * @default 'Playwright Test Session: {directoryName}'
-     * @example
-     * // Static string
-     * sessionName: 'My E2E Tests'
-     *
-     * // Dynamic with callback
-     * sessionName: ({ directoryName, config }) => `E2E: ${directoryName} (${config.projects.length} projects)`
-     */
-    sessionName?: SessionNameOption;
-    /**
-     * Enable verbose logging for debugging
-     * Logs detailed information about each phase of report generation
-     * Can also be enabled via CHECKLY_REPORTER_VERBOSE=true environment variable
-     * @default false
-     */
-    verbose?: boolean;
+type TestOutcome = 'expected' | 'unexpected' | 'skipped' | 'flaky';
+interface Location {
+    file: string;
+    line: number;
+    column: number;
 }
-/**
- * Warning types that can be attached to test results
- */
-type ChecklyWarningType = 'trace-off' | 'trace-retained-on-failure' | 'trace-first-retry-only' | 'trace-retries-only' | 'trace-retained-on-first-failure' | 'trace-missing';
-/**
- * A warning attached to a test result
- */
-interface ChecklyWarning {
-    /**
-     * Type of warning for programmatic handling
-     */
-    type: ChecklyWarningType;
-    /**
-     * Human-readable warning message
-     */
-    message: string;
+interface TestError {
+    message?: string;
+    stack?: string;
+    location?: Location;
+    snippet?: string;
+    value?: string;
+    matcherResult?: unknown;
+}
+interface Attachment {
+    name: string;
+    contentType: string;
+    path?: string;
+    body?: string;
+}
+interface TestStep {
+    title: string;
+    duration: number;
+    error?: TestError;
+    steps?: TestStep[];
+}
+interface Annotation {
+    type: string;
+    description?: string;
+    location?: {
+        file: string;
+        line: number;
+        column: number;
+    };
+}
+interface TestResult {
+    workerIndex: number;
+    parallelIndex: number;
+    status: TestStatus;
+    duration: number;
+    startTime: string;
+    retry: number;
+    errors: TestError[];
+    error?: TestError;
+    errorLocation?: Location;
+    stdout: Array<{
+        text: string;
+    } | {
+        buffer: string;
+    }>;
+    stderr: Array<{
+        text: string;
+    } | {
+        buffer: string;
+    }>;
+    attachments: Attachment[];
+    steps?: TestStep[];
+    annotations: Annotation[];
+}
+interface Test {
+    projectId: string;
+    projectName: string;
+    timeout: number;
+    expectedStatus: TestStatus;
+    annotations: Annotation[];
+    results: TestResult[];
+    status: TestOutcome;
+}
+interface Spec {
+    id: string;
+    title: string;
+    file: string;
+    line: number;
+    column: number;
+    tags: string[];
+    ok: boolean;
+    tests: Test[];
+}
+interface Suite {
+    title: string;
+    file: string;
+    line: number;
+    column: number;
+    specs: Spec[];
+    suites?: Suite[];
+}
+interface ProjectConfig {
+    id: string;
+    name: string;
+    testDir: string;
+    outputDir: string;
+    timeout: number;
+    retries: number;
+    repeatEach: number;
+    metadata: Record<string, unknown>;
+    testMatch: string[];
+    testIgnore: string[];
+}
+interface ReportConfig {
+    rootDir: string;
+    configFile?: string;
+    version: string;
+    workers: number;
+    fullyParallel: boolean;
+    forbidOnly: boolean;
+    globalTimeout: number;
+    maxFailures: number;
+    projects: ProjectConfig[];
+    shard?: {
+        current: number;
+        total: number;
+    } | null;
+    metadata: Record<string, unknown>;
+    tags?: string[];
+    updateSourceMethod?: string;
+    preserveOutput?: string;
+    quiet?: boolean;
+    reportSlowTests?: {
+        max: number;
+        threshold: number;
+    } | null;
+    webServer?: unknown;
+    globalSetup?: string | null;
+    globalTeardown?: string | null;
+    grep?: unknown;
+    grepInvert?: unknown;
+    reporter?: unknown;
+    updateSnapshots?: string;
+}
+interface Stats {
+    startTime: string;
+    duration: number;
+    expected: number;
+    unexpected: number;
+    flaky: number;
+    skipped: number;
+}
+interface JSONReport {
+    config: ReportConfig;
+    suites: Suite[];
+    errors: TestError[];
+    stats: Stats;
 }
 /**
- * Console message type matching the webapp's CheckRunNavigationTracePage.console type
+ * Type guard to check if an object is a valid JSONReport
  */
-type ConsoleMessageType = 'debug' | 'error' | 'info' | 'log' | 'warning';
+declare function isValidJSONReport(obj: unknown): obj is JSONReport;
 /**
- * Location of a console message in source code
+ * Type guard to check if stats are valid
  */
-interface ConsoleMessageLocation {
-    url: string;
-    columnNumber: number;
-    lineNumber: number;
-}
+declare function isValidStats(obj: unknown): obj is Stats;
 /**
- * Console message extracted from Playwright trace
- * Matches the webapp's CheckRunNavigationTracePage.console array item type
+ * Type guard to check if a test result is valid
  */
-interface ConsoleMessage {
-    /**
-     * Unique identifier for the console message
-     */
-    id: string;
-    /**
-     * Source location where the console message was triggered
-     */
-    location: ConsoleMessageLocation;
-    /**
-     * The text content of the console message
-     */
-    text: string;
+declare function isValidTestResult(obj: unknown): obj is TestResult;
+
+interface BaseReporterOptions {
     /**
-     * Timestamp when the message was logged (milliseconds)
+     * Directory for output files. JSON report is written to `{outputDir}/checkly-report.json`.
      */
-    timestamp: number;
+    outputDir?: string;
     /**
-     * Type of console message
+     * @deprecated Use `outputDir` instead. Will be removed in next major version.
      */
-    type: ConsoleMessageType;
+    outputFile?: string;
+    verbose?: boolean;
 }
-/**
- * Network request extracted from Playwright trace
- * Matches the webapp's CheckRunNavigationTraceNetworkEntry type
- */
-interface NetworkRequest {
-    id: string;
-    url: string;
-    domain: string;
-    method: string;
-    resourceType: string;
-    statusCode: number;
-    statusText: string;
-    start: number;
-    startedAt: number;
-    finishedAt: number;
-    time: number;
-    hasFinished: boolean;
-    hasSucceeded: boolean;
-    requestHeaders: Record<string, string>;
-    responseHeaders: Record<string, string>;
-    transferBytes?: number;
-    resourceBytes?: number;
+type LogFn = (message: string, data?: Record<string, unknown>) => void;
+interface ExtensionContext$1 {
+    log: LogFn;
 }
-/**
- * Checkly-specific extensions added to JSONReportTestResult
- */
-interface ChecklyTestResultExtensions {
+interface Extension$1 {
+    name: string;
+    onBegin?(ctx: ExtensionContext$1 & {
+        config: FullConfig;
+        suite: Suite$1;
+    }): void | Promise<void>;
+    onTestBegin?(ctx: ExtensionContext$1 & {
+        test: TestCase;
+        result: TestResult$1;
+    }): void | Promise<void>;
+    onStepBegin?(ctx: ExtensionContext$1 & {
+        test: TestCase;
+        result: TestResult$1;
+        step: TestStep$1;
+    }): void | Promise<void>;
+    onStepEnd?(ctx: ExtensionContext$1 & {
+        test: TestCase;
+        result: TestResult$1;
+        step: TestStep$1;
+    }): void | Promise<void>;
+    onTestEnd?(ctx: ExtensionContext$1 & {
+        test: TestCase;
+        result: TestResult$1;
+    }): void | Promise<void>;
+    onStdOut?(ctx: ExtensionContext$1 & {
+        chunk: string | Buffer;
+        test?: TestCase;
+        result?: TestResult$1;
+    }): void | Promise<void>;
+    onStdErr?(ctx: ExtensionContext$1 & {
+        chunk: string | Buffer;
+        test?: TestCase;
+        result?: TestResult$1;
+    }): void | Promise<void>;
+    onError?(ctx: ExtensionContext$1 & {
+        error: TestError$1;
+    }): void | Promise<void>;
+    onEnd?(ctx: ExtensionContext$1 & {
+        result: FullResult;
+        report: JSONReport;
+        addSummaryLine: (line: string) => void;
+    }): void | Promise<void>;
+    onExit?(ctx: ExtensionContext$1): void | Promise<void>;
+}
+declare class BaseReporter implements Reporter {
+    private config;
+    private suite;
+    private startTime;
+    private options;
+    private verbose;
+    private globalErrors;
+    private tests;
+    private expectedCount;
+    private unexpectedCount;
+    private flakyCount;
+    private skippedCount;
+    private _report;
+    private extensions;
+    private summaryLines;
+    constructor(options?: BaseReporterOptions);
+    protected use(extension: Extension$1): this;
+    private log;
+    private createExtensionLogger;
+    onBegin(config: FullConfig, suite: Suite$1): void;
+    onTestBegin(test: TestCase, result: TestResult$1): void;
+    onStepBegin(test: TestCase, result: TestResult$1, step: TestStep$1): void;
+    onStepEnd(test: TestCase, result: TestResult$1, step: TestStep$1): void;
+    onTestEnd(test: TestCase, result: TestResult$1): void;
+    onStdOut(chunk: string | Buffer, test?: TestCase, result?: TestResult$1): void;
+    onStdErr(chunk: string | Buffer, test?: TestCase, result?: TestResult$1): void;
+    onError(error: TestError$1): void;
+    onEnd(result: FullResult): Promise<void>;
+    onExit(): Promise<void>;
+    printsToStdio(): boolean;
+    getReport(): JSONReport;
+    private buildReport;
+    private serializeConfig;
+    private serializeProject;
+    /**
+     * Serialize suites following the same order as native Playwright JSON reporter.
+     * Iterates through suite tree structure (discovery order) rather than test completion order.
+     */
+    private serializeSuites;
+    /**
+     * Recursively serialize a suite and its children.
+     * Returns null if the suite has no tests.
+     */
+    private serializeSuite;
+    /**
+     * Merge tests from 'from' suite into 'to' suite (for multi-project scenarios).
+     * Matches native Playwright JSON reporter behavior - specs are NOT merged,
+     * each project gets its own spec even for the same test.
+     */
+    private mergeSuites;
+    private serializeSpec;
+    /**
+     * Extract tags from test case - uses testCase.tags (1.42+) or extracts @tags from title
+     * Tags are returned without @ prefix to match native Playwright JSON reporter
+     */
+    private extractTags;
+    private serializeTest;
+    private serializeTestResult;
+    private serializeStep;
+    private serializeError;
+    private serializeAnnotations;
+    private countTests;
+    private getFileName;
+    private mapOutcome;
+    private printSummary;
+}
+
+type ChecklyEnvironment = 'local' | 'development' | 'staging' | 'production';
+interface SessionNameContext {
+    directoryName: string;
+    config: FullConfig;
+    suite: Suite$1;
+}
+type SessionNameOption = string | ((context: SessionNameContext) => string);
+interface ChecklyUploadOptions {
+    apiKey?: string;
+    accountId?: string;
+    environment?: ChecklyEnvironment;
+    sessionName?: SessionNameOption;
+    dryRun?: boolean;
     /**
-     * Warnings about the test result (e.g., missing traces)
+     * Directory for assets and ZIP output. Defaults to Playwright's outputDir.
+     * - Assets (screenshots, videos, traces) are read from here
+     * - ZIP is written to `{outputDir}/checkly-report.zip`
      */
-    warnings?: ChecklyWarning[];
+    outputDir?: string;
     /**
-     * Console messages extracted from the Playwright trace
+     * @deprecated Use `outputDir` instead. Will be removed in next major version.
      */
-    console?: ConsoleMessage[];
+    testResultsDir?: string;
     /**
-     * Network requests extracted from the Playwright trace
+     * @deprecated ZIP is now written to `{outputDir}/checkly-report.zip`. Will be removed in next major version.
      */
-    network?: NetworkRequest[];
+    outputPath?: string;
 }
+interface ExtensionContext {
+    log: LogFn;
+}
+interface Extension {
+    name: string;
+    onBegin?(ctx: ExtensionContext & {
+        config: FullConfig;
+        suite: Suite$1;
+    }): void | Promise<void>;
+    onTestEnd?(ctx: ExtensionContext & {
+        test: TestCase;
+        result: TestResult$1;
+    }): void | Promise<void>;
+    onEnd?(ctx: ExtensionContext & {
+        result: unknown;
+        report: JSONReport;
+        addSummaryLine: (line: string) => void;
+    }): void | Promise<void>;
+}
+declare function checklyUpload(options?: ChecklyUploadOptions): Extension;
+
 /**
- * Extended JSONReportTestResult with Checkly-specific data
- */
-type JSONReportTestResult = JSONReportTestResult$1 & {
-    _checkly?: ChecklyTestResultExtensions;
-};
-/**
- * Extended JSONReportTest with Checkly-extended results
- */
-type JSONReportTest = Omit<JSONReportTest$1, 'results'> & {
-    results: JSONReportTestResult[];
-};
-/**
- * Extended JSONReportSpec with Checkly-extended tests
- */
-type JSONReportSpec = Omit<JSONReportSpec$1, 'tests'> & {
-    tests: JSONReportTest[];
-};
-/**
- * Extended JSONReportSuite with Checkly-extended specs and nested suites
+ * @checkly/playwright-reporter-next
+ *
+ * Standalone Playwright reporter for Checkly
+ * Compatible with Playwright 1.40 through 1.57+
  */
-type JSONReportSuite = Omit<JSONReportSuite$1, 'suites' | 'specs'> & {
-    suites?: JSONReportSuite[];
-    specs: JSONReportSpec[];
-};
+
+interface ChecklyReporterOptions extends BaseReporterOptions, ChecklyUploadOptions {
+}
 /**
- * Extended JSONReport with Checkly-extended suites
+ * Full-featured reporter with all Checkly functionality.
+ * This is what Playwright loads when using the package.
  */
-type JSONReport = Omit<JSONReport$1, 'suites'> & {
-    suites: JSONReportSuite[];
-};
+declare class ChecklyReporter extends BaseReporter {
+    constructor(options?: ChecklyReporterOptions);
+}
 
 /**
- * Checkly Playwright Reporter
+ * Create a Checkly reporter configuration with full intellisense support.
  *
- * Creates a ZIP archive containing the JSON report and all test assets.
- * Designed to work alongside Playwright's built-in JSONReporter.
+ * Use this instead of the array-based syntax for better IDE experience.
  *
  * @example
- * // playwright.config.ts
+ * import { createChecklyReporter } from '@checkly/playwright-reporter'
+ *
  * export default defineConfig({
  *   reporter: [
- *     ['json', { outputFile: 'test-results/playwright-test-report.json' }],
- *     ['@checkly/playwright-reporter', {
- *       apiKey: process.env.CHECKLY_API_KEY,
- *       accountId: process.env.CHECKLY_ACCOUNT_ID,
- *     }]
- *   ]
- * });
+ *     createChecklyReporter({ outputDir: 'test-results' }),
+ *   ],
+ * })
  */
-declare class ChecklyReporter implements Reporter {
-    private options;
-    private assetCollector;
-    private zipper;
-    private testResults?;
-    private testSession?;
-    private startTime?;
-    private testCounts;
-    private stepsMap;
-    private warningsMap;
-    private tracePathsMap;
-    private consoleMessagesMap;
-    private networkRequestsMap;
-    /**
-     * Log a message if verbose mode is enabled
-     */
-    private log;
-    constructor(options?: ChecklyReporterOptions);
-    /**
-     * Resolves the session name from options
-     * Supports string, callback function, or falls back to default
-     */
-    private resolveSessionName;
-    /**
-     * Checks if test result has a trace attachment and adds context-aware warning if missing
-     * Also captures trace file path for later console message extraction
-     * The warning type depends on the trace configuration and test result state
-     */
-    private checkTraceAttachment;
-    /**
-     * Called once before running tests
-     * Creates test session in Checkly if credentials provided
-     */
-    onBegin(config: FullConfig, suite: Suite): void;
-    /**
-     * Called for each test when it completes
-     * Captures steps and warnings, tracks test results for final status calculation
-     */
-    onTestEnd(test: TestCase, result: TestResult): void;
-    /**
-     * Called after all tests have completed
-     * This is where we create the ZIP archive and upload results
-     */
-    onEnd(): Promise<void>;
-    private printSummary;
-    /**
-     * Extracts console messages and network requests from all captured traces
-     * Called before injecting data into the report
-     */
-    private extractDataFromTraces;
-    /**
-     * Injects captured steps, warnings, console messages, and network requests into the JSON report
-     * Traverses the report structure and matches by test ID + retry
-     */
-    private injectDataIntoReport;
-    /**
-     * Reconstructs config.projects and test.projectId from test data
-     * This is necessary for blob merge scenarios where Playwright's JSON reporter
-     * doesn't populate projects array or projectId fields
-     */
-    private reconstructProjectsFromTests;
-    /**
-     * Uploads test results to Checkly API
-     */
-    private uploadResults;
-    /**
-     * Called when a global error occurs
-     */
-    onError(error: TestError): void;
-}
+declare function createChecklyReporter(options?: ChecklyReporterOptions): ['@checkly/playwright-reporter', ChecklyReporterOptions];
 
-export { ChecklyReporter, type ChecklyReporterOptions, type ChecklyTestResultExtensions, type ChecklyWarning, type ChecklyWarningType, type ConsoleMessage, type ConsoleMessageLocation, type ConsoleMessageType, type JSONReport, type JSONReportSpec, type JSONReportSuite, type JSONReportTest, type JSONReportTestResult, type NetworkRequest, ChecklyReporter as default };
+export { type Annotation, type Attachment, BaseReporter, type BaseReporterOptions, ChecklyReporter, type ChecklyReporterOptions, type ChecklyUploadOptions, type JSONReport, type Location, type LogFn, type ProjectConfig, type ReportConfig, type Spec, type Stats, type Suite, type Test, type TestError, type TestOutcome, type TestResult, type TestStatus, type TestStep, checklyUpload, createChecklyReporter, ChecklyReporter as default, isValidJSONReport, isValidStats, isValidTestResult };