Merge pull request #87 from Integration-Automation/dev

Static-analysis cleanup, integration tests, cookbook + WR_sleep + API façade

Author: JE-Chen

README.md

@@ -265,6 +265,76 @@ je_web_runner/
     └── xml/                     # XML utilities
 ```
 
+## Cookbook
+
+The `examples/` directory ships runnable recipes that exercise the new
+helpers against real Chrome / network. Each is invoked from the repo root:
+
+| Example | Demonstrates |
+|---|---|
+| `counting_stars.{py,json}` | `WR_sleep`, `WR_set_driver` with Chrome flags, autoplay-policy override, JS-driven `video.play()`, skip-ad polling. |
+| `google_search.py` | Consent dismissal, search-box typing, ENTER submit, result heading scrape. |
+| `form_submit.py` | `form_autofill.plan_fill_actions` + `state_diff.capture_state` round trip against `httpbin/forms/post`. |
+| `smart_wait_demo.py` | `wait_for_fetch_idle` + `wait_for_spa_route_stable` + `memory_leak.detect_growth` against a real page. |
+| `fanout_demo.py` | `fanout.run_fan_out` parallel HTTP preflights. |
+| `pii_redact_demo.py` | `pii_scanner.scan_text` + `redact_text` + `assert_no_pii` (pure logic). |
+| `quick_smoke.json` | Minimal `WR_set_driver` → `WR_sleep` → `WR_execute_script` → `WR_quit_all` smoke via the executor CLI. |
+
+Run a Python example directly:
+
+```bash
+python examples/google_search.py
+```
+
+Run an action JSON example through the executor:
+
+```bash
+python -m je_web_runner -e examples/quick_smoke.json
+```
+
+## Test Tiers
+
+```
+test/
+├── unit_test/         # 1200 mock-based unit tests (~12s)
+├── integration_test/  #   30 wired-modules tests with real I/O (~6s)
+└── e2e_test/          #    6 real-browser tests; skips without Selenium Grid
+```
+
+- **Unit** (`test/unit_test/test_*.py`) — runs everywhere; pulled in by both
+  `test_dev.yml` and `test_stable.yml`.
+- **Integration** (`test/integration_test/`) — wires 2+ modules together
+  with real SQLite, in-process HTTP servers, and real subprocesses for
+  the MCP / LSP. Same workflows as unit, second step.
+- **E2E** (`test/e2e_test/`) — talks to a Selenium Grid via
+  `WEBRUNNER_E2E_HUB`. Locally: `cd docker && docker compose up -d`.
+  CI: `.github/workflows/e2e_browser.yml` boots `selenium/hub:4.20.0`
+  + `selenium/node-chrome` daily / on demand.
+
+## Thematic API Façade
+
+The 80+ utility helpers live under `je_web_runner.utils.<area>`; for
+discoverability they are also re-exported under `je_web_runner.api`:
+
+```python
+from je_web_runner.api import (
+    authoring,      # action_formatter, md_authoring, templates, sel_to_pw, bootstrap
+    debugging,      # cross_browser, pr_comment, extension_harness
+    frontend,       # device emulation, geo/locale, multi-tab, shadow pierce, …
+    infra,          # driver pin, k8s runner, pipeline, lock, watch_mode, …
+    mobile,         # Appium gestures
+    networking,     # api_mock, contract_testing, GraphQL, mock services, har_replay
+    observability,  # timeline, failure bundle, trace recorder, OTLP, BiDi, cdp_tap
+    quality,        # a11y_diff, a11y_trend, perf budgets/drift, trend, failure cluster
+    reliability,    # adaptive retry, browser pool, smart wait, throttler, supervisor
+    security,       # PII, license, CSP, cookie consent, header tampering
+    test_data,      # DB fixtures, fixture record/replay, form auto-fill
+)
+```
+
+The original Selenium-flavoured top-level surface (`webdriver_wrapper_instance`,
+`execute_action`, `TestObject`, …) is unchanged.
+
 ## Quick Start
 
 ### Direct API
@@ -346,6 +416,20 @@ The executor maps a string command name to a Python callable. Every backend, int
 ]
 ```
 
+### Pacing actions
+
+`WR_sleep` blocks the executor thread for a given number of seconds — useful when the page needs settle time, when a JS animation needs to finish, or when an example wants to hold the browser open for the user to watch:
+
+```python
+[
+    ["WR_to_url", {"url": "https://example.com"}],
+    ["WR_sleep", {"seconds": 2.5}],
+    ["WR_get_screenshot_as_png"],
+]
+```
+
+Negative or non-numeric `seconds` raise `ValueError`. For pacing inside JavaScript (e.g. waiting on a custom event from the page) use `WR_execute_async_script` with a `setTimeout`-driven callback.
+
 ### Top-level shapes
 
 ```python

docs/source/Eng/doc/extended_features/extended_features_doc.rst

@@ -593,3 +593,67 @@ Storybook visual snapshots / Appium gestures / coverage map
 * ``coverage_map.build_coverage_map("./actions")`` — reverse index of
   ``WR_to_url`` paths (numeric / UUID segments collapsed to ``:id``);
   ``coverage.uncovered(declared_routes)`` flags missing routes.
+
+WR_sleep
+========
+
+The executor exposes ``WR_sleep`` so action JSON pipelines can pace
+themselves natively without resorting to ``WR_execute_async_script``
+``setTimeout`` tricks:
+
+.. code-block:: json
+
+   [
+     ["WR_to_url", {"url": "https://example.com"}],
+     ["WR_sleep", {"seconds": 2.5}],
+     ["WR_get_screenshot_as_png"]
+   ]
+
+Negative or non-numeric ``seconds`` raise ``ValueError`` so a typo can't
+silently no-op the pipeline.
+
+Cookbook examples
+=================
+
+The ``examples/`` directory ships runnable recipes that drive real Chrome
+end-to-end. Each found a real bug the unit suite missed:
+
+* ``counting_stars.{py,json}`` — open YouTube and play OneRepublic
+  Counting Stars; revealed the bug where
+  ``webdriver_wrapper.execute_script`` was swallowing return values.
+* ``google_search.py`` — consent dismissal + result heading scrape.
+* ``form_submit.py`` — ``form_autofill.plan_fill_actions`` +
+  ``state_diff.capture_state`` round trip against ``httpbin``.
+* ``smart_wait_demo.py`` — ``wait_for_fetch_idle``,
+  ``wait_for_spa_route_stable``, ``memory_leak.detect_growth``.
+* ``fanout_demo.py`` — parallel HTTP preflights via ``run_fan_out``.
+* ``pii_redact_demo.py`` — pure-logic ``scan_text`` / ``redact_text``.
+
+Test tiers
+==========
+
+* ``test/unit_test/`` — 1200 mock-based unit tests, ~12s.
+* ``test/integration_test/`` — 30 wired-modules tests with real I/O
+  (in-memory SQLite, in-process HTTP servers, real subprocesses for
+  the MCP / LSP). Surfaced the Windows LSP CRLF framing bug.
+* ``test/e2e_test/`` — six real-browser smoke tests; skips cleanly when
+  ``WEBRUNNER_E2E_HUB`` doesn't resolve. Use
+  ``cd docker && docker compose up -d`` locally;
+  ``.github/workflows/e2e_browser.yml`` runs them daily / on demand.
+
+Thematic façade
+===============
+
+The 80+ helpers under ``je_web_runner.utils.<area>`` are also re-exported
+under ``je_web_runner.api`` grouped by theme:
+
+.. code-block:: python
+
+   from je_web_runner.api import (
+       authoring, debugging, frontend, infra, mobile,
+       networking, observability, quality, reliability,
+       security, test_data,
+   )
+
+The original Selenium-flavoured top-level surface stays unchanged so
+existing user code keeps working.

docs/source/Zh/doc/extended_features/extended_features_doc.rst

@@ -421,3 +421,57 @@ Storybook 視覺快照 / Appium gestures / Coverage map
 * ``coverage_map.build_coverage_map`` — 從 action JSON 抽出 ``WR_to_url``
   的 path 建立 route → files 反查表，``coverage.uncovered`` 找出未覆蓋
   的 route
+
+WR_sleep
+========
+
+Executor 內建的同步 sleep 命令，給 action JSON 用：
+
+.. code-block:: json
+
+   [
+     ["WR_to_url", {"url": "https://example.com"}],
+     ["WR_sleep", {"seconds": 2.5}],
+     ["WR_get_screenshot_as_png"]
+   ]
+
+負數 / 非數字會丟 ``ValueError``，typo 不會被默默忽略。
+
+Cookbook 範例
+=============
+
+``examples/`` 提供可直接跑的真實 Chrome 範例，每個都剛好揪出一個既有 bug：
+
+* ``counting_stars.{py,json}`` — 開 YouTube 播 OneRepublic Counting Stars
+  （順帶揪出 ``execute_script`` 吞回傳值的 bug）
+* ``google_search.py`` — 處理 GDPR 同意彈窗、抓首個搜尋結果標題
+* ``form_submit.py`` — ``form_autofill`` + ``state_diff`` 串連 httpbin
+* ``smart_wait_demo.py`` — fetch idle / SPA route stable / memory leak
+* ``fanout_demo.py`` — ``run_fan_out`` 平行 HTTP preflight
+* ``pii_redact_demo.py`` — 純邏輯 PII redaction
+
+測試分層
+========
+
+* ``test/unit_test/`` — 1200 個 mock-based 單元測試，約 12 秒
+* ``test/integration_test/`` — 30 個整合測試，串接真 I/O（SQLite、HTTP
+  server、MCP / LSP 子行程），曾揪出 Windows LSP CRLF framing bug
+* ``test/e2e_test/`` — 六個真瀏覽器 smoke，``WEBRUNNER_E2E_HUB`` 未設定
+  時自動 skip。本機跑：``cd docker && docker compose up -d``。CI 走
+  ``.github/workflows/e2e_browser.yml``，每日 + 手動觸發
+
+主題式 façade
+=============
+
+80+ helpers 除了原本的 ``je_web_runner.utils.<area>`` 路徑，現在也透過
+``je_web_runner.api`` 主題分組重新匯出：
+
+.. code-block:: python
+
+   from je_web_runner.api import (
+       authoring, debugging, frontend, infra, mobile,
+       networking, observability, quality, reliability,
+       security, test_data,
+   )
+
+原本的 Selenium 式頂層 API 不變，舊程式碼可繼續運作。