# Testing and troubleshooting

Run checks for the subsystem you changed. A syntax check, import, unit test, benchmark, live provider call, native build, and proof check establish different things.

## Research routing

From the repository root, with the environment from [Getting started](GETTING_STARTED.md):

```bash
cd research/sparse-routing
python -m pytest tests/ -q
cd ../..
python scripts/benchmark_sparse_routing.py --trials 10 --output docs/benchmarks/sparse-routing-local.json
```

The runner records versions, source commit, warmups, trials, timings, and traced allocations. The historical artifact lacks some machine metadata; do not interpret a different machine's timings as a code speedup.

## Documentation examples

The Python examples in Routing, Tools, Continuity, Security, and Machine runtime are standalone files run from the repository root. Tool registration additionally needs `jsonschema`. Check [the validation record](VALIDATION.md) for actual executions.

## Other check surfaces

| Surface | Command or location | Scope |
|---|---|---|
| Engine VM stress script | `python tests/stress_test_no_drift.py` | Deterministic operations; read assertions first |
| Trace endpoint examples | [test_routing_trace_endpoints.py](../tests/test_routing_trace_endpoints.py) | Requires inspection of server assumptions |
| Live routing demonstration | [live_routing_test.py](../tests/live_routing_test.py) | Can use a mock fallback |
| Bash router | `bash src/routing/sparse-latency-routing/tests/run_tests.sh` | Separate reference implementation |
| Cobalt | `cabal build`, `cabal test` inside `cobalt/` | Haskell package and its declared suites |
| Desktop | `npm run verify` inside `ide/desktop/` | TypeScript/build and Jest, after `npm ci` |
| Native IDE | [IDE guide](IDE.md) | Windows CMake project |
| Formal sources | [research/formal/](../research/formal/) | Requires individual proof-project dependencies |

These are check entry points, not a claim that all currently pass.

## Troubleshooting

| Symptom | Check |
|---|---|
| `No module named sparse_routing` | Run research tests from `research/sparse-routing`; use the root wrapper for repeated benchmarks |
| Missing `numpy`, `scipy`, `pytest`, or `hypothesis` | Install the research requirements with the selected environment's `python -m pip` |
| Missing `aiohttp` | Provider/bridge modules use it; it is absent from the root requirements list |
| “object dict can't be used in await” / awaitable error | Expert callbacks must be async; see Routing |
| Unexpected `context` argument or missing continuity task method | Known engine integration mismatch; see deployment readiness |
| Bedrock credential/model error | Confirm the backend's configured region/model and your account access; no live call is part of the offline benchmark |
| Ollama connection or model error | Confirm the service URL and a locally installed model; inspect direct provider health/list methods |
| Bridge ignores `--port` | Its module entrypoint does not parse CLI flags |
| Native CMake failure on another OS | The IDE's CMake project explicitly requires Windows |
| Desktop Vite input not found | Check that the declared `desktop/index.html` renderer exists in your checkout |

Record failures without replacing them with simulated success output. Keep test data and benchmark artifacts separate from credentials and trained model weights.