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

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:

node --version

System Libraries for TUI Package

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

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:

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:

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

Compile all four packages:

npm run build

The root 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:

npm test

This command triggers npm run test --workspaces --if-present defined at 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:

cd packages/ai
npm test

This executes vitest --run as specified in packages/ai/package.json#L71.

Run a specific test file:

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 to mock LLM responses without real API calls.

Coding-Agent Package Tests

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

cd packages/coding-agent
npm test

Specialized scripts defined in 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:

cd packages/tui
npm test

Configuration lives in 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:

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.

Complete Testing Workflow Example

# 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	Orchestrates workspace test execution	package.json
AI package tests	Vitest runner configuration	packages/ai/package.json
Coding-agent CI scripts	Sharding and specialized test targets	packages/coding-agent/package.json
TUI Vitest config	UI-specific test settings	packages/tui/vitest.config.ts
CI workflow	GitHub Actions test matrix	.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 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 file, with test commands defined in individual 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 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.

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