playwright-order-manager 0.1.0

package/dist/types/index.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Controls how tests are grouped and sequenced before execution.
+ *
+ * - 'basic'    → runs tests in the order Playwright discovers them. No reordering.
+ * - 'priority' → groups tests by @P1/@P2/@P3/@P4 tags, runs highest priority first.
+ * - 'custom'   → reserved for v2. Allows user-defined ordering functions.
+ */
+export type OrderMode = 'basic' | 'priority' | 'custom';
+/**
+ * Controls what happens when a bucket (group of tests) fails.
+ *
+ * - 'critical'   → if a bucket marked critical fails, stop the entire run immediately.
+ * - 'continue'   → log the failure and continue running remaining buckets.
+ * - 'immediate'  → stop the entire run on the very first failure, regardless of bucket.
+ */
+export type FailurePolicy = 'critical' | 'continue' | 'immediate';
+/**
+ * The four priority tags your tests can be annotated with.
+ * @P1 = highest priority, @P4 = lowest priority.
+ */
+export type PriorityTag = '@P1' | '@P2' | '@P3' | '@P4';
+/**
+ * How a bucket was formed.
+ *
+ * - 'boundary'  → a special bucket: the @runFirst or @runLast group.
+ * - 'priority'  → a bucket formed from a @P1/@P2/@P3/@P4 group.
+ * - 'none'      → a bucket formed from tests with no priority tag (NoPriority group).
+ */
+export type BucketKind = 'boundary' | 'priority' | 'none';
+/**
+ * Represents a single test case as discovered by `playwright --list`.
+ * This is the raw information before any ordering or grouping happens.
+ */
+export interface DiscoveredTestCase {
+    /** Full test title including describe block(s), e.g. "Login > should redirect on success" */
+    title: string;
+    /** Absolute path to the test file on disk */
+    file: string;
+    /** Line number where the test is defined in its file */
+    line: number;
+    /**
+     * All tags attached to this test.
+     * e.g. ['@P1', '@runFirst', '@smoke']
+     */
+    tags: string[];
+    /**
+     * The project name this test belongs to, as defined in playwright.config.ts.
+     * e.g. 'chromium', 'firefox', 'Mobile Chrome'
+     */
+    project: string;
+}
+/**
+ * The outcome of a single test after it has been executed.
+ */
+export type TestStatus = 'passed' | 'failed' | 'skipped' | 'timedOut' | 'interrupted';
+/**
+ * Represents the result of one test case after a Playwright run completes.
+ */
+export interface ExecutedTestResult {
+    /** Full test title, matching what was in DiscoveredTestCase */
+    title: string;
+    /** Absolute path to the test file */
+    file: string;
+    /** Final status of this test */
+    status: TestStatus;
+    /**
+     * How long this test took to run, in milliseconds.
+     * Will be 0 for skipped tests.
+     */
+    duration: number;
+    /**
+     * Number of retry attempts used.
+     * 0 means the test passed (or failed) on the first try.
+     */
+    retries: number;
+    /** Error message if the test failed. undefined if it passed or was skipped. */
+    errorMessage?: string;
+    /**
+     * Tags attached to this test, e.g. ['@P1', '@runFirst', '@smoke'].
+     * Optional — populated during discovery, carried through to the report.
+     */
+    tags?: string[];
+}
+/**
+ * A planned group of tests before execution begins.
+ * OrderedExecution.buildBuckets() produces an array of these.
+ */
+export interface BucketPlan {
+    /**
+     * Unique identifier for this bucket.
+     * e.g. 'boundary-run-first', 'priority-P1', 'priority-P2', 'none'
+     */
+    key: string;
+    /**
+     * Human-readable label shown in logs and reports.
+     * e.g. 'Run First', 'Priority P1', 'No Priority'
+     */
+    label: string;
+    /** How this bucket was formed */
+    kind: BucketKind;
+    /**
+     * If true, a failure in this bucket will trigger the FailurePolicy.
+     * Boundary buckets (@runFirst) are typically critical.
+     */
+    critical: boolean;
+    /** The tests that belong to this bucket, in execution order */
+    tests: DiscoveredTestCase[];
+}
+/**
+ * The result record for a bucket after it has been fully executed.
+ * One of these is written to disk for every bucket that ran.
+ */
+export interface BucketExecutionRecord {
+    /** Matches the key from BucketPlan */
+    key: string;
+    /** Matches the label from BucketPlan */
+    label: string;
+    /** Whether this bucket was marked critical */
+    critical: boolean;
+    /** Total number of tests in this bucket */
+    totalTests: number;
+    /** How many tests passed */
+    passed: number;
+    /** How many tests failed */
+    failed: number;
+    /** How many tests were skipped */
+    skipped: number;
+    /** Total wall-clock time for the entire bucket, in milliseconds */
+    duration: number;
+    /** The final status of the bucket as a whole */
+    status: 'passed' | 'failed' | 'skipped';
+    /**
+     * ISO 8601 timestamp of when this bucket started executing.
+     * Optional — only present when the runner records timing per bucket.
+     */
+    startedAt?: string;
+    /**
+     * ISO 8601 timestamp of when this bucket finished executing.
+     * Optional — only present when the runner records timing per bucket.
+     */
+    finishedAt?: string;
+    /** Individual test results within this bucket */
+    results: ExecutedTestResult[];
+}
+/**
+ * The complete summary of an ordered test run.
+ * Written to disk as JSON and used to generate the HTML report.
+ */
+export interface OrderedRunSummary {
+    /** ISO 8601 timestamp of when the run started, e.g. "2024-03-27T10:30:00.000Z" */
+    startedAt: string;
+    /** ISO 8601 timestamp of when the run finished */
+    finishedAt: string;
+    /** Total wall-clock duration of the entire run, in milliseconds */
+    totalDuration: number;
+    /** The OrderMode that was used for this run */
+    orderMode: OrderMode;
+    /** The FailurePolicy that was used for this run */
+    failurePolicy: FailurePolicy;
+    /** Summary counts across all buckets */
+    totals: {
+        tests: number;
+        passed: number;
+        failed: number;
+        skipped: number;
+        buckets: number;
+    };
+    /** Whether the overall run should be considered a success */
+    success: boolean;
+    /** One record per bucket that was executed */
+    buckets: BucketExecutionRecord[];
+}
+/**
+ * Options passed to OrderedExecution.buildBuckets().
+ * Controls how tests are grouped into buckets.
+ */
+export interface BuildBucketOptions {
+    /** The discovered tests to group */
+    tests: DiscoveredTestCase[];
+    /** How to order and group them */
+    orderMode: OrderMode;
+    /**
+     * Tags that force a test to run first, before all other buckets.
+     * Defaults to ['@runFirst']
+     */
+    runFirstTags?: string[];
+    /**
+     * Tags that force a test to run last, after all other buckets.
+     * Defaults to ['@runLast']
+     */
+    runLastTags?: string[];
+}
+/**
+ * The full configuration object for a programmatic run.
+ * Passed to TestOrderManager when used as a library (not via CLI).
+ * All fields are optional — anything not provided falls back to env vars,
+ * then to the defaults in RunnerConstants.
+ */
+export interface RunConfig {
+    /** Path to your playwright.config.ts. Defaults to ./playwright.config.ts */
+    playwrightConfigPath?: string;
+    /** Path to your merge config. Defaults to ./playwright.merge.config.ts */
+    mergeConfigPath?: string;
+    /** Directory where run output (JSON, HTML) is written. Defaults to ./ordered-results */
+    reportRoot?: string;
+    /** How to order tests. Defaults to 'priority' */
+    orderMode?: OrderMode;
+    /** What to do when a critical bucket fails. Defaults to 'critical' */
+    failurePolicy?: FailurePolicy;
+    /** Playwright project name(s) to run, e.g. 'chromium'. Forwarded to Playwright. */
+    project?: string | string[];
+    /** Any extra flags to forward to the Playwright CLI */
+    extraArgs?: string[];
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

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

package/dist/types/index.js

@@ -0,0 +1,6 @@
+"use strict";
+// =============================================================================
+// ORDER MODES & POLICIES
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,yBAAyB;AACzB,gFAAgF"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "playwright-order-manager",
+  "version": "0.1.0",
+  "description": "Priority-ordered test execution for Playwright",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./fixtures": {
+      "require": "./dist/fixtures/index.js",
+      "types": "./dist/fixtures/index.d.ts"
+    }
+  },
+  "bin": {
+    "pw-order": "bin/run.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "templates",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "playwright test --config=tests/playwright.config.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.40.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@types/node": "^22.19.15",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "dotenv": "^16.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "playwright",
+    "test-order",
+    "priority",
+    "test-runner",
+    "ordered-execution"
+  ],
+  "author": "rajeshyemul",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rajeshyemul/playwright-order-manager.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rajeshyemul/playwright-order-manager/issues"
+  },
+  "homepage": "https://github.com/rajeshyemul/playwright-order-manager#readme"
+}

package/templates/playwright.merge.config.ts

@@ -0,0 +1,57 @@
+/**
+ * playwright.merge.config.ts
+ *
+ * Copy this file into your project root and adjust as needed.
+ *
+ * This config is used by playwright-order-manager during the merge phase —
+ * after all buckets have executed, it merges their individual JSON reports
+ * into one combined HTML report using Playwright's built-in merge-reports.
+ *
+ * SETUP:
+ *   1. Copy this file to your project root:
+ *      cp node_modules/playwright-order-manager/templates/playwright.merge.config.ts .
+ *
+ *   2. Point the runner at it via env var or RunConfig:
+ *      PLAYWRIGHT_MERGE_CONFIG=./playwright.merge.config.ts
+ *
+ * DOCS:
+ *   https://playwright.dev/docs/test-reporters#merge-reports-cli
+ */
+
+import { defineConfig } from '@playwright/test';
+import * as path from 'path';
+
+/**
+ * The directory where playwright-order-manager writes per-bucket blob reports.
+ * Must match the ORDERED_REPORT_ROOT env var (default: 'ordered-results').
+ */
+const REPORT_ROOT = process.env['ORDERED_REPORT_ROOT'] ?? 'ordered-results';
+
+export default defineConfig({
+  // The merge config does not run tests — it only merges reports.
+  // Point testDir at a non-existent path so no tests are accidentally discovered.
+  testDir: './this-dir-does-not-exist',
+
+  reporter: [
+    // 1. HTML reporter — opens in browser, full test details
+    [
+      'html',
+      {
+        outputFolder: path.join(REPORT_ROOT, 'playwright-html-report'),
+        open: 'never', // never auto-open — let the user decide
+      },
+    ],
+
+    // 2. JUnit XML — useful for CI systems like Jenkins, GitLab, Azure DevOps
+    // Comment this out if you don't need JUnit output.
+    [
+      'junit',
+      {
+        outputFile: path.join(REPORT_ROOT, 'junit-results.xml'),
+      },
+    ],
+
+    // 3. Line reporter — shows a summary line in the terminal during merge
+    ['line'],
+  ],
+});