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

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 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 files. Here are the standard patterns:

Run All Tests (Repository Root)

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

bunx --bun vitest run

The root 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:

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

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

cd web && bunx --bun vitest run

Each package defines its own Vitest scripts. In packages/agent/package.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:

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

Watch Mode

Start Vitest in watch mode for continuous testing during development:

bunx --bun vitest

Or explicitly:

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	Documents the --bun requirement for test execution
packages/agent/package.json	Defines test:vitest and test:vitest:watch scripts
packages/sdk/package.json	Contains SDK-specific test configuration
web/package.json	Configures web UI test execution
.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

# 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 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 at line 46: bunx --bun vitest run. This ensures your CI environment matches local development and production runtime behavior.

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