Testing Harness & Strategies

Relevant source files

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

• src/test-support/run-cli.ts
• src/test-support/command-path-mocks.ts
• src/cli.test.ts
• src/command-paths.test.ts
• src/internal/output.test.ts
• src/internal/state.test.ts
• CLAUDE.md

The testing harness for putio-cli is designed to provide comprehensive coverage of the CLI's command surface, internal logic, and output formatting. The project prioritizes in-process tests over external process boundaries, using a modular architecture built on the Effect framework to facilitate dependency injection and mocking.

The strategy encompasses unit tests for internal services, integration tests for command execution paths, and specialized mock environments to simulate API interactions and filesystem states. This ensures that the CLI remains deterministic and safe for both human users and automated agents.

Sources: CLAUDE.md:46-48, src/cli.test.ts:39-66

Test Infrastructure & Environment

The test environment leverages vite-plus as the test runner and utilizes specialized utility functions to isolate CLI execution from the host system. This is achieved by overriding configuration paths and mocking global objects like console.

CLI Execution Wrapper

The core of the integration testing is the runProcessArgv (or runCli) function. This wrapper creates a temporary directory for configuration, mocks stdout and stderr to capture output, and provides a custom ConfigProvider and AppLayer to the CLI runtime.

The diagram shows the lifecycle of a single CLI execution test, emphasizing the isolation of filesystem and output.

Sources: src/cli.test.ts:39-85, src/test-support/run-cli.ts

Mocking Registry

To test complex command paths without hitting the live put.io API, the project maintains a centralized mock registry in command-path-mocks.ts. This file defines fakeSdk, which replicates the structure of the @putdotio/sdk.

Mock Component	Description
fakeSdk	A deep mock of the put.io SDK including files, transfers, account, and auth modules.
writeOutputMock	Captures data sent to the user/terminal to verify rendering logic.
savePersistedStateMock	Simulates saving tokens and profiles to the local config file.
waitForDeviceTokenMock	Simulates the polling behavior during the OAuth device login flow.

Sources: src/test-support/command-path-mocks.ts:77-164, src/command-paths.test.ts:16-150

Testing Strategies

Command Path Coverage

Command path tests verify that flag parsing, input validation, and SDK calls are correctly wired. These tests use runCliInTest to execute full commands against the mocked SDK.

• Success Paths: Verifies that correct flags result in specific SDK method calls (e.g., putio files list --per-page 5 calls sdk.files.list with the correct arguments).
• Validation Failures: Ensures that invalid input (like non-integer IDs) is caught before API calls are made.
• Dry Runs: Validates that the --dry-run flag correctly prevents side effects while still calculating the intended request payload.

Sources: src/command-paths.test.ts:220-250, src/command-paths.test.ts:546-560, src/cli.test.ts:251-285

Output & Sanitization Verification

A significant portion of the test suite is dedicated to ensuring that sensitive information (like auth_token) is never leaked to the terminal or JSON logs.

The diagram illustrates how the sanitization service intercepts data before rendering.

Tests in src/internal/output.test.ts verify:

1. Redaction: Sensitive keys like password, token, and auth_token are replaced with [REDACTED].
2. Control Characters: Terminal escape sequences are stripped from terminal output but escaped in JSON.
3. Agent Safety: Metadata (_meta.agentSafety) is added to JSON output when untrusted API content is detected.

Sources: src/internal/output.test.ts:15-45, src/internal/output.test.ts:75-95

State & Profile Management

Tests for src/internal/state.ts focus on the persistence layer. They verify how the CLI handles the config.json file across different scenarios:

• Filesystem Permissions: Ensuring config files are created with 0o600 (private) permissions.
• Profile Isolation: Testing that operations on a specific profile (via --profile or PUTIO_CLI_PROFILE) do not affect other profiles or the legacy global token.
• Migration & Cleanup: Verifying that logout correctly clears tokens while optionally preserving custom api_base_url settings.

Sources: src/internal/state.test.ts:74-95, src/internal/state.test.ts:250-285

Key Utility Functions for Testing

Function	Source File	Purpose
runCli	src/cli.test.ts	High-level wrapper for executing the CLI binary in a unit test context.
resetCommandPathMocks	src/test-support/command-path-mocks.ts	Resets all SDK and service mocks to a clean state between tests.
parseJsonOutput	src/cli.test.ts	Utility to deserialize captured stdout strings for assertion.
withTerminalLoaderMock	src/test-support/command-path-mocks.ts	Mocks the UI spinner/loader to avoid interference with output capture.

Sources: src/cli.test.ts:31-35, src/test-support/command-path-mocks.ts:222-230

Conclusion

The testing harness of putio-cli leverages the modularity of the Effect framework to create a reliable and isolated environment for verifying CLI behavior. By combining deep SDK mocking with strict output sanitization checks and filesystem isolation, the harness ensures that the CLI behaves predictably across various platforms and authentication states, maintaining a high bar for both security and developer experience.