rwsdk 1.0.0-beta.1 → 1.0.0-beta.10

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

@@ -0,0 +1,13 @@
+export declare const IS_DEBUG_MODE: string | boolean;
+export declare const SETUP_PLAYGROUND_ENV_TIMEOUT: number;
+export declare const DEPLOYMENT_TIMEOUT: number;
+export declare const DEPLOYMENT_MIN_TRIES: number;
+export declare const DEPLOYMENT_CHECK_TIMEOUT: number;
+export declare const PUPPETEER_TIMEOUT: number;
+export declare const HYDRATION_TIMEOUT: number;
+export declare const DEV_SERVER_TIMEOUT: number;
+export declare const DEV_SERVER_MIN_TRIES: number;
+export declare const SETUP_WAIT_TIMEOUT: number;
+export declare const TEST_MAX_RETRIES: number;
+export declare const TEST_MAX_RETRIES_PER_CODE: number;
+export declare const INSTALL_DEPENDENCIES_RETRIES: number;

package/dist/lib/e2e/constants.mjs

@@ -0,0 +1,67 @@
+export const IS_DEBUG_MODE = process.env.RWSDK_E2E_DEBUG
+    ? process.env.RWSDK_E2E_DEBUG
+    : !process.env.CI;
+export const SETUP_PLAYGROUND_ENV_TIMEOUT = process.env
+    .RWSDK_SETUP_PLAYGROUND_ENV_TIMEOUT
+    ? parseInt(process.env.RWSDK_SETUP_PLAYGROUND_ENV_TIMEOUT, 10)
+    : IS_DEBUG_MODE
+        ? 10 * 60 * 1000
+        : 15 * 60 * 1000;
+export const DEPLOYMENT_TIMEOUT = process.env.RWSDK_DEPLOYMENT_TIMEOUT
+    ? parseInt(process.env.RWSDK_DEPLOYMENT_TIMEOUT, 10)
+    : IS_DEBUG_MODE
+        ? 5 * 30 * 1000
+        : 5 * 60 * 1000;
+export const DEPLOYMENT_MIN_TRIES = process.env.RWSDK_DEPLOYMENT_MIN_TRIES
+    ? parseInt(process.env.RWSDK_DEPLOYMENT_MIN_TRIES, 10)
+    : IS_DEBUG_MODE
+        ? 1
+        : 5;
+export const DEPLOYMENT_CHECK_TIMEOUT = process.env
+    .RWSDK_DEPLOYMENT_CHECK_TIMEOUT
+    ? parseInt(process.env.RWSDK_DEPLOYMENT_CHECK_TIMEOUT, 10)
+    : IS_DEBUG_MODE
+        ? 30 * 1000
+        : 5 * 60 * 1000;
+export const PUPPETEER_TIMEOUT = process.env.RWSDK_PUPPETEER_TIMEOUT
+    ? parseInt(process.env.RWSDK_PUPPETEER_TIMEOUT, 10)
+    : IS_DEBUG_MODE
+        ? 30 * 1000
+        : 60 * 1000 * 2;
+export const HYDRATION_TIMEOUT = process.env.RWSDK_HYDRATION_TIMEOUT
+    ? parseInt(process.env.RWSDK_HYDRATION_TIMEOUT, 10)
+    : IS_DEBUG_MODE
+        ? 2000
+        : 5000;
+export const DEV_SERVER_TIMEOUT = process.env.RWSDK_DEV_SERVER_TIMEOUT
+    ? parseInt(process.env.RWSDK_DEV_SERVER_TIMEOUT, 10)
+    : IS_DEBUG_MODE
+        ? 60 * 1000
+        : 5 * 60 * 1000;
+export const DEV_SERVER_MIN_TRIES = process.env.RWSDK_DEV_SERVER_MIN_TRIES
+    ? parseInt(process.env.RWSDK_DEV_SERVER_MIN_TRIES, 10)
+    : IS_DEBUG_MODE
+        ? 1
+        : 5;
+export const SETUP_WAIT_TIMEOUT = process.env.RWSDK_SETUP_WAIT_TIMEOUT
+    ? parseInt(process.env.RWSDK_SETUP_WAIT_TIMEOUT, 10)
+    : IS_DEBUG_MODE
+        ? 60 * 1000
+        : 10 * 60 * 1000;
+export const TEST_MAX_RETRIES = process.env.RWSDK_TEST_MAX_RETRIES
+    ? parseInt(process.env.RWSDK_TEST_MAX_RETRIES, 10)
+    : IS_DEBUG_MODE
+        ? 1
+        : 10;
+export const TEST_MAX_RETRIES_PER_CODE = process.env
+    .RWSDK_TEST_MAX_RETRIES_PER_CODE
+    ? parseInt(process.env.RWSDK_TEST_MAX_RETRIES_PER_CODE, 10)
+    : IS_DEBUG_MODE
+        ? 0
+        : 6;
+export const INSTALL_DEPENDENCIES_RETRIES = process.env
+    .RWSDK_INSTALL_DEPENDENCIES_RETRIES
+    ? parseInt(process.env.RWSDK_INSTALL_DEPENDENCIES_RETRIES, 10)
+    : IS_DEBUG_MODE
+        ? 1
+        : 10;

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

@@ -3,7 +3,7 @@ import { PackageManager } from "./types.mjs";
 /**
  * Copy project to a temporary directory with a unique name
  */
-export declare function copyProjectToTempDir(projectDir: string, resourceUniqueKey: string, packageManager?: PackageManager, monorepoRoot?: string): Promise<{
+export declare function copyProjectToTempDir(projectDir: string, resourceUniqueKey: string, packageManager?: PackageManager, monorepoRoot?: string, installDependenciesRetries?: number): Promise<{
     tempDir: tmp.DirectoryResult;
     targetDir: string;
     workerName: string;

package/dist/lib/e2e/environment.mjs

@@ -8,8 +8,12 @@ import { basename, join, relative, resolve } from "path";
 import tmp from "tmp-promise";
 import { $ } from "../../lib/$.mjs";
 import { ROOT_DIR } from "../constants.mjs";
+import { INSTALL_DEPENDENCIES_RETRIES } from "./constants.mjs";
 import { retry } from "./retry.mjs";
 const log = debug("rwsdk:e2e:environment");
+const getTempDir = async () => {
+    return tmp.dir({ unsafeCleanup: true });
+};
 const createSdkTarball = async () => {
     const existingTarballPath = process.env.RWSKD_SMOKE_TEST_TARBALL_PATH;
     if (existingTarballPath) {
@@ -46,12 +50,11 @@ const setTarballDependency = async (targetDir, tarballName) => {
 /**
  * Copy project to a temporary directory with a unique name
  */
-export async function copyProjectToTempDir(projectDir, resourceUniqueKey, packageManager, monorepoRoot) {
+export async function copyProjectToTempDir(projectDir, resourceUniqueKey, packageManager, monorepoRoot, installDependenciesRetries) {
     const { tarballPath, cleanupTarball } = await createSdkTarball();
     try {
         log("Creating temporary directory for project");
-        // Create a temporary directory
-        const tempDir = await tmp.dir({ unsafeCleanup: true });
+        const tempDir = await getTempDir();
         // Determine the source directory to copy from
         const sourceDir = monorepoRoot || projectDir;
         // Create unique project directory name
@@ -130,7 +133,6 @@ export async function copyProjectToTempDir(projectDir, resourceUniqueKey, packag
         log("⚙️  Configuring temp project to not use frozen lockfile...");
         const npmrcPath = join(targetDir, ".npmrc");
         await fs.promises.writeFile(npmrcPath, "frozen-lockfile=false\n");
-        // For yarn, create .yarnrc.yml to disable PnP and allow lockfile changes
         if (packageManager === "yarn") {
             const yarnrcPath = join(targetDir, ".yarnrc.yml");
             const yarnCacheDir = path.join(os.tmpdir(), "yarn-cache");
@@ -144,11 +146,19 @@ export async function copyProjectToTempDir(projectDir, resourceUniqueKey, packag
             await fs.promises.writeFile(yarnrcPath, yarnConfig);
             log("Created .yarnrc.yml to allow lockfile changes for yarn");
         }
+        if (packageManager === "yarn-classic") {
+            const yarnrcPath = join(targetDir, ".yarnrc");
+            const yarnCacheDir = path.join(os.tmpdir(), "yarn-classic-cache");
+            await fs.promises.mkdir(yarnCacheDir, { recursive: true });
+            const yarnConfig = `cache-folder "${yarnCacheDir}"`;
+            await fs.promises.writeFile(yarnrcPath, yarnConfig);
+            log("Created .yarnrc with cache-folder for yarn-classic");
+        }
         await setTarballDependency(targetDir, tarballFilename);
         // Install dependencies in the target directory
         const installDir = monorepoRoot ? tempCopyRoot : targetDir;
         await retry(() => installDependencies(installDir, packageManager), {
-            retries: 3,
+            retries: INSTALL_DEPENDENCIES_RETRIES,
             delay: 1000,
         });
         // Return the environment details
@@ -185,7 +195,7 @@ async function installDependencies(targetDir, packageManager = "pnpm") {
             }
             else if (packageManager === "yarn-classic") {
                 log(`Preparing yarn@1.22.19 with corepack...`);
-                await $("corepack", ["prepare", "yarn@1.22.19", "--activate"], {
+                await $("corepack", ["prepare", "yarn@1.x", "--activate"], {
                     cwd: targetDir,
                     stdio: "pipe",
                 });

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

@@ -1,3 +1,4 @@
+export * from "../$.mjs";
 export * from "./browser.mjs";
 export * from "./dev.mjs";
 export * from "./environment.mjs";

package/dist/lib/e2e/index.mjs

@@ -1,3 +1,4 @@
+export * from "../$.mjs";
 export * from "./browser.mjs";
 export * from "./dev.mjs";
 export * from "./environment.mjs";

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

@@ -1,8 +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 { 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 {
@@ -41,17 +44,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.
@@ -61,13 +76,25 @@ 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: {
+    createDevServer: () => Promise<DevServerInstance>;
+    createDeployment: () => Promise<DeploymentInstance>;
+    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
@@ -81,6 +108,7 @@ export declare namespace testDev {
         browser: Browser;
         page: Page;
         url: string;
+        projectDir: string;
     }) => Promise<void>) => void;
 }
 /**
@@ -96,6 +124,7 @@ export declare namespace testDeploy {
         browser: Browser;
         page: Page;
         url: string;
+        projectDir: string;
     }) => Promise<void>) => void;
 }
 /**
@@ -108,6 +137,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

@@ -4,44 +4,12 @@ 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 { 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 { 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";
@@ -52,6 +20,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
@@ -62,11 +32,11 @@ 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());
         }
-        if (globalDeploymentInstance) {
-            cleanupPromises.push(globalDeploymentInstance.cleanup());
+        for (const instance of deploymentInstances) {
+            cleanupPromises.push(instance.cleanup());
         }
         if (globalDevPlaygroundEnv) {
             cleanupPromises.push(globalDevPlaygroundEnv.cleanup());
@@ -75,8 +45,8 @@ function ensureHooksRegistered() {
             cleanupPromises.push(globalDeployPlaygroundEnv.cleanup());
         }
         await Promise.all(cleanupPromises);
-        globalDevInstance = null;
-        globalDeploymentInstance = null;
+        devInstances.length = 0;
+        deploymentInstances.length = 0;
         globalDevPlaygroundEnv = null;
         globalDeployPlaygroundEnv = null;
     });
@@ -114,7 +84,7 @@ 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 = {}) {
+export function setupPlaygroundEnvironment(options) {
     const { sourceProjectDir, monorepoRoot, dev = true, deploy = true, } = typeof options === "string" ? { sourceProjectDir: options } : options;
     ensureHooksRegistered();
     beforeAll(async () => {
@@ -141,7 +111,8 @@ export function setupPlaygroundEnvironment(options = {}) {
                 projectDir: devEnv.targetDir,
                 cleanup: devEnv.cleanup,
             };
-            globalDevInstancePromise = createDevServer(devEnv.targetDir).then((instance) => {
+            const devControl = createDevServer();
+            globalDevInstancePromise = devControl.start().then((instance) => {
                 globalDevInstance = instance;
                 return instance;
             });
@@ -150,7 +121,7 @@ export function setupPlaygroundEnvironment(options = {}) {
             globalDevInstancePromise.catch(() => { });
         }
         else {
-            globalDevInstancePromise = Promise.resolve(null);
+            globalDevPlaygroundEnv = null;
         }
         if (deploy) {
             const deployEnv = await setupTarballEnvironment({
@@ -162,7 +133,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;
             });
@@ -170,7 +144,7 @@ export function setupPlaygroundEnvironment(options = {}) {
             globalDeploymentInstancePromise.catch(() => { });
         }
         else {
-            globalDeploymentInstancePromise = Promise.resolve(null);
+            globalDeployPlaygroundEnv = null;
         }
     }, SETUP_PLAYGROUND_ENV_TIMEOUT);
 }
@@ -178,82 +152,106 @@ 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);
+                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);
+                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.
@@ -302,7 +300,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, () => {
@@ -364,12 +362,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(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 () => {
+                    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/runtime/client/client.d.ts

@@ -1,6 +1,7 @@
 import "./setWebpackRequire";
 export { default as React } from "react";
 export { ClientOnly } from "./ClientOnly.js";
+export { initClientNavigation, navigate } from "./navigation.js";
 import type { HydrationOptions, Transport } from "./types";
 export declare const fetchTransport: Transport;
 export declare const initClient: ({ transport, hydrateRootOptions, handleResponse, }?: {