Testing Strategy & Vitest

Relevant source files

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

• vitest.config.ts
• CLAUDE.md
• tests/client.test.ts
• tests/output.test.ts
• tests/commands/content.test.ts
• tests/commands/tasks.test.ts
• package.json

The testing strategy for the Recoup CLI centers on ensuring the reliability of its command-line interface and its interactions with the Recoup platform API. The project utilizes Vitest as its primary testing framework, leveraging its speed and compatibility with modern ESM modules and TypeScript. The strategy follows a Test-Driven Development (TDD) approach, where tests are prioritized alongside or before implementation to maintain a simple, thin wrapper over REST endpoints.

Tests are categorized into unit tests for core utilities (client, output formatters) and command-specific integration tests that verify the behavior of the Commander.js subcommands. Mocking is heavily employed to isolate the CLI from actual network requests, allowing for deterministic testing of API interaction logic and error handling.

Sources: CLAUDE.md:12-25, package.json:16-25

Test Configuration & Environment

The testing environment is configured via vitest.config.ts and managed through standard npm scripts. The project uses a Node.js environment for testing, reflecting its target deployment as a CLI tool.

Component	Configuration/Tool	Description
Framework	Vitest	Used for execution, assertions, and mocking.
Environment	Node	Configured in vitest.config.ts for server-side logic testing.
Test Command	pnpm test	Executes vitest run to perform a single test pass.
Global Variables	Enabled	globals: true allows usage of describe, it, expect without imports.

Sources: vitest.config.ts:1-7, package.json:17, CLAUDE.md:10

Testing Architecture

The testing architecture relies on mocking external dependencies, specifically the HTTP client and global Node.js objects, to verify that commands correctly parse input and format output.

Mocking Strategy

The project employs several layers of mocking:

1. Global Mocks: Using vi.stubGlobal to mock the fetch API for low-level client tests.
2. Environment Mocks: Using vi.stubEnv to simulate API keys and URLs.
3. Module Mocks: Using vi.mock to replace the internal src/client.js with Vitest mock functions (vi.fn()) when testing command logic.
4. Spying: Using vi.spyOn on console.log, console.error, and process.exit to capture and assert CLI output and lifecycle events.

The following diagram illustrates the flow of a command test utilizing these mocks:

A typical test flow involving command invocation and mock verification.
Sources: tests/client.test.ts:4-10, tests/commands/content.test.ts:3-22, tests/output.test.ts:4-15

Core Module Testing

HTTP Client Testing

The src/client.ts module is tested to ensure it correctly constructs requests, appends query parameters, and handles headers like x-api-key.

• GET Requests: Verified for URL construction and query parameter serialization.
• POST Requests: Verified for JSON body stringification.
• Error Handling: Ensures that non-OK HTTP statuses or API-level error statuses throw descriptive exceptions.

Sources: tests/client.test.ts:21-88

Output Formatting Testing

Output tests verify that the CLI renders data correctly to the terminal in both human-readable and machine-readable (JSON) formats.

• Table Rendering: printTable tests ensure headers and rows are aligned and handles null values gracefully.
• JSON Rendering: printJson tests verify formatted JSON output.
• Error Reporting: printError tests verify that error messages are sent to stderr and the process terminates with exit code 1.

Sources: tests/output.test.ts:18-63

Command Integration Testing

Command tests verify the integration between Commander.js definitions and the HTTP client. Every command file follows a pattern of mocking the API response and asserting the resulting console output.

Pattern: Content Command Testing

The content command tests demonstrate complex validation logic and multi-run handling.

Sequence of interactions during a content creation command test.
Sources: tests/commands/content.test.ts:71-88

Test Coverage Areas

Command Group	Focus Areas
Tasks	Status polling, run retrieval, and Video URL extraction.
Sandboxes	List table formatting, sandbox creation, and JSON flag support.
Content	Template listing, cost estimation, batch creation, and validation error paths.
Songs	Preset management, custom prompts, and audio URL inclusion.

Sources: tests/commands/tasks.test.ts:25-50, tests/commands/sandboxes.test.ts:30-70, tests/commands/songs.test.ts:23-50

Lifecycle Management

To ensure test isolation, the suite uses Vitest lifecycle hooks:

• beforeEach: Resets mocks and clears spies to prevent state leakage between tests.
• afterEach: Restores all mocks and unsubs environment/global variables.

Sources: tests/commands/content.test.ts:16-24, tests/client.test.ts:12-17

Summary

The Recoup CLI testing strategy prioritizes modularity and predictable output. By mocking the network layer and spying on terminal output, the project ensures that the CLI remains a reliable interface for the Recoup platform while maintaining a fast, TypeScript-aware test suite powered by Vitest.