feat: runCommand to support interactive write+read

Author: AriPerkkio

README.md

@@ -56,9 +56,10 @@ test("run development server inside webcontainer", async ({
   await webcontainer.mount("path/to/project");
 
   await webcontainer.runCommand("npm", ["install"]);
-  webcontainer.runCommand("npm", ["run", "dev"]);
+  const { exit } = webcontainer.runCommand("npm", ["run", "dev"]);
 
   await preview.getByRole("heading", { level: 1, name: "Hello Vite!" });
+  await exit();
 });
 ```
 
@@ -111,14 +112,37 @@ await webcontainer.mount({
 
 ##### `runCommand`
 
-Run command inside webcontainer. Returns command output.
+Run command inside webcontainer.
 
 ```ts
 await webcontainer.runCommand("npm", ["install"]);
+```
+
+Calling `await` on the result resolves into the command output:
 
+```ts
 const files = await webcontainer.runCommand("ls", ["-l"]);
 ```
 
+To write into the output stream, use `write` method of the non-awaited output.
+
+To verify output of continuous stream, use `waitForText()`:
+
+```ts
+const { write, waitForText, exit } = webcontainer.runCommand("npm", [
+  "create",
+  "vite",
+]);
+
+await waitForText("What would you like to call your project?");
+await write("Example Project\n");
+
+await waitForText("Where should the project be created?");
+await write("./example-project\n");
+
+await exit();
+```
+
 ##### `readFile`
 
 WebContainer's [`readFile`](https://webcontainers.io/guides/working-with-the-file-system#readfile) method.

src/fixtures/file-system.ts

@@ -8,7 +8,7 @@ import type {
 export class FileSystem {
   /** @internal */
   protected get _instance(): WebContainer {
-    throw new Error("_instance should be overwritte");
+    throw new Error("_instance should be overwritten");
   }
 
   /**

src/fixtures/index.ts

@@ -17,9 +17,10 @@ import { WebContainer } from "./webcontainer";
  *   await webcontainer.mount("path/to/project");
  *
  *   await webcontainer.runCommand("npm", ["install"]);
- *   webcontainer.runCommand("npm", ["run", "dev"]);
+ *   const { exit } = webcontainer.runCommand("npm", ["run", "dev"]);
  *
  *   await preview.getByRole("heading", { level: 1, name: "Hello Vite!" });
+ *   await exit();
  * });
  * ```
  */

src/fixtures/process.ts

@@ -0,0 +1,127 @@
+import { WebContainerProcess } from "@webcontainer/api";
+
+export class ProcessWrap {
+  /** @internal */
+  private _webcontainerProcess!: WebContainerProcess;
+
+  /** @internal */
+  private _isReady: Promise<void>;
+
+  /** @internal */
+  private _output: string = "";
+
+  /** @internal */
+  private _listeners: (() => void)[] = [];
+
+  /** @internal */
+  private _writer?: ReturnType<WebContainerProcess["input"]["getWriter"]>;
+
+  /**
+   * Wait for process to exit.
+   */
+  isDone: Promise<void>;
+
+  constructor(promise: Promise<WebContainerProcess>) {
+    let setDone: () => void = () => undefined;
+    this.isDone = new Promise((resolve) => (setDone = resolve));
+
+    this._isReady = promise.then((webcontainerProcess) => {
+      this._webcontainerProcess = webcontainerProcess;
+      this._writer = webcontainerProcess.input.getWriter();
+
+      webcontainerProcess.exit.then(() => setDone());
+
+      this._webcontainerProcess.output.pipeTo(
+        new WritableStream({
+          write: (data) => {
+            this._output += data;
+            this._listeners.forEach((fn) => fn());
+          },
+        }),
+      );
+    });
+  }
+
+  then<TResult1 = string, TResult2 = never>(
+    onfulfilled?: ((value: string) => TResult1 | PromiseLike<TResult1>) | null,
+    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+  ): Promise<TResult1 | TResult2> {
+    return this.isDone
+      .then(() => this._output.trim())
+      .then(onfulfilled, onrejected);
+  }
+
+  /**
+   * Write command into the process.
+   */
+  write = async (text: string) => {
+    await this._isReady;
+
+    this.resetCapturedText();
+
+    if (!this._writer) {
+      throw new Error("Process setup failed, writer not initialized");
+    }
+
+    return this._writer.write(text);
+  };
+
+  /**
+   * Reset captured output, so that `waitForText` does not match previous captured outputs.
+   */
+  resetCapturedText = () => {
+    this._output = "";
+  };
+
+  /**
+   * Wait for process to output expected text.
+   */
+  waitForText = async (expected: string, timeoutMs = 10_000) => {
+    const error = new Error("Timeout");
+
+    if ("captureStackTrace" in Error) {
+      Error.captureStackTrace(error, this.waitForText);
+    }
+
+    await this._isReady;
+
+    return new Promise<void>((resolve, reject) => {
+      if (this._output.includes(expected)) {
+        resolve();
+        return;
+      }
+
+      const timeout = setTimeout(() => {
+        error.message = `Timeout when waiting for error "${expected}".\nReceived:\n${this._output}`;
+        reject(error);
+      }, timeoutMs);
+
+      const listener = () => {
+        if (this._output.includes(expected)) {
+          clearTimeout(timeout);
+          this._listeners.splice(this._listeners.indexOf(listener), 1);
+
+          resolve();
+        }
+      };
+
+      this._listeners.push(listener);
+    });
+  };
+
+  /**
+   * Exit the process.
+   */
+  exit = async () => {
+    await this._isReady;
+
+    // @ts-ignore -- internal check
+    if (this._webcontainerProcess._process != null) {
+      this._webcontainerProcess.kill();
+    }
+
+    this._listeners.splice(0);
+
+    return this.isDone;
+  };
+}

src/fixtures/webcontainer.ts

@@ -1,5 +1,7 @@
 import { WebContainer as WebContainerApi } from "@webcontainer/api";
+
 import { FileSystem } from "./file-system";
+import { ProcessWrap } from "./process";
 
 export class WebContainer extends FileSystem {
   /** @internal */
@@ -55,33 +57,18 @@ export class WebContainer extends FileSystem {
 
   /**
    * Run command inside WebContainer.
-   * Returns the output of the command.
+   * See [`runCommand` documentation](https://github.com/stackblitz/webcontainer-test#runcommand) for usage examples.
    */
-  async runCommand(command: string, args: string[] = []) {
-    let output = "";
-
-    const process = await this._instance.spawn(command, args, { output: true });
-
-    process.output.pipeTo(
-      new WritableStream({
-        write(data) {
-          output += data;
-        },
-      }),
+  runCommand(
+    command: string,
+    args: string[] = [],
+  ): PromiseLike<string> & ProcessWrap {
+    const proc = new ProcessWrap(
+      this._instance.spawn(command, args, { output: true }),
     );
 
-    // make sure any long-living processes are terminated before teardown, e.g. "npm run dev" commands
-    this._onExit.push(() => {
-      // @ts-ignore -- internal
-      if (process._process != null) {
-        process.kill();
-      }
-
-      return process.exit;
-    });
-
-    await process.exit;
+    this._onExit.push(() => proc.exit());
 
-    return output.trim();
+    return proc;
   }
 }

test/preview.test.ts

@@ -5,30 +5,30 @@ test("user can see server output in preview", async ({
   preview,
 }) => {
   await webcontainer.mount("test/fixtures/starter-vite");
-
   await webcontainer.runCommand("npm", ["install"]);
-  void webcontainer.runCommand("npm", ["run", "dev"]);
+
+  const { exit } = webcontainer.runCommand("npm", ["run", "dev"]);
 
   await preview.getByRole("heading", { level: 1, name: "Hello Vite!" });
+  await exit();
 });
 
 test("user can see HMR changes in preview", async ({
   webcontainer,
   preview,
 }) => {
   await webcontainer.mount("test/fixtures/starter-vite");
-
   await webcontainer.runCommand("npm", ["install"]);
-  void webcontainer.runCommand("npm", ["run", "dev"]);
 
+  const { exit } = webcontainer.runCommand("npm", ["run", "dev"]);
   await preview.getByRole("heading", { level: 1, name: "Hello Vite!" });
 
   const content = await webcontainer.readFile("/src/main.js");
-
   await webcontainer.writeFile(
     "/src/main.js",
     content.replace("Hello Vite!", "Modified title!"),
   );
 
   await preview.getByRole("heading", { level: 1, name: "Modified title!" });
+  await exit();
 });

test/run-command.test.ts

@@ -7,3 +7,18 @@ test("user can run commands inside webcontainer", async ({ webcontainer }) => {
 
   expect(output).toMatchInlineSnapshot(`"v20.19.0"`);
 });
+
+test("user can run interactive commands inside webcontainer", async ({
+  webcontainer,
+}) => {
+  const { exit, waitForText, write } = webcontainer.runCommand("node");
+  await waitForText("Welcome to Node.js v20.19.0");
+
+  await write("console.log(20 + 19)\n");
+  await waitForText("39");
+
+  await write("console.log(os.platform(), os.arch())\n");
+  await waitForText("linux x64");
+
+  await exit();
+});