How to Run Tests for cloudflare/computer: Complete Monorepo Guide

You must build the Cloudflare Computer monorepo workspace before running tests because the test suite imports compiled artifacts from sibling packages.

The cloudflare/computer repository is a TypeScript monorepo containing inter-dependent packages such as dofs, rpc, computerd, and computer. Because the test files import built output from sibling workspaces, running tests requires a specific three-phase workflow: install dependencies, build all packages, then execute the Vitest test suite. This architecture ensures type safety across package boundaries but mandates that contributors follow the build-first protocol documented in COLLABORATORS.md and individual package READMEs.

Prerequisites

Before executing the test suite, ensure your environment meets the baseline requirements.

• Node.js and npm – The workspace uses npm workspaces for dependency management.
• Git – Required to clone the repository and its submodules.
• Optional: Docker – Required for container-based tests in packages/computerd/src/exec/runner.fuse.test.ts.
• Optional: FUSE access – Native FUSE tests require /dev/fuse access on Linux; otherwise, tests fall back to a userspace shim.

Step-by-Step Test Workflow

The repository enforces a strict sequence: install once, build everywhere, then test. Skipping the build step will cause import errors when Vitest attempts to resolve dist/ directories that do not yet exist.

Clone and Install Dependencies

Clone the repository and perform a workspace-wide installation. Do not run npm install inside individual package directories.

git clone https://github.com/cloudflare/computer.git
cd computer
npm install

This command installs all dependencies for every package in the monorepo simultaneously, ensuring consistent version resolution across workspaces.

Build the Workspace

Compile TypeScript sources to populate the dist/ directories that tests import at runtime.

npm run build

As noted in packages/computerd/README.md, the test command does not trigger a build automatically. You must execute this step manually whenever source code changes affect cross-package imports.

Execute the Test Suite

Run the full test suite across all packages using Vitest:

npm test

For targeted development, run tests for a specific package using the workspace filter:

npm test --workspace=@cloudflare/computerd

To run a single test file within a package, append the file path:

npm test --workspace=@cloudflare/dofs -- src/path/to/file.test.ts

Testing Individual Packages vs. Full Workspace

The monorepo structure supports both comprehensive and granular testing strategies.

• Full workspace (npm test): Validates all packages and their integration points. Use this before submitting pull requests.
• Single package (npm test --workspace=@cloudflare/<pkg>): Accelerates development cycles when modifying isolated code. The COLLABORATORS.md file explicitly recommends this approach: "Run the package-level tests for whatever you touched."

Each package's README contains specific guidance. For example, packages/dofs/README.md and packages/rpc/README.md document package-level test commands, while packages/computerd/README.md details additional prerequisites for daemon-specific tests.

Platform-Specific Test Requirements

Certain test suites in the computerd package require specific host capabilities.

FUSE Prerequisites

Tests located in packages/computerd access the FUSE filesystem interface. According to the source:

• Linux with /dev/fuse: Tests exercise the native FUSE implementation when the device is present and the process has sufficient privileges.
• Fallback mode: In CI environments or containers without FUSE access, tests automatically use a userspace shim instead of failing.

To force real FUSE testing, ensure your Linux environment exposes /dev/fuse and run the test suite with appropriate permissions.

Docker-Based Integration Tests

The file src/exec/runner.fuse.test.ts contains integration tests that require Docker. These tests launch the computerd binary inside privileged containers to validate filesystem isolation. Without Docker installed and running, Vitest skips these suites automatically.

Summary

• Build first: Always run npm run build before npm test because the test suite imports compiled dist/ artifacts from sibling packages.
• Workspace commands: Use npm test for the full suite or npm test --workspace=@cloudflare/<package> for isolated package testing.
• Documentation: Reference COLLABORATORS.md for official contributor workflows and individual package READMEs for specific requirements.
• Platform support: FUSE tests require Linux/Docker for full coverage, but gracefully degrade to shims in restricted environments.

Frequently Asked Questions

Do I need to build the project before every test run?

You only need to rebuild when source files change in a package that another package depends upon. Since the test files import from dist/ directories rather than source files directly, stale builds cause module resolution errors. Run npm run build whenever you modify shared interfaces or cross-package APIs.

Can I run tests without Docker installed?

Yes. While packages/computerd includes Docker-dependent tests in src/exec/runner.fuse.test.ts, Vitest automatically skips these when Docker is unavailable. The majority of the unit test suite runs without containerization.

Why does npm test fail with "Cannot find module" errors?

This occurs when you attempt to run tests before building the workspace. The monorepo architecture requires compiled JavaScript in dist/ folders because tests reference sibling packages via their built outputs, not their TypeScript sources. Execute npm run build from the repository root to resolve these errors.

How do I run tests for just the dofs package?

Use the workspace-specific test command: npm test --workspace=@cloudflare/dofs. This executes only the Vitest suites within the dofs package, reducing feedback time during development. You can further narrow the scope by appending a specific test file path after the double-dash separator.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}