What Tests Are Included in pi-web? A Complete Guide to the Test Suite

The pi-web codebase ships with approximately 150 automated tests written in Node Test (node:test) that validate everything from RPC session lifecycles to React UI components and secure file access controls.

The agegr/pi-web repository maintains a rigorous test suite ensuring deterministic behavior across its entire stack. These tests use the native Node Test runner and assert module to verify core runtime logic, UI rendering, and security boundaries without relying on external testing frameworks.

Test Framework and Structure

Every test file in the repository uses the .test.mjs extension and follows a consistent pattern. The suite relies on Node Test (node:test) for test definition and Node Assert (node:assert/strict) for verification. This native approach eliminates third-party dependencies while providing robust asynchronous testing capabilities.

Tests typically import the module under test, extract relevant code segments, and verify expected patterns using assert.ok or assert.match:

import assert from "node:assert/strict";
import test from "node:test";

test("RPC session startup resolves and passes the SDK-native enabled model scope", async () => {
  const src = await readFile(new URL("./rpc-manager.ts", import.meta.url), "utf8");
  const startup = src.slice(src.indexOf("export async function startRpcSession"));
  assert.ok(startup.includes("resolveVisibleModels("));
  assert.match(startup, /selectInitialModelScope\(/);
});

Core Runtime and Session Management Tests

The foundation of the test suite covers the RPC layer and session handling. In lib/rpc-manager.test.mjs, tests verify the full session lifecycle including startup flow, model-scope resolution via resolveVisibleModels(), idle-timer handling, graceful shutdown, and forking mechanisms.

Session persistence and metadata handling are validated in lib/session-reader.test.mjs, which ensures proper loading of session files, path resolution, timing metadata extraction, and title handling. The model discovery logic is tested in lib/model-scope.test.mjs, covering catalog fetching, scope validation, and cache invalidation.

Tool preset functionality is split across lib/tool-presets.test.mjs and lib/tool-preset-preference.test.mjs, verifying default tool sets, user-selected presets, and persistence of preference choices.

Provider and Authentication Tests

Authentication flows and credential management are thoroughly validated in lib/provider-listing.test.mjs. These tests cover provider discovery, API-key storage mechanisms, OAuth flow handling, and secure credential resolution to ensure user secrets remain properly isolated.

File System and Security Tests

Security-critical file operations are tested in lib/file-access.test.mjs, which validates allowed-root directory constraints, directory browsing permissions, fuzzy search functionality, upload handling, and path traversal protections. The Git worktree integration is verified in lib/worktree.test.mjs, testing worktree resolution, creation and removal operations, and trust-relationship handling.

Frontend Component and Hook Tests

The React layer includes dedicated tests for both components and hooks. components/MessageView.test.mjs validates the rendering pipeline for user messages, assistant responses, tool results, and markdown body formatting.

State management and side effects are tested in hooks/useAgentSession.test.mjs, which verifies the agent session lifecycle, viewport height handling, model-switching logic, and streaming behavior that drives the chat UI.

API Route Tests

Server-side API functionality is covered in app/api/agent/events-route.test.mjs, testing Server-Sent Events (SSE) streaming endpoints, agent RPC routes, session CRUD operations, and plugin management interfaces. These tests ensure that HTTP boundaries and event streaming protocols function correctly under various network conditions.

Utility and Helper Tests

Low-level utilities maintain their own test coverage across numerous files. lib/ansi.test.mjs validates ANSI parsing logic, while other modules test atomic file writes, bash output handling, terminal UI façade patterns, compaction summaries, lazy loading behavior, and notification systems.

Summary

• pi-web includes approximately 150 test files using the .test.mjs naming convention.
• The suite runs on Node Test (node:test) and Node Assert (node:assert/strict) without external testing dependencies.
• Coverage spans RPC session management (lib/rpc-manager.test.mjs), React components (components/MessageView.test.mjs), API routes (app/api/agent/events-route.test.mjs), and security-critical file access (lib/file-access.test.mjs).
• Tests validate deterministic behavior for model scoping, credential handling, Git worktree operations, and streaming chat interfaces.

Frequently Asked Questions

What testing framework does pi-web use?

The repository uses Node Test (node:test), the native testing framework included in Node.js, paired with the built-in node:assert/strict module for assertions. This eliminates external dependencies like Jest or Mocha while providing comprehensive asynchronous testing capabilities.

How many tests are included in pi-web?

The codebase contains approximately 150 individual test files identified by the **/*.test.mjs glob pattern. This extensive suite covers utility functions, UI components, API routes, and core runtime logic.

Does pi-web include tests for React components?

Yes. The repository includes dedicated tests for React components such as components/MessageView.test.mjs (validating message rendering) and hooks like hooks/useAgentSession.test.mjs (testing session lifecycle and streaming behavior).

Are security features tested in pi-web?

Security-critical functionality is extensively tested, particularly in lib/file-access.test.mjs which validates allowed-root directory constraints, path traversal protections, and upload security. Authentication flows and credential resolution are also verified in lib/provider-listing.test.mjs.

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