docs: readme and jsdocs

Author: AriPerkkio

README.md

@@ -76,8 +76,12 @@ await preview.getByRole("heading", { level: 1, name: "Hello Vite!" });
 
 Vitest's [`getByText`](https://vitest.dev/guide/browser/locators.html#getbytext) that's scoped to the preview window.
 
+##### `locator`
+
+Vitest's [`locator`](https://vitest.dev/guide/browser/locators.html) of the preview window.
+
 ```ts
-await preview.getByText("Hello Vite!");
+await preview.locator.hover();
 ```
 
 #### `webcontainer`
@@ -102,5 +106,53 @@ await webcontainer.runCommand("npm", ["install"]);
 const files = await webcontainer.runCommand("ls", ["-l"]);
 ```
 
+##### `readFile`
+
+WebContainer's [`readFile`](https://webcontainers.io/guides/working-with-the-file-system#readfile) method.
+
+```ts
+const content = await webcontainer.readFile("/package.json");
+```
+
+##### `writeFile`
+
+WebContainer's [`writeFile`](https://webcontainers.io/guides/working-with-the-file-system#writefile) method.
+
+```ts
+await webcontainer.writeFile("/main.ts", "console.log('Hello world!')");
+```
+
+##### `rename`
+
+WebContainer's [`rename`](https://webcontainers.io/guides/working-with-the-file-system#rename) method.
+
+```ts
+await webcontainer.rename("/before.ts", "/after.ts");
+```
+
+##### `mkdir`
+
+WebContainer's [`mkdir`](https://webcontainers.io/guides/working-with-the-file-system#mkdir) method.
+
+```ts
+await webcontainer.mkdir("/src/components");
+```
+
+##### `readdir`
+
+WebContainer's [`readdir`](https://webcontainers.io/guides/working-with-the-file-system#readdir) method.
+
+```ts
+const contents = await webcontainer.readdir("/src");
+```
+
+##### `rm`
+
+WebContainer's [`rm`](https://webcontainers.io/guides/working-with-the-file-system#rm) method.
+
+```ts
+await webcontainer.rm("/node_modules");
+```
+
 [version-badge]: https://img.shields.io/npm/v/@webcontainer/test
 [npm-url]: https://www.npmjs.com/package/@webcontainer/test

src/fixtures/index.ts

@@ -3,6 +3,26 @@ import { test as base } from "vitest";
 import { Preview } from "./preview";
 import { WebContainer } from "./webcontainer";
 
+/**
+ * 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"]);
+ *   webcontainer.runCommand("npm", ["run", "dev"]);
+ *
+ *   await preview.getByRole("heading", { level: 1, name: "Hello Vite!" });
+ * });
+ * ```
+ */
 export const test = base.extend<{
   preview: Preview;
   webcontainer: WebContainer;

src/fixtures/preview.ts

@@ -3,13 +3,17 @@ import { type Locator, page } from "@vitest/browser/context";
 const TEST_ID = "webcontainers-iframe";
 
 export class Preview {
+  /** @internal */
   private _preview: Locator;
+
+  /** @internal */
   private _iframe?: HTMLIFrameElement;
 
   constructor() {
     this._preview = page.getByTestId(TEST_ID);
   }
 
+  /** @internal */
   async setup(url: string) {
     const iframe = document.createElement("iframe");
     iframe.setAttribute("src", url);
@@ -21,17 +25,31 @@ export class Preview {
     this._iframe = iframe;
   }
 
+  /** @internal */
   async teardown() {
     if (this._iframe) {
       document.body.removeChild(this._iframe);
     }
   }
 
+  /**
+   * Vitest's [`getByRole`](https://vitest.dev/guide/browser/locators.html#getbyrole) that's scoped to the preview window.
+   */
   async getByRole(...options: Parameters<typeof page.getByRole>) {
     return this._preview.getByRole(...options);
   }
 
+  /**
+   * Vitest's [`getByText`](https://vitest.dev/guide/browser/locators.html#getbytext) that's scoped to the preview window.
+   */
   async getByText(...options: Parameters<typeof page.getByText>) {
     return this._preview.getByText(...options);
   }
+
+  /**
+   * Vitest's [`locator`](https://vitest.dev/guide/browser/locators.html) of the preview window.
+   */
+  get locator() {
+    return this._preview;
+  }
 }

src/fixtures/webcontainer.ts

@@ -6,8 +6,13 @@ import {
 } from "@webcontainer/api";
 
 export class WebContainer {
+  /** @internal */
   private _instancePromise?: WebContainerApi;
+
+  /** @internal */
   private _isReady: Promise<void>;
+
+  /** @internal */
   private _onExit: (() => Promise<unknown>)[] = [];
 
   constructor() {
@@ -26,18 +31,20 @@ export class WebContainer {
     return this._instancePromise;
   }
 
+  /** @internal */
   async wait() {
     await this._isReady;
   }
 
+  /** @internal */
   onServerReady(callback: (options: { port: number; url: string }) => void) {
     this._instance.on("server-ready", (port, url) => {
       callback({ port, url });
     });
   }
 
   /**
-   * Mount file directory into webcontainer.
+   * Mount file directory into WebContainer.
    * `string` arguments are considered paths that are relative to [`root`](https://vitest.dev/config/#root)
    */
   async mount(filesOrPath: string | FileSystemTree) {
@@ -48,6 +55,7 @@ export class WebContainer {
     return await this._instance.mount(filesOrPath as FileSystemTree);
   }
 
+  /** @internal */
   async teardown() {
     await Promise.all(this._onExit.map((fn) => fn()));
 
@@ -58,6 +66,10 @@ export class WebContainer {
     this._instancePromise = undefined;
   }
 
+  /**
+   * Run command inside WebContainer.
+   * Returns the output of the command.
+   */
   async runCommand(command: string, args: string[] = []) {
     let output = "";
 
@@ -86,26 +98,44 @@ export class WebContainer {
     return output.trim();
   }
 
+  /**
+   * WebContainer's [`readFile`](https://webcontainers.io/guides/working-with-the-file-system#readfile) method.
+   */
   async readFile(path: string, encoding: BufferEncoding = "utf8") {
     return this._instance.fs.readFile(path, encoding);
   }
 
+  /**
+   * WebContainer's [`writeFile`](https://webcontainers.io/guides/working-with-the-file-system#writefile) method.
+   */
   async writeFile(path: string, data: string, encoding = "utf8") {
     return this._instance.fs.writeFile(path, data, { encoding });
   }
 
+  /**
+   * WebContainer's [`rename`](https://webcontainers.io/guides/working-with-the-file-system#rename) method.
+   */
   async rename(oldPath: string, newPath: string) {
     return this._instance.fs.rename(oldPath, newPath);
   }
 
+  /**
+   * WebContainer's [`mkdir`](https://webcontainers.io/guides/working-with-the-file-system#mkdir) method.
+   */
   async mkdir(path: string) {
     return this._instance.fs.mkdir(path);
   }
 
+  /**
+   * WebContainer's [`readdir`](https://webcontainers.io/guides/working-with-the-file-system#readdir) method.
+   */
   async readdir(path: string) {
     return this._instance.fs.readdir(path);
   }
 
+  /**
+   * WebContainer's [`rm`](https://webcontainers.io/guides/working-with-the-file-system#rm) method.
+   */
   async rm(path: string) {
     return this._instance.fs.rm(path);
   }

src/plugin.ts

@@ -1,6 +1,5 @@
 import type { Vite } from "vitest/node";
 import { readDirectory } from "./commands";
-import "./types.d.ts";
 
 const COEP = "Cross-Origin-Embedder-Policy";
 const COOP = "Cross-Origin-Opener-Policy";

tsconfig.json

@@ -4,7 +4,8 @@
     "module": "ESNext",
     "target": "ESNext",
     "moduleResolution": "bundler",
-    "skipLibCheck": true
+    "skipLibCheck": true,
+    "stripInternal": true
   },
   "include": ["src", "test"]
 }