jarca-ledger-mcp/docs/runbooks/ci-smoke.md

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:

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:

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.