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

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 (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. For example, in 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:

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:

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 (lines 1-14), which enumerates all testable packages.

bunx --bun vitest run

When executed from the root, Vitest automatically discovers the 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:

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 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, workspace config lives in vitest.workspace.ts, and runtime requirements are documented in 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, 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. For example, 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.

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