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 ---- 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: