# CI Smoke Gates Runbook

- Scope: BAT-006 / REQ-006 pytest, Streamlit AppTest, dashboard HTTP smoke, and DB safety smoke gates.
- Safety rule: every command below creates or uses a synthetic fixture/temporary validation DB only. Do not set `JARCA_LEDGER_DB_PATH` to the operating ledger DB for CI reproduction.

## GitHub Actions gates

The workflow is `.github/workflows/ci.yml` and runs on:

- `pull_request`
- `push` to `main`
- `workflow_dispatch`

Stable job/check names:

- `pytest-regression`
- `dashboard-app-test`
- `dashboard-http-smoke`
- `db-safety-smoke`

## Local reproduction

From repository root:

```bash
source .venv/bin/activate
pytest --ignore=tests/test_dashboard_app.py
pytest tests/test_dashboard_app.py
python scripts/ci_dashboard_http_smoke.py --host 127.0.0.1 --port 18501 --timeout 45
python scripts/ci_db_safety_smoke.py --timeout 45
```

With uv, equivalent CI-style commands are:

```bash
uv sync --extra dev --extra dashboard
uv run pytest --ignore=tests/test_dashboard_app.py
uv run pytest tests/test_dashboard_app.py
uv run python scripts/ci_dashboard_http_smoke.py --host 127.0.0.1 --port 18501 --timeout 45
uv run python scripts/ci_db_safety_smoke.py --timeout 45
```

## Wrapper responsibilities

- `scripts/ci_fixture_db.py`
  - Creates a deterministic synthetic fixture DB named `fixture.sqlite3`, `ci-ledger-fixture.sqlite3`, or `ledger-fixture.sqlite3`.
  - Refuses the default operating DB path.
  - Seeds only synthetic accounts, categories, budgets, and transactions.
- `scripts/ci_dashboard_http_smoke.py`
  - Creates a temp synthetic fixture DB.
  - Starts Streamlit with `JARCA_LEDGER_DB_PATH` pointed at that fixture.
  - Polls a loopback URL until HTTP 200 or timeout.
  - Terminates/kills the Streamlit process during cleanup.
  - Emits status-only JSON.
- `scripts/ci_db_safety_smoke.py`
  - Creates a temp synthetic fixture DB and backup copy.
  - Runs `scripts/ledger_restore_smoke.py` against temp source/backup/target paths only.
  - Emits status-only JSON and never requires restore approval because the target is newly created under temp space.

## Browser evidence boundary

Browser screenshot/DOM evidence remains local evidence from `scripts/streamlit_browser_evidence.py`. It is not a required GitHub Actions gate. Use it in addition to the CI gates when a change materially affects visual layout or browser-only behavior.

## Failure triage

- `pytest-regression` failure: reproduce with `pytest --ignore=tests/test_dashboard_app.py` and fix the failing unit/service/parser test.
- `dashboard-app-test` failure: reproduce with `pytest tests/test_dashboard_app.py`; inspect Streamlit AppTest exceptions first.
- `dashboard-http-smoke` failure: check whether port 18501 is already in use locally, then rerun with a different port if needed. In CI the job uses a fresh runner.
- `db-safety-smoke` failure: inspect the wrapper JSON fields `restore_smoke_exit_code`, `restored_integrity`, and `health_success`. Do not retry against the operating DB.