@webcontainer/test/dist/index.d.ts

Utilities for testing applications in WebContainers

import * as vitest from 'vitest';
import { page, Locator } from '@vitest/browser/context';
import { FileSystemTree, BufferEncoding, WebContainerProcess } from '@webcontainer/api';

declare class Preview {
    constructor();
    /**
     * Vitest's [`getByRole`](https://vitest.dev/guide/browser/locators.html#getbyrole) that's scoped to the preview window.
     */
    getByRole(...options: Parameters<typeof page.getByRole>): Promise<Locator>;
    /**
     * Vitest's [`getByText`](https://vitest.dev/guide/browser/locators.html#getbytext) that's scoped to the preview window.
     */
    getByText(...options: Parameters<typeof page.getByText>): Promise<Locator>;
    /**
     * Vitest's [`locator`](https://vitest.dev/guide/browser/locators.html) of the preview window.
     */
    get locator(): Locator;
}

declare class FileSystem {
    /**
     * Mount file directory into WebContainer.
     * `string` arguments are considered paths that are relative to [`root`](https://vitest.dev/config/#root)
     */
    mount(filesOrPath: string | FileSystemTree): Promise<void>;
    /**
     * WebContainer's [`readFile`](https://webcontainers.io/guides/working-with-the-file-system#readfile) method.
     */
    readFile(path: string, encoding?: BufferEncoding): Promise<string>;
    /**
     * WebContainer's [`writeFile`](https://webcontainers.io/guides/working-with-the-file-system#writefile) method.
     */
    writeFile(path: string, data: string, encoding?: string): Promise<void>;
    /**
     * WebContainer's [`rename`](https://webcontainers.io/guides/working-with-the-file-system#rename) method.
     */
    rename(oldPath: string, newPath: string): Promise<void>;
    /**
     * WebContainer's [`mkdir`](https://webcontainers.io/guides/working-with-the-file-system#mkdir) method.
     */
    mkdir(path: string): Promise<void>;
    /**
     * WebContainer's [`readdir`](https://webcontainers.io/guides/working-with-the-file-system#readdir) method.
     */
    readdir(path: string): Promise<string[]>;
    /**
     * WebContainer's [`rm`](https://webcontainers.io/guides/working-with-the-file-system#rm) method.
     */
    rm(path: string): Promise<void>;
}

declare class ProcessWrap {
    /**
     * Wait for process to exit.
     */
    isDone: Promise<void>;
    constructor(promise: Promise<WebContainerProcess>);
    then<TResult1 = string, TResult2 = never>(onfulfilled?: ((value: string) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
    /**
     * Write command into the process.
     */
    write: (text: string) => Promise<void>;
    /**
     * Reset captured output, so that `waitForText` does not match previous captured outputs.
     */
    resetCapturedText: () => void;
    /**
     * Wait for process to output expected text.
     */
    waitForText: (expected: string, timeoutMs?: number) => Promise<void>;
    /**
     * Listen for data stream chunks.
     */
    onData: (listener: (chunk: string) => void) => void;
    /**
     * Exit the process.
     */
    exit: () => Promise<void>;
}

declare class WebContainer extends FileSystem {
    constructor();
    /**
     * Run command inside WebContainer.
     * See [`runCommand` documentation](https://github.com/stackblitz/webcontainer-test#runcommand) for usage examples.
     */
    runCommand(command: string, args?: string[]): PromiseLike<string> & ProcessWrap;
}

interface TestContext {
    preview: Preview;
    webcontainer: WebContainer;
    setup: (callback: () => Promise<void>) => Promise<void>;
}
/**
 * Pre-defined [`test()` function](https://vitest.dev/guide/test-context.html#extend-test-context) with WebContainer fixtures.
 *
 * @example
 * ```ts
 * import { test } from "@webcontainer/test";
 *
 * test("run development server inside webcontainer", async ({
 *   webcontainer,
 *   preview,
 * }) => {
 *   await webcontainer.mount("path/to/project");
 *
 *   await webcontainer.runCommand("npm", ["install"]);
 *   const { exit } = webcontainer.runCommand("npm", ["run", "dev"]);
 *
 *   await preview.getByRole("heading", { level: 1, name: "Hello Vite!" });
 *   await exit();
 * });
 * ```
 */
declare const test: vitest.TestAPI<{
    preview: Preview;
    webcontainer: WebContainer;
    setup: (callback: () => Promise<void>) => Promise<void>;
}>;

export { type TestContext, test };