rwsdk 1.0.0-alpha.2 → 1.0.0-alpha.20-test.20250929144616

package/dist/lib/e2e/tarball.d.mts

@@ -0,0 +1,14 @@
+interface SetupTarballOptions {
+    projectDir: string;
+    monorepoRoot?: string;
+    packageManager?: "pnpm" | "npm" | "yarn" | "yarn-classic";
+}
+interface TarballEnvironment {
+    targetDir: string;
+    cleanup: () => Promise<void>;
+}
+/**
+ * Creates a tarball-based test environment similar to the release script approach
+ */
+export declare function setupTarballEnvironment({ projectDir, monorepoRoot, packageManager, }: SetupTarballOptions): Promise<TarballEnvironment>;
+export {};

package/dist/lib/e2e/tarball.mjs

@@ -0,0 +1,99 @@
+import { createHash } from "crypto";
+import { $ } from "execa";
+import fs from "node:fs";
+import path from "node:path";
+import { adjectives, animals, uniqueNamesGenerator, } from "unique-names-generator";
+import { ROOT_DIR } from "../constants.mjs";
+import { copyProjectToTempDir } from "./environment.mjs";
+const log = (message) => console.log(message);
+/**
+ * Copies wrangler cache from monorepo to temp directory for deployment tests
+ */
+async function copyWranglerCache(targetDir, sdkRoot) {
+    try {
+        // Find the monorepo root by starting from the SDK root directory
+        // and walking up to find the monorepo root
+        let currentDir = path.resolve(sdkRoot);
+        let monorepoRoot = null;
+        // Walk up the directory tree to find the monorepo root
+        while (currentDir !== path.dirname(currentDir)) {
+            const nodeModulesPath = path.join(currentDir, "node_modules");
+            const packageJsonPath = path.join(currentDir, "package.json");
+            if (fs.existsSync(nodeModulesPath) && fs.existsSync(packageJsonPath)) {
+                try {
+                    const packageJson = JSON.parse(await fs.promises.readFile(packageJsonPath, "utf8"));
+                    // Check if this looks like our monorepo root
+                    if (packageJson.name === "rw-sdk-monorepo" ||
+                        packageJson.private === true) {
+                        monorepoRoot = currentDir;
+                        break;
+                    }
+                }
+                catch {
+                    // Continue searching if we can't read the package.json
+                }
+            }
+            currentDir = path.dirname(currentDir);
+        }
+        if (!monorepoRoot) {
+            log(`  ⚠️ Could not find monorepo root, skipping wrangler cache copy`);
+            return;
+        }
+        const sourceCachePath = path.join(monorepoRoot, "node_modules/.cache/wrangler");
+        const targetCachePath = path.join(targetDir, "node_modules/.cache/wrangler");
+        if (fs.existsSync(sourceCachePath)) {
+            log(`  🔐 Copying wrangler cache from monorepo to temp directory...`);
+            // Ensure the target cache directory exists
+            await fs.promises.mkdir(path.dirname(targetCachePath), {
+                recursive: true,
+            });
+            // Copy the entire wrangler cache directory
+            await $ `cp -r ${sourceCachePath} ${path.dirname(targetCachePath)}`;
+            log(`  ✅ Wrangler cache copied successfully`);
+        }
+        else {
+            log(`  ⚠️ No wrangler cache found in monorepo, deployment tests may require authentication`);
+        }
+    }
+    catch (error) {
+        log(`  ⚠️ Failed to copy wrangler cache: ${error.message}`);
+        // Don't throw - this is not a fatal error, deployment tests will just need manual auth
+    }
+}
+/**
+ * Creates a tarball-based test environment similar to the release script approach
+ */
+export async function setupTarballEnvironment({ projectDir, monorepoRoot, packageManager = "pnpm", }) {
+    log(`🚀 Setting up tarball environment for ${projectDir}`);
+    // Generate a resource unique key for this test run
+    const uniqueNameSuffix = uniqueNamesGenerator({
+        dictionaries: [adjectives, animals],
+        separator: "-",
+        length: 2,
+        style: "lowerCase",
+    });
+    // Create a short unique hash based on the timestamp
+    const hash = createHash("md5")
+        .update(Date.now().toString())
+        .digest("hex")
+        .substring(0, 8);
+    const resourceUniqueKey = `${uniqueNameSuffix}-${hash}`;
+    try {
+        const { tempDir, targetDir } = await copyProjectToTempDir(projectDir, resourceUniqueKey, packageManager, monorepoRoot);
+        // Copy wrangler cache to improve deployment performance
+        const sdkRoot = ROOT_DIR;
+        await copyWranglerCache(targetDir, sdkRoot);
+        log(`✅ Tarball environment setup complete`);
+        return {
+            targetDir,
+            cleanup: async () => {
+                log(`🧹 Cleaning up tarball environment: ${tempDir.path}`);
+                await tempDir.cleanup();
+            },
+        };
+    }
+    catch (error) {
+        // Cleanup tarball on error
+        throw error;
+    }
+}

package/dist/lib/e2e/testHarness.d.mts

@@ -0,0 +1,132 @@
+import { type Browser, type Page } from "puppeteer-core";
+import { test } from "vitest";
+export type { Browser, Page } from "puppeteer-core";
+interface DevServerInstance {
+    url: string;
+    stopDev: () => Promise<void>;
+}
+interface DeploymentInstance {
+    url: string;
+    workerName: string;
+    resourceUniqueKey: string;
+    projectDir: string;
+    cleanup: () => Promise<void>;
+}
+export interface SetupPlaygroundEnvironmentOptions {
+    /**
+     * The directory of the playground project to set up.
+     * Can be an absolute path, or a `import.meta.url` `file://` string.
+     * If not provided, it will be inferred from the test file's path.
+     */
+    sourceProjectDir?: string;
+    /**
+     * The root directory of the monorepo, if the project is part of one.
+     * This is used to correctly set up the test environment for monorepo projects.
+     */
+    monorepoRoot?: string;
+    /**
+     * Whether to provision a dev server for the test suite.
+     * @default true
+     */
+    dev?: boolean;
+    /**
+     * Whether to provision a deployment for the test suite.
+     * @default true
+     */
+    deploy?: boolean;
+}
+/**
+ * A Vitest hook that sets up a playground environment for a test file.
+ * It creates a temporary directory, copies the playground project into it,
+ * and installs dependencies using a tarball of the SDK.
+ * This ensures that tests run in a clean, isolated environment.
+ */
+export declare function setupPlaygroundEnvironment(options?: string | SetupPlaygroundEnvironmentOptions): void;
+/**
+ * Creates a dev server instance using the shared playground environment.
+ * Automatically registers cleanup to run after the test.
+ */
+export declare function createDevServer(projectDir: string): Promise<DevServerInstance>;
+/**
+ * Creates a deployment instance using the shared playground environment.
+ * Automatically registers cleanup to run after the test.
+ */
+export declare function createDeployment(projectDir: string): Promise<DeploymentInstance>;
+/**
+ * Executes a test function with a retry mechanism for specific error codes.
+ * @param name - The name of the test, used for logging.
+ * @param attemptFn - A function that executes one attempt of the test.
+ *                     It should set up resources, run the test logic, and
+ *                     return a cleanup function. The cleanup function will be
+ *                     called automatically on failure.
+ */
+export declare function runTestWithRetries(name: string, attemptFn: () => Promise<void>): Promise<void>;
+declare function createTestRunner(testFn: (typeof test | typeof test.only)["concurrent"], envType: "dev" | "deploy"): (name: string, testLogic: (context: {
+    devServer?: DevServerInstance;
+    deployment?: DeploymentInstance;
+    browser: Browser;
+    page: Page;
+    url: string;
+}) => Promise<void>) => void;
+/**
+ * High-level test wrapper for dev server tests.
+ * Automatically skips if RWSDK_SKIP_DEV=1
+ */
+export declare function testDev(...args: Parameters<ReturnType<typeof createTestRunner>>): void;
+export declare namespace testDev {
+    var skip: (name: string, testFn?: any) => void;
+    var only: (name: string, testLogic: (context: {
+        devServer?: DevServerInstance;
+        deployment?: DeploymentInstance;
+        browser: Browser;
+        page: Page;
+        url: string;
+    }) => Promise<void>) => void;
+}
+/**
+ * High-level test wrapper for deployment tests.
+ * Automatically skips if RWSDK_SKIP_DEPLOY=1
+ */
+export declare function testDeploy(...args: Parameters<ReturnType<typeof createTestRunner>>): void;
+export declare namespace testDeploy {
+    var skip: (name: string, testFn?: any) => void;
+    var only: (name: string, testLogic: (context: {
+        devServer?: DevServerInstance;
+        deployment?: DeploymentInstance;
+        browser: Browser;
+        page: Page;
+        url: string;
+    }) => Promise<void>) => void;
+}
+/**
+ * Unified test function that runs the same test against both dev server and deployment.
+ * Automatically skips based on environment variables.
+ */
+export declare function testDevAndDeploy(name: string, testFn: (context: {
+    devServer?: DevServerInstance;
+    deployment?: DeploymentInstance;
+    browser: Browser;
+    page: Page;
+    url: string;
+}) => Promise<void>): void;
+export declare namespace testDevAndDeploy {
+    var skip: (name: string, testFn?: any) => void;
+    var only: (name: string, testFn: (context: {
+        devServer?: DevServerInstance;
+        deployment?: DeploymentInstance;
+        browser: Browser;
+        page: Page;
+        url: string;
+    }) => Promise<void>) => void;
+}
+/**
+ * Waits for the page to be fully loaded and hydrated.
+ * This should be used before any user interaction is simulated.
+ */
+export declare function waitForHydration(page: Page): Promise<void>;
+export declare function trackPageErrors(page: Page): {
+    get: () => {
+        consoleErrors: string[];
+        failedRequests: string[];
+    };
+};

package/dist/lib/e2e/testHarness.mjs

@@ -0,0 +1,436 @@
+import fs from "fs-extra";
+import os from "os";
+import path, { basename, dirname, join as pathJoin } from "path";
+import puppeteer from "puppeteer-core";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, test, } from "vitest";
+import { launchBrowser } from "./browser.mjs";
+import { runDevServer } from "./dev.mjs";
+import { poll, pollValue } from "./poll.mjs";
+import { deleteD1Database, deleteWorker, isRelatedToTest, runRelease, } from "./release.mjs";
+import { setupTarballEnvironment } from "./tarball.mjs";
+const SETUP_PLAYGROUND_ENV_TIMEOUT = process.env
+    .RWSDK_SETUP_PLAYGROUND_ENV_TIMEOUT
+    ? parseInt(process.env.RWSDK_SETUP_PLAYGROUND_ENV_TIMEOUT, 10)
+    : 15 * 60 * 1000;
+const DEPLOYMENT_TIMEOUT = process.env.RWSDK_DEPLOYMENT_TIMEOUT
+    ? parseInt(process.env.RWSDK_DEPLOYMENT_TIMEOUT, 10)
+    : 5 * 60 * 1000;
+const DEPLOYMENT_MIN_TRIES = process.env.RWSDK_DEPLOYMENT_MIN_TRIES
+    ? parseInt(process.env.RWSDK_DEPLOYMENT_MIN_TRIES, 10)
+    : 5;
+const DEPLOYMENT_CHECK_TIMEOUT = process.env.RWSDK_DEPLOYMENT_CHECK_TIMEOUT
+    ? parseInt(process.env.RWSDK_DEPLOYMENT_CHECK_TIMEOUT, 10)
+    : 5 * 60 * 1000;
+const PUPPETEER_TIMEOUT = process.env.RWSDK_PUPPETEER_TIMEOUT
+    ? parseInt(process.env.RWSDK_PUPPETEER_TIMEOUT, 10)
+    : 60 * 1000 * 2;
+const HYDRATION_TIMEOUT = process.env.RWSDK_HYDRATION_TIMEOUT
+    ? parseInt(process.env.RWSDK_HYDRATION_TIMEOUT, 10)
+    : 5000;
+const DEV_SERVER_TIMEOUT = process.env.RWSDK_DEV_SERVER_TIMEOUT
+    ? parseInt(process.env.RWSDK_DEV_SERVER_TIMEOUT, 10)
+    : 5 * 60 * 1000;
+const DEV_SERVER_MIN_TRIES = process.env.RWSDK_DEV_SERVER_MIN_TRIES
+    ? parseInt(process.env.RWSDK_DEV_SERVER_MIN_TRIES, 10)
+    : 5;
+const SETUP_WAIT_TIMEOUT = process.env.RWSDK_SETUP_WAIT_TIMEOUT
+    ? parseInt(process.env.RWSDK_SETUP_WAIT_TIMEOUT, 10)
+    : 10 * 60 * 1000;
+// Environment variable flags for skipping tests
+const SKIP_DEV_SERVER_TESTS = process.env.RWSDK_SKIP_DEV === "1";
+const SKIP_DEPLOYMENT_TESTS = process.env.RWSDK_SKIP_DEPLOY === "1";
+// Global test environment state
+let globalDevPlaygroundEnv = null;
+let globalDeployPlaygroundEnv = null;
+let globalDevInstancePromise = null;
+let globalDeploymentInstancePromise = null;
+let globalDevInstance = null;
+let globalDeploymentInstance = null;
+let hooksRegistered = false;
+/**
+ * Registers global cleanup hooks automatically
+ */
+function ensureHooksRegistered() {
+    if (hooksRegistered)
+        return;
+    // Register global afterAll to clean up the playground environment
+    afterAll(async () => {
+        const cleanupPromises = [];
+        if (globalDevInstance) {
+            cleanupPromises.push(globalDevInstance.stopDev());
+        }
+        if (globalDeploymentInstance) {
+            cleanupPromises.push(globalDeploymentInstance.cleanup());
+        }
+        if (globalDevPlaygroundEnv) {
+            cleanupPromises.push(globalDevPlaygroundEnv.cleanup());
+        }
+        if (globalDeployPlaygroundEnv) {
+            cleanupPromises.push(globalDeployPlaygroundEnv.cleanup());
+        }
+        await Promise.all(cleanupPromises);
+        globalDevInstance = null;
+        globalDeploymentInstance = null;
+        globalDevPlaygroundEnv = null;
+        globalDeployPlaygroundEnv = null;
+    });
+    hooksRegistered = true;
+}
+/**
+ * Get the project directory for the current test by looking at the call stack
+ */
+function getProjectDirectory() {
+    // For now, let's hardcode this to '../playground/hello-world' since we only have one project
+    // TODO: Make this more dynamic when we have multiple playground projects
+    return "../playground/hello-world";
+}
+/**
+ * Derive the playground directory from import.meta.url by finding the nearest package.json
+ */
+function getPlaygroundDirFromImportMeta(importMetaUrl) {
+    const url = new URL(importMetaUrl);
+    const testFilePath = url.pathname;
+    let currentDir = dirname(testFilePath);
+    // Walk up the tree from the test file's directory
+    while (currentDir !== "/") {
+        // Check if a package.json exists in the current directory
+        if (fs.existsSync(pathJoin(currentDir, "package.json"))) {
+            return currentDir;
+        }
+        currentDir = dirname(currentDir);
+    }
+    throw new Error(`Could not determine playground directory from import.meta.url: ${importMetaUrl}. ` +
+        `Failed to find a package.json in any parent directory.`);
+}
+/**
+ * A Vitest hook that sets up a playground environment for a test file.
+ * It creates a temporary directory, copies the playground project into it,
+ * and installs dependencies using a tarball of the SDK.
+ * This ensures that tests run in a clean, isolated environment.
+ */
+export function setupPlaygroundEnvironment(options = {}) {
+    const { sourceProjectDir, monorepoRoot, dev = true, deploy = true, } = typeof options === "string" ? { sourceProjectDir: options } : options;
+    ensureHooksRegistered();
+    beforeAll(async () => {
+        let projectDir;
+        if (!sourceProjectDir) {
+            projectDir = getProjectDirectory();
+        }
+        else if (sourceProjectDir.startsWith("file://")) {
+            // This is import.meta.url, derive the playground directory
+            projectDir = getPlaygroundDirFromImportMeta(sourceProjectDir);
+        }
+        else {
+            // This is an explicit path
+            projectDir = sourceProjectDir;
+        }
+        console.log(`Setting up playground environment from ${projectDir}...`);
+        if (dev) {
+            const devEnv = await setupTarballEnvironment({
+                projectDir,
+                monorepoRoot,
+                packageManager: process.env.PACKAGE_MANAGER || "pnpm",
+            });
+            globalDevPlaygroundEnv = {
+                projectDir: devEnv.targetDir,
+                cleanup: devEnv.cleanup,
+            };
+            globalDevInstancePromise = createDevServer(devEnv.targetDir).then((instance) => {
+                globalDevInstance = instance;
+                return instance;
+            });
+            // Prevent unhandled promise rejections. The error will be handled inside
+            // the test's beforeEach hook where this promise is awaited.
+            globalDevInstancePromise.catch(() => { });
+        }
+        else {
+            globalDevInstancePromise = Promise.resolve(null);
+        }
+        if (deploy) {
+            const deployEnv = await setupTarballEnvironment({
+                projectDir,
+                monorepoRoot,
+                packageManager: process.env.PACKAGE_MANAGER || "pnpm",
+            });
+            globalDeployPlaygroundEnv = {
+                projectDir: deployEnv.targetDir,
+                cleanup: deployEnv.cleanup,
+            };
+            globalDeploymentInstancePromise = createDeployment(deployEnv.targetDir).then((instance) => {
+                globalDeploymentInstance = instance;
+                return instance;
+            });
+            // Prevent unhandled promise rejections
+            globalDeploymentInstancePromise.catch(() => { });
+        }
+        else {
+            globalDeploymentInstancePromise = Promise.resolve(null);
+        }
+    }, SETUP_PLAYGROUND_ENV_TIMEOUT);
+}
+/**
+ * Creates a dev server instance using the shared playground environment.
+ * Automatically registers cleanup to run after the test.
+ */
+export async function createDevServer(projectDir) {
+    if (SKIP_DEV_SERVER_TESTS) {
+        throw new Error("Dev server tests are skipped via RWSDK_SKIP_DEV=1");
+    }
+    const packageManager = process.env.PACKAGE_MANAGER || "pnpm";
+    const devResult = await pollValue(() => runDevServer(packageManager, projectDir), {
+        timeout: DEV_SERVER_TIMEOUT,
+        minTries: DEV_SERVER_MIN_TRIES,
+        onRetry: (error, tries) => {
+            console.log(`Retrying dev server creation (attempt ${tries})... Error: ${error.message}`);
+        },
+    });
+    return {
+        url: devResult.url,
+        stopDev: devResult.stopDev,
+    };
+}
+/**
+ * Creates a deployment instance using the shared playground environment.
+ * Automatically registers cleanup to run after the test.
+ */
+export async function createDeployment(projectDir) {
+    if (SKIP_DEPLOYMENT_TESTS) {
+        throw new Error("Deployment tests are skipped via RWSDK_SKIP_DEPLOY=1");
+    }
+    return await pollValue(async () => {
+        // Extract the unique key from the project directory name instead of generating a new one
+        // The directory name format is: {projectName}-e2e-test-{randomId}
+        const dirName = basename(projectDir);
+        const match = dirName.match(/-e2e-test-([a-f0-9]+)$/);
+        const resourceUniqueKey = match
+            ? match[1]
+            : Math.random().toString(36).substring(2, 15);
+        const deployResult = await runRelease(projectDir, projectDir, resourceUniqueKey);
+        // Poll the URL to ensure it's live before proceeding
+        await poll(async () => {
+            try {
+                const response = await fetch(deployResult.url);
+                // We consider any response (even 4xx or 5xx) as success,
+                // as it means the worker is routable.
+                return response.status > 0;
+            }
+            catch (e) {
+                return false;
+            }
+        }, {
+            timeout: DEPLOYMENT_CHECK_TIMEOUT,
+        });
+        const cleanup = async () => {
+            // Run deployment cleanup in background without blocking
+            const performCleanup = async () => {
+                if (isRelatedToTest(deployResult.workerName, resourceUniqueKey)) {
+                    await deleteWorker(deployResult.workerName, projectDir, resourceUniqueKey);
+                }
+                await deleteD1Database(resourceUniqueKey, projectDir, resourceUniqueKey);
+            };
+            // Start cleanup in background and return immediately
+            performCleanup().catch((error) => {
+                console.warn(`Warning: Background deployment cleanup failed: ${error.message}`);
+            });
+            return Promise.resolve();
+        };
+        return {
+            url: deployResult.url,
+            workerName: deployResult.workerName,
+            resourceUniqueKey,
+            projectDir: projectDir,
+            cleanup,
+        };
+    }, {
+        timeout: DEPLOYMENT_TIMEOUT,
+        minTries: DEPLOYMENT_MIN_TRIES,
+        onRetry: (error, tries) => {
+            console.log(`Retrying deployment creation (attempt ${tries})... Error: ${error.message}`);
+        },
+    });
+}
+/**
+ * Executes a test function with a retry mechanism for specific error codes.
+ * @param name - The name of the test, used for logging.
+ * @param attemptFn - A function that executes one attempt of the test.
+ *                     It should set up resources, run the test logic, and
+ *                     return a cleanup function. The cleanup function will be
+ *                     called automatically on failure.
+ */
+export async function runTestWithRetries(name, attemptFn) {
+    const MAX_RETRIES_PER_CODE = 6;
+    const retryCounts = {};
+    let attempt = 0;
+    while (true) {
+        attempt++;
+        try {
+            await attemptFn();
+            if (attempt > 1) {
+                console.log(`[runTestWithRetries] Test "${name}" succeeded on attempt ${attempt}.`);
+            }
+            return; // Success
+        }
+        catch (e) {
+            const errorCode = e?.code;
+            if (typeof errorCode === "string" && errorCode) {
+                const count = (retryCounts[errorCode] || 0) + 1;
+                retryCounts[errorCode] = count;
+                if (count <= MAX_RETRIES_PER_CODE) {
+                    console.log(`[runTestWithRetries] Attempt ${attempt} for "${name}" failed with code ${errorCode}. Retrying (failure ${count}/${MAX_RETRIES_PER_CODE} for this code)...`);
+                    await new Promise((resolve) => setTimeout(resolve, 1000));
+                    continue; // Next attempt
+                }
+                else {
+                    console.error(`[runTestWithRetries] Test "${name}" failed with code ${errorCode} after ${MAX_RETRIES_PER_CODE} retries for this code.`);
+                    throw e; // Give up
+                }
+            }
+            else {
+                console.error(`[runTestWithRetries] Test "${name}" failed on attempt ${attempt} with a non-retryable error:`, e);
+                throw e;
+            }
+        }
+    }
+}
+function createTestRunner(testFn, envType) {
+    return (name, testLogic) => {
+        if ((envType === "dev" && SKIP_DEV_SERVER_TESTS) ||
+            (envType === "deploy" && SKIP_DEPLOYMENT_TESTS)) {
+            test.skip(name, () => { });
+            return;
+        }
+        describe.concurrent(name, () => {
+            let page;
+            let instance;
+            let browser;
+            beforeAll(async () => {
+                const tempDir = path.join(os.tmpdir(), "rwsdk-e2e-tests");
+                const wsEndpointFile = path.join(tempDir, "wsEndpoint");
+                try {
+                    const wsEndpoint = await fs.readFile(wsEndpointFile, "utf-8");
+                    browser = await puppeteer.connect({ browserWSEndpoint: wsEndpoint });
+                }
+                catch (error) {
+                    console.warn("Failed to connect to existing browser instance. " +
+                        "This might happen if you are running a single test file. " +
+                        "Launching a new browser instance instead.");
+                    browser = await launchBrowser();
+                }
+            }, SETUP_WAIT_TIMEOUT);
+            afterAll(async () => {
+                if (browser) {
+                    await browser.disconnect();
+                }
+            });
+            beforeEach(async () => {
+                const instancePromise = envType === "dev"
+                    ? globalDevInstancePromise
+                    : globalDeploymentInstancePromise;
+                if (!instancePromise) {
+                    throw new Error("Test environment promises not initialized. Call setupPlaygroundEnvironment() in your test file.");
+                }
+                [instance] = await Promise.all([instancePromise]);
+                if (!instance) {
+                    throw new Error(`No ${envType} instance found. Make sure to enable it in setupPlaygroundEnvironment.`);
+                }
+                page = await browser.newPage();
+                page.setDefaultTimeout(PUPPETEER_TIMEOUT);
+            }, SETUP_WAIT_TIMEOUT);
+            afterEach(async () => {
+                if (page) {
+                    try {
+                        await page.close();
+                    }
+                    catch (error) {
+                        // Suppress errors during page close, as the browser might already be disconnecting
+                        // due to the test suite finishing.
+                        console.warn(`Suppressing error during page.close() in test "${name}":`, error);
+                    }
+                }
+            });
+            testFn(">", async () => {
+                if (!instance || !browser) {
+                    throw new Error("Test environment not ready.");
+                }
+                await runTestWithRetries(name, async () => {
+                    await testLogic({
+                        [envType === "dev" ? "devServer" : "deployment"]: instance,
+                        browser: browser,
+                        page: page,
+                        url: instance.url,
+                    });
+                });
+            });
+        });
+    };
+}
+/**
+ * High-level test wrapper for dev server tests.
+ * Automatically skips if RWSDK_SKIP_DEV=1
+ */
+export function testDev(...args) {
+    return createTestRunner(test.concurrent, "dev")(...args);
+}
+testDev.skip = (name, testFn) => {
+    test.skip(name, testFn || (() => { }));
+};
+testDev.only = createTestRunner(test.only, "dev");
+/**
+ * High-level test wrapper for deployment tests.
+ * Automatically skips if RWSDK_SKIP_DEPLOY=1
+ */
+export function testDeploy(...args) {
+    return createTestRunner(test.concurrent, "deploy")(...args);
+}
+testDeploy.skip = (name, testFn) => {
+    test.skip(name, testFn || (() => { }));
+};
+testDeploy.only = createTestRunner(test.only, "deploy");
+/**
+ * Unified test function that runs the same test against both dev server and deployment.
+ * Automatically skips based on environment variables.
+ */
+export function testDevAndDeploy(name, testFn) {
+    testDev(`${name} (dev)`, testFn);
+    testDeploy(`${name} (deployment)`, testFn);
+}
+/**
+ * Skip version of testDevAndDeploy
+ */
+testDevAndDeploy.skip = (name, testFn) => {
+    test.skip(name, testFn || (() => { }));
+};
+testDevAndDeploy.only = (name, testFn) => {
+    testDev.only(`${name} (dev)`, testFn);
+    testDeploy.only(`${name} (deployment)`, testFn);
+};
+/**
+ * Waits for the page to be fully loaded and hydrated.
+ * This should be used before any user interaction is simulated.
+ */
+export async function waitForHydration(page) {
+    // 1. Wait for the document to be fully loaded.
+    await page.waitForFunction('document.readyState === "complete"');
+    // 2. Wait a short, fixed amount of time for client-side hydration to finish.
+    // This is a pragmatic approach to ensure React has mounted.
+    await new Promise((resolve) => setTimeout(resolve, HYDRATION_TIMEOUT));
+}
+export function trackPageErrors(page) {
+    const consoleErrors = [];
+    const failedRequests = [];
+    page.on("requestfailed", (request) => {
+        failedRequests.push(`${request.url()} | ${request.failure()?.errorText}`);
+    });
+    page.on("console", (msg) => {
+        if (msg.type() === "error") {
+            consoleErrors.push(msg.text());
+        }
+    });
+    return {
+        get: () => ({
+            // context(justinvdm, 25 Sep 2025): Filter out irrelevant 404s (e.g. favicon)
+            consoleErrors: consoleErrors.filter((e) => !e.includes("404")),
+            failedRequests,
+        }),
+    };
+}