70 lines
2.9 KiB
Markdown
70 lines
2.9 KiB
Markdown
# 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.
|