Testing Strategy

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• CONTRIBUTING.md
• packages/cli/tests/update.test.ts
• packages/cli/tests/terminal-title.test.ts
• packages/cli/tests/self-update/check.test.ts
• workers/kdco-registry/files/skill/code-review/SKILL.md
• workers/kdco-registry/files/skill/plan-review/SKILL.md
• workers/kdco-registry/files/plugin/workspace-plugin.ts

The OCX project employs a multi-layered testing strategy designed to ensure the reliability of its CLI tool, registry components, and internal logic. This strategy integrates automated unit and integration tests with systematic manual and AI-driven verification protocols. The primary goal is to maintain high code quality across the monorepo while facilitating a "copy-and-own" component model.

Sources: AGENTS.md:13-35, CONTRIBUTING.md:73-81

Automated Testing Framework

The project utilizes Bun as its primary runtime and test runner. Tests are written in TypeScript and located within tests/ directories across the different packages.

Test Execution Commands

Scope	Command	Description
Root	bun run test	Runs all tests across the monorepo using Turbo.
CLI Package	bun test	Runs tests specific to the @ocx/cli package.
Specific File	bun test packages/cli/tests/add.test.ts	Executes a single test file.
Pattern Matching	bun test --grep "pattern"	Runs tests with titles matching the regex.
Watch Mode	bun test --watch	Re-runs tests automatically on file changes.

Sources: AGENTS.md:16-35, CONTRIBUTING.md:144-146

Testing Infrastructure and Helpers

Automated tests for the CLI often involve complex setup, such as creating temporary directories and mocking registries to simulate real-world scenarios.

The diagram shows the lifecycle of a CLI integration test, from environment preparation to final cleanup.

Sources: packages/cli/tests/update.test.ts:31-50

Testing Modalities

1. Integration Testing (CLI)

Integration tests verify the end-to-end functionality of CLI commands like update, add, and init. These tests ensure that the CLI interacts correctly with the local filesystem and remote (or mocked) registries.

• Registry Mocking: Tests use a MockRegistry to simulate network responses and file content changes without requiring actual internet access.
• Verification: Success is verified by checking exit codes, terminal output, and the state of .opencode/ocx.lock or opencode.jsonc files.

Sources: packages/cli/tests/update.test.ts:58-90, CONTRIBUTING.md:165-185

2. Unit Testing

Unit tests focus on individual utility functions and logic blocks, such as terminal title formatting or version comparison.

• Terminal Utilities: Tests for formatTerminalName ensure correct string construction for different profiles and git branches, including truncation logic.
• Self-Update Logic: Tests for the update checker use spyOn for global.fetch to simulate network failures, timeouts, and successful version retrieval from npm.

Sources: packages/cli/tests/terminal-title.test.ts:98-140, packages/cli/tests/self-update/check.test.ts:34-75

3. Profile Mode Testing (Manual & AI)

For manual or AI-driven verification, the project recommends "Profile Mode" using a dedicated ocx-dev profile. This provides an isolated environment that does not interfere with the developer's global configuration.

Sources: CONTRIBUTING.md:83-95

Review Protocols

The testing strategy is augmented by systematic review skills that AI agents must load to verify work before completion.

Code Review Methodology

Code is reviewed across four distinct layers to ensure correctness, security, performance, and style.

Layer	Focus Areas
Correctness	Logic errors, edge cases, type safety, and null checks.
Security	Secret detection, input validation, and injection prevention.
Performance	N+1 queries, caching, and algorithmic complexity.
Style	Adherence to project conventions (The 5 Laws) and DRY principles.

Sources: workers/kdco-registry/files/skill/code-review/SKILL.md:14-41

Plan Review

Implementation plans are reviewed against structural and quality standards before any code is written. This includes verifying specific goals, citation quality (linking decisions to research via ref:id), and actionability of tasks.

Sources: workers/kdco-registry/files/skill/plan-review/SKILL.md:14-55

Workspace Integration

The WorkspacePlugin automates parts of the testing and review workflow within the OpenCode environment. It tracks active tasks and triggers reminders to delegate code reviews when implementation is finished.

The sequence diagram illustrates how the WorkspacePlugin monitors implementation progress and enforces the review protocol.

Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:553-585

Summary

The OCX testing strategy combines robust automated suites with strict human-in-the-loop and AI-driven review protocols. By leveraging Bun's testing capabilities, isolated profile environments, and systematic review layers, the project ensures that both the CLI infrastructure and the reusable components remain stable and secure.