README.md

@webcontainer/test

Utilities for testing applications in WebContainers

Installation | Configuration | API

---

Test your applications and packages inside WebContainers.

Installation

Add @webcontainer/test to your development dependencies.

$ npm install --save-dev @webcontainer/test

Vitest is also required as peer dependency.

$ npm install --save-dev vitest @vitest/browser

Configuration

Add vitestWebcontainers plugin in your Vitest config and enable browser mode:

import { defineConfig } from "vitest/config";
import { vitestWebcontainers } from "@webcontainer/test/plugin";

export default defineConfig({
  plugins: [vitestWebcontainers()],
  test: {
    browser: {
      enabled: true,
      provider: "playwright",
      instances: [{ browser: "chromium" }],
    },
  },
});

API

Webcontainer utilities are exposed as test fixtures.

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"]);
  webcontainer.runCommand("npm", ["run", "dev"]);

  await preview.getByRole("heading", { level: 1, name: "Hello Vite!" });
});

preview

getByRole

Vitest's getByRole that's scoped to the preview window.

await preview.getByRole("heading", { level: 1, name: "Hello Vite!" });

getByText

Vitest's getByText that's scoped to the preview window.

await preview.getByText("Hello Vite!");

webcontainer

mount

Mount file system inside webcontainer.

Accepts a path that is relative to the project root, or inlined FileSystemTree.

await webcontainer.mount("/path/to/project");

runCommand

Run command inside webcontainer. Returns command output.

await webcontainer.runCommand("npm", ["install"]);

const files = await webcontainer.runCommand("ls", ["-l"]);