65 lines
4.1 KiB
Markdown
65 lines
4.1 KiB
Markdown
# BAT-006 Design
|
|
|
|
## Architecture Summary
|
|
|
|
BAT-006 introduces a CI safety layer around existing test and smoke assets. GitHub Actions becomes the external gate for PR/push validation, while CI wrapper scripts provide deterministic entrypoints for environment setup, synthetic fixture DB creation, Streamlit readiness checks, DB safety smoke invocation, timeout handling, cleanup, and sensitive-output control.
|
|
|
|
The required CI gates are pytest, Streamlit AppTest, dashboard HTTP smoke, and DB safety smoke. Browser screenshot E2E remains a local evidence workflow from dcy-004 and is intentionally excluded from the required CI blocker set.
|
|
|
|
## Changed Areas
|
|
|
|
- `.github/workflows/`
|
|
- New workflow for `pull_request`, `push` to `main`, and `workflow_dispatch`.
|
|
- Required jobs should have stable names so branch protection can reference them later.
|
|
- `scripts/`
|
|
- New or adapted CI wrapper entrypoint for dashboard HTTP smoke.
|
|
- New or adapted CI wrapper entrypoint for DB safety smoke using existing `ledger_restore_smoke.py` logic where appropriate.
|
|
- Wrapper logs must avoid dumping raw transactions, account numbers, `raw_payload`, source file names, passwords, or live DB paths.
|
|
- `tests/`
|
|
- Existing pytest and Streamlit AppTest assets are reused. Add fixture helpers only if needed to make CI deterministic.
|
|
- `pyproject.toml` / dependency setup
|
|
- Confirm CI installs the extras required for pytest and dashboard/AppTest execution.
|
|
- Docs
|
|
- `docs/project-structure.md`: CI workflow and wrapper responsibilities.
|
|
- `docs/runtime-flows.md`: PR/push -> CI jobs -> gate result flow and synthetic fixture DB boundary.
|
|
- `docs/runbooks/`: CI failure reproduction runbook if the workflow/wrapper commands need operator guidance.
|
|
|
|
## Key Decisions
|
|
|
|
1. CI platform is GitHub Actions, with `pull_request`, `push` to `main`, and optional `workflow_dispatch`.
|
|
2. Required blocker gates are pytest, Streamlit AppTest, dashboard HTTP smoke, and DB safety smoke.
|
|
3. HTTP smoke and DB safety smoke use CI-specific thin wrappers rather than ad-hoc shell snippets, so exit codes, logs, readiness, timeout, and cleanup are deterministic.
|
|
4. Every CI run creates or uses synthetic fixture/temporary validation DBs. The operating DB default path is not used.
|
|
5. Browser screenshot E2E is not a required CI gate. It remains a local/manual evidence path for UI-heavy changes.
|
|
6. Branch protection enforcement is external GitHub repository configuration; the batch stabilizes workflow/check names and documents the required-check expectation.
|
|
|
|
## CI Job Boundary
|
|
|
|
- `pytest` gate:
|
|
- Install project with test dependencies.
|
|
- Run the repository pytest suite using the standard project command.
|
|
- Fail the workflow on any test failure.
|
|
- `dashboard-app-test` gate:
|
|
- Prepare synthetic fixture DB.
|
|
- Run Streamlit AppTest coverage, especially `tests/test_dashboard_app.py`.
|
|
- Fail with test-level logs only.
|
|
- `dashboard-http-smoke` gate:
|
|
- Prepare synthetic fixture DB in runner temp space.
|
|
- Start Streamlit dashboard with that DB and deterministic port policy.
|
|
- Poll HTTP readiness until 200 or timeout.
|
|
- Terminate the server and fail if cleanup fails materially.
|
|
- `db-safety-smoke` gate:
|
|
- Prepare source/backup/target paths under runner temp space.
|
|
- Invoke DB restore/safety smoke without live DB paths.
|
|
- Fail if overwrite approval policy, integrity check, or fixture health check fails.
|
|
|
|
## Sensitive Evidence Boundary
|
|
|
|
CI output may include command names, job names, synthetic DB temp paths, test identifiers, exit status, row counts for synthetic fixtures, and high-level error messages. CI output must not include live account numbers, real balances, `raw_payload`, original financial file names, passwords, or full transaction row dumps.
|
|
|
|
## Reference Doc Update Plan
|
|
|
|
- Update `docs/project-structure.md` to replace the current "CI workflow ... not yet defined" baseline with the BAT-006 workflow and wrapper structure.
|
|
- Update `docs/runtime-flows.md` with the CI validation flow and the local browser evidence boundary.
|
|
- Add a `docs/runbooks/ci-smoke.md` or equivalent only if local reproduction commands are not already obvious from the workflow/wrappers.
|