How to Run Unit Tests for t3code: A Complete Guide

To run unit tests for t3code, install dependencies with bun install . and execute bun run test to trigger Turbo-orchestrated Vitest across the monorepo.

The t3code repository uses Vitest as its test runner and Turbo to orchestrate test execution across its monorepo packages. Understanding how to run unit tests for t3code requires familiarity with its Bun-based toolchain and workspace configuration. This guide covers every method to execute tests, from full suite runs to single-file debugging.

Prerequisites and Installation

Before running tests, ensure you have Bun installed. The repository pins version 1.3.11 in the root package.json under the "packageManager" field.

Install all workspace dependencies from the repository root:

bun install .

This command resolves dependencies for all packages under apps/*, packages/*, and scripts/ as defined in the workspace configuration.

Running the Full Test Suite

To execute all unit tests across the monorepo, run:

bun run test

The test script in the root package.json translates to turbo run test. Turbo scans the workspace and executes the test script defined in each package's package.json in parallel, respecting dependency order.

Under the hood, each package invokes Vitest via its local vitest.config.ts. The shared configuration at the repository root (vitest.config.ts) provides common settings and path aliases, including the @t3tools/contracts alias.

Running Specific Tests

When debugging or working on a specific feature, you can filter tests by package or file pattern.

By Package

Use Turbo's --filter flag to run tests for a specific application or package:

bun run test --filter=apps/web      # Web UI tests only

bun run test --filter=apps/server   # Server application tests

bun run test --filter=packages/shared # Shared utilities tests

This ensures only the specified workspace member executes its test suite, significantly reducing execution time.

By File or Pattern

For granular control, invoke Vitest directly using bunx:

# Run a specific test file

bunx vitest ./apps/web/src/threadSelectionStore.test.ts

# Run tests matching a glob pattern

bunx vitest ./apps/web/src/**/*.test.ts

# Run tests in a specific package

bunx vitest ./packages/shared/src/git.test.ts

Bun automatically adds vitest to the $PATH, making bunx vitest function identically to npx vitest but with Bun's execution speed.

Watch Mode and Development Workflow

During active development, use watch mode to automatically re-run affected tests when files change:

bunx vitest --watch

This monitors the entire workspace or current directory, depending on where you execute the command. For watch mode filtered to a specific package, navigate to that package directory first or use the --root flag.

Understanding the Test Architecture

The t3code testing infrastructure relies on several architectural decisions that influence how you run and write tests.

Monorepo Layout

Tests reside alongside source files using the *.test.ts naming convention. Key test locations include:

• apps/server/src/git/Layers/GitManager.test.ts – Complex integration tests for Git operations
• packages/shared/src/git.test.ts – Unit tests for shared Git utilities
• apps/web/src/threadSelectionStore.test.ts – UI layer tests for React store logic

This co-location ensures tests naturally import from the source modules they verify.

Effect-TS Integration

Many tests utilize Effect-TS and the @effect/vitest package, which provides helpers like it.effect and assert. These utilities allow test bodies to return Effect values that Vitest automatically runs, handling asynchronous operations and resource management safely.

For example, tests in packages/shared/src/git.test.ts use Effect.gen to orchestrate complex setup scenarios involving temporary directories and Git repositories.

Summary

• Install dependencies with bun install . from the repository root.
• Run all tests using bun run test, which invokes Turbo to orchestrate Vitest across the monorepo.
• Filter by package with bun run test --filter=apps/web or by file with bunx vitest ./path/to/file.test.ts.
• Use watch mode via bunx vitest --watch for rapid development feedback.
• Understand the stack: Vitest executes tests, Turbo manages the monorepo workflow, and Bun provides the runtime.

Frequently Asked Questions

How do I run tests for a single package in the t3code monorepo?

Use Turbo's filter flag: bun run test --filter=packages/shared. Replace packages/shared with the workspace name defined in that package's package.json. This executes only that package's test suite while still respecting Turbo's caching and dependency graph.

Can I run t3code unit tests without using Turbo?

Yes, invoke Vitest directly with bunx vitest from any directory. For example, bunx vitest ./apps/web/src/threadSelectionStore.test.ts runs a specific test file while bypassing Turbo's orchestration. This is useful for rapid debugging but lacks the monorepo-wide caching benefits.

What testing framework does t3code use?

t3code uses Vitest as the primary test runner, configured via vitest.config.ts at the repository root. Many tests also leverage Effect-TS through the @effect/vitest integration, allowing tests to return Effect values for resource-safe asynchronous operations.

Why does t3code use Bun instead of Node.js for running tests?

The repository pins bun@1.3.11 as its package manager and runtime because Bun offers faster package installation and test execution compared to Node.js. All test scripts are optimized for Bun's runtime, though Vitest itself remains compatible with both environments.

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