<!-- source: https://deepwiki.com/qhkm/zeptoclaw/13.3-testing-strategy -->

# Testing Strategy

- landing/zeptoclaw/og-image.png
- src/cli/uninstall.rs
- src/main.rs
- src/runtime/apple.rs
- src/runtime/docker.rs
- src/runtime/factory.rs
- src/runtime/mod.rs
- src/runtime/native.rs
- src/runtime/types.rs
- src/tools/find.rs
- src/tools/grep.rs
- src/tools/output.rs
- test-coding-pristine/TASK.txt
- test-coding-pristine/buggy_data.py
- test-coding-pristine/verify.py
- test-coding/TASK.txt
- test-coding/buggy_data.py
- test-coding/verify.py
- tests/cli_smoke.rs
- tests/conformance/fixtures/.gitkeep
- tests/conformance/fixtures/edit_tool.json
- tests/conformance/fixtures/find_tool.json
- tests/integration.rs

This page documents ZeptoClaw's testing infrastructure, covering unit tests, integration tests, and end-to-end tests. It describes test patterns, fixtures, mock providers, and the automated CI/CD pipeline that ensures system stability across multiple platforms and architectures.

## Test Architecture

ZeptoClaw uses a three-tier testing strategy with clear separation between unit tests, integration tests, and end-to-end tests. Each tier validates different aspects of the system with varying levels of component integration.

### Test Tier Overview

The following diagram maps the testing levels to their corresponding code entities and scopes.

```

```

**Sources:** [tests/integration.rs1-6](https://github.com/qhkm/zeptoclaw/blob/2c743d31/tests/integration.rs#L1-L6) [tests/cli_smoke.rs1-5](https://github.com/qhkm/zeptoclaw/blob/2c743d31/tests/cli_smoke.rs#L1-L5)

## Test Organization

ZeptoClaw's tests are organized into distinct locations based on their scope and dependency requirements:

**Sources:** [tests/integration.rs1-10](https://github.com/qhkm/zeptoclaw/blob/2c743d31/tests/integration.rs#L1-L10) [tests/cli_smoke.rs1-26](https://github.com/qhkm/zeptoclaw/blob/2c743d31/tests/cli_smoke.rs#L1-L26) [src/tools/output.rs97-100](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/output.rs#L97-L100)

## Integration Testing

Integration tests in `tests/integration.rs` verify multi-component workflows with real (but in-memory) dependencies. These tests validate that components work together correctly without requiring external network access.

### Message Bus Integration

[tests/integration.rs84-150](https://github.com/qhkm/zeptoclaw/blob/2c743d31/tests/integration.rs#L84-L150) validates the pub/sub messaging infrastructure. These tests ensure that messages published to the `MessageBus` can be correctly consumed by agents and routed back to channels.

- test_message_flow : Single publish/consume cycle tests/integration.rs 84-92
- test_message_bus_roundtrip : InboundMessage → OutboundMessage routing tests/integration.rs 94-116
- test_concurrent_message_producers : Multi-channel message publishing safety using Arc<MessageBus> tests/integration.rs 118-150

### Tool Execution Integration

[tests/integration.rs156-203](https://github.com/qhkm/zeptoclaw/blob/2c743d31/tests/integration.rs#L156-L203) validates tool registration, execution, and context handling using the `ToolRegistry` and `ToolContext`.

```

```

**Sources:** [tests/integration.rs156-203](https://github.com/qhkm/zeptoclaw/blob/2c743d31/tests/integration.rs#L156-L203)

## CLI Smoke Testing

The `tests/cli_smoke.rs` suite verifies the compiled `zeptoclaw` binary. It uses the `run_cli` helper function which executes the binary with a dummy `ZEPTOCLAW_MASTER_KEY` to ensure non-interactive behavior [tests/cli_smoke.rs8-26](https://github.com/qhkm/zeptoclaw/blob/2c743d31/tests/cli_smoke.rs#L8-L26)

### Verified Command Groups

- System : version validates semver-like output tests/cli_smoke.rs 49-55
- Configuration : config check validates configuration logic tests/cli_smoke.rs 62-72
- Authentication : auth status validates provider status reporting tests/cli_smoke.rs 86-100
- Management : history list and skills list validate data retrieval tests/cli_smoke.rs 130-160

**Sources:** [tests/cli_smoke.rs1-214](https://github.com/qhkm/zeptoclaw/blob/2c743d31/tests/cli_smoke.rs#L1-L214)

## Runtime and Platform Testing

ZeptoClaw emphasizes platform-specific isolation, which is validated through specialized test runs and runtime factory checks.

### Container Runtime Validation

Each runtime implementation (Docker, Apple, Landlock, etc.) includes an `is_available()` check used during test gating and runtime factory creation [src/runtime/factory.rs16-103](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/factory.rs#L16-L103)

- Apple Container : Validated by checking container --version and container run --help syntax on macOS src/runtime/apple.rs 70-111
- Docker : Validated via docker info src/runtime/docker.rs 102-112
- Native : Fallback runtime that is always available src/runtime/native.rs 30-33

### Tool Output Truncation

To prevent context window exhaustion, the system includes utilities to truncate tool output. These are heavily unit-tested to ensure UTF-8 character boundary safety [src/tools/output.rs138-151](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/output.rs#L138-L151)

**Sources:** [src/runtime/factory.rs16-103](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/factory.rs#L16-L103) [src/runtime/apple.rs70-111](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/apple.rs#L70-L111) [src/tools/output.rs42-95](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/output.rs#L42-L95)

## Conformance and Benchmarks

ZeptoClaw includes specialized fixtures for validating agent behavior and tool correctness.

### Coding Benchmark Fixture

The `test-coding/` directory contains a self-contained coding task used to compare different agents. It includes a `buggy_data.py` file and a `verify.py` script that uses the Python `unittest` framework to check the agent's fixes [test-coding/verify.py1-37](https://github.com/qhkm/zeptoclaw/blob/2c743d31/test-coding/verify.py#L1-L37)

### Tool Conformance

JSON fixtures in `tests/conformance/fixtures/` define expected inputs and outputs for complex tools like `edit_tool` and `find_tool`.

**Sources:** [test-coding/TASK.txt1-11](https://github.com/qhkm/zeptoclaw/blob/2c743d31/test-coding/TASK.txt#L1-L11) [test-coding/verify.py8-33](https://github.com/qhkm/zeptoclaw/blob/2c743d31/test-coding/verify.py#L8-L33)

## Code Entity Mapping

The following diagram bridges the conceptual testing space to the actual code entities within the ZeptoClaw repository.

```

```

**Sources:** [src/main.rs1-16](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/main.rs#L1-L16) [tests/integration.rs84-150](https://github.com/qhkm/zeptoclaw/blob/2c743d31/tests/integration.rs#L84-L150) [src/runtime/mod.rs1-30](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/mod.rs#L1-L30)
