playwright-order-manager 0.1.0

package/dist/core/OrderedExecution.js

@@ -0,0 +1,253 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrderedExecution = void 0;
+const constants_1 = require("../constants");
+// =============================================================================
+// INTERNAL HELPERS
+// These are private to this file. Not exported. Not part of the public API.
+// =============================================================================
+/**
+ * Returns true if the test has ANY of the given tags.
+ *
+ * Why a separate helper?
+ * Tag matching happens in multiple places (boundary detection, priority grouping).
+ * Centralizing it means if Playwright ever changes how tags work, we fix one place.
+ */
+function hasAnyTag(test, tags) {
+    return test.tags.some((tag) => tags.includes(tag));
+}
+/**
+ * Returns the highest-priority tag found on a test.
+ *
+ * "Highest priority" means earliest in the PRIORITY_TAGS array.
+ * So if a test has both '@P2' and '@P3', this returns '@P2'.
+ *
+ * Returns undefined if the test has no priority tag at all.
+ */
+function getHighestPriorityTag(test) {
+    return constants_1.RunnerConstants.PRIORITY_TAGS.find((tag) => test.tags.includes(tag));
+}
+// =============================================================================
+// BUCKET BUILDERS — one function per OrderMode
+// =============================================================================
+/**
+ * Builds buckets for 'basic' mode.
+ *
+ * Basic mode does the minimum: boundary tests (@runFirst / @runLast) get
+ * their own buckets, everything else goes into one single bucket in the
+ * middle. No priority ordering within that middle bucket.
+ */
+function buildBasicBuckets(tests, runFirstTags, runLastTags) {
+    const runFirstTests = [];
+    const middleTests = [];
+    const runLastTests = [];
+    for (const test of tests) {
+        if (hasAnyTag(test, runFirstTags)) {
+            runFirstTests.push(test);
+        }
+        else if (hasAnyTag(test, runLastTags)) {
+            runLastTests.push(test);
+        }
+        else {
+            middleTests.push(test);
+        }
+    }
+    const buckets = [];
+    if (runFirstTests.length > 0) {
+        buckets.push({
+            key: constants_1.RunnerConstants.BUCKET_KEYS.RUN_FIRST,
+            label: 'Run First',
+            kind: 'boundary',
+            critical: true,
+            tests: runFirstTests,
+        });
+    }
+    if (middleTests.length > 0) {
+        buckets.push({
+            key: constants_1.RunnerConstants.BUCKET_KEYS.NO_PRIORITY,
+            label: 'All Tests',
+            kind: 'none',
+            critical: false,
+            tests: middleTests,
+        });
+    }
+    if (runLastTests.length > 0) {
+        buckets.push({
+            key: constants_1.RunnerConstants.BUCKET_KEYS.RUN_LAST,
+            label: 'Run Last',
+            kind: 'boundary',
+            critical: false,
+            tests: runLastTests,
+        });
+    }
+    return buckets;
+}
+/**
+ * Builds buckets for 'priority' mode.
+ *
+ * Priority mode creates one bucket per priority level that has at least
+ * one test. So if you have @P1 and @P3 tests but no @P2, you get two
+ * priority buckets (not three). Tests with no priority tag go into the
+ * NoPriority bucket, which runs after all priority buckets.
+ *
+ * Full execution order:
+ *   [runFirst] → [@P1] → [@P2] → [@P3] → [@P4] → [NoPriority] → [runLast]
+ *
+ * Empty buckets are omitted entirely.
+ */
+function buildPriorityBuckets(tests, runFirstTags, runLastTags) {
+    const runFirstTests = [];
+    const runLastTests = [];
+    const noPriorityTests = [];
+    // One array per priority tag, keyed by tag name
+    const priorityMap = new Map(constants_1.RunnerConstants.PRIORITY_TAGS.map((tag) => [tag, []]));
+    // Single pass through all tests — assign each to exactly one bucket
+    for (const test of tests) {
+        if (hasAnyTag(test, runFirstTags)) {
+            runFirstTests.push(test);
+            continue;
+        }
+        if (hasAnyTag(test, runLastTags)) {
+            runLastTests.push(test);
+            continue;
+        }
+        const priorityTag = getHighestPriorityTag(test);
+        if (priorityTag) {
+            // Non-null assertion safe here: we just found the tag in PRIORITY_TAGS
+            priorityMap.get(priorityTag).push(test);
+        }
+        else {
+            noPriorityTests.push(test);
+        }
+    }
+    const buckets = [];
+    // 1. runFirst bucket (critical — if this fails, we stop)
+    if (runFirstTests.length > 0) {
+        buckets.push({
+            key: constants_1.RunnerConstants.BUCKET_KEYS.RUN_FIRST,
+            label: 'Run First',
+            kind: 'boundary',
+            critical: true,
+            tests: runFirstTests,
+        });
+    }
+    // 2. One bucket per priority tag, in P1 → P4 order
+    // Skip empty priority buckets entirely
+    for (const tag of constants_1.RunnerConstants.PRIORITY_TAGS) {
+        const testsForTag = priorityMap.get(tag);
+        if (testsForTag.length === 0)
+            continue;
+        // '@P1' → 'P1', '@P2' → 'P2', etc.
+        const shortTag = tag.replace('@', '');
+        buckets.push({
+            key: `priority-${shortTag}`,
+            label: `Priority ${shortTag}`,
+            kind: 'priority',
+            critical: false,
+            tests: testsForTag,
+        });
+    }
+    // 3. NoPriority bucket — tests with no @Px tag
+    if (noPriorityTests.length > 0) {
+        buckets.push({
+            key: constants_1.RunnerConstants.BUCKET_KEYS.NO_PRIORITY,
+            label: constants_1.RunnerConstants.NO_PRIORITY_TOKEN,
+            kind: 'none',
+            critical: false,
+            tests: noPriorityTests,
+        });
+    }
+    // 4. runLast bucket (not critical — cleanup should always attempt to run)
+    if (runLastTests.length > 0) {
+        buckets.push({
+            key: constants_1.RunnerConstants.BUCKET_KEYS.RUN_LAST,
+            label: 'Run Last',
+            kind: 'boundary',
+            critical: false,
+            tests: runLastTests,
+        });
+    }
+    return buckets;
+}
+// =============================================================================
+// PUBLIC API
+// =============================================================================
+class OrderedExecution {
+    /**
+     * Takes a flat list of discovered tests and groups them into ordered buckets.
+     *
+     * This is the core algorithm of the entire package. The buckets returned
+     * here define the execution order — the runner executes them one by one,
+     * in the order they appear in this array.
+     *
+     * @param options - See BuildBucketOptions in types/index.ts
+     * @returns An ordered array of BucketPlan objects, ready for execution
+     *
+     * @example
+     * ```typescript
+     * const buckets = OrderedExecution.buildBuckets({
+     *   tests: discoveredTests,
+     *   orderMode: 'priority',
+     * });
+     * // buckets[0] = runFirst tests (if any)
+     * // buckets[1] = @P1 tests (if any)
+     * // buckets[2] = @P2 tests (if any)
+     * // ...and so on
+     * ```
+     */
+    static buildBuckets(options) {
+        const { tests, orderMode, runFirstTags = [constants_1.RunnerConstants.RUN_FIRST_TAG], runLastTags = [constants_1.RunnerConstants.RUN_LAST_TAG], } = options;
+        // Guard: nothing to do with an empty test list
+        if (tests.length === 0) {
+            return [];
+        }
+        switch (orderMode) {
+            case 'basic':
+                return buildBasicBuckets(tests, runFirstTags, runLastTags);
+            case 'priority':
+                return buildPriorityBuckets(tests, runFirstTags, runLastTags);
+            case 'custom':
+                // v2 — not implemented yet
+                // We throw instead of silently falling back so the user knows immediately
+                throw new Error(`OrderMode 'custom' is not implemented in v1. ` +
+                    `Use 'basic' or 'priority'.`);
+            default: {
+                // This branch should be unreachable if TypeScript types are respected.
+                // But if someone passes an invalid value via JavaScript or env vars,
+                // we want a clear error message.
+                const exhaustiveCheck = orderMode;
+                throw new Error(`Unknown orderMode: '${exhaustiveCheck}'. ` +
+                    `Valid values are: 'basic', 'priority'.`);
+            }
+        }
+    }
+    /**
+     * Splits an array of buckets into three phases for the runner to process.
+     *
+     * Why split into phases?
+     * The runner needs to handle the runFirst bucket specially — if it fails
+     * and the FailurePolicy is 'critical', we stop before running any middle
+     * buckets. Similarly, runLast should always attempt to run (cleanup)
+     * even if middle buckets failed.
+     *
+     * @param buckets - The output from buildBuckets()
+     * @returns An object with three arrays: runFirst, middle, runLast
+     *
+     * @example
+     * ```typescript
+     * const { runFirst, middle, runLast } = OrderedExecution.groupBuckets(buckets);
+     * // Run runFirst phase, check failure policy
+     * // Run middle phase buckets in order
+     * // Run runLast phase regardless of middle results
+     * ```
+     */
+    static groupBuckets(buckets) {
+        const runFirst = buckets.filter((b) => b.key === constants_1.RunnerConstants.BUCKET_KEYS.RUN_FIRST);
+        const runLast = buckets.filter((b) => b.key === constants_1.RunnerConstants.BUCKET_KEYS.RUN_LAST);
+        const middle = buckets.filter((b) => b.key !== constants_1.RunnerConstants.BUCKET_KEYS.RUN_FIRST &&
+            b.key !== constants_1.RunnerConstants.BUCKET_KEYS.RUN_LAST);
+        return { runFirst, middle, runLast };
+    }
+}
+exports.OrderedExecution = OrderedExecution;
+//# sourceMappingURL=OrderedExecution.js.map

package/dist/core/OrderedExecution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OrderedExecution.js","sourceRoot":"","sources":["../../src/core/OrderedExecution.ts"],"names":[],"mappings":"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"}

package/dist/core/OrderedReportParser.d.ts

@@ -0,0 +1,38 @@
+import type { DiscoveredTestCase, ExecutedTestResult } from '../types';
+export declare class OrderedReportParser {
+    /**
+     * Parses Playwright's execution JSON report into our typed ExecutedTestResult array.
+     *
+     * Call this after a Playwright run completes and writes its JSON report.
+     * The result is what OrderedSummary uses to build the final summary.
+     *
+     * @param rawJson - The parsed contents of Playwright's JSON report file.
+     *                  Pass the result of JSON.parse(fs.readFileSync(reportPath, 'utf8')).
+     * @returns A flat array of ExecutedTestResult, one entry per test per project.
+     *
+     * @example
+     * ```typescript
+     * const raw = JSON.parse(fs.readFileSync('./test-results/report.json', 'utf8'));
+     * const results = OrderedReportParser.parseExecutionReport(raw);
+     * ```
+     */
+    static parseExecutionReport(rawJson: unknown): ExecutedTestResult[];
+    /**
+     * Parses the discovery JSON written during `playwright --list` phase.
+     *
+     * During discovery, our fixture writes a JSON file containing the list
+     * of all tests Playwright found. This method reads that file's contents
+     * and converts them into DiscoveredTestCase objects.
+     *
+     * @param rawJson - The parsed contents of the discovery JSON file.
+     * @returns A flat array of DiscoveredTestCase objects.
+     *
+     * @example
+     * ```typescript
+     * const raw = JSON.parse(fs.readFileSync('./ordered-results/ordered-discovery.json', 'utf8'));
+     * const tests = OrderedReportParser.parseDiscoveryReport(raw);
+     * ```
+     */
+    static parseDiscoveryReport(rawJson: unknown): DiscoveredTestCase[];
+}
+//# sourceMappingURL=OrderedReportParser.d.ts.map

package/dist/core/OrderedReportParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OrderedReportParser.d.ts","sourceRoot":"","sources":["../../src/core/OrderedReportParser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAEnB,MAAM,UAAU,CAAC;AA0JlB,qBAAa,mBAAmB;IAC9B;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,kBAAkB,EAAE;IA0DnE;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,kBAAkB,EAAE;CA8BpE"}

package/dist/core/OrderedReportParser.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrderedReportParser = void 0;
+// =============================================================================
+// INTERNAL HELPERS
+// =============================================================================
+/**
+ * Normalises whatever status string Playwright gives us into our TestStatus type.
+ * Playwright uses 'expected', 'unexpected', 'flaky', 'skipped' — we map those
+ * to our simpler 'passed' | 'failed' | 'skipped' | 'timedOut' | 'interrupted'.
+ */
+function normaliseStatus(raw) {
+    switch (raw) {
+        case 'expected':
+        case 'passed':
+            return 'passed';
+        case 'skipped':
+            return 'skipped';
+        case 'timedOut':
+            return 'timedOut';
+        case 'interrupted':
+            return 'interrupted';
+        // 'unexpected', 'flaky', or anything else we don't recognise → failed
+        default:
+            return 'failed';
+    }
+}
+/**
+ * Extracts the most useful error message from a Playwright error array.
+ * Playwright can report multiple errors per test — we take the first non-empty one.
+ */
+function extractErrorMessage(errors) {
+    if (!errors || errors.length === 0)
+        return undefined;
+    for (const error of errors) {
+        const msg = error.message ?? error.value;
+        if (msg && msg.trim().length > 0) {
+            // Trim to first 500 chars — full stack traces belong in the HTML report,
+            // not in our summary JSON
+            return msg.trim().slice(0, 500);
+        }
+    }
+    return undefined;
+}
+/**
+ * Recursively walks a Playwright suite tree and collects all specs.
+ * Suites can be nested arbitrarily deep (file → describe → describe → spec).
+ *
+ * @param suite     - The current suite node to walk
+ * @param filePath  - The file path, carried down from the top-level suite
+ * @param collected - Accumulator array — specs are pushed here
+ */
+function collectSpecs(suite, filePath, collected) {
+    // Collect specs at this level
+    if (suite.specs) {
+        for (const spec of suite.specs) {
+            collected.push({ spec, file: filePath });
+        }
+    }
+    // Recurse into nested suites
+    if (suite.suites) {
+        for (const child of suite.suites) {
+            // Use the child's own file path if it has one, otherwise inherit from parent
+            collectSpecs(child, child.file ?? filePath, collected);
+        }
+    }
+}
+// =============================================================================
+// PUBLIC API
+// =============================================================================
+class OrderedReportParser {
+    /**
+     * Parses Playwright's execution JSON report into our typed ExecutedTestResult array.
+     *
+     * Call this after a Playwright run completes and writes its JSON report.
+     * The result is what OrderedSummary uses to build the final summary.
+     *
+     * @param rawJson - The parsed contents of Playwright's JSON report file.
+     *                  Pass the result of JSON.parse(fs.readFileSync(reportPath, 'utf8')).
+     * @returns A flat array of ExecutedTestResult, one entry per test per project.
+     *
+     * @example
+     * ```typescript
+     * const raw = JSON.parse(fs.readFileSync('./test-results/report.json', 'utf8'));
+     * const results = OrderedReportParser.parseExecutionReport(raw);
+     * ```
+     */
+    static parseExecutionReport(rawJson) {
+        // Validate that we got something that looks like a Playwright report
+        if (!rawJson || typeof rawJson !== 'object') {
+            throw new Error('OrderedReportParser.parseExecutionReport: ' +
+                'expected a JSON object, got ' + typeof rawJson);
+        }
+        const report = rawJson;
+        if (!Array.isArray(report.suites)) {
+            throw new Error('OrderedReportParser.parseExecutionReport: ' +
+                'JSON does not look like a Playwright report (missing "suites" array)');
+        }
+        const results = [];
+        // Collect all specs from the entire suite tree
+        const allSpecs = [];
+        for (const topSuite of report.suites) {
+            collectSpecs(topSuite, topSuite.file ?? '', allSpecs);
+        }
+        // Convert each spec + its tests into ExecutedTestResult entries
+        for (const { spec, file } of allSpecs) {
+            if (!spec.tests || spec.tests.length === 0)
+                continue;
+            for (const test of spec.tests) {
+                // How many retries were used?
+                // results array has one entry per attempt. retries = attempts - 1.
+                const retries = test.results
+                    ? Math.max(0, test.results.length - 1)
+                    : 0;
+                // The final error comes from the last result attempt (if it failed)
+                const lastResult = test.results?.[test.results.length - 1];
+                const errorMessage = extractErrorMessage(lastResult?.errors ?? test.errors);
+                results.push({
+                    title: spec.title,
+                    file,
+                    status: normaliseStatus(test.status),
+                    duration: test.duration,
+                    retries,
+                    errorMessage,
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Parses the discovery JSON written during `playwright --list` phase.
+     *
+     * During discovery, our fixture writes a JSON file containing the list
+     * of all tests Playwright found. This method reads that file's contents
+     * and converts them into DiscoveredTestCase objects.
+     *
+     * @param rawJson - The parsed contents of the discovery JSON file.
+     * @returns A flat array of DiscoveredTestCase objects.
+     *
+     * @example
+     * ```typescript
+     * const raw = JSON.parse(fs.readFileSync('./ordered-results/ordered-discovery.json', 'utf8'));
+     * const tests = OrderedReportParser.parseDiscoveryReport(raw);
+     * ```
+     */
+    static parseDiscoveryReport(rawJson) {
+        if (!rawJson || typeof rawJson !== 'object') {
+            throw new Error('OrderedReportParser.parseDiscoveryReport: ' +
+                'expected a JSON object, got ' + typeof rawJson);
+        }
+        const data = rawJson;
+        if (!Array.isArray(data.tests)) {
+            throw new Error('OrderedReportParser.parseDiscoveryReport: ' +
+                'discovery JSON missing "tests" array. ' +
+                'Make sure the orderedDiscovery fixture is set up correctly.');
+        }
+        // Validate and cast each entry
+        return data.tests
+            .filter((entry) => {
+            return (entry !== null &&
+                typeof entry === 'object' &&
+                typeof entry.title === 'string' &&
+                typeof entry.file === 'string' &&
+                Array.isArray(entry.tags));
+        });
+    }
+}
+exports.OrderedReportParser = OrderedReportParser;
+//# sourceMappingURL=OrderedReportParser.js.map

package/dist/core/OrderedReportParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OrderedReportParser.js","sourceRoot":"","sources":["../../src/core/OrderedReportParser.ts"],"names":[],"mappings":"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"}

package/dist/core/OrderedSummary.d.ts

@@ -0,0 +1,20 @@
+import type { OrderedRunSummary, BucketExecutionRecord } from '../types';
+export declare class OrderedSummary {
+    /**
+     * Writes the ordered run summary to disk as both JSON and HTML.
+     *
+     * @param summary    - The complete run summary to write
+     * @param reportRoot - Directory to write into. Defaults to RunnerConstants.DEFAULTS.REPORT_ROOT
+     * @returns Absolute paths of the files written: { jsonPath, htmlPath }
+     */
+    static write(summary: OrderedRunSummary, reportRoot?: string): {
+        jsonPath: string;
+        htmlPath: string;
+    };
+    /**
+     * Builds an OrderedRunSummary from raw bucket execution records.
+     * Call this after all buckets finish, then pass the result to write().
+     */
+    static buildSummary(buckets: BucketExecutionRecord[], startedAt: string, orderMode: string, failurePolicy: string): OrderedRunSummary;
+}
+//# sourceMappingURL=OrderedSummary.d.ts.map

package/dist/core/OrderedSummary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OrderedSummary.d.ts","sourceRoot":"","sources":["../../src/core/OrderedSummary.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EAEtB,MAAM,UAAU,CAAC;AAyqBlB,qBAAa,cAAc;IACzB;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,CACV,OAAO,EAAE,iBAAiB,EAC1B,UAAU,GAAE,MAA6C,GACxD;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IA2BzC;;;OAGG;IACH,MAAM,CAAC,YAAY,CACjB,OAAO,EAAE,qBAAqB,EAAE,EAChC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,iBAAiB;CA6BrB"}