Streamlit Browser Evidence Runbook

목적

Streamlit dashboard 변경을 QC할 때 synthetic DB와 local Chrome으로 browser-level screenshot/snapshot evidence를 수집한다. 운영 DB, 실제 금융 파일, 비밀번호, raw_payload는 사용하지 않는다.

표준 명령

cd /root/projects/jarca-ledger-mcp
.venv/bin/python scripts/streamlit_browser_evidence.py

기본 산출물 위치:

docs/batches/bat-014_20260703_adapter-surface-narrowing-baseline-refresh/evidence/run-YYYYMMDD-HHMMSS/
├── fixture.sqlite3
├── manifest.json
├── overview.png
├── overview.dom.html
├── rules.png
├── rules.dom.html
├── transfer-review.png
├── transfer-review.dom.html
├── import.png
└── import.dom.html

전제 조건

Chrome: /usr/bin/google-chrome-stable
Streamlit: .venv/bin/streamlit
Dashboard dependencies installed in .venv
실행 DB는 script가 생성하는 fixture.sqlite3만 사용

실행 흐름

script가 output directory를 만들고 synthetic fixture DB를 생성한다.
JARCA_LEDGER_DB_PATH=<output>/fixture.sqlite3로 Streamlit을 127.0.0.1:18501에 기동한다.
Chrome DevTools Protocol로 page를 열고 page 제목 텍스트가 렌더링될 때까지 대기한다.
각 page의 PNG screenshot과 DOM snapshot을 저장한다.
manifest.json에 page/url/path/byte size와 fixture DB 정보를 남긴다.
script 종료 시 Streamlit과 Chrome process를 종료한다.

대상 페이지

기본 대상:

요약
분류 규칙
확인필요 큐
Import

추가 page를 지정하려면 --page를 반복한다.

.venv/bin/python scripts/streamlit_browser_evidence.py --page 계좌 --page 미분류

QC evidence gate

Batch 유형	최소 evidence	판정 기준
Streamlit UI 또는 `dashboard/app.py` 영향	Browser screenshot + DOM snapshot + manifest	누락 시 QC BLOCK 또는 재실행
비-UI service/MCP/parser 변경	pytest/py_compile 중심, browser evidence 선택	browser 누락 비차단
docs-only 변경	문서 diff/review	browser evidence 불필요
Chrome 환경 장애가 입증된 UI 변경	AppTest + HTTP 200 + 실패 로그	`PASS_WITH_NOTES`만 허용

민감정보 금지

다음은 screenshot, snapshot, manifest, test log, docs에 남기지 않는다.

운영 DB 기본 경로의 실제 row dump
실제 계좌번호/카드번호/잔액 화면
실제 거래처/상대방 full dump
원본 금융 파일명 또는 파일 내용
비밀번호, PDF/XLSX password
raw_payload 원문

실패 시 fallback

Chrome 또는 browser capture가 실패한 경우:

실패 명령, Chrome 경로, stderr/오류 메시지를 verification 문서에 기록한다.
.venv/bin/python -m py_compile dashboard/app.py를 실행한다.
streamlit.testing.v1.AppTest 또는 HTTP 200 smoke를 실행한다.
UI 영향 batch라면 fallback evidence만으로는 PASS_WITH_NOTES까지만 허용하고 browser evidence 복구 잔여 항목을 남긴다.

주의

이 runbook은 로컬 재현 절차다. CI 통합은 후속 Project #4 항목에서 별도 다룬다.
Playwright Python은 후속 CI 후보이며 현재 표준 경로가 아니다.

3.2 KiB Raw Blame History