Quality

# Testing and Quality Guide

The suite is based on `unittest` and covers sync/async execution, retries/timeouts, live startup retries, session metadata persistence, migration, locking, and observability hooks.

## Run Unit Tests

    python3 -m unittest discover -s tests -p "test_*.py"

Key files:

- `tests/test_codex_local_sdk.py`
- `tests/test_client_sync_extended.py`
- `tests/test_client_live_extended.py`
- `tests/test_models_and_sessions_extended.py`
- `tests/test_async_retry_and_session_store.py`
- `tests/test_v2_hardening.py`

## Coverage Focus

Area | Scenarios | Outcome
--- | --- | ---
Retry engine | Exit-code retries, jitter behavior, max retry window cutoff. | Backoff behavior is deterministic and bounded.
Timeout support | Timeout result generation, retry-on-timeout enabled/disabled. | Timeout path is explicit and policy-driven.
Live startup retries | Launch exception retry, immediate-exit retry, no retry post-handle return. | Startup resilience without post-stream side effects.
Session metadata | Record updates, bounded history truncation, named-session continuation. | Persistent records remain compact and useful.
Migration + locking | Legacy file auto-migration, concurrent writer safety checks. | JSON store remains valid and forward-compatible.
Telemetry hooks | Attempt/retry/live/session events, hook exception swallowing. | Observability is rich and non-disruptive.

## Real CLI Integration Tests

Integration tests run real `codex exec` commands and are intentionally gated.

    export CODEX_INTEGRATION=1
    export CODEX_API_KEY=your_key_here  # optional if local Codex auth session is already valid
    python3 -m unittest discover -s tests/integration -p "test_*.py"

Integration test module:

- `tests/integration/test_codex_cli_integration.py`

## CI Guidance

- `.github/workflows/unit.yml`: runs full unit suite on push and pull request.
- `.github/workflows/integration.yml`: manual `workflow_dispatch` run, secret-gated by `CODEX_API_KEY`.
- Keep unit tests hermetic (mock CLI interactions).
- Run integration tests only in controlled environments with secure credentials.
- Document every new public API with tests covering success and failure paths.