# How to Run Magnitude Tests with `bunx --bun vitest`: Why the `--bun` Flag Is Required

> Learn to run Magnitude tests with bunx --bun vitest. Discover why the --bun flag is crucial for utilizing Bun-specific globals like Bun.spawn and Bun.file.

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

---

**Use `bunx --bun vitest` to run Magnitude's test suite — the `--bun` flag forces Vitest to spawn workers under the Bun runtime instead of Node.js, which is required because Magnitude relies on Bun-specific globals like `Bun.spawn` and `Bun.file`.**

Magnitude is an AI-powered testing framework built on Bun's high-performance JavaScript runtime. Because the codebase uses Bun-native APIs throughout, its Vitest-powered test suite must execute inside a Bun environment. This article explains the exact command structure, why the `--bun` flag is mandatory, and how to run tests at different scopes within the repository.

## Understanding the `bunx --bun vitest` Command

The test command combines two distinct behaviors:

- **`bunx`** — Invokes a package-local binary without global installation, similar to `npx` but Bun-native.
- **`--bun`** — Forces Vitest to launch its worker processes using Bun as the runtime instead of the default Node.js.

Without `--bun`, Vitest spawns workers under Node. This causes immediate failures because Magnitude's source code references `Bun.spawn`, `Bun.file`, and other Bun-specific globals that don't exist in Node.js environments.

As documented in [`AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/AGENTS.md) at line 56:

> "Run tests with `bunx --bun vitest` (not `bun vitest` — without `--bun`, vitest workers run under Node and Bun globals aren't available)."

## Running Tests at Different Scopes

Magnitude uses a monorepo structure with test commands defined in individual [`package.json`](https://github.com/magnitudedev/magnitude/blob/main/package.json) files. Here are the standard patterns:

### Run All Tests (Repository Root)

From the project root, execute the full test suite across all packages:

```bash
bunx --bun vitest run

```

The root [`package.json`](https://github.com/magnitudedev/magnitude/blob/main/package.json) forwards this command to each workspace package, ensuring comprehensive coverage.

### Run Tests for a Single Package

For faster feedback during development, target a specific package:

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

```

```bash
cd packages/sdk && bunx --bun vitest run

```

```bash
cd web && bunx --bun vitest run

```

Each package defines its own Vitest scripts. In [`packages/agent/package.json`](https://github.com/magnitudedev/magnitude/blob/main/packages/agent/package.json):

```json
{
  "scripts": {
    "test:vitest": "bunx --bun vitest run",
    "test:vitest:watch": "bunx --bun vitest"
  }
}

```

The web UI package uses a simpler configuration in [`web/package.json`](https://github.com/magnitudedev/magnitude/blob/main/web/package.json):

```json
{
  "scripts": {
    "test": "bunx --bun vitest run"
  }
}

```

### Watch Mode

Start Vitest in watch mode for continuous testing during development:

```bash
bunx --bun vitest

```

Or explicitly:

```bash
bunx --bun vitest --watch

```

Watch mode monitors file changes and re-runs affected tests automatically.

## Why the `--bun` Flag Is Mandatory

Omitting `--bun` produces immediate runtime failures. The flag is required for three technical reasons inherent to Magnitude's architecture:

**Bun-Native APIs**

The codebase uses `Bun.spawn` for process management and `Bun.file` for optimized file I/O. These APIs are undefined in Node.js, causing reference errors.

**Effect-TS Integration**

Magnitude leverages Effect-TS, a functional programming library that expects Bun's `globalThis` extensions. Node's different global object structure breaks Effect-TS runtime assumptions.

**Environment Consistency**

Using `--bun` guarantees that the test runner and the code under test share identical runtime behavior. This eliminates subtle differences between Bun and Node.js that could mask bugs or produce false positives.

Typical error messages when `--bun` is missing include:
- `Bun is not defined`
- `Bun.spawn is not a function`
- `Bun.file is not a function`

## Key Source Files and CI Configuration

The following files define and enforce the `bunx --bun vitest` pattern:

| File | Purpose |
| --- | --- |
| [`AGENTS.md`](https://github.com/magnitudedev/magnitude/blob/main/AGENTS.md) | Documents the `--bun` requirement for test execution |
| [`packages/agent/package.json`](https://github.com/magnitudedev/magnitude/blob/main/packages/agent/package.json) | Defines `test:vitest` and `test:vitest:watch` scripts |
| [`packages/sdk/package.json`](https://github.com/magnitudedev/magnitude/blob/main/packages/sdk/package.json) | Contains SDK-specific test configuration |
| [`web/package.json`](https://github.com/magnitudedev/magnitude/blob/main/web/package.json) | Configures web UI test execution |
| [`.github/workflows/integrations.yml`](https://github.com/magnitudedev/magnitude/blob/main/.github/workflows/integrations.yml) | CI workflow running `bunx --bun vitest run` at line 46 |

The CI pipeline uses identical commands to ensure test results match local development behavior.

## Complete Command Reference

```bash

# Full repository test suite

bunx --bun vitest run

# Single package tests

cd packages/agent && bunx --bun vitest run
cd packages/sdk && bunx --bun vitest run
cd web && bunx --bun vitest run

# Watch mode (any package)

bunx --bun vitest

# Using package.json scripts

cd packages/agent && bun run test:vitest
cd web && bun run test

```

## Summary

- **Command structure**: `bunx --bun vitest` is the only correct pattern — `bun vitest` without `--bun` fails.
- **Flag purpose**: `--bun` forces Vitest workers to run under Bun, preserving access to `Bun.spawn`, `Bun.file`, and other Bun-native globals.
- **Scope flexibility**: Run tests from repository root (all packages) or individual package directories for targeted feedback.
- **Watch mode**: Omit `run` to enable file watching with automatic test re-execution.
- **CI alignment**: The [`.github/workflows/integrations.yml`](https://github.com/magnitudedev/magnitude/blob/main/.github/workflows/integrations.yml) file uses identical commands, ensuring consistent behavior across environments.

## Frequently Asked Questions

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

Vitest spawns its worker processes under Node.js instead of Bun. Since Magnitude's source code references Bun-specific globals like `Bun.spawn` and `Bun.file`, tests immediately fail with reference errors such as `Bun is not defined`.

### Can I use `npx vitest` instead of `bunx vitest`?

No. `npx` invokes Node.js-based package execution, which bypasses Bun's runtime entirely. Even with `--bun` appended, `npx` does not provide the Bun environment that Vitest's workers require.

### Why does Magnitude depend on Bun-specific APIs instead of cross-platform alternatives?

Magnitude uses `Bun.spawn` for performant process management and `Bun.file` for zero-copy file operations. These APIs provide significant performance advantages over Node.js equivalents. The trade-off is runtime specificity, which the `--bun` flag accommodates.

### How do I run tests in CI pipelines?

Use the exact command from [`.github/workflows/integrations.yml`](https://github.com/magnitudedev/magnitude/blob/main/.github/workflows/integrations.yml) at line 46: `bunx --bun vitest run`. This ensures your CI environment matches local development and production runtime behavior.