Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The testing strategy for PlanQueue focuses on ensuring the reliability of the prompt queue logic and its integration with the Oh My Pi (OMP) harness. The project utilizes a multi-layered verification approach that includes static analysis, type checking, and automated unit/integration testing powered by the Bun runtime.
The core philosophy dictates that all "pure logic" (logic independent of the OMP host) must reside in specific modules and be accompanied by corresponding tests. This separation ensures that the critical path of note parsing, path resolution, and queue management can be verified in isolation from the complex UI and agent interaction layers.
Sources: CONTRIBUTING.md:15-18, README.md:162-167
Verification Layers
The project defines a "full gate" of verification that must pass before any pull request is opened or code is merged. This gate consists of three primary stages:
| Stage | Command | Description |
|---|---|---|
| Linting | bun run lint | Enforces code style and catches common errors using Biome. |
| Type Checking | bun run typecheck | Validates TypeScript strict mode compliance via tsc. |
| Testing | bun test | Executes unit and integration tests using the Bun test runner. |
Sources: CONTRIBUTING.md:10-12, package.json:34-37
Static Analysis and Formatting
PlanQueue uses Biome for both linting and formatting. The configuration enforces recommended rules, such as prohibiting the use of any, requiring parameter assignments to be immutable, and enforcing double quotes for JavaScript/TypeScript files.
Sources: biome.json:1-36, CONTRIBUTING.md:19-20
Type Safety
The project runs TypeScript in strict mode. This is enforced during the typecheck stage to ensure the codebase remains type-clean. The configuration target is ESNext and utilizes the bundler module resolution strategy.
Sources: tsconfig.json:1-15, CONTRIBUTING.md:14-14
Testing Architecture
The testing architecture distinguishes between pure logic and OMP-specific wiring. Pure logic is tested in isolation to facilitate fast feedback loops.
The diagram shows the relationship between the Bun runtime tools and the different testing layers.
Sources: CONTRIBUTING.md:15-18, tests/core-integration.test.ts:1-26
Core Integration Testing
Integration tests verify the "package surface" of the @aryrabelo/planqueue-core dependency. These tests ensure that critical utilities like path resolution, task parsing, and widget rendering work correctly together.
Key areas covered by integration tests include:
- Path Resolution: Verifying that note paths are correctly generated based on repository, branch, and session ID.
- Legacy Support: Ensuring that legacy note paths (e.g.,
.free-text/) are still correctly identified for backward compatibility. - Parsing Logic: Validating that raw Markdown task lines are correctly parsed into pending or in-flight states.
- Widget Rendering: Confirming that the UI representation of the queue contains the expected content.
This sequence illustrates the verification of core utilities during an integration test.
Sources: tests/core-integration.test.ts:9-26, src/main.ts:14-41
Continuous Integration (CI)
Automated verification is performed on every push and pull request via GitHub Actions. The CI environment replicates the local "full gate" to ensure that no regressions are introduced into the main branch.
CI Workflow Components:
- Runtime: Bun
- Triggers: Push, Pull Request
- Gates: Linting, Type Checking, Testing
Sources: README.md:3-3, CONTRIBUTING.md:12-12
Summary
PlanQueue's testing strategy relies on the high-performance Bun runtime to execute a comprehensive suite of static and dynamic checks. By strictly separating pure logic from host-specific wiring and enforcing a mandatory verification gate, the project maintains high technical standards and ensures compatibility across repository migrations and legacy storage structures.