@checkly/playwright-reporter 0.1.9 → 1.0.0

package/dist/index.d.ts

@@ -1,219 +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
+ * 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)
  */
-type ChecklyEnvironment = 'local' | 'development' | 'staging' | 'production';
 /**
- * Context passed to sessionName callback function
+ * Individual test run status
  */
-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;
+type TestStatus = 'passed' | 'failed' | 'skipped' | 'timedOut' | 'interrupted';
+/**
+ * Overall test outcome (aggregated across retries)
+ */
+type TestOutcome = 'expected' | 'unexpected' | 'skipped' | 'flaky';
+interface Location {
+    file: string;
+    line: number;
+    column: number;
+}
+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;
 }
 /**
- * Session name can be a static string or a function that returns a string
+ * Type guard to check if an object is a valid JSONReport
  */
-type SessionNameOption = string | ((context: SessionNameContext) => string);
+declare function isValidJSONReport(obj: unknown): obj is JSONReport;
+/**
+ * Type guard to check if stats are valid
+ */
+declare function isValidStats(obj: unknown): obj is Stats;
 /**
- * Configuration options for ChecklyReporter
+ * Type guard to check if a test result is valid
  */
-interface ChecklyReporterOptions {
+declare function isValidTestResult(obj: unknown): obj is TestResult;
+
+interface BaseReporterOptions {
     /**
-     * Checkly account ID for uploading test results
-     * Required for Phase 2 (upload functionality)
+     * Directory for output files. JSON report is written to `{outputDir}/checkly-report.json`.
      */
-    accountId?: string;
+    outputDir?: string;
     /**
-     * Checkly API key for authentication
-     * Required for Phase 2 (upload functionality)
+     * @deprecated Use `outputDir` instead. Will be removed in next major version.
      */
-    apiKey?: string;
+    outputFile?: string;
+    verbose?: boolean;
+}
+type LogFn = (message: string, data?: Record<string, unknown>) => void;
+interface ExtensionContext$1 {
+    log: LogFn;
+}
+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;
     /**
-     * Checkly environment to use
-     * Can also be set via CHECKLY_ENV environment variable
-     * @default 'production'
+     * Serialize suites following the same order as native Playwright JSON reporter.
+     * Iterates through suite tree structure (discovery order) rather than test completion order.
      */
-    environment?: ChecklyEnvironment;
+    private serializeSuites;
     /**
-     * Output path for the generated ZIP file (for testing/debugging)
-     * @default 'checkly-report.zip'
-     * @internal
+     * Recursively serialize a suite and its children.
+     * Returns null if the suite has no tests.
      */
-    outputPath?: string;
+    private serializeSuite;
     /**
-     * Path to the JSON report file generated by Playwright's json reporter
-     * @default 'test-results/playwright-test-report.json'
-     * @internal
+     * 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.
      */
-    jsonReportPath?: string;
+    private mergeSuites;
+    private serializeSpec;
     /**
-     * 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
+     * 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;
     /**
-     * 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)`
+     * 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`
      */
-    sessionName?: SessionNameOption;
-}
-/**
- * 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 {
+    outputDir?: string;
     /**
-     * Type of warning for programmatic handling
+     * @deprecated Use `outputDir` instead. Will be removed in next major version.
      */
-    type: ChecklyWarningType;
+    testResultsDir?: string;
     /**
-     * Human-readable warning message
+     * @deprecated ZIP is now written to `{outputDir}/checkly-report.zip`. Will be removed in next major version.
      */
-    message: string;
+    outputPath?: string;
 }
-/**
- * Checkly-specific extensions added to JSONReportTestResult
- */
-interface ChecklyTestResultExtensions {
-    /**
-     * Warnings about the test result (e.g., missing traces)
-     */
-    warnings?: ChecklyWarning[];
+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;
-    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
-     * 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;
-    /**
-     * Injects captured steps and warnings 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 JSONReport, type JSONReportSpec, type JSONReportSuite, type JSONReportTest, type JSONReportTestResult, 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 };