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

Build fast, server-driven webapps on Cloudflare with SSR, RSC, and realtime

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 {
    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;
    /**
     * Whether to automatically start the dev server.
     * @default true
     */
    autoStartDevServer?: 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: 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;
    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;
    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.
 * @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>;
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
 */
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;
        projectDir: 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;
        projectDir: 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;
    projectDir: 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[];
    };
};