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

> Explore the pi-web test suite covering RPC sessions, React UI components, and file access controls. Discover over 150 automated Node Test validations.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: how-to-guide
- Published: 2026-08-09

---

**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`:

```javascript
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`.