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

> Learn how to run tests for cloudflare/computer monorepo. Build the workspace first to import compiled artifacts and ensure your tests pass smoothly.

- Repository: [Cloudflare/computer](https://github.com/cloudflare/computer)
- Tags: how-to-guide
- Published: 2026-08-09

---

**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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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.

```bash
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.

```bash
npm run build

```

As noted in [`packages/computerd/README.md`](https://github.com/cloudflare/computer/blob/main/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:

```bash
npm test

```

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

```bash
npm test --workspace=@cloudflare/computerd

```

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

```bash
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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/packages/dofs/README.md) and [`packages/rpc/README.md`](https://github.com/cloudflare/computer/blob/main/packages/rpc/README.md) document package-level test commands, while [`packages/computerd/README.md`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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`](https://github.com/cloudflare/computer/blob/main/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.