@dionlarson/playwright-orchestrator-core 1.3.9 → 1.5.0

package/README.md

@@ -142,14 +142,27 @@ Creates and configures a new test run. Outputs created run ID. Supports most of
 
 Starts a test shard for the provided test run. If used with a finished run, it will only start failed tests.
 
-Command generate blob reports into `--output` directory. To merge it use [Playwright's Merge-reports CLI](https://playwright.dev/docs/test-sharding#merge-reports-cli)
+Command generates blob reports into `--output` directory. To merge them use [Playwright's Merge-reports CLI](https://playwright.dev/docs/test-sharding#merge-reports-cli)
 
-**`webServer` property is not supported and is ignored; make sure the app run beforehand.**
+#### Setup Phase
 
-| Option         | Description                               | Type     | Default        | Required? |
-| -------------- | ----------------------------------------- | -------- | -------------- | --------- |
-| `--run-id`     | Run ID generated by `create` command      | `string` | -              | yes       |
-| `-o, --output` | Directory for artifacts produced by tests | `string` | `blob_reports` | no        |
+Each shard automatically runs these setup operations **once** before executing tests:
+
+1. **globalSetup** - Runs your `globalSetup` file (if configured in playwright.config.ts)
+2. **webServer** - Starts your `webServer` (if configured) and waits for it to be ready
+3. **Setup projects** - Runs any projects that are dependencies but have no dependencies themselves
+
+After all tests complete (or on failure), teardown runs in reverse order: stop webServer → run globalTeardown.
+
+**Note:** Each shard is independent (runs on different machines), so setup runs once per shard, not once globally.
+
+| Option                   | Description                                        | Type     | Default        | Required? |
+| ------------------------ | -------------------------------------------------- | -------- | -------------- | --------- |
+| `--run-id`               | Run ID generated by `create` command               | `string` | -              | yes       |
+| `-o, --output`           | Directory for artifacts produced by tests          | `string` | `blob_reports` | no        |
+| `--skip-global-setup`    | Skip globalSetup (use when managed externally)     | -        | -              | no        |
+| `--skip-web-server`      | Skip webServer startup (use when already running)  | -        | -              | no        |
+| `--skip-setup-projects`  | Skip setup project execution                       | -        | -              | no        |
 
 ### `create-report`
 

package/dist/adapter.d.ts

@@ -11,6 +11,7 @@ export declare abstract class Adapter {
     abstract finishShard(runId: string): Promise<void>;
     abstract getReportData(runId: string): Promise<TestRunReport>;
     abstract dispose(): Promise<void>;
+    abstract cleanupStaleTests(runId: string, staleMinutes: number): Promise<number>;
     protected transformTestRunToItems(run: TestRun): ReporterTestItem[];
     protected sortTests(tests: ReporterTestItem[], testInfoMap: Map<string, TestSortItem>, { historyWindow, reverse }: SortTestsOptions): ReporterTestItem[];
     private extractCompareValue;

package/dist/commands/cleanup.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/dist/commands/cleanup.js

@@ -0,0 +1,17 @@
+import { loadPlugins } from '../helpers/plugin.js';
+import { withErrorHandling } from './error-handler.js';
+import { program } from './program.js';
+export default async () => {
+    const command = program.command('cleanup').description('Reset stale tests for a run');
+    for await (const { factory, subCommand } of loadPlugins(command)) {
+        subCommand
+            .requiredOption('--run-id <string>', 'Run id to cleanup')
+            .option('--stale-minutes <number>', 'Consider tests stale after N minutes', '10')
+            .action(withErrorHandling(async (options) => {
+            const adapter = await factory(options);
+            const count = await adapter.cleanupStaleTests(options.runId, parseInt(options.staleMinutes));
+            console.log(`Reset ${count} stale tests`);
+            await adapter.dispose();
+        }));
+    }
+};

package/dist/commands/program.js

@@ -3,6 +3,7 @@ import init from './init.js';
 import run from './run.js';
 import create from './create.js';
 import createReport from './create-report.js';
+import cleanup from './cleanup.js';
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
@@ -17,4 +18,5 @@ await init();
 await run();
 await create();
 await createReport();
+await cleanup();
 program.parse();

package/dist/commands/run.js

@@ -8,9 +8,19 @@ export default async () => {
         subCommand
             .requiredOption('--run-id <string>', 'Run id generated by create command')
             .option('-o, --output <string>', 'Output folder for blob reports. Existing content is deleted before writing the new report.', 'blob-reports')
+            .option('--skip-global-setup', 'Skip globalSetup (use when managed externally)')
+            .option('--skip-web-server', 'Skip webServer startup (use when server already running)')
+            .option('--skip-setup-projects', 'Skip setup project execution')
             .action(withErrorHandling(async (options) => {
             const adapter = await factory(options);
-            const runner = new TestRunner(options, adapter);
+            const runnerOptions = {
+                runId: options.runId,
+                output: options.output,
+                skipGlobalSetup: options.skipGlobalSetup,
+                skipWebServer: options.skipWebServer,
+                skipSetupProjects: options.skipSetupProjects,
+            };
+            const runner = new TestRunner(runnerOptions, adapter);
             await runner.runTests();
             console.log('Run completed');
         }));

package/dist/helpers/setup-manager.d.ts

@@ -0,0 +1,37 @@
+import { SetupConfig } from '../types/test-info.js';
+export interface SetupManagerOptions {
+    configFile?: string;
+    skipGlobalSetup?: boolean;
+    skipWebServer?: boolean;
+    skipSetupProjects?: boolean;
+}
+/**
+ * Manages shard-level setup and teardown.
+ * Each shard runs independently on potentially different machines,
+ * so setup runs once per shard (not once globally).
+ */
+export declare class SetupManager {
+    private readonly setup;
+    private readonly options;
+    private webServerProcesses;
+    private setupComplete;
+    constructor(setup: SetupConfig, options?: SetupManagerOptions);
+    /**
+     * Run all setup operations in order: globalSetup → webServers → setupProjects
+     */
+    runSetup(): Promise<void>;
+    /**
+     * Run teardown operations: stop webServers → globalTeardown
+     * Always runs in finally block, even on test failures.
+     */
+    runTeardown(): Promise<void>;
+    private runGlobalSetup;
+    private runGlobalTeardown;
+    private startWebServers;
+    private startWebServer;
+    private waitForServer;
+    private stopWebServers;
+    private runSetupProjects;
+    private execCommand;
+    private buildConfigForHooks;
+}

package/dist/helpers/setup-manager.js

@@ -0,0 +1,182 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+/**
+ * Manages shard-level setup and teardown.
+ * Each shard runs independently on potentially different machines,
+ * so setup runs once per shard (not once globally).
+ */
+export class SetupManager {
+    setup;
+    options;
+    webServerProcesses = [];
+    setupComplete = false;
+    constructor(setup, options = {}) {
+        this.setup = setup;
+        this.options = options;
+    }
+    /**
+     * Run all setup operations in order: globalSetup → webServers → setupProjects
+     */
+    async runSetup() {
+        console.log('[orchestrator:setup] Starting shard setup...');
+        try {
+            await this.runGlobalSetup();
+            await this.startWebServers();
+            await this.runSetupProjects();
+            this.setupComplete = true;
+            console.log('[orchestrator:setup] Shard setup complete');
+        }
+        catch (error) {
+            console.error('[orchestrator:setup] Setup failed:', error);
+            // Clean up any started web servers before re-throwing
+            await this.stopWebServers();
+            throw error;
+        }
+    }
+    /**
+     * Run teardown operations: stop webServers → globalTeardown
+     * Always runs in finally block, even on test failures.
+     */
+    async runTeardown() {
+        console.log('[orchestrator:teardown] Starting shard teardown...');
+        await this.stopWebServers();
+        // Only run globalTeardown if setup completed successfully
+        if (this.setupComplete) {
+            await this.runGlobalTeardown();
+        }
+        console.log('[orchestrator:teardown] Shard teardown complete');
+    }
+    async runGlobalSetup() {
+        if (this.options.skipGlobalSetup || !this.setup.globalSetup) {
+            return;
+        }
+        console.log(`[orchestrator:setup] Running globalSetup: ${this.setup.globalSetup}`);
+        const setupPath = path.resolve(this.setup.globalSetup);
+        // Dynamic import handles ESM/CJS/TS via Node's loader
+        const setupModule = await import(setupPath);
+        const setupFn = setupModule.default || setupModule;
+        if (typeof setupFn === 'function') {
+            // Pass minimal config object matching Playwright's FullConfig shape
+            const config = this.buildConfigForHooks();
+            await setupFn(config);
+        }
+    }
+    async runGlobalTeardown() {
+        if (!this.setup.globalTeardown) {
+            return;
+        }
+        console.log(`[orchestrator:teardown] Running globalTeardown: ${this.setup.globalTeardown}`);
+        const teardownPath = path.resolve(this.setup.globalTeardown);
+        const teardownModule = await import(teardownPath);
+        const teardownFn = teardownModule.default || teardownModule;
+        if (typeof teardownFn === 'function') {
+            const config = this.buildConfigForHooks();
+            await teardownFn(config);
+        }
+    }
+    async startWebServers() {
+        if (this.options.skipWebServer || this.setup.webServers.length === 0) {
+            return;
+        }
+        console.log(`[orchestrator:setup] Starting ${this.setup.webServers.length} webServer(s)...`);
+        for (const server of this.setup.webServers) {
+            await this.startWebServer(server);
+        }
+    }
+    async startWebServer(server) {
+        const name = server.url || `port ${server.port}`;
+        console.log(`[orchestrator:setup] Starting webServer: ${server.command}`);
+        const proc = spawn(server.command, {
+            shell: true,
+            cwd: server.cwd,
+            env: { ...process.env, ...server.env },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: process.platform !== 'win32',
+        });
+        this.webServerProcesses.push(proc);
+        // Log stderr for debugging
+        proc.stderr?.on('data', (data) => {
+            console.error(`[webServer:stderr] ${data.toString().trim()}`);
+        });
+        // Wait for server to be ready
+        if (server.url || server.port) {
+            const timeout = server.timeout || 60000;
+            await this.waitForServer(server, timeout);
+            console.log(`[orchestrator:setup] webServer ready at ${name}`);
+        }
+    }
+    async waitForServer(server, timeout) {
+        const resource = server.url || `http://localhost:${server.port}`;
+        const startTime = Date.now();
+        // Simple polling loop - check every 500ms
+        while (Date.now() - startTime < timeout) {
+            try {
+                const response = await fetch(resource, { method: 'HEAD' });
+                if (response.ok || response.status < 500) {
+                    return; // Server is ready
+                }
+            }
+            catch {
+                // Server not ready yet, continue polling
+            }
+            await new Promise((resolve) => setTimeout(resolve, 500));
+        }
+        throw new Error(`webServer at ${resource} did not become ready within ${timeout}ms`);
+    }
+    async stopWebServers() {
+        if (this.webServerProcesses.length === 0) {
+            return;
+        }
+        console.log(`[orchestrator:teardown] Stopping ${this.webServerProcesses.length} webServer(s)...`);
+        for (const proc of this.webServerProcesses) {
+            if (proc.pid && !proc.killed) {
+                try {
+                    // Kill the process group on unix, just the process on windows
+                    if (process.platform !== 'win32') {
+                        process.kill(-proc.pid, 'SIGTERM');
+                    }
+                    else {
+                        proc.kill('SIGTERM');
+                    }
+                }
+                catch {
+                    // Process may have already exited
+                }
+            }
+        }
+        this.webServerProcesses = [];
+    }
+    async runSetupProjects() {
+        if (this.options.skipSetupProjects || this.setup.setupProjects.length === 0) {
+            return;
+        }
+        for (const projectName of this.setup.setupProjects) {
+            console.log(`[orchestrator:setup] Running setup project: ${projectName}`);
+            const args = ['npx', 'playwright', 'test', '--project', projectName];
+            if (this.options.configFile) {
+                args.push('--config', this.options.configFile);
+            }
+            await this.execCommand(args.join(' '));
+        }
+    }
+    execCommand(command) {
+        return new Promise((resolve, reject) => {
+            const proc = spawn(command, {
+                shell: true,
+                stdio: 'inherit',
+            });
+            proc.on('close', (code) => {
+                if (code === 0)
+                    resolve();
+                else
+                    reject(new Error(`Command failed with code ${code}: ${command}`));
+            });
+            proc.on('error', reject);
+        });
+    }
+    buildConfigForHooks() {
+        return {
+            configFile: this.options.configFile,
+        };
+    }
+}

package/dist/playwright-tools/run-builder.d.ts

@@ -5,6 +5,9 @@ export declare class RunBuilder {
     private config;
     parseEntry(entry: TestCase | Suite): this;
     parseConfig(config: FullConfig): this;
+    private extractSetupConfig;
+    private extractWebServers;
+    private findSetupProjects;
     build(): TestRunInfo;
     private parseSuitesHelper;
     private tryParseEntry;

package/dist/playwright-tools/run-builder.js

@@ -13,9 +13,45 @@ export class RunBuilder {
                 name: project.name,
                 outputDir: project.outputDir,
             })),
+            setup: this.extractSetupConfig(config),
         };
         return this;
     }
+    extractSetupConfig(config) {
+        return {
+            globalSetup: config.globalSetup ?? undefined,
+            globalTeardown: config.globalTeardown ?? undefined,
+            webServers: this.extractWebServers(config.webServer),
+            setupProjects: this.findSetupProjects(config.projects),
+        };
+    }
+    extractWebServers(webServer) {
+        if (!webServer)
+            return [];
+        const servers = Array.isArray(webServer) ? webServer : [webServer];
+        return servers.map((s) => ({
+            command: s.command,
+            url: s.url,
+            port: s.port,
+            timeout: s.timeout,
+            reuseExistingServer: s.reuseExistingServer,
+            cwd: s.cwd,
+            env: s.env,
+        }));
+    }
+    findSetupProjects(projects) {
+        // Collect all dependency names
+        const allDependencies = new Set();
+        for (const project of projects) {
+            for (const dep of project.dependencies || []) {
+                allDependencies.add(dep);
+            }
+        }
+        // Setup projects = projects that ARE dependencies but have no dependencies themselves
+        return projects
+            .filter((p) => allDependencies.has(p.name) && (!p.dependencies || p.dependencies.length === 0))
+            .map((p) => p.name);
+    }
     build() {
         return structuredClone({
             config: this.config,

package/dist/test-runner.d.ts

@@ -1,13 +1,19 @@
 import { Adapter } from './adapter.js';
+export interface TestRunnerOptions {
+    runId: string;
+    output: string;
+    skipGlobalSetup?: boolean;
+    skipWebServer?: boolean;
+    skipSetupProjects?: boolean;
+}
 export declare class TestRunner {
+    private readonly options;
     private readonly adapter;
     private readonly runId;
     private readonly outputFolder;
     private readonly reporter;
-    constructor(options: {
-        runId: string;
-        output: string;
-    }, adapter: Adapter);
+    private setupManager?;
+    constructor(options: TestRunnerOptions, adapter: Adapter);
     runTests(): Promise<void>;
     private runTestsUntilAvailable;
     private removePreviousReports;

package/dist/test-runner.js

@@ -5,6 +5,7 @@ import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { TestExecutionReporter } from './reporters/test-execution-reporter.js';
 import path from 'node:path';
 import * as uuid from 'uuid';
+import { SetupManager } from './helpers/setup-manager.js';
 const exec = promisify(child_process.exec);
 function spawnPassthrough(command, env) {
     return new Promise((resolve, reject) => {
@@ -18,11 +19,14 @@ function spawnPassthrough(command, env) {
     });
 }
 export class TestRunner {
+    options;
     adapter;
     runId;
     outputFolder;
     reporter = new TestExecutionReporter();
+    setupManager;
     constructor(options, adapter) {
+        this.options = options;
         this.adapter = adapter;
         this.runId = options.runId;
         this.outputFolder = options.output;
@@ -32,6 +36,16 @@ export class TestRunner {
         await this.removePreviousReports();
         const config = await this.adapter.startShard(this.runId);
         console.log(`[orchestrator] Shard started. Workers: ${config.workers}, Config: ${config.configFile || 'default'}`);
+        // Run setup phase (globalSetup → webServers → setup projects)
+        if (config.setup) {
+            this.setupManager = new SetupManager(config.setup, {
+                configFile: config.configFile,
+                skipGlobalSetup: this.options.skipGlobalSetup,
+                skipWebServer: this.options.skipWebServer,
+                skipSetupProjects: this.options.skipSetupProjects,
+            });
+            await this.setupManager.runSetup();
+        }
         config.configFile = await this.createTempConfig(config.configFile);
         try {
             await this.runTestsUntilAvailable(config);
@@ -43,6 +57,10 @@ export class TestRunner {
         finally {
             if (config.configFile)
                 await rm(config.configFile);
+            // Run teardown phase (stop webServers → globalTeardown)
+            if (this.setupManager) {
+                await this.setupManager.runTeardown();
+            }
         }
     }
     async runTestsUntilAvailable(config) {
@@ -59,10 +77,21 @@ export class TestRunner {
                     runningTests.delete(testPromise);
                 });
                 runningTests.add(testPromise);
-                next = await this.adapter.getNextTest(this.runId, config);
+                // Only prefetch if we still have capacity after starting this test
+                // This prevents claiming more tests than we can run with workers=1
+                if (runningTests.size < config.workers) {
+                    next = await this.adapter.getNextTest(this.runId, config);
+                }
+                else {
+                    next = undefined;
+                }
             }
             else {
                 await Promise.race(runningTests);
+                // Fetch next test after a slot opens up
+                if (!next) {
+                    next = await this.adapter.getNextTest(this.runId, config);
+                }
             }
         }
         console.log(`[orchestrator] Finished ${testCount} tests`);
@@ -130,16 +159,20 @@ export class TestRunner {
     async createTempConfig(file) {
         if (!file)
             return;
-        // Modify config: remove webServer, clear project dependencies, add our reporters
+        // Modify config: remove setup options (handled by orchestrator), clear dependencies, add reporters
         const content = `
         import config from '${path.resolve(file)}';
 
-        // Remove webServer - not supported in orchestrator (server should already be running)
+        // Remove webServer - managed by orchestrator's SetupManager
         delete config.webServer;
 
-        // Clear project dependencies - setup projects should be run separately before orchestrator
-        // Each orchestrator test runs in a fresh playwright process, and we don't want
-        // setup projects re-running for every test
+        // Remove globalSetup/globalTeardown - managed by orchestrator's SetupManager
+        // Without this, they would run for EVERY individual test process
+        delete config.globalSetup;
+        delete config.globalTeardown;
+
+        // Clear project dependencies - setup projects are run once by orchestrator
+        // Each test runs in a fresh playwright process, we don't want setup re-running
         if (config.projects) {
             for (const project of config.projects) {
                 project.dependencies = [];

package/dist/types/test-info.d.ts

@@ -3,10 +3,34 @@ export interface Project {
     name: string;
     outputDir: string;
 }
+/**
+ * WebServer configuration extracted from Playwright config.
+ * Mirrors Playwright's WebServerConfig but serializable for storage.
+ */
+export interface WebServerConfig {
+    command: string;
+    url?: string;
+    port?: number;
+    timeout?: number;
+    reuseExistingServer?: boolean;
+    cwd?: string;
+    env?: Record<string, string>;
+}
+/**
+ * Setup configuration extracted during `create` and used during `run`.
+ * Each shard runs setup independently (different machines).
+ */
+export interface SetupConfig {
+    globalSetup?: string;
+    globalTeardown?: string;
+    webServers: WebServerConfig[];
+    setupProjects: string[];
+}
 export interface TestConfig {
     workers: number;
     configFile?: string;
     projects: Project[];
+    setup?: SetupConfig;
 }
 export interface TestRunConfig extends TestConfig {
     historyWindow: number;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dionlarson/playwright-orchestrator-core",
-    "version": "1.3.9",
+    "version": "1.5.0",
     "description": "Core lib and cli for Playwright test orchestration",
     "keywords": [
         "playwright",