rwsdk 1.0.0-beta.3 → 1.0.0-beta.30

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

@@ -1,9 +1,11 @@
 import { type Browser, type Page } from "puppeteer-core";
 import { test } from "vitest";
+import { DEPLOYMENT_CHECK_TIMEOUT, DEPLOYMENT_MIN_TRIES, DEPLOYMENT_TIMEOUT, DEV_SERVER_MIN_TRIES, DEV_SERVER_TIMEOUT, HYDRATION_TIMEOUT, INSTALL_DEPENDENCIES_RETRIES, PUPPETEER_TIMEOUT, SETUP_PLAYGROUND_ENV_TIMEOUT, SETUP_WAIT_TIMEOUT, TEST_MAX_RETRIES, TEST_MAX_RETRIES_PER_CODE } from "./constants.mjs";
 export type { Browser, Page } from "puppeteer-core";
-export declare const INSTALL_DEPENDENCIES_RETRIES: number;
+export { DEPLOYMENT_CHECK_TIMEOUT, DEPLOYMENT_MIN_TRIES, DEPLOYMENT_TIMEOUT, DEV_SERVER_MIN_TRIES, DEV_SERVER_TIMEOUT, HYDRATION_TIMEOUT, INSTALL_DEPENDENCIES_RETRIES, PUPPETEER_TIMEOUT, SETUP_PLAYGROUND_ENV_TIMEOUT, SETUP_WAIT_TIMEOUT, TEST_MAX_RETRIES, TEST_MAX_RETRIES_PER_CODE, };
 interface DevServerInstance {
     url: string;
+    projectDir: string;
     stopDev: () => Promise<void>;
 }
 interface DeploymentInstance {
@@ -35,6 +37,11 @@ export interface SetupPlaygroundEnvironmentOptions {
      * @default true
      */
     deploy?: boolean;
+    /**
+     * Whether to automatically start the dev server.
+     * @default true
+     */
+    autoStartDevServer?: boolean;
 }
 /**
  * A Vitest hook that sets up a playground environment for a test file.
@@ -42,17 +49,29 @@ export interface SetupPlaygroundEnvironmentOptions {
  * 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;
+export declare function setupPlaygroundEnvironment(options: SetupPlaygroundEnvironmentOptions | string): 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>;
+export declare function createDevServer(): {
+    projectDir: string;
+    start: () => 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>;
+export declare function createDeployment(): {
+    projectDir: string;
+    start: () => Promise<{
+        url: string;
+        workerName: string;
+        resourceUniqueKey: string;
+        projectDir: string;
+        cleanup: () => Promise<void>;
+    }>;
+};
 /**
  * Executes a test function with a retry mechanism for specific error codes.
  * @param name - The name of the test, used for logging.
@@ -62,13 +81,23 @@ export declare function createDeployment(projectDir: string): Promise<Deployment
  *                     called automatically on failure.
  */
 export declare function runTestWithRetries(name: string, attemptFn: () => Promise<void>): Promise<void>;
+type SDKRunner = (name: string, testLogic: (context: {
+    browser: Browser;
+    page: Page;
+    projectDir: string;
+}) => Promise<void>) => 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;
+    projectDir: string;
 }) => Promise<void>) => void;
+export declare const testSDK: SDKRunner & {
+    only: SDKRunner;
+    skip: typeof test.skip;
+};
 /**
  * High-level test wrapper for dev server tests.
  * Automatically skips if RWSDK_SKIP_DEV=1
@@ -82,6 +111,7 @@ export declare namespace testDev {
         browser: Browser;
         page: Page;
         url: string;
+        projectDir: string;
     }) => Promise<void>) => void;
 }
 /**
@@ -97,6 +127,7 @@ export declare namespace testDeploy {
         browser: Browser;
         page: Page;
         url: string;
+        projectDir: string;
     }) => Promise<void>) => void;
 }
 /**
@@ -109,6 +140,7 @@ export declare function testDevAndDeploy(name: string, testFn: (context: {
     browser: Browser;
     page: Page;
     url: string;
+    projectDir: string;
 }) => Promise<void>): void;
 export declare namespace testDevAndDeploy {
     var skip: (name: string, testFn?: any) => void;

package/dist/lib/e2e/testHarness.mjs

@@ -1,51 +1,16 @@
 import fs from "fs-extra";
-import os from "os";
 import path, { basename, dirname, join as pathJoin } from "path";
 import puppeteer from "puppeteer-core";
+import { fileURLToPath } from "url";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, test, } from "vitest";
 import { launchBrowser } from "./browser.mjs";
+import { DEPLOYMENT_CHECK_TIMEOUT, DEPLOYMENT_MIN_TRIES, DEPLOYMENT_TIMEOUT, DEV_SERVER_MIN_TRIES, DEV_SERVER_TIMEOUT, HYDRATION_TIMEOUT, INSTALL_DEPENDENCIES_RETRIES, PUPPETEER_TIMEOUT, SETUP_PLAYGROUND_ENV_TIMEOUT, SETUP_WAIT_TIMEOUT, TEST_MAX_RETRIES, TEST_MAX_RETRIES_PER_CODE, } from "./constants.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;
-const TEST_MAX_RETRIES = process.env.RWSDK_TEST_MAX_RETRIES
-    ? parseInt(process.env.RWSDK_TEST_MAX_RETRIES, 10)
-    : 10;
-const TEST_MAX_RETRIES_PER_CODE = process.env.RWSDK_TEST_MAX_RETRIES_PER_CODE
-    ? parseInt(process.env.RWSDK_TEST_MAX_RETRIES_PER_CODE, 10)
-    : 6;
-export const INSTALL_DEPENDENCIES_RETRIES = process.env
-    .RWSDK_INSTALL_DEPENDENCIES_RETRIES
-    ? parseInt(process.env.RWSDK_INSTALL_DEPENDENCIES_RETRIES, 10)
-    : 10;
+import { ensureTmpDir } from "./utils.mjs";
+export { DEPLOYMENT_CHECK_TIMEOUT, DEPLOYMENT_MIN_TRIES, DEPLOYMENT_TIMEOUT, DEV_SERVER_MIN_TRIES, DEV_SERVER_TIMEOUT, HYDRATION_TIMEOUT, INSTALL_DEPENDENCIES_RETRIES, PUPPETEER_TIMEOUT, SETUP_PLAYGROUND_ENV_TIMEOUT, SETUP_WAIT_TIMEOUT, TEST_MAX_RETRIES, TEST_MAX_RETRIES_PER_CODE, };
 // 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";
@@ -56,6 +21,8 @@ let globalDevInstancePromise = null;
 let globalDeploymentInstancePromise = null;
 let globalDevInstance = null;
 let globalDeploymentInstance = null;
+const devInstances = [];
+const deploymentInstances = [];
 let hooksRegistered = false;
 /**
  * Registers global cleanup hooks automatically
@@ -66,21 +33,33 @@ function ensureHooksRegistered() {
     // Register global afterAll to clean up the playground environment
     afterAll(async () => {
         const cleanupPromises = [];
-        if (globalDevInstance) {
-            cleanupPromises.push(globalDevInstance.stopDev());
+        for (const instance of devInstances) {
+            cleanupPromises.push(instance.stopDev().catch((error) => {
+                // Suppress all cleanup errors - they don't affect test results
+                console.warn(`Suppressing error during dev server cleanup: ${error instanceof Error ? error.message : String(error)}`);
+            }));
         }
-        if (globalDeploymentInstance) {
-            cleanupPromises.push(globalDeploymentInstance.cleanup());
+        for (const instance of deploymentInstances) {
+            cleanupPromises.push(instance.cleanup().catch((error) => {
+                // Suppress all cleanup errors - they don't affect test results
+                console.warn(`Suppressing error during deployment cleanup: ${error instanceof Error ? error.message : String(error)}`);
+            }));
         }
         if (globalDevPlaygroundEnv) {
-            cleanupPromises.push(globalDevPlaygroundEnv.cleanup());
+            cleanupPromises.push(globalDevPlaygroundEnv.cleanup().catch((error) => {
+                // Suppress all cleanup errors - they don't affect test results
+                console.warn(`Suppressing error during dev environment cleanup: ${error instanceof Error ? error.message : String(error)}`);
+            }));
         }
         if (globalDeployPlaygroundEnv) {
-            cleanupPromises.push(globalDeployPlaygroundEnv.cleanup());
+            cleanupPromises.push(globalDeployPlaygroundEnv.cleanup().catch((error) => {
+                // Suppress all cleanup errors - they don't affect test results
+                console.warn(`Suppressing error during deploy environment cleanup: ${error instanceof Error ? error.message : String(error)}`);
+            }));
         }
         await Promise.all(cleanupPromises);
-        globalDevInstance = null;
-        globalDeploymentInstance = null;
+        devInstances.length = 0;
+        deploymentInstances.length = 0;
         globalDevPlaygroundEnv = null;
         globalDeployPlaygroundEnv = null;
     });
@@ -98,11 +77,11 @@ function getProjectDirectory() {
  * 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;
+    const testFilePath = fileURLToPath(importMetaUrl);
     let currentDir = dirname(testFilePath);
     // Walk up the tree from the test file's directory
-    while (currentDir !== "/") {
+    // Stop when the parent directory is the same as the current directory (we've reached the root)
+    while (dirname(currentDir) !== currentDir) {
         // Check if a package.json exists in the current directory
         if (fs.existsSync(pathJoin(currentDir, "package.json"))) {
             return currentDir;
@@ -118,8 +97,10 @@ function getPlaygroundDirFromImportMeta(importMetaUrl) {
  * 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;
+export function setupPlaygroundEnvironment(options) {
+    const { sourceProjectDir, monorepoRoot, dev = true, deploy = true, autoStartDevServer = true, } = typeof options === "string"
+        ? { sourceProjectDir: options, autoStartDevServer: true }
+        : options;
     ensureHooksRegistered();
     beforeAll(async () => {
         let projectDir;
@@ -145,18 +126,21 @@ export function setupPlaygroundEnvironment(options = {}) {
                 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(() => { });
+            if (autoStartDevServer) {
+                const devControl = createDevServer();
+                globalDevInstancePromise = devControl.start().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);
+            globalDevPlaygroundEnv = null;
         }
-        if (deploy) {
+        if (deploy && !SKIP_DEPLOYMENT_TESTS) {
             const deployEnv = await setupTarballEnvironment({
                 projectDir,
                 monorepoRoot,
@@ -166,7 +150,10 @@ export function setupPlaygroundEnvironment(options = {}) {
                 projectDir: deployEnv.targetDir,
                 cleanup: deployEnv.cleanup,
             };
-            globalDeploymentInstancePromise = createDeployment(deployEnv.targetDir).then((instance) => {
+            const deployControl = createDeployment();
+            globalDeploymentInstancePromise = deployControl
+                .start()
+                .then((instance) => {
                 globalDeploymentInstance = instance;
                 return instance;
             });
@@ -174,7 +161,7 @@ export function setupPlaygroundEnvironment(options = {}) {
             globalDeploymentInstancePromise.catch(() => { });
         }
         else {
-            globalDeploymentInstancePromise = Promise.resolve(null);
+            globalDeployPlaygroundEnv = null;
         }
     }, SETUP_PLAYGROUND_ENV_TIMEOUT);
 }
@@ -182,82 +169,109 @@ export function setupPlaygroundEnvironment(options = {}) {
  * 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");
+export function createDevServer() {
+    ensureHooksRegistered();
+    if (!globalDevPlaygroundEnv) {
+        throw new Error("Dev playground environment not initialized. Enable `dev: true` in setupPlaygroundEnvironment.");
     }
+    const { projectDir } = globalDevPlaygroundEnv;
     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}`);
-        },
-    });
+    let instance = null;
     return {
-        url: devResult.url,
-        stopDev: devResult.stopDev,
+        projectDir,
+        start: async () => {
+            if (instance)
+                return instance;
+            if (SKIP_DEV_SERVER_TESTS) {
+                throw new Error("Dev server tests are skipped via RWSDK_SKIP_DEV=1");
+            }
+            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}`);
+                },
+            });
+            instance = {
+                url: devResult.url,
+                projectDir,
+                stopDev: devResult.stopDev,
+            };
+            devInstances.push(instance);
+            return instance;
+        },
     };
 }
 /**
  * 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");
+export function createDeployment() {
+    ensureHooksRegistered();
+    if (!globalDeployPlaygroundEnv) {
+        throw new Error("Deploy playground environment not initialized. Enable `deploy: true` in setupPlaygroundEnvironment.");
     }
-    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;
+    const { projectDir } = globalDeployPlaygroundEnv;
+    let instance = null;
+    return {
+        projectDir,
+        start: async () => {
+            if (instance)
+                return instance;
+            if (SKIP_DEPLOYMENT_TESTS) {
+                throw new Error("Deployment tests are skipped via RWSDK_SKIP_DEPLOY=1");
             }
-        }, {
-            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}`);
+            const newInstance = await pollValue(async () => {
+                const dirName = basename(projectDir);
+                // Match formats: {projectName}-t-{hash}, {projectName}-test-{hash}, or {projectName}-e2e-test-{hash}
+                const match = dirName.match(/-t-([a-f0-9]+)$/) ||
+                    dirName.match(/-test-([a-f0-9]+)$/) ||
+                    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);
+                await poll(async () => {
+                    try {
+                        const response = await fetch(deployResult.url);
+                        return response.status > 0;
+                    }
+                    catch (e) {
+                        return false;
+                    }
+                }, {
+                    timeout: DEPLOYMENT_CHECK_TIMEOUT,
+                });
+                const cleanup = async () => {
+                    const performCleanup = async () => {
+                        if (isRelatedToTest(deployResult.workerName, resourceUniqueKey)) {
+                            await deleteWorker(deployResult.workerName, projectDir, resourceUniqueKey);
+                        }
+                        await deleteD1Database(resourceUniqueKey, projectDir, resourceUniqueKey);
+                    };
+                    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}`);
+                },
             });
-            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}`);
+            deploymentInstances.push(newInstance);
+            return newInstance;
         },
-    });
+    };
 }
 /**
  * Executes a test function with a retry mechanism for specific error codes.
@@ -306,7 +320,7 @@ function createTestRunner(testFn, envType) {
     return (name, testLogic) => {
         if ((envType === "dev" && SKIP_DEV_SERVER_TESTS) ||
             (envType === "deploy" && SKIP_DEPLOYMENT_TESTS)) {
-            test.skip(name, () => { });
+            test.skip(`${name} (${envType})`, () => { });
             return;
         }
         describe.concurrent(name, () => {
@@ -314,7 +328,7 @@ function createTestRunner(testFn, envType) {
             let instance;
             let browser;
             beforeAll(async () => {
-                const tempDir = path.join(os.tmpdir(), "rwsdk-e2e-tests");
+                const tempDir = path.join(await ensureTmpDir(), "rwsdk-e2e-tests");
                 const wsEndpointFile = path.join(tempDir, "wsEndpoint");
                 try {
                     const wsEndpoint = await fs.readFile(wsEndpointFile, "utf-8");
@@ -368,12 +382,86 @@ function createTestRunner(testFn, envType) {
                         browser: browser,
                         page: page,
                         url: instance.url,
+                        projectDir: instance
+                            .projectDir,
                     });
                 });
             });
         });
     };
 }
+/**
+ * Creates a low-level test runner that provides utilities for creating
+ * tests that need to perform setup actions before the server starts.
+ */
+function createSDKTestRunner() {
+    const internalRunner = (testFn) => {
+        return (name, testLogic) => {
+            describe.concurrent(name, () => {
+                let page;
+                let browser;
+                beforeAll(async () => {
+                    const tempDir = path.join(await ensureTmpDir(), "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 () => {
+                    if (!globalDevPlaygroundEnv && !globalDeployPlaygroundEnv) {
+                        throw new Error("Test environment not initialized. Call setupPlaygroundEnvironment() in your test file.");
+                    }
+                    page = await browser.newPage();
+                    page.setDefaultTimeout(PUPPETEER_TIMEOUT);
+                }, SETUP_WAIT_TIMEOUT);
+                afterEach(async () => {
+                    if (page) {
+                        try {
+                            await page.close();
+                        }
+                        catch (error) {
+                            console.warn(`Suppressing error during page.close() in test "${name}":`, error);
+                        }
+                    }
+                });
+                testFn(">", async () => {
+                    if (!browser) {
+                        throw new Error("Test environment not ready.");
+                    }
+                    await runTestWithRetries(name, async () => {
+                        await testLogic({
+                            browser: browser,
+                            page: page,
+                            projectDir: globalDevPlaygroundEnv?.projectDir ||
+                                globalDeployPlaygroundEnv?.projectDir ||
+                                "",
+                        });
+                    });
+                });
+            });
+        };
+    };
+    const main = internalRunner(test);
+    return Object.assign(main, {
+        only: internalRunner(test.only),
+        skip: test.skip,
+    });
+}
+export const testSDK = createSDKTestRunner();
 /**
  * High-level test wrapper for dev server tests.
  * Automatically skips if RWSDK_SKIP_DEV=1

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

@@ -0,0 +1 @@
+export declare function ensureTmpDir(): Promise<string>;

package/dist/lib/e2e/utils.mjs

@@ -0,0 +1,15 @@
+import { mkdirp } from "fs-extra";
+import os from "node:os";
+import fs from "node:fs";
+import path from "node:path";
+export async function ensureTmpDir() {
+    let baseTmpDir = os.tmpdir();
+    // context(justinvdm, 2 Nov 2025): Normalize the base temp dir on Windows
+    // to prevent short/long path mismatches that break Vite's alias resolution.
+    if (process.platform === "win32") {
+        baseTmpDir = fs.realpathSync.native(baseTmpDir);
+    }
+    const tmpDir = path.join(baseTmpDir, "rwsdk-e2e");
+    await mkdirp(tmpDir);
+    return tmpDir;
+}

package/dist/runtime/client/client.d.ts

@@ -1,8 +1,43 @@
 import "./setWebpackRequire";
 export { default as React } from "react";
+export type { Dispatch, MutableRefObject, SetStateAction } from "react";
 export { ClientOnly } from "./ClientOnly.js";
+export { initClientNavigation, navigate } from "./navigation.js";
 import type { HydrationOptions, Transport } from "./types";
 export declare const fetchTransport: Transport;
+/**
+ * Initializes the React client and hydrates the RSC payload.
+ *
+ * This function sets up client-side hydration for React Server Components,
+ * making the page interactive. Call this from your client entry point.
+ *
+ * @param transport - Custom transport for server communication (defaults to fetchTransport)
+ * @param hydrateRootOptions - Options passed to React's hydrateRoot
+ * @param handleResponse - Custom response handler for navigation errors
+ *
+ * @example
+ * // Basic usage
+ * import { initClient } from "rwsdk/client";
+ *
+ * initClient();
+ *
+ * @example
+ * // With client-side navigation
+ * import { initClient, initClientNavigation } from "rwsdk/client";
+ *
+ * const { handleResponse } = initClientNavigation();
+ * initClient({ handleResponse });
+ *
+ * @example
+ * // With custom React hydration options
+ * initClient({
+ *   hydrateRootOptions: {
+ *     onRecoverableError: (error) => {
+ *       console.warn("Recoverable error:", error);
+ *     },
+ *   },
+ * });
+ */
 export declare const initClient: ({ transport, hydrateRootOptions, handleResponse, }?: {
     transport?: Transport;
     hydrateRootOptions?: HydrationOptions;