# How to Run Unit Tests for t3code: A Complete Guide

> Learn to run unit tests for t3code with our complete guide. Install dependencies and execute tests using Bun and Vitest for seamless monorepo testing.

- Repository: [Ping.gg/t3code](https://github.com/pingdotgg/t3code)
- Tags: how-to-guide
- Published: 2026-04-18

---

**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`](https://github.com/pingdotgg/t3code/blob/main/package.json) under the `"packageManager"` field.

Install all workspace dependencies from the repository root:

```bash
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:

```bash
bun run test

```

The `test` script in the root [`package.json`](https://github.com/pingdotgg/t3code/blob/main/package.json) translates to `turbo run test`. Turbo scans the workspace and executes the `test` script defined in each package's [`package.json`](https://github.com/pingdotgg/t3code/blob/main/package.json) in parallel, respecting dependency order.

Under the hood, each package invokes **Vitest** via its local [`vitest.config.ts`](https://github.com/pingdotgg/t3code/blob/main/vitest.config.ts). The shared configuration at the repository root ([`vitest.config.ts`](https://github.com/pingdotgg/t3code/blob/main/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:

```bash
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`:

```bash

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

```bash
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`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/git/Layers/GitManager.test.ts) – Complex integration tests for Git operations
- [`packages/shared/src/git.test.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/shared/src/git.test.ts) – Unit tests for shared Git utilities
- [`apps/web/src/threadSelectionStore.test.ts`](https://github.com/pingdotgg/t3code/blob/main/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`](https://github.com/pingdotgg/t3code/blob/main/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`](https://github.com/pingdotgg/t3code/blob/main/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`](https://github.com/pingdotgg/t3code/blob/main/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.