# How to Run Tests for the pi-web Project Using Node.js Native Test Runner > Learn how to run tests for the pi-web project using Node.js native test runner. Execute tests with `node --test` on Node ≥22.19.0 without external frameworks. - Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web) - Tags: how-to-guide - Published: 2026-08-09 --- **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`](https://github.com/agegr/pi-web/blob/main/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: ```bash npm ci ``` This command guarantees a reproducible environment by installing the precise versions recorded in [`package-lock.json`](https://github.com/agegr/pi-web/blob/main/package-lock.json). ## Running the Complete Test Suite To run tests for the pi-web project, execute the predefined script in [`package.json`](https://github.com/agegr/pi-web/blob/main/package.json). The test command automatically discovers and executes all `*.test.mjs` files across the main source directories. Run the full test suite with: ```bash 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`](https://github.com/agegr/pi-web/blob/main/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:** ```bash npm run test -- lib/**/*.test.mjs ``` This limits execution to only the library tests located in the `lib/` directory. **Run a single test file:** ```bash node --experimental-strip-types --test lib/rpc-manager.test.mjs ``` **Enable watch mode (Node.js > 22):** ```bash 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`](https://github.com/agegr/pi-web/blob/main/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`.