# How to Test PrimeIntellect-ai/prime-agent: Complete Guide to Running Unit, Integration, and Sharded Tests

> Learn how to test PrimeIntellect-ai/prime-agent with our comprehensive guide. Discover steps for unit, integration, and sharded tests. Get started today!

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: how-to-guide
- Published: 2026-08-16

---

**Run `npm test` from the repository root after installing Node ≥22.8.0, system libraries, and building all workspaces with `npm run build`.**

PrimeIntellect's **prime-agent** is a TypeScript monorepo containing four independent packages—`ai`, `agent`, `tui`, and `coding-agent`—each with its own test suite. Understanding how to test prime-agent locally ensures you can validate changes before contributing or deploying. This guide walks through the exact commands, configuration files, and CI-matching workflows used in the repository.

## Prerequisites for Testing Prime Agent

Before running any tests, ensure your environment matches the requirements defined in the source code.

### Node.js Version

The repository requires **Node ≥22.8.0**. Verify with:

```bash
node --version

```

### System Libraries for TUI Package

The `tui` package depends on native image and text rendering libraries. On Ubuntu, install:

```bash
sudo apt-get update && sudo apt-get install -y \
  libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev \
  fd-find ripgrep

```

Create a symlink for `fd` accessibility:

```bash
sudo ln -s $(which fdfind) /usr/local/bin/fd

```

## Installing Dependencies and Building

The prime-agent repository uses npm workspaces with a shared lockfile. Always install from the root:

```bash
git clone https://github.com/PrimeIntellect-ai/prime-agent
cd prime-agent
npm ci

```

Compile all four packages:

```bash
npm run build

```

The root [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json) delegates this build command to each workspace via `packages/*/npm run build`.

## Running the Full Test Suite

To execute all tests exactly as the CI does, run:

```bash
npm test

```

This command triggers `npm run test --workspaces --if-present` defined at [package.json#L22](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json#L22), which sequentially runs each package's individual test script.

## Testing Individual Prime Agent Packages

Each package maintains isolated test configuration. Navigate to the specific package directory for focused testing.

### AI Package Tests

The `ai` package uses **Vitest** with a single test command:

```bash
cd packages/ai
npm test

```

This executes `vitest --run` as specified in [packages/ai/package.json#L71](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/package.json#L71).

Run a specific test file:

```bash
cd packages/ai
vitest run test/stream.test.ts

```

The `ai` package includes a **faux provider** mechanism in [`packages/ai/test/faux-provider.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/test/faux-provider.test.ts) to mock LLM responses without real API calls.

### Coding-Agent Package Tests

The `coding-agent` package offers the most testing options. Basic execution:

```bash
cd packages/coding-agent
npm test

```

Specialized scripts defined in [packages/coding-agent/package.json#L40-L48](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/package.json#L40-L48) include:

| Script | Purpose |
|--------|---------|
| `npm run test:ci` | Optimized for CI execution |
| `npm run test:process` | Daemon-supervisor startup smoke test |
| `npm run test:kernel` | Kernel-specific validation |

### TUI Package Tests

The `tui` package also uses Vitest:

```bash
cd packages/tui
npm test

```

Configuration lives in [`packages/tui/vitest.config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/vitest.config.ts).

## Running Sharded Tests (CI-Exact Workflow)

The prime-agent CI splits the `coding-agent` test suite across three parallel runners. Replicate this locally for large-scale validation:

```bash
cd packages/coding-agent

# First shard

npm run test:ci -- --shard=1/3

# Second shard

npm run test:ci -- --shard=2/3

# Third shard

npm run test:ci -- --shard=3/3

```

This sharding strategy appears in [.github/workflows/ci.yml#L75-L99](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/.github/workflows/ci.yml#L75-L99).

## Complete Testing Workflow Example

```bash

# Clone and setup

git clone https://github.com/PrimeIntellect-ai/prime-agent
cd prime-agent
npm ci

# Install TUI system dependencies (Ubuntu)

sudo apt-get update && sudo apt-get install -y \
  libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev \
  fd-find ripgrep
sudo ln -s $(which fdfind) /usr/local/bin/fd

# Build all packages

npm run build

# Run complete test matrix

npm test

```

## Key Configuration Files for Prime Agent Testing

| File | Role | Location |
|------|------|----------|
| Root [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json) | Orchestrates workspace test execution | [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json) |
| AI package tests | Vitest runner configuration | [`packages/ai/package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/package.json) |
| Coding-agent CI scripts | Sharding and specialized test targets | [`packages/coding-agent/package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/package.json) |
| TUI Vitest config | UI-specific test settings | [`packages/tui/vitest.config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/vitest.config.ts) |
| CI workflow | GitHub Actions test matrix | [`.github/workflows/ci.yml`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/.github/workflows/ci.yml) |

## Summary

- **Prime-agent testing** requires Node ≥22.8.0, native system libraries, and workspace-aware npm commands
- **`npm test`** from root runs all packages; **`cd packages/<name> && npm test`** runs individually
- **Vitest** powers all test suites with per-package [`vitest.config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/vitest.config.ts) files
- **Sharding** via `--shard=N/3` replicates the CI parallelization strategy for `coding-agent`
- **Faux providers** in `packages/ai/test/` enable safe, API-free test execution

## Frequently Asked Questions

### What test framework does prime-agent use?

Prime-agent uses **Vitest**, a Jest-compatible test runner. Each package configures Vitest through its own [`vitest.config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/vitest.config.ts) file, with test commands defined in individual [`package.json`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/package.json) files. The `ai`, `tui`, and `coding-agent` packages all specify `vitest --run` as their default test command.

### Can I run tests without installing system libraries?

You can run tests for the `ai` and `agent` packages without TUI libraries, since they don't depend on Cairo, Pango, or image rendering. However, the full `npm test` command will fail when reaching the `tui` package. Install the system dependencies to execute the complete test matrix.

### How do I debug a single failing test in prime-agent?

Navigate to the specific package and use Vitest's file filter: `cd packages/<package> && vitest run test/specific-file.test.ts`. For watch mode during debugging, remove `--run` to use `vitest test/specific-file.test.ts` and enable automatic re-runs on file changes.

### Are prime-agent tests safe to run without API keys?

Yes. The `ai` package implements a **faux provider** pattern in tests like [`packages/ai/test/faux-provider.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/ai/test/faux-provider.test.ts) that mocks LLM responses. This design ensures all tests execute without external API calls, making them safe for CI environments and local development without credentials.