How to Run Freebuff Tests: Complete Guide to the Bun-Based Suite

Run bun test from the repository root to execute the entire TypeScript monorepo test suite, or cd into specific packages to run targeted tests with automatic environment fixture loading.

Freebuff is a TypeScript monorepo managed by Bun that uses a sophisticated test environment to ensure code reliability. Knowing how to run freebuff tests correctly requires understanding the workspace structure, the Bun test runner configuration, and the environment fixtures that prevent validation errors. This guide explains the exact commands, configuration files, and advanced scripts used in the CodebuffAI/freebuff repository.

Quick Start Commands for Running Freebuff Tests

Execute the Entire Test Suite

To run every test across all workspace packages, use Bun's built-in workspace test runner from the repository root.

# From the repository root

bun test

This command discovers all packages defined in the root package.json workspaces and executes their respective test suites in parallel.

# Example output

$ bun test

# → 5 292 tests across 73 files

Run Tests for a Single Package

For targeted testing during development, navigate to a specific package directory and run the test command.

# Example: Run only the CLI package tests

cd cli
bun test

The same approach works for any workspace including common, sdk, or agents. Each package automatically loads the shared environment configuration through its local bunfig.toml file.

Test Environment Configuration and Setup

Environment Fixture in sdk/test/setup-env.ts

The file sdk/test/setup-env.ts provides placeholder values for all required NEXT_PUBLIC_* environment variables, preventing import-time validation errors during test execution. This fixture ensures that tests run without requiring real API credentials or production environment variables.

Source: https://github.com/CodebuffAI/freebuff/blob/main/sdk/test/setup-env.ts

Bunfig.toml Preloading

Each package contains a bunfig.toml file that configures the Bun test runner to preload sdk/test/setup-env.ts before executing any test file. This automatic preloading eliminates the need to manually export environment variables or create local .env files for testing.

Source: https://github.com/CodebuffAI/freebuff/tree/main/cli (contains example bunfig.toml)

CI Guard and Advanced Testing Workflows

The CI Guard Script (scripts/ci/test-with-guard.ts)

The continuous integration pipeline does not invoke bun test directly. Instead, it uses scripts/ci/test-with-guard.ts, a wrapper that enforces test baseline requirements and aborts on unhandled import-time errors that Bun might otherwise swallow.

To run the exact CI verification locally:

bun run scripts/ci/test-with-guard.ts

This script verifies that the number of executed tests meets the baseline recorded in .github/test-baselines.json and fails the build if any "outside-test" errors occur.

Source: https://github.com/CodebuffAI/freebuff/blob/main/.github/workflows/ci.yml

Interactive E2E Testing with Tmux

For end-to-end testing of the terminal UI, Freebuff provides a tmux-based harness. This requires tmux to be installed on your system.

# Install tmux (macOS example)

brew install tmux

# Run the proof-of-concept E2E suite

bun run test:tmux-poc

The test script launches a headless tmux session, feeds input to the CLI using bracketed-paste mode, and captures output for verification. Captured sessions can be inspected using the viewer at scripts/tmux/tmux-viewer/index.tsx.

Documentation: https://github.com/CodebuffAI/freebuff/blob/main/cli/README.md

Key Files for Understanding Freebuff Tests

Understanding the following source files is essential for debugging and extending the test suite:

• package.json (root): Defines the workspace structure and Bun scripts. https://github.com/CodebuffAI/freebuff/blob/main/package.json
• docs/testing.md: Contains the complete testing philosophy, environment setup details, and CI guard behavior. https://github.com/CodebuffAI/freebuff/blob/main/docs/testing.md
• sdk/test/setup-env.ts: The environment fixture that injects placeholder values for all required environment variables. https://github.com/CodebuffAI/freebuff/blob/main/sdk/test/setup-env.ts
• scripts/ci/test-with-guard.ts: The CI wrapper script that ensures no hidden failures slip through. https://github.com/CodebuffAI/freebuff/blob/main/scripts/ci/test-with-guard.ts
• cli/README.md: Provides specific instructions for running the CLI test suite and tmux-based E2E tests. https://github.com/CodebuffAI/freebuff/blob/main/cli/README.md

Summary

• Run bun test from the repository root to execute all tests across the monorepo using Bun's workspace mode.
• Use cd <package> && bun test to run targeted tests for specific packages like cli or sdk.
• The sdk/test/setup-env.ts fixture automatically provides placeholder environment variables via bunfig.toml preloading.
• For CI-equivalent verification locally, use bun run scripts/ci/test-with-guard.ts to catch unhandled errors and verify test baselines.
• Install tmux and run bun run test:tmux-poc to execute interactive end-to-end tests of the terminal interface.

Frequently Asked Questions

Why do I get environment variable errors when running tests?

If you see import-time validation errors for NEXT_PUBLIC_* variables, the sdk/test/setup-env.ts fixture is not being preloaded. Ensure you are running bun test from within a package directory or the repository root, and verify that the local bunfig.toml contains the preload configuration. Do not try to export real credentials; the test fixture provides harmless placeholders automatically.

How does the CI guard script differ from running bun test directly?

The scripts/ci/test-with-guard.ts wrapper adds two critical safety checks missing from the standard bun test command. It aborts the process on any unhandled error that occurs outside of test blocks, and it verifies that the total number of executed tests meets the baseline stored in .github/test-baselines.json, preventing silent test skipping.

Can I run the interactive tmux tests on Linux?

Yes, the tmux-based E2E tests work on any platform that supports tmux. Install tmux using your distribution's package manager (e.g., apt-get install tmux for Debian/Ubuntu), then execute bun run test:tmux-poc from the CLI package directory. The test harness uses bracketed-paste mode to ensure reliable input feeding regardless of the host operating system.

Where is the test baseline configuration stored?

The CI system maintains test count baselines in .github/test-baselines.json. When you run scripts/ci/test-with-guard.ts, the script compares the current test execution count against this file to ensure no tests are accidentally skipped or removed. Update this file intentionally when adding or removing test suites.

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