How to Run Tests for PrimeAgent: Complete Guide to Vitest Workspaces

Run all PrimeAgent tests with npm run test from the repository root, or target specific packages with npx vitest run and individual test paths.

PrimeAgent is a monorepo containing multiple independent packages (ai, agent, coding-agent, tui, and others), each with its own Vitest test suite. Understanding how to run tests for PrimeAgent requires familiarity with npm workspaces and the repository's top-level orchestration commands.

PrimeAgent Test Architecture

PrimeAgent uses Vitest as its test runner across all packages. Each package ships with its own vitest.config.ts that configures the Node environment, timeouts, and other test-specific settings.

The AI package configuration at packages/ai/vitest.config.ts demonstrates this pattern—defining environment targets and discovery rules for test files. This modular approach lets teams customize testing behavior per domain without affecting other packages.

The top-level package.json defines the workspace-aware entry point:

{
  "scripts": {
    "test": "npm run test --workspaces --if-present"
  }
}

This command iterates through all packages/* directories and executes each package's local test script when present.

Running All Tests

Execute the full repository test suite from the repository root:

npm run test

Npm will discover every workspace with a test script and run them sequentially. Failures are isolated per package, making debugging straightforward.

This design keeps CI pipelines simple—the GitHub Actions workflow relies solely on this single command to validate all changes.

Running Tests for a Specific Package

Navigate to an individual package directory and invoke its local test script:

cd packages/ai
npm run test

This respects the package's vitest.config.ts, applying any custom settings for that domain.

Running Specific Test Files Directly

Target individual test files with Vitest's CLI for faster feedback:

# Run a specific provider test

npx vitest run packages/ai/test/google-thinking-signature.test.ts

# Run all tests matching a pattern

npx vitest run packages/ai/test/*.test.ts

The google-thinking-signature.test.ts file validates Google provider authentication, tool-call signatures, and response parsing for the recursive language model implementation.

Watch Mode for Development

Enable file-watching during active development:

npx vitest --watch

Tests re-run automatically when source or test files change, supporting rapid iteration on the TUI rendering pipeline, daemon communication, or provider integrations.

Key Test Files and Configuration

Path	Purpose
package.json	Root workspace configuration with orchestrated test script
packages/ai/vitest.config.ts	AI package Vitest configuration (Node environment)
packages/ai/test/google-thinking-signature.test.ts	Provider-specific authentication and streaming tests
packages/ai/src/env-api-keys.ts	Credential detection logic under test
packages/ai/src/stream.ts	Streaming behavior validation
packages/tui/vitest.config.ts	TUI package with browser-smoke configurations
packages/agent/test/agent.test.ts	Core agent session and daemon communication tests

Summary

• Root command: npm run test executes all workspace tests
• Package command: cd packages/<name> && npm run test runs single-package tests
• Direct execution: npx vitest run <path> targets specific files
• Development: npx vitest --watch enables automatic re-runs
• Configuration: Each package maintains independent vitest.config.ts settings

Frequently Asked Questions

What test runner does PrimeAgent use?

PrimeAgent uses Vitest exclusively. Every package in the monorepo includes its own vitest.config.ts file that configures the Node environment and test discovery patterns.

Can I run tests without npm workspaces?

Yes. Use npx vitest run directly with any test file path or directory pattern. This bypasses the workspace orchestration and executes Vitest against the specified targets immediately.

Where are test files located in PrimeAgent?

Test files live alongside source code within each package—typically in packages/<name>/test/ directories. For example, AI provider tests reside at packages/ai/test/ with files like google-thinking-signature.test.ts covering authentication, streaming in packages/ai/src/stream.ts, and token limit handling.

How does PrimeAgent handle test configuration per package?

Each package defines its own vitest.config.ts. The AI package configures Node environment settings and timeouts, while the TUI package includes browser-smoke checks. This isolation lets packages evolve testing strategies independently without cross-package dependencies.

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