# How to Run Magnitude's Test Suite with Vitest and the --bun Flag

> Learn to run magnitudedev/magnitude's test suite with Vitest and the --bun flag. Execute tests faster using Bun runtime for improved performance and access to Bun globals.

- Repository: [Magnitude/magnitude](https://github.com/magnitudedev/magnitude)
- Tags: how-to-guide
- Published: 2026-09-08

---

**Use `bunx --bun vitest run` from any package directory or the repository root to execute tests under the Bun runtime, ensuring Vitest has access to Bun-specific globals like `Bun.file` and `Bun.env`.**

Magnitude uses **Vitest** as its test runner, but the suite must execute under the **Bun** runtime rather than Node.js. This requirement exists because the codebase relies on Bun-specific built-ins that are unavailable in standard Node environments, making the `--bun` flag essential when you run the test suite with vitest and the `--bun` flag in magnitudedev/magnitude.

## Why the --bun Flag is Required

Running plain `vitest` or even `bun vitest` launches Vitest workers under **Node.js**, which lacks access to Bun's native APIs. According to the project documentation in [`AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/AGENTS.md) (lines 56-60), you must use `bunx --bun vitest` to force Vitest to run inside the Bun runtime. This ensures tests can access `Bun.file`, `Bun.env`, and other Bun-specific globals that the Magnitude source code depends on.

## Running Tests in Individual Packages

Each package in the `packages/` directory defines its own test scripts in [`package.json`](https://github.com/magnitudedev/magnitude/blob/main/package.json). For example, in [`packages/agent/package.json`](https://github.com/magnitudedev/magnitude/blob/main/packages/agent/package.json) (lines 9-12), you'll find the `test:vitest` and `test:vitest:watch` scripts.

### Single Run Execution

Navigate to a specific package directory and run the tests once:

```bash
cd packages/agent
bunx --bun vitest run

```

This command executes the test suite for that package and exits upon completion.

### Watch Mode for Development

For continuous feedback during development, use watch mode:

```bash
cd packages/agent
bunx --bun vitest

```

This monitors file changes and re-runs affected tests automatically, providing rapid iteration during coding sessions.

## Running Tests Across the Monorepo

To execute the complete test suite for all packages simultaneously, run from the repository root. The project uses a workspace configuration defined in [`vitest.workspace.ts`](https://github.com/magnitudedev/magnitude/blob/main/vitest.workspace.ts) (lines 1-14), which enumerates all testable packages.

```bash
bunx --bun vitest run

```

When executed from the root, Vitest automatically discovers the [`vitest.workspace.ts`](https://github.com/magnitudedev/magnitude/blob/main/vitest.workspace.ts) file and runs tests across all configured packages, ensuring comprehensive coverage of the entire codebase.

## Targeting Specific Test Files

You can also run individual test files directly from the repository root without changing directories:

```bash
bunx --bun vitest run packages/agent/tests/observer-window-prompt.vitest.ts

```

This approach is useful when debugging specific failures or working on isolated features.

## Summary

- **Always use `bunx --bun`**: Prevents Vitest from falling back to Node.js and losing access to Bun globals.
- **Package-level testing**: Run `bunx --bun vitest run` inside any `packages/` subdirectory for focused feedback.
- **Monorepo-wide testing**: Execute the same command from the root to leverage [`vitest.workspace.ts`](https://github.com/magnitudedev/magnitude/blob/main/vitest.workspace.ts) and test all packages.
- **File-specific execution**: Pass the relative path to a test file to run a subset of the suite.
- **Source locations**: Scripts are defined in [`packages/agent/package.json`](https://github.com/magnitudedev/magnitude/blob/main/packages/agent/package.json), workspace config lives in [`vitest.workspace.ts`](https://github.com/magnitudedev/magnitude/blob/main/vitest.workspace.ts), and runtime requirements are documented in [`AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/AGENTS.md).

## Frequently Asked Questions

### What happens if I run vitest without the --bun flag?

Without the `--bun` flag, Vitest spawns workers under Node.js rather than Bun. This causes test failures because the Magnitude codebase relies on Bun-specific globals like `Bun.file` and `Bun.env` that do not exist in Node.js environments. As documented in [`AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/AGENTS.md), the `--bun` flag is mandatory for correct test execution.

### Where are the test scripts defined?

Package-level test commands are defined in each package's [`package.json`](https://github.com/magnitudedev/magnitude/blob/main/package.json). For example, [`packages/agent/package.json`](https://github.com/magnitudedev/magnitude/blob/main/packages/agent/package.json) (lines 9-12) contains the `test:vitest` and `test:vitest:watch` scripts. These scripts use the `bunx --bun vitest` pattern to ensure proper runtime execution.

### How do I run tests for a specific package?

Navigate to the package directory (e.g., `cd packages/agent`) and execute `bunx --bun vitest run`. This runs only the tests within that package's scope, providing faster feedback than running the entire monorepo suite.

### Can I use npm or pnpm instead of bunx?

No. The Magnitude test suite fundamentally requires the Bun runtime to provide `Bun.file` and other Bun-specific APIs. While you could theoretically use npm or pnpm to install dependencies, you must use `bunx --bun` to execute Vitest and maintain access to the Bun environment that the code expects.