diff --git a/docs/DEVELOPER.md b/docs/DEVELOPER.md
index 05122ab..8846f4f 100644
--- a/docs/DEVELOPER.md
+++ b/docs/DEVELOPER.md
@@ -158,8 +158,12 @@ All `DataToolsError` subclasses extend stdlib `ValueError` or `OSError` so exist
 ## Tests
 
 ```bash
-# All
+# All (core + CLI + GUI)
 pytest -q
+# Quick loop — skip the GUI layer
+pytest -q -m 'not gui'
+# Only the GUI tests
+pytest -q -m gui
 # By module
 pytest tests/test_dedup.py
 # Include slow / integration
@@ -171,16 +175,42 @@ pytest tests/test_dedup.py::TestExactMatch::test_basic
 Test layout:
 ```
 tests/
-├── conftest.py                        # fixtures
+├── conftest.py                        # core/CLI fixtures
 ├── test_dedup.py · test_normalizers.py · test_io.py · test_config.py
 ├── test_analyze.py · test_normalize.py · test_text_clean.py
 ├── test_format_standardize.py
 ├── test_format_standardize_corpus.py  # 199-row buyer corpus
 ├── test_audit_fixes.py · test_errors.py · test_fixes_unit.py
 ├── test_corpus.py · test_encodings_corpus.py · test_fixtures_sweep.py
-└── test_cli.py · test_cli_*.py · test_e2e.py · test_install.py
+├── test_cli.py · test_cli_*.py · test_e2e.py · test_install.py
+├── test_perf_regressions.py           # shape pins for the perf wins
+└── gui/                               # Streamlit AppTest-driven tests
+    ├── conftest.py                    # AppTest fixtures + helpers
+    ├── _findings_panel_harness.py     # isolated component test page
+    ├── test_smoke.py                  # every page renders in EN + ES
+    ├── test_chrome.py                 # language selector, hide_chrome
+    ├── test_gate.py                   # require_normalization_gate
+    ├── test_workflows.py              # happy path per Ready tool
+    ├── test_dedup_review.py           # match-group card interactions
+    ├── test_advanced_panels.py        # config_panel widgets
+    ├── test_errors.py                 # malformed-upload error paths
+    └── test_findings_panel.py         # analyzer findings rendering
 ```
 
+### GUI test layer
+
+GUI tests drive pages with `streamlit.testing.v1.AppTest` —
+in-process, no browser, no display. They pre-populate
+`st.session_state` with stashed-upload bytes (via the
+`stash_upload()` helper in `tests/gui/conftest.py`) and either click
+buttons via `app.button[i].click().run()` or assert on the
+`session_state` after the run.
+
+Marker registered in `pytest.ini`. Default `pytest` runs everything;
+`pytest -m 'not gui'` skips them for a faster core-only loop.
+Coming-Soon stubs are pinned by the smoke tests so a regression
+("import error", "missing widget") shows up immediately.
+
 Fixture corpora: `test-cases/text-cleaner-corpus/` (21 files) · `test-cases/encodings-corpus/` (31 files) · `test-cases/format-cleaner-corpus/` (7 files + spec).
 
 ## Known limitations
diff --git a/docs/REQUIREMENTS.md b/docs/REQUIREMENTS.md
index 2b5c3d0..cd2d786 100644
--- a/docs/REQUIREMENTS.md
+++ b/docs/REQUIREMENTS.md
@@ -174,7 +174,12 @@ and proceeds.
 - **Dev**: pytest, tox.
 
 ## 16. Test coverage
-- 1,777 tests passing, 0 skipped, 0 xfailed (incl. 15 perf-shape regression tests).
+- 1,916 tests passing, 0 skipped, 0 xfailed.
+  - 1,777 core + CLI tests (run with `pytest -m 'not gui'` for a quick loop).
+  - 139 GUI tests under `tests/gui/` driving Streamlit pages via `AppTest`
+    (smoke + EN/ES localization, chrome, gate, workflows, dedup review,
+    advanced panels, error paths, findings panel). Marked `gui`.
+  - Includes 15 perf-shape regression tests.
 - Fixture corpora: text-cleaner (21), encodings (31), reference UTF-8 (9), format-cleaner (199 buyer cases + 20-row international stress fixture), missing-handler (3 use cases + 16 edge cases), column-mapper (3 use cases + 5 edge cases).
 - Run: `python run_tests.py [--tool …] [--fixtures] [--coverage]`.