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

> Learn how to run Freebuff tests in this comprehensive guide. Execute the full suite with bun test or target specific packages for efficient testing.

- Repository: [Codebuff/freebuff](https://github.com/CodebuffAI/freebuff)
- Tags: how-to-guide
- Published: 2026-08-22

---

**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.

```bash

# From the repository root

bun test

```

This command discovers all packages defined in the root [`package.json`](https://github.com/CodebuffAI/freebuff/blob/main/package.json) workspaces and executes their respective test suites in parallel.

```bash

# 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.

```bash

# 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`](https://github.com/CodebuffAI/freebuff/blob/main/bunfig.toml) file.

## Test Environment Configuration and Setup

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

The file [`sdk/test/setup-env.ts`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/bunfig.toml) file that configures the Bun test runner to preload [`sdk/test/setup-env.ts`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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:

```bash
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`](https://github.com/CodebuffAI/freebuff/blob/main/.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.

```bash

# 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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/package.json)** (root): Defines the workspace structure and Bun scripts. https://github.com/CodebuffAI/freebuff/blob/main/package.json
- **[`docs/testing.md`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/sdk/test/setup-env.ts) fixture automatically provides placeholder environment variables via [`bunfig.toml`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/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`](https://github.com/CodebuffAI/freebuff/blob/main/.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`](https://github.com/CodebuffAI/freebuff/blob/main/.github/test-baselines.json). When you run [`scripts/ci/test-with-guard.ts`](https://github.com/CodebuffAI/freebuff/blob/main/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.