How to Run Tests for the pi-web Project Using Node.js Native Test Runner

The pi-web repository uses Node.js's built-in test runner via node --test to execute tests written in ECMAScript modules, requiring only Node ≥22.19.0 and no external testing frameworks like Jest.

The pi-web project leverages modern Node.js testing capabilities to verify its components, hooks, and library modules. According to the source code in package.json, the test suite runs using the native Node test runner with experimental TypeScript support. This guide explains how to run tests for the pi-web project using the exact configuration defined in the repository.

Prerequisites and Environment Setup

Before executing tests, ensure your environment meets the minimum requirements defined in the repository. The project requires Node.js version 22.19.0 or higher to support the experimental flags used in the test command.

Install the exact dependency versions specified in the lockfile:

npm ci

This command guarantees a reproducible environment by installing the precise versions recorded in package-lock.json.

Running the Complete Test Suite

To run tests for the pi-web project, execute the predefined script in package.json. The test command automatically discovers and executes all *.test.mjs files across the main source directories.

Run the full test suite with:

npm test

This command executes node --experimental-strip-types --test followed by glob patterns targeting test files in app/**/*.test.mjs, components/**/*.test.mjs, hooks/**/*.test.mjs, lib/**/*.test.mjs, and public/**/*.test.mjs.

Understanding the Test Command Configuration

The test configuration in package.json uses specific Node.js flags to enable modern JavaScript testing without transpilation steps.

Key flags explained:

• --experimental-strip-types: Removes TypeScript type-only imports at runtime, allowing the test runner to load files containing import type … statements without errors.
• --test: Activates Node.js's native test runner, which automatically handles describe, it, and expect-style assertions using the native test API.
• Glob patterns: The command explicitly lists "app/**/*.test.mjs" "components/**/*.test.mjs" "hooks/**/*.test.mjs" "lib/**/*.test.mjs" "public/**/*.test.mjs" to ensure comprehensive coverage across all modules.

Running Specific Tests or Individual Files

For development workflows, you may need to run tests for the pi-web project selectively rather than executing the entire suite.

Filter tests by directory:

npm run test -- lib/**/*.test.mjs

This limits execution to only the library tests located in the lib/ directory.

Run a single test file:

node --experimental-strip-types --test lib/rpc-manager.test.mjs

Enable watch mode (Node.js > 22):

node --experimental-strip-types --test --watch lib/**/*.test.mjs

Watch mode reruns tests automatically whenever source files change, providing immediate feedback during development.

Key Test Files and Structure

The pi-web project organizes tests alongside source code using the .test.mjs extension. Understanding the location of key test files helps when targeting specific functionality.

Core test files referenced in the source:

• lib/rpc-manager.test.mjs: Verifies the RPC manager's lifecycle and communication protocols.
• components/MessageView.test.mjs: Tests UI-level rendering for assistant and tool messages.
• hooks/useAgentSession.test.mjs: Validates the hook driving the chat UI's SSE connection and session handling.

The lib/ directory contains the bulk of the test suite, while app/, components/, hooks/, and public/ directories contain domain-specific tests. Most tests import source directly, so a build step is optional for testing purposes, though you can run npm run build beforehand if verifying the production build is necessary.

Summary

• pi-web uses Node.js's native test runner (node --test) rather than external frameworks like Jest or Mocha.
• The test command requires Node.js ≥22.19.0 and uses --experimental-strip-types to handle TypeScript syntax.
• Run the full suite with npm test, which executes all *.test.mjs files in app/, components/, hooks/, lib/, and public/ directories.
• Execute specific tests by passing glob patterns or individual file paths to the Node test runner.
• Key test files include lib/rpc-manager.test.mjs, components/MessageView.test.mjs, and hooks/useAgentSession.test.mjs.

Frequently Asked Questions

Does pi-web require Jest or another testing framework?

No, pi-web does not require Jest or any external testing framework. According to the repository's package.json, tests run using Node.js's built-in test runner via the node --test flag. The project uses modern ECMAScript modules (.mjs) and native assertion APIs, eliminating dependencies on third-party testing libraries.

What Node.js version is required to run pi-web tests?

The project requires Node.js version 22.19.0 or higher. This version requirement ensures compatibility with the --experimental-strip-types flag used to handle TypeScript type imports during test execution without additional transpilation tools.

How do I run only the library tests in pi-web?

To run only the library tests, pass the specific glob pattern to the test command: npm run test -- lib/**/*.test.mjs. Alternatively, use the Node command directly: node --experimental-strip-types --test lib/**/*.test.mjs. This targets only files ending in .test.mjs within the lib/ directory.

Do I need to build the project before running tests?

No, building is optional for test execution. Most tests in pi-web import source files directly, so the test runner can execute them without a prior build step. However, if you want to verify that the production build works correctly alongside tests, you can run npm run build before executing npm test.

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