# Testing — browser-automation-cli
> Run the right suite for the risk, not every browser path by default.
## Why Categorized Tests
- Browser runtime tests are slower and host-dependent
- Schema and inventory tests catch contract drift without Chrome
- Keeping categories explicit protects local iteration speed
- Local validation replaces any claim of hosted GitHub Actions CI
## Test Categories
- Unit and library tests in `src/` (`cargo test --lib`)
- CLI smoke tests such as `tests/doctor_cli.rs` and `tests/goto_smoke.rs`
- Envelope and schema gates such as `tests/envelope_schema.rs` and `tests/parity_toolref_schema.rs`
- Parity inventory and matrix tests (`tests/parity_inventory.rs`, `tests/parity_matrix.rs`)
- Robots and pipe behaviour tests (`tests/robots_http.rs`, `tests/pipe_broken.rs`)
- Golden i18n and cold-start helpers (`tests/golden_i18n.rs`, `tests/cold_start.rs`)
- Optional e2e CDP event coverage when Chrome is available (`tests/e2e_cdp_events.rs`)
- Full 52-tool e2e script: `scripts/e2e_all_52_tools.sh`
- Vendored tool-ref fixture: `tests/fixtures/tool-reference.md`
## How to Run
```bash
timeout 300 cargo test --locked
timeout 300 cargo test --lib --locked
timeout 120 cargo clippy --all-targets --locked -- -D warnings
cargo fmt --check
```
- Run a single file with `cargo test --test doctor_cli --locked`
- Use `-- --nocapture` only while debugging
- Prefer library and schema gates first when iterating on contracts
## E2E 52 Tools
```bash
cargo build --release --locked
bash scripts/e2e_all_52_tools.sh
```
- Requires a release binary at `target/release/browser-automation-cli` (or set `BIN`)
- Exercises DevTools-parity tools against the local fixture page under `scripts/fixtures/e2e_page/`
- Writes a report under a temp workdir and prints PASS/FAIL/SKIP counts
- Maintainer evidence for v0.1.1: 52 PASS / 0 FAIL on a local host with Chrome
## Lighthouse Mock
```bash
browser-automation-cli --json lighthouse https://example.com \
--lighthouse-path ./scripts/mock-lighthouse.sh
```
- Use `--lighthouse-path` to point at `scripts/mock-lighthouse.sh` when a real Lighthouse install is unavailable
- The mock writes minimal HTML/JSON reports for smoke paths
- Doctor reports lighthouse presence as informational when the binary is missing
## Local Validation Profiles
- Run fmt, clippy, and non-browser contract tests first on your machine
- Browser-backed tests require Chrome or Chromium installed locally
- Validation runs locally with cargo on the maintainer machine
- There is no hosted GitHub Actions workflow matrix in this repository
- Keep crates.io publish blocked without explicit maintainer approval
- Optional pillar smokes after e2e: `run` + scrape, `config path`, `mitm start`, doctor XDG
## Documentation Schema and Bilingual Audit
```bash
cargo build --release --locked
bash scripts/generate_command_schemas.sh
bash scripts/generate_command_schemas.sh --check
bash scripts/audit_bilingual_docs.sh
```
- `generate_command_schemas.sh` writes one `docs/schemas/<cmd>.schema.json` per inventory command from live `schema --cmd` (meta.rs surface)
- `--check` fails when static command schemas drift from the installed binary
- Envelopes and `run-script-step.schema.json` are preserved and not overwritten by the generator
- `audit_bilingual_docs.sh` compares `browser-automation-cli` invocations inside code fences for EN and `.pt-BR` pairs
- Exit `0` means fence multisets match; exit `1` means drift; exit `2` means a missing pair file
## Environment Variables
- `RUST_LOG` for deeper tracing during failing tests
- `NO_COLOR` to disable ANSI color on human stderr paths
- `BIN` overrides the e2e script binary path (`scripts/e2e_all_52_tools.sh` only)
- There is no product `BROWSER_AUTOMATION_CLI_DEBUG` (or other product env) setting
- Host-specific Chrome path overrides only when discovery needs a host PATH change
## Troubleshooting
- Doctor fails on chrome: install Chromium or Google Chrome first
- Timeouts in goto smoke: raise process timeout or inspect network policy
- Schema gate failures: update both code and `docs/schemas/` in the same change
- Command schema drift: re-run `bash scripts/generate_command_schemas.sh` after changing `meta.rs`
- Bilingual fence drift: re-run `bash scripts/audit_bilingual_docs.sh` and align EN and `.pt-BR` command blocks
- Inventory drift: refresh against `commands --json` and `tests/fixtures/tool-reference.md`
- E2E script missing binary: build release first or export `BIN=/path/to/browser-automation-cli`
- Lighthouse path missing: pass `--lighthouse-path ./scripts/mock-lighthouse.sh`
- MITM bind issues: ensure local loopback is free and review `mitm status --json`
- Workflow journal confusion: inspect `workflow status` and XDG `workflow_dir` from `config path --json`