From 5209aea854652abaa394a8e847c4caa91c756817 Mon Sep 17 00:00:00 2001 From: JeffreyChen Date: Tue, 28 Apr 2026 15:17:28 +0800 Subject: [PATCH 1/2] Fix dir-existence check in executor template branch Both clauses checked keyword_dir_path; the executor branch should validate its own directory. Harmless until now (both dirs are created together) but the logic was wrong. --- je_web_runner/utils/project/create_project_structure.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/je_web_runner/utils/project/create_project_structure.py b/je_web_runner/utils/project/create_project_structure.py index bb2ef39..e2a2f32 100644 --- a/je_web_runner/utils/project/create_project_structure.py +++ b/je_web_runner/utils/project/create_project_structure.py @@ -58,7 +58,7 @@ def create_template(parent_name: str, project_path: str = None) -> None: # 建立 executor Python 檔案 # Create executor Python files - if executor_dir_path.exists() and keyword_dir_path.is_dir(): + if executor_dir_path.exists() and executor_dir_path.is_dir(): lock.acquire() try: with open(project_root + EXECUTOR_DIR + "/executor_one_file.py", "w+") as file: From f79875d1ccb40a4425ad0e0640610d1f678d0f1a Mon Sep 17 00:00:00 2001 From: JeffreyChen Date: Tue, 28 Apr 2026 16:19:23 +0800 Subject: [PATCH 2/2] Reorganize docs into chapter-based toctrees and add MCP Claude guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Split the English, 繁體中文 and API books into captioned chapters (Getting Started, Core Wrappers, Actions, Backends, Reporting, Orchestration, Quality, Tooling, Integrations, Reference) so readers can navigate by topic instead of a flat list. Add a dedicated mcp_claude page in both languages covering the MCP server entry point, Claude Desktop and Claude Code configuration, in-conversation usage examples, the full ~22-tool catalog, custom tool registration and troubleshooting. Hide the redundant toctree inside extended_features_doc so the same subtopic pages do not produce duplicate-parent warnings while still keeping the legacy hub link resolvable. --- docs/source/API/api_index.rst | 28 +- .../extended_features_doc.rst | 6 +- .../Eng/doc/mcp_claude/mcp_claude_doc.rst | 308 ++++++++++++++++++ docs/source/Eng/eng_index.rst | 173 +++++++++- .../extended_features_doc.rst | 6 +- .../Zh/doc/mcp_claude/mcp_claude_doc.rst | 279 ++++++++++++++++ docs/source/Zh/zh_index.rst | 162 ++++++++- docs/source/index.rst | 26 +- 8 files changed, 959 insertions(+), 29 deletions(-) create mode 100644 docs/source/Eng/doc/mcp_claude/mcp_claude_doc.rst create mode 100644 docs/source/Zh/doc/mcp_claude/mcp_claude_doc.rst diff --git a/docs/source/API/api_index.rst b/docs/source/API/api_index.rst index 03d217a..1e4758f 100644 --- a/docs/source/API/api_index.rst +++ b/docs/source/API/api_index.rst @@ -2,8 +2,24 @@ WebRunner API Documentation ==================================== +Auto-generated reference for the public Python surface, split into two +chapters: the **utility package** (action executor, reports, helpers) +and the **wrapper package** (Selenium-facing classes). + +.. contents:: On this page + :local: + :depth: 1 + +---- + +Chapter A — Utilities (``je_web_runner.utils``) +=============================================== + +Action authoring, reporting, sockets, and supporting utilities. + .. toctree:: - :maxdepth: 4 + :maxdepth: 2 + :caption: Utilities utils/assert.rst utils/callback.rst @@ -17,6 +33,16 @@ WebRunner API Documentation utils/test_object.rst utils/test_record.rst utils/xml.rst + +Chapter B — Wrappers (``je_web_runner.wrapper``) +================================================ + +The Selenium facade — drivers, elements, manager, and shared helpers. + +.. toctree:: + :maxdepth: 2 + :caption: Wrappers + wrapper/element.rst wrapper/manager.rst wrapper/utils.rst diff --git a/docs/source/Eng/doc/extended_features/extended_features_doc.rst b/docs/source/Eng/doc/extended_features/extended_features_doc.rst index 7da9df2..cad1e0e 100644 --- a/docs/source/Eng/doc/extended_features/extended_features_doc.rst +++ b/docs/source/Eng/doc/extended_features/extended_features_doc.rst @@ -19,8 +19,12 @@ A JSON Schema describing the action JSON format is exported alongside it: The detailed feature documentation is split across these subtopic pages: +The chapters below own these subtopics in the main TOC; this hidden +toctree only keeps the cross-references resolvable for older guides +that link in via ``extended_features``. + .. toctree:: - :maxdepth: 2 + :hidden: ../architecture/architecture_doc.rst ../backends/backends_doc.rst diff --git a/docs/source/Eng/doc/mcp_claude/mcp_claude_doc.rst b/docs/source/Eng/doc/mcp_claude/mcp_claude_doc.rst new file mode 100644 index 0000000..fb52e2b --- /dev/null +++ b/docs/source/Eng/doc/mcp_claude/mcp_claude_doc.rst @@ -0,0 +1,308 @@ +================================== +Using WebRunner with Claude (MCP) +================================== + +WebRunner ships a **Model Context Protocol (MCP) server** that exposes +its action authoring helpers and a curated subset of its browser-driving +``WR_*`` actions to any MCP-aware client. This guide walks through +wiring the server into Claude Code, the Claude Desktop app, and other +clients, plus the full tool catalog. + +.. contents:: On this page + :local: + :depth: 2 + +---- + +What is MCP? +============ + +The Model Context Protocol is a JSON-RPC 2.0 wire protocol Anthropic +uses to give Claude controlled access to local tools. WebRunner +implements protocol version ``2024-11-05`` over **newline-delimited +JSON over stdio** — every line is one JSON-RPC message — so any client +that speaks MCP stdio can drive WebRunner without HTTP, sockets, or +custom glue. + +The server entry point is:: + + python -m je_web_runner.mcp_server + +It registers two tool families on startup: + +* **Default helpers** (``build_default_tools``) — pure-Python action + authoring, linting, locator scoring, PII redaction, sharding, + templating, etc. No browser is launched. +* **Browser tools** (``build_browser_tools``) — drive a real browser + through the WebRunner action executor. + +If a tool name above appears in a configured client, you can call it +straight from a chat with Claude. + +---- + +Quick start +=========== + +1. Install WebRunner with browser support:: + + pip install je_web_runner + +2. Confirm the server starts:: + + python -m je_web_runner.mcp_server + + It will block on stdin reading; press *Ctrl-C* to exit. + +3. Wire the server into your client (next two sections). + +4. In a new Claude conversation, ask: + + "List the WebRunner MCP tools you can see." + + Claude should call ``tools/list`` and respond with the registered + tools. + +---- + +Configuring Claude Desktop +========================== + +Claude Desktop reads MCP servers from +``claude_desktop_config.json``: + +* **macOS** — ``~/Library/Application Support/Claude/claude_desktop_config.json`` +* **Windows** — ``%APPDATA%\Claude\claude_desktop_config.json`` + +Add a ``webrunner`` entry under ``mcpServers``: + +.. code-block:: json + + { + "mcpServers": { + "webrunner": { + "command": "python", + "args": ["-m", "je_web_runner.mcp_server"], + "env": { + "WEBRUNNER_HEADLESS": "1" + } + } + } + } + +Quit and relaunch Claude Desktop; the WebRunner tools appear in the +*Tools* drawer. + +.. tip:: + + On Windows, prefer the absolute path to ``python.exe`` from the + virtualenv where ``je_web_runner`` is installed + (e.g. ``C:\\Users\\you\\.venvs\\webrunner\\Scripts\\python.exe``). + Claude Desktop runs without the user shell, so ``PATH`` may not + resolve a generic ``python``. + +---- + +Configuring Claude Code (CLI) +============================= + +Claude Code (the terminal client) configures MCP servers per-project +in ``.mcp.json`` next to your repo root: + +.. code-block:: json + + { + "mcpServers": { + "webrunner": { + "command": "python", + "args": ["-m", "je_web_runner.mcp_server"] + } + } + } + +Or globally in ``~/.claude/mcp.json``. Restart Claude Code and run +``/mcp`` to confirm the server connects. + +If a tool needs the action JSON to live somewhere Claude can read, +keep your action files inside the project directory — Claude Code's +file allow-list is repo-scoped by default. + +---- + +Using WebRunner tools from a Claude conversation +================================================ + +Once configured, Claude can call MCP tools the same way it calls +built-in tools. Practical examples: + +* **Lint an action draft.** Paste a JSON action list and ask Claude + to *"call ``webrunner_lint_action`` and report any issues."* Claude + receives a structured ``[{rule, severity, message, location}, ...]`` + array and summarises it. + +* **Score locator strength.** *"For each step in this action list, + rate the locator quality with ``webrunner_score_action_locators`` + and propose a stronger replacement where the score is below 60."* + +* **Drive a browser.** *"Use ``webrunner_run_actions`` to open + example.com in a Playwright session and fill the search box."* + Claude composes the ``[command, params]`` payload, the executor + runs against a real browser, and Claude reads back ``{stdout, + record}``. + +* **Extract a Page Object.** *"Run ``webrunner_pom_from_html`` on the + attached login page HTML and produce a ``LoginPage`` Python module."* + +For browser tools, the server is **stateful inside the process**: +calling ``WR_get_webdriver_manager`` once creates the driver, and +subsequent ``webrunner_run_actions`` calls reuse it until you issue +``WR_quit``. + +---- + +Tool catalog +============ + +The server registers ~22 tools out of the box. Use +``webrunner_list_commands`` for the *full* runtime command list (every +``WR_*`` registered in the action executor — typically ~200 entries). + +Authoring & lint +---------------- + +* ``webrunner_lint_action`` — Lint an action JSON list and report + issues; returns ``[{rule, severity, message, location}, …]``. +* ``webrunner_score_action_locators`` — Score every locator referenced + by an action list on a 0–100 scale. +* ``webrunner_locator_strength`` — Score a single + ``(strategy, value)`` locator. +* ``webrunner_format_actions`` — Canonical-order action JSON. +* ``webrunner_parse_markdown`` — Transpile a Markdown bullet list + into a ``WR_*`` action list. +* ``webrunner_render_template`` — Render a registered action template + with parameters. + +Code generation +--------------- + +* ``webrunner_pom_from_html`` — Discover ``[data-testid]`` / ``id`` / + form fields and render a Python Page Object module. +* ``webrunner_translate_actions_to_playwright`` — Rewrite a ``WR_*`` + action list to its ``WR_pw_*`` Playwright equivalent. +* ``webrunner_translate_python_to_playwright`` — Static rewrite of + Selenium-style Python source into Playwright equivalents with + per-line diffs. + +Quality & triage +---------------- + +* ``webrunner_a11y_diff`` — Diff two ``axe-core`` violations arrays + into added / resolved / persisting / regressed. +* ``webrunner_cluster_failures`` — Group failures by normalised error + signature. +* ``webrunner_compute_trend`` — Pass-rate / duration trend from a + ledger file. + +Security +-------- + +* ``webrunner_scan_pii`` — Detect email / phone / Luhn-card / SSN / + ROC-ID / IPv4 in text. +* ``webrunner_redact_pii`` — Replace each match with a sentinel + string. + +Reporting & contract +-------------------- + +* ``webrunner_summary_markdown`` — Build a PR summary in Markdown + from totals. +* ``webrunner_validate_response`` — Validate JSON against a minimal + JSON-Schema; returns ``{valid, errors}``. + +Sharding & infra +---------------- + +* ``webrunner_diff_shard`` — Pick changed action files from + candidate / changed lists. +* ``webrunner_render_k8s`` — Render Kubernetes Job manifests for + shard parallelism. +* ``webrunner_partition_shard`` — Deterministic SHA-1 mod-N file + partitioning. + +Browser execution +----------------- + +* ``webrunner_run_actions`` — Execute an action list against a real + browser. Returns ``{stdout, record}``. +* ``webrunner_run_action_files`` — Read JSON action files from disk + and run them sequentially. +* ``webrunner_list_commands`` — Discover every ``WR_*`` command + currently registered in the executor. + +---- + +Registering custom tools +======================== + +External code can extend the server by calling ``McpServer.register``: + +.. code-block:: python + + from je_web_runner.mcp_server import McpServer, build_default_tools + from je_web_runner.mcp_server.server import Tool + + def my_tool(arguments): + return {"echo": arguments.get("text", "")} + + server = McpServer() + for tool in build_default_tools(): + server.register(tool) + + server.register(Tool( + name="my_echo", + description="Echo a string back.", + input_schema={ + "type": "object", + "properties": {"text": {"type": "string"}}, + "required": ["text"], + }, + handler=my_tool, + )) + + from je_web_runner.mcp_server.server import serve_stdio + serve_stdio(server=server) + +Save the script as ``my_mcp.py`` and point your client's ``command`` / +``args`` at it instead of ``python -m je_web_runner.mcp_server``. + +---- + +Troubleshooting +=============== + +* **Claude says "no tools registered"** — confirm the server starts + manually (``python -m je_web_runner.mcp_server`` should not exit + immediately) and check the configured ``command`` / ``args`` resolve + on the client's ``PATH``. +* **Browser tools hang** — the browser tools use the WebRunner + executor, which prints to stdout. The server captures stdout and + surfaces it in the ``stdout`` field; if a callback writes directly + to ``sys.__stdout__`` it can corrupt the wire. Avoid raw prints in + callbacks. +* **JSON not serialisable** — browser tools convert + ``WebDriver`` / ``WebElement`` instances to ``repr()`` strings via + ``_serialize_value``. Custom return types must be JSON-friendly or + reduce cleanly under that helper. +* **Protocol mismatch** — WebRunner advertises + ``protocolVersion=2024-11-05``. Newer clients negotiate down; if + yours doesn't, pin the client to that version. + +---- + +See also +======== + +* :doc:`../integrations/integrations_doc` — Recorder, CI, JIRA / Slack + notifiers, and the overview of MCP and the action JSON LSP. +* `Anthropic MCP spec `_ — the + upstream protocol reference. diff --git a/docs/source/Eng/eng_index.rst b/docs/source/Eng/eng_index.rst index ef24f40..9a6973a 100644 --- a/docs/source/Eng/eng_index.rst +++ b/docs/source/Eng/eng_index.rst @@ -2,26 +2,177 @@ WebRunner English Documentation ==================================== +The English manual is split into chapters that follow a typical reader +journey: install → drive a browser → author actions → scale → integrate. +Use the table of contents on the left, or jump straight to a chapter +below. + +.. contents:: On this page + :local: + :depth: 1 + +---- + +.. _eng-getting-started: + +Chapter 1 — Getting Started +=========================== + +Install WebRunner, run your first browser session, and scaffold a new +project skeleton. + .. toctree:: - :maxdepth: 4 + :maxdepth: 2 + :caption: Getting Started doc/installation/installation_doc.rst doc/quick_start/quick_start_doc.rst - doc/extended_features/extended_features_doc.rst - doc/api_reference/api_reference.rst - doc/webdriver_manager/webdriver_manager_doc.rst + doc/create_project/create_project_doc.rst + +.. _eng-core-wrappers: + +Chapter 2 — Core Wrappers +========================= + +The Selenium-facing facade: drivers, options, elements, and locator +value objects. Read this once and the rest of the framework stops +feeling like magic. + +.. toctree:: + :maxdepth: 2 + :caption: Core Wrappers + + doc/architecture/architecture_doc.rst doc/webdriver_wrapper/webdriver_wrapper_doc.rst + doc/webdriver_manager/webdriver_manager_doc.rst + doc/webdriver_options/webdriver_options_doc.rst doc/web_element/web_element_doc.rst doc/test_object/test_object_doc.rst + +.. _eng-actions: + +Chapter 3 — Action Authoring & Execution +======================================== + +Compose JSON-driven action scripts, register callbacks, plug in custom +packages, and record what the browser did. + +.. toctree:: + :maxdepth: 2 + :caption: Actions + doc/action_executor/action_executor_doc.rst - doc/create_project/create_project_doc.rst - doc/generate_report/generate_report_doc.rst + doc/assertion/assertion_doc.rst doc/callback_function/callback_function_doc.rst + doc/test_record/test_record_doc.rst + doc/package_manager/package_manager_doc.rst + +.. _eng-backends: + +Chapter 4 — Browser Backends +============================ + +Selenium and Playwright back-ends, plus the lower-level browser glue +(CDP / DevTools, capabilities, network shaping). + +.. toctree:: + :maxdepth: 2 + :caption: Backends + + doc/backends/backends_doc.rst + doc/browser_internals/browser_internals_doc.rst + +.. _eng-reporting: + +Chapter 5 — Reporting & Observability +===================================== + +Generate HTML / JSON / XML reports, ship logs, surface metrics, and +diff trends across runs. + +.. toctree:: + :maxdepth: 2 + :caption: Reporting + + doc/generate_report/generate_report_doc.rst + doc/reports/reports_doc.rst + doc/observability/observability_doc.rst + doc/logging/logging_doc.rst + +.. _eng-orchestration: + +Chapter 6 — Orchestration & Scale +================================= + +Parallel runs, sharding, retries, Selenium Grid, and Kubernetes Job +manifests. + +.. toctree:: + :maxdepth: 2 + :caption: Orchestration + + doc/orchestration/orchestration_doc.rst + +.. _eng-quality: + +Chapter 7 — Quality, Security & Data +==================================== + +Linting, locator scoring, PII redaction, accessibility diffs, contract +testing, and data / auth helpers. + +.. toctree:: + :maxdepth: 2 + :caption: Quality & Data + + doc/quality_security/quality_security_doc.rst + doc/data_auth_api/data_auth_api_doc.rst + +.. _eng-tooling: + +Chapter 8 — Tooling, CLI & Diagnostics +====================================== + +Command-line entry points, the remote socket driver, and the +exception hierarchy you will see in tracebacks. + +.. toctree:: + :maxdepth: 2 + :caption: Tooling + doc/cli/cli_doc.rst + doc/tooling/tooling_doc.rst doc/socket_driver/socket_driver_doc.rst - doc/package_manager/package_manager_doc.rst - doc/webdriver_options/webdriver_options_doc.rst - doc/assertion/assertion_doc.rst - doc/test_record/test_record_doc.rst doc/exception/exception_doc.rst - doc/logging/logging_doc.rst + +.. _eng-integrations: + +Chapter 9 — Integrations +======================== + +CI annotations, JIRA / TestRail / Slack notifiers, IDE schema mappings, +and the **Model Context Protocol (MCP)** server that lets Claude drive +WebRunner. + +.. toctree:: + :maxdepth: 2 + :caption: Integrations + + doc/integrations/integrations_doc.rst + doc/mcp_claude/mcp_claude_doc.rst + doc/cookbook/cookbook_doc.rst + +.. _eng-reference: + +Chapter 10 — API Reference +========================== + +Auto-generated Python API reference and the legacy "extended features" +hub, kept for cross-linking from older guides. + +.. toctree:: + :maxdepth: 2 + :caption: Reference + + doc/api_reference/api_reference.rst + doc/extended_features/extended_features_doc.rst diff --git a/docs/source/Zh/doc/extended_features/extended_features_doc.rst b/docs/source/Zh/doc/extended_features/extended_features_doc.rst index 0d01bf0..f688316 100644 --- a/docs/source/Zh/doc/extended_features/extended_features_doc.rst +++ b/docs/source/Zh/doc/extended_features/extended_features_doc.rst @@ -14,10 +14,12 @@ WebRunner 除了原本的 Selenium 包裝，現已附帶 Playwright backend、JS docs/reference/webrunner-action-schema.json -詳細功能文件已拆分成下列子主題頁： +詳細功能文件已拆分成下列子主題頁，並在主目錄中歸入對應章節； +此處僅以隱藏 toctree 保留交互參照，方便舊版指南仍能透過 +``extended_features`` 連到內頁。 .. toctree:: - :maxdepth: 2 + :hidden: ../architecture/architecture_doc.rst ../backends/backends_doc.rst diff --git a/docs/source/Zh/doc/mcp_claude/mcp_claude_doc.rst b/docs/source/Zh/doc/mcp_claude/mcp_claude_doc.rst new file mode 100644 index 0000000..8f559d5 --- /dev/null +++ b/docs/source/Zh/doc/mcp_claude/mcp_claude_doc.rst @@ -0,0 +1,279 @@ +============================================ +搭配 Claude 使用 WebRunner (MCP) +============================================ + +WebRunner 內建 **Model Context Protocol (MCP) server**,把 action 撰寫 +工具與部分 ``WR_*`` 瀏覽器動作開放給任何支援 MCP 的客戶端。本章說明 +如何把 server 接到 Claude Code、Claude Desktop 與其他客戶端,並列出完整 +工具表。 + +.. contents:: 本頁目錄 + :local: + :depth: 2 + +---- + +什麼是 MCP? +=========== + +Model Context Protocol 是 Anthropic 用來讓 Claude 安全呼叫本機工具的 +JSON-RPC 2.0 協定。WebRunner 實作 ``2024-11-05`` 版本, +透過 **stdio 上的 newline-delimited JSON** (每行一個 JSON-RPC 訊息) +通訊,因此任何支援 MCP stdio 的客戶端都能直接驅動 WebRunner, +不需 HTTP、socket 或自訂橋接。 + +啟動指令:: + + python -m je_web_runner.mcp_server + +server 啟動時會註冊兩組工具: + +* **Default helpers** (``build_default_tools``) — 純 Python 的 action + 撰寫、lint、locator 評分、PII 遮罩、sharding、模板等,**不會**啟動 + 瀏覽器。 +* **Browser tools** (``build_browser_tools``) — 透過 WebRunner action + executor 操作真實瀏覽器。 + +凡是已註冊的工具,Claude 都能在對話中直接呼叫。 + +---- + +快速上手 +======== + +1. 安裝 WebRunner:: + + pip install je_web_runner + +2. 確認 server 啟得起來:: + + python -m je_web_runner.mcp_server + + 會卡在讀取 stdin,按 *Ctrl-C* 結束即可。 + +3. 把 server 設定到客戶端(下兩節)。 + +4. 在 Claude 對話中問: + + "列出你看得到的 WebRunner MCP 工具。" + + Claude 會呼叫 ``tools/list`` 並回覆已註冊的工具清單。 + +---- + +設定 Claude Desktop +=================== + +Claude Desktop 從 ``claude_desktop_config.json`` 讀取 MCP server: + +* **macOS**:``~/Library/Application Support/Claude/claude_desktop_config.json`` +* **Windows**:``%APPDATA%\Claude\claude_desktop_config.json`` + +在 ``mcpServers`` 下新增 ``webrunner`` 條目: + +.. code-block:: json + + { + "mcpServers": { + "webrunner": { + "command": "python", + "args": ["-m", "je_web_runner.mcp_server"], + "env": { + "WEBRUNNER_HEADLESS": "1" + } + } + } + } + +關閉並重開 Claude Desktop,WebRunner 工具就會出現在 *Tools* 抽屜。 + +.. tip:: + + Windows 上建議直接寫安裝 ``je_web_runner`` 那個 venv 的 + ``python.exe`` 絕對路徑(例如 + ``C:\\Users\\you\\.venvs\\webrunner\\Scripts\\python.exe``), + 因為 Claude Desktop 不會載入使用者 shell 的 ``PATH``, + 通用的 ``python`` 不一定能解析到。 + +---- + +設定 Claude Code (CLI) +====================== + +Claude Code(終端機客戶端)以專案為單位,從 repo 根目錄的 +``.mcp.json`` 讀取 MCP server 設定: + +.. code-block:: json + + { + "mcpServers": { + "webrunner": { + "command": "python", + "args": ["-m", "je_web_runner.mcp_server"] + } + } + } + +或寫到全域的 ``~/.claude/mcp.json``。重啟 Claude Code 後執行 ``/mcp`` +確認 server 連得上。 + +如果工具會讀寫 action JSON,請把檔案放在專案目錄內 — Claude Code +預設只允許 repo 範圍內的檔案存取。 + +---- + +在對話中使用 WebRunner 工具 +=========================== + +設定完成後,Claude 呼叫 MCP 工具就跟內建工具一樣自然。常見用法: + +* **Lint 一份 action 草稿。** 貼一段 action JSON,然後請 Claude + *「呼叫 ``webrunner_lint_action`` 並整理問題清單。」* Claude 會收到 + ``[{rule, severity, message, location}, ...]``,再幫你摘要。 + +* **評估 locator 強度。** *「對這份 action list,用 + ``webrunner_score_action_locators`` 評分,並把分數低於 60 的步驟 + 改寫成更穩定的 locator。」* + +* **驅動瀏覽器。** *「用 ``webrunner_run_actions`` 開啟 example.com, + 在搜尋欄輸入文字。」* Claude 會組好 ``[command, params]`` payload, + executor 在真實瀏覽器執行,Claude 再讀回 ``{stdout, record}``。 + +* **產生 Page Object。** *「用 ``webrunner_pom_from_html`` 把附上的 + 登入頁 HTML 轉成 ``LoginPage`` Python 模組。」* + +對於 browser tools,server **在同一個 process 內保持狀態**:呼叫一次 +``WR_get_webdriver_manager`` 建立 driver 後,後續的 +``webrunner_run_actions`` 都會重用,直到呼叫 ``WR_quit``。 + +---- + +工具清單 +======== + +server 預設註冊約 22 個工具。完整 runtime 指令清單(executor 中所有 +``WR_*``,通常約 200 個)請呼叫 ``webrunner_list_commands``。 + +撰寫與 lint +----------- + +* ``webrunner_lint_action`` — 對 action JSON list 跑 lint,回傳 + ``[{rule, severity, message, location}, …]``。 +* ``webrunner_score_action_locators`` — 對 action list 中每個 locator + 評分(0–100)。 +* ``webrunner_locator_strength`` — 對單一 ``(strategy, value)`` 評分。 +* ``webrunner_format_actions`` — 用一致的順序輸出 action JSON。 +* ``webrunner_parse_markdown`` — 把 Markdown 列表轉成 ``WR_*`` action。 +* ``webrunner_render_template`` — 套用已註冊的 action 模板與參數。 + +程式碼生成 +---------- + +* ``webrunner_pom_from_html`` — 從 HTML 找出 ``[data-testid]`` / + ``id`` / 表單欄位,生成 Page Object Python 模組。 +* ``webrunner_translate_actions_to_playwright`` — 把 ``WR_*`` action + list 改寫成 ``WR_pw_*`` Playwright 版本。 +* ``webrunner_translate_python_to_playwright`` — 靜態翻譯 + Selenium 風格 Python 為 Playwright,並回傳逐行 diff。 + +品質與 triage +------------- + +* ``webrunner_a11y_diff`` — 對兩份 axe-core violations 做 diff, + 分為 added / resolved / persisting / regressed。 +* ``webrunner_cluster_failures`` — 依錯誤特徵 cluster 失敗。 +* ``webrunner_compute_trend`` — 從 ledger 算 pass-rate / 時長趨勢。 + +安全 +---- + +* ``webrunner_scan_pii`` — 偵測 email / 電話 / Luhn 卡號 / SSN / + ROC ID / IPv4。 +* ``webrunner_redact_pii`` — 對偵測到的字串遮罩成 sentinel。 + +報告與 contract +--------------- + +* ``webrunner_summary_markdown`` — 由統計值生成 PR Markdown 摘要。 +* ``webrunner_validate_response`` — 用最小 JSON-Schema 驗證 JSON, + 回傳 ``{valid, errors}``。 + +Sharding 與 infra +----------------- + +* ``webrunner_diff_shard`` — 從候選 / 變更檔案中挑出需要重跑的。 +* ``webrunner_render_k8s`` — 產生 Kubernetes Job manifest。 +* ``webrunner_partition_shard`` — SHA-1 mod-N 的決定性檔案分配。 + +瀏覽器執行 +---------- + +* ``webrunner_run_actions`` — 對真實瀏覽器執行 action list,回傳 + ``{stdout, record}``。 +* ``webrunner_run_action_files`` — 讀檔並依序執行 action JSON 檔。 +* ``webrunner_list_commands`` — 列出 executor 目前註冊的所有 + ``WR_*`` 指令。 + +---- + +註冊自訂工具 +============ + +外部程式可透過 ``McpServer.register`` 擴充 server: + +.. code-block:: python + + from je_web_runner.mcp_server import McpServer, build_default_tools + from je_web_runner.mcp_server.server import Tool + + def my_tool(arguments): + return {"echo": arguments.get("text", "")} + + server = McpServer() + for tool in build_default_tools(): + server.register(tool) + + server.register(Tool( + name="my_echo", + description="Echo a string back.", + input_schema={ + "type": "object", + "properties": {"text": {"type": "string"}}, + "required": ["text"], + }, + handler=my_tool, + )) + + from je_web_runner.mcp_server.server import serve_stdio + serve_stdio(server=server) + +把上面這段存成 ``my_mcp.py``,並把客戶端的 ``command`` / ``args`` 改指 +這個檔(取代 ``python -m je_web_runner.mcp_server``)即可。 + +---- + +疑難排解 +======== + +* **Claude 顯示「沒有可用的工具」** — 先手動執行 + ``python -m je_web_runner.mcp_server`` 確認 server 沒立刻退出, + 並檢查設定中的 ``command`` / ``args`` 在客戶端的 ``PATH`` 下解析得到。 +* **Browser tools 卡住不動** — Browser tools 透過 executor 執行, + executor 會 print 到 stdout。Server 已經把 stdout 重新導向到 buffer + 並放在回傳的 ``stdout`` 欄位;但若 callback 直接寫 + ``sys.__stdout__`` 仍會破壞 wire,務必避免在 callback 中 raw print。 +* **JSON 無法序列化** — Browser tools 透過 ``_serialize_value`` 把 + ``WebDriver`` / ``WebElement`` 轉成 ``repr()`` 字串。自訂回傳值若不是 + JSON-friendly,需要在該 helper 下能 reduce。 +* **Protocol 版本不合** — WebRunner 公告 ``protocolVersion=2024-11-05``, + 較新的客戶端會自動 negotiate down;若不行請把客戶端鎖定在這版。 + +---- + +延伸閱讀 +======== + +* :doc:`../integrations/integrations_doc` — Recorder、CI、JIRA / Slack + 通知、以及 MCP 與 action JSON LSP 的概觀。 +* `Anthropic MCP 規格 `_ — 上游協定 + 參考。 diff --git a/docs/source/Zh/zh_index.rst b/docs/source/Zh/zh_index.rst index e73915f..1a4be1a 100644 --- a/docs/source/Zh/zh_index.rst +++ b/docs/source/Zh/zh_index.rst @@ -2,25 +2,167 @@ WebRunner 繁體中文文件 ==================================== +中文手冊依「安裝 → 操作瀏覽器 → 撰寫動作 → 擴展 → 整合」的順序拆成多個章節， +請從左側目錄選擇章節，或從下方直接跳轉。 + +.. contents:: 本頁目錄 + :local: + :depth: 1 + +---- + +.. _zh-getting-started: + +第 1 章 — 入門 +============== + +安裝 WebRunner、跑第一支瀏覽器腳本、以及產生新專案骨架。 + .. toctree:: - :maxdepth: 4 + :maxdepth: 2 + :caption: 入門 doc/installation/installation_doc.rst doc/quick_start/quick_start_doc.rst - doc/extended_features/extended_features_doc.rst - doc/webdriver_manager/webdriver_manager_doc.rst + doc/create_project/create_project_doc.rst + +.. _zh-core-wrappers: + +第 2 章 — 核心包裝器 +==================== + +對 Selenium 的封裝層：driver、options、element 與 locator 值物件， +讀完這章後其他模組會變得直觀。 + +.. toctree:: + :maxdepth: 2 + :caption: 核心包裝器 + + doc/architecture/architecture_doc.rst doc/webdriver_wrapper/webdriver_wrapper_doc.rst + doc/webdriver_manager/webdriver_manager_doc.rst + doc/webdriver_options/webdriver_options_doc.rst doc/web_element/web_element_doc.rst doc/test_object/test_object_doc.rst + +.. _zh-actions: + +第 3 章 — 動作撰寫與執行 +======================== + +撰寫 JSON 驅動的 action 腳本、註冊 callback、外掛動態載入、 +以及記錄瀏覽器執行軌跡。 + +.. toctree:: + :maxdepth: 2 + :caption: 動作 + doc/action_executor/action_executor_doc.rst - doc/create_project/create_project_doc.rst - doc/generate_report/generate_report_doc.rst + doc/assertion/assertion_doc.rst doc/callback_function/callback_function_doc.rst + doc/test_record/test_record_doc.rst + doc/package_manager/package_manager_doc.rst + +.. _zh-backends: + +第 4 章 — 瀏覽器後端 +==================== + +Selenium 與 Playwright 後端,以及更底層的瀏覽器整合(CDP、capability、 +網路條件)。 + +.. toctree:: + :maxdepth: 2 + :caption: 瀏覽器後端 + + doc/backends/backends_doc.rst + doc/browser_internals/browser_internals_doc.rst + +.. _zh-reporting: + +第 5 章 — 報告與觀測性 +====================== + +產生 HTML / JSON / XML 報告、輸出 log、暴露 metrics、以及跨 run 的趨勢比對。 + +.. toctree:: + :maxdepth: 2 + :caption: 報告 + + doc/generate_report/generate_report_doc.rst + doc/reports/reports_doc.rst + doc/observability/observability_doc.rst + doc/logging/logging_doc.rst + +.. _zh-orchestration: + +第 6 章 — 調度與擴展 +==================== + +平行執行、shard 拆分、重試、Selenium Grid、以及 Kubernetes Job 範本。 + +.. toctree:: + :maxdepth: 2 + :caption: 調度 + + doc/orchestration/orchestration_doc.rst + +.. _zh-quality: + +第 7 章 — 品質、安全與資料 +========================== + +Action linter、locator 評分、PII 偵測與遮罩、accessibility diff、 +contract testing、資料/認證 helper。 + +.. toctree:: + :maxdepth: 2 + :caption: 品質與資料 + + doc/quality_security/quality_security_doc.rst + doc/data_auth_api/data_auth_api_doc.rst + +.. _zh-tooling: + +第 8 章 — 工具、CLI 與診斷 +========================== + +命令列介面、遠端 socket driver、以及在 traceback 中會看到的例外階層。 + +.. toctree:: + :maxdepth: 2 + :caption: 工具 + doc/cli/cli_doc.rst + doc/tooling/tooling_doc.rst doc/socket_driver/socket_driver_doc.rst - doc/package_manager/package_manager_doc.rst - doc/webdriver_options/webdriver_options_doc.rst - doc/assertion/assertion_doc.rst - doc/test_record/test_record_doc.rst doc/exception/exception_doc.rst - doc/logging/logging_doc.rst + +.. _zh-integrations: + +第 9 章 — 外部整合 +================== + +CI 註解、JIRA / TestRail / Slack 通知、IDE schema 設定,以及讓 Claude 透過 +**Model Context Protocol (MCP)** 操作 WebRunner 的 server。 + +.. toctree:: + :maxdepth: 2 + :caption: 整合 + + doc/integrations/integrations_doc.rst + doc/mcp_claude/mcp_claude_doc.rst + doc/cookbook/cookbook_doc.rst + +.. _zh-reference: + +第 10 章 — 參考資料 +=================== + +舊的 extended features hub 頁面,留作向下相容,實際內容已分散到上面各章。 + +.. toctree:: + :maxdepth: 2 + :caption: 參考 + + doc/extended_features/extended_features_doc.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 88a2fa1..77676bb 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -4,8 +4,10 @@ WebRunner **A cross-platform web automation framework built on Selenium** -WebRunner (``je_web_runner``) simplifies browser automation with multi-browser support, -parallel execution, automatic driver management, JSON-driven action scripts, and detailed report generation. +WebRunner (``je_web_runner``) simplifies browser automation with +multi-browser support, parallel execution, automatic driver +management, JSON-driven action scripts, and detailed report +generation. * **PyPI**: https://pypi.org/project/je-web-runner/ * **GitHub**: https://github.com/Intergration-Automation-Testing/WebRunner @@ -13,12 +15,28 @@ parallel execution, automatic driver management, JSON-driven action scripts, and ---- +The documentation is split by language and by content type. Each +language manual is organised into chapters (Getting Started, Core +Wrappers, Actions, Backends, Reporting, Orchestration, Quality, +Tooling, Integrations, Reference); the API book holds the +auto-generated Python reference. + .. toctree:: - :maxdepth: 4 - :caption: Documentation + :maxdepth: 2 + :caption: English manual Eng/eng_index.rst + +.. toctree:: + :maxdepth: 2 + :caption: 繁體中文手冊 + Zh/zh_index.rst + +.. toctree:: + :maxdepth: 2 + :caption: API reference + API/api_index.rst ----