Release dev to main

.github/dependabot.yml

@@ -9,3 +9,7 @@ updates:
     directory: "/" # Location of package manifests
     schedule:
       interval: "daily"
+  - package-ecosystem: "github-actions" # Keep workflow action versions current
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/e2e_browser.yml

@@ -41,6 +41,8 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: "3.12"
+          cache: 'pip'
+          cache-dependency-path: dev_requirements.txt
 
       - name: Install dependencies
         run: |

.github/workflows/test_dev.yml

@@ -27,12 +27,13 @@ jobs:
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+        cache-dependency-path: dev_requirements.txt
 
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip wheel
         pip install -r dev_requirements.txt
-        pip install pytest
 
     - name: Run unit tests
       run: python -m pytest test/unit_test/test_*.py -v
@@ -63,6 +64,8 @@ jobs:
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+        cache-dependency-path: dev_requirements.txt
 
     - name: Install dependencies
       run: |

.github/workflows/test_stable.yml

@@ -27,6 +27,8 @@ jobs:
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+        cache-dependency-path: requirements.txt
 
     - name: Install dependencies
       run: |
@@ -63,6 +65,8 @@ jobs:
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+        cache-dependency-path: requirements.txt
 
     - name: Install dependencies
       run: |

.gitignore

@@ -123,9 +123,21 @@ dmypy.json
 # Driver
 *.zip
 *.exe
+# webdriver-manager driver cache (set_driver caches drivers under cwd)
+.wdm/
 
 /.claude/
 /.claude
 issues.json
 hotspots.json
 codacy.json
+
+# Static-analysis exports (SonarCloud / Codacy / pyflakes scratch files)
+.codacy_*.json
+.sonar_*.json
+.pyflakes_files*.txt
+
+# Local report-generation scratch output
+default_name*.html
+default_name*.json
+default_name*.xml

CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to WebRunner
+
+Thanks for your interest in improving WebRunner (`je_web_runner`). This
+guide covers the local setup, the checks we expect to pass, and the branch
+/ PR conventions.
+
+## Development setup
+
+WebRunner targets **Python 3.10+**.
+
+```bash
+# Runtime dependencies
+pip install -r requirements.txt
+
+# Development dependencies (tests, linters, docs, build tooling)
+pip install -r dev_requirements.txt
+```
+
+## Running the tests
+
+```bash
+# Whole suite (unit + integration; e2e tests skip without a Selenium hub)
+python -m pytest test/
+
+# Unit tests only
+python -m pytest test/unit_test/test_*.py
+```
+
+The pure-Python unit suite needs no browser. Integration tests spawn
+short-lived subprocesses. The real-browser e2e tests under
+`test/e2e_test/` skip cleanly unless `WEBRUNNER_E2E_HUB` points at a
+reachable Selenium Grid (see `docker/`).
+
+## Before opening a pull request
+
+Run the linters and keep them clean (no new findings):
+
+```bash
+python -m flake8 je_web_runner/ --max-line-length=120 --max-complexity=10
+python -m pylint je_web_runner/
+python -m bandit -r je_web_runner/ -ll
+python -m mypy je_web_runner/
+```
+
+Please also:
+
+- Add or update tests for any behaviour you change.
+- Keep public functions type-hinted and documented.
+- Avoid introducing new static-analysis issues (SonarQube / Codacy).
+
+## Branches and commits
+
+- `main` is the stable branch; `dev` is the development branch.
+- Open pull requests **from `dev` into `main`**.
+- Write concise, imperative commit messages (e.g. "Add element
+  validation", "Fix driver cleanup on timeout").
+
+## Reporting security issues
+
+Do **not** file security vulnerabilities as public issues — see
+[SECURITY.md](SECURITY.md) for the private disclosure process.

SECURITY.md

@@ -0,0 +1,42 @@
+# Security Policy
+
+## Supported Versions
+
+WebRunner (`je_web_runner`) is distributed on PyPI. Security fixes are
+applied to the latest released version. Please upgrade to the most recent
+release before reporting an issue, as the problem may already be resolved.
+
+| Version        | Supported          |
+| -------------- | ------------------ |
+| Latest release | :white_check_mark: |
+| Older releases | :x:                |
+
+## Reporting a Vulnerability
+
+Please report security vulnerabilities **privately** — do not open a public
+issue, pull request, or discussion for a suspected vulnerability.
+
+Use either of the following private channels:
+
+- **GitHub Security Advisories** — open a private report via the
+  repository's *Security* tab → *Report a vulnerability*. This is the
+  preferred channel.
+- **Email** — `jechenmailman@gmail.com` with a subject line beginning
+  `[SECURITY]`.
+
+To help triage quickly, please include where practical:
+
+- A description of the vulnerability and its impact.
+- The affected version(s) and platform.
+- Step-by-step reproduction instructions or a minimal proof of concept.
+- Any suggested remediation.
+
+## Disclosure Process
+
+- We aim to acknowledge a report within **5 business days**.
+- We target a fix and coordinated disclosure within **90 days** of the
+  initial report, sooner for actively exploited issues.
+- We will credit reporters who wish to be acknowledged once a fix is
+  released. Please let us know your preference.
+
+Thank you for helping keep WebRunner and its users safe.

dev_requirements.txt

@@ -7,4 +7,9 @@ Pyside6
 defusedxml
 Pillow
 faker
-sqlalchemy
+sqlalchemy
+pytest
+pylint
+flake8
+bandit
+mypy

docs/source/Zh/doc/specialized_modules/specialized_modules_doc.rst

@@ -514,7 +514,7 @@ CODEOWNERS 解析器(GitHub 語意:最後一條 match 的規則勝出)+ 每
 * ``web_push_assert`` —— Push subscription VAPID key 匹配、endpoint
   白名單、``userVisibleOnly``、``showNotification`` payload。
 * ``background_sync_assert`` —— Background Sync register / fire /
-  retry / ``lastChance``(quota 耗盡)斷言。
+  retry / ``lastChance``\ (quota 耗盡)斷言。
 * ``wake_lock_assert`` —— Screen wake lock acquire / release /
   漏掉 / 切回前景時 re-acquire 偵測。
 * ``pip_assert`` —— Picture-in-Picture(影片 + Document PiP)
@@ -569,7 +569,7 @@ Email 與通知送達
 ================
 
 * ``email_deliverability`` —— SPF / DKIM / DMARC header +
-  ``List-Unsubscribe``(Gmail/Yahoo 大量寄件規則)+ BCC 外洩稽核。
+  ``List-Unsubscribe``\ (Gmail/Yahoo 大量寄件規則)+ BCC 外洩稽核。
 * ``inbox_render_outlook`` —— Outlook(Word 引擎)/ Gmail / Apple
   Mail 渲染相容性 pre-flight 檢查。
 * ``push_delivery`` —— FCM / APNs payload 大小 + 必填欄位 + PII

docs/source/Zh/doc/webdriver_wrapper/webdriver_wrapper_doc.rst

@@ -304,7 +304,7 @@ CDP Fetch 攔截
 --------------
 
 ``Fetch.*`` CDP 命令薄包裝。要實際收事件 (``Fetch.requestPaused``) 請使用
-``CDPEventListener``（或 Selenium trio-based devtools listener）自行訂閱：
+``CDPEventListener``\ （或 Selenium trio-based devtools listener）自行訂閱：
 
 .. code-block:: python
 

je_web_runner/__main__.py

@@ -9,6 +9,6 @@
 if __name__ == "__main__":
     try:
         sys.exit(main())
-    except Exception as error:  # noqa: BLE001 — surface any failure as exit-1 to the shell
+    except Exception as error:
         print(repr(error), file=sys.stderr)
         sys.exit(1)

je_web_runner/action_lsp/server.py

@@ -17,7 +17,7 @@
 import json
 import sys
 from dataclasses import dataclass, field
-from typing import Any, Dict, List, Optional, TextIO
+from typing import Any, TextIO
 
 from je_web_runner.utils.exception.exceptions import WebRunnerException
 from je_web_runner.utils.logging.loggin_instance import web_runner_logger
@@ -36,11 +36,11 @@
 
 @dataclass
 class ActionLspServer:
-    documents: Dict[str, _Document] = field(default_factory=dict)
+    documents: dict[str, _Document] = field(default_factory=dict)
     initialized: bool = False
-    _command_names: Optional[List[str]] = field(default=None, init=False, repr=False)
+    _command_names: list[str] | None = field(default=None, init=False, repr=False)
 
-    def command_names(self) -> List[str]:
+    def command_names(self) -> list[str]:
         if self._command_names is None:
             try:
                 from je_web_runner.utils.executor.action_executor import executor
@@ -53,7 +53,7 @@
 
     # --- Top-level dispatch ----------------------------------------------
 
-    def handle(self, message: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    def handle(self, message: dict[str, Any]) -> dict[str, Any] | None:
         method = message.get("method")
         request_id = message.get("id")
         params = message.get("params") or {}
@@ -78,7 +78,7 @@
 
     # --- Handlers --------------------------------------------------------
 
-    def _initialize(self) -> Dict[str, Any]:
+    def _initialize(self) -> dict[str, Any]:
         return {
             "capabilities": {
                 "textDocumentSync": 1,  # full sync
@@ -87,14 +87,14 @@
             "serverInfo": {"name": "webrunner-action-lsp", "version": "0.1.0"},
         }
 
-    def _on_did_open(self, params: Dict[str, Any]) -> Dict[str, Any]:
+    def _on_did_open(self, params: dict[str, Any]) -> dict[str, Any]:
         document = params.get("textDocument") or {}
         uri = str(document.get("uri", ""))
         text = str(document.get("text", ""))
         self.documents[uri] = _Document(uri=uri, text=text, version=int(document.get("version", 0)))
         return self._diagnostics_notification(uri, text)
 
-    def _on_did_change(self, params: Dict[str, Any]) -> Dict[str, Any]:
+    def _on_did_change(self, params: dict[str, Any]) -> dict[str, Any]:
         document = params.get("textDocument") or {}
         uri = str(document.get("uri", ""))
         changes = params.get("contentChanges") or []
@@ -108,12 +108,12 @@
         self.documents[uri].version = int(document.get("version", 0))
         return self._diagnostics_notification(uri, full_text)
 
-    def _on_did_close(self, params: Dict[str, Any]) -> None:
+    def _on_did_close(self, params: dict[str, Any]) -> None:
         uri = str((params.get("textDocument") or {}).get("uri", ""))
         self.documents.pop(uri, None)
-        return None
+        return
 
-    def _completion(self, _params: Dict[str, Any]) -> Dict[str, Any]:
+    def _completion(self, _params: dict[str, Any]) -> dict[str, Any]:
         # ``_params`` is part of the LSP request shape but the suggestion
         # list is identical for every cursor position, so the textDocument
         # / position payload is intentionally ignored.
@@ -130,7 +130,7 @@
 
     # --- Diagnostics -----------------------------------------------------
 
-    def _diagnostics_notification(self, uri: str, text: str) -> Dict[str, Any]:
+    def _diagnostics_notification(self, uri: str, text: str) -> dict[str, Any]:
         return {
             "jsonrpc": "2.0",
             "method": "textDocument/publishDiagnostics",
@@ -140,7 +140,7 @@
             },
         }
 
-    def _lint_diagnostics(self, text: str) -> List[Dict[str, Any]]:
+    def _lint_diagnostics(self, text: str) -> list[dict[str, Any]]:
         if not text.strip():
             return []
         try:
@@ -151,7 +151,7 @@
         if not isinstance(actions, list):
             return [_diagnostic("Action document root must be a JSON array.",
                                 line=0, severity=1)]
-        diagnostics: List[Dict[str, Any]] = []
+        diagnostics: list[dict[str, Any]] = []
         try:
             from je_web_runner.utils.linter.action_linter import lint_action
         except Exception:  # pylint: disable=broad-except
@@ -168,18 +168,18 @@
     # --- Helpers ---------------------------------------------------------
 
     @staticmethod
-    def _respond(request_id: Any, result: Any) -> Dict[str, Any]:
+    def _respond(request_id: Any, result: Any) -> dict[str, Any]:
         return {"jsonrpc": "2.0", "id": request_id, "result": result}
 
     @staticmethod
-    def _error(request_id: Any, code: int, message: str) -> Dict[str, Any]:
+    def _error(request_id: Any, code: int, message: str) -> dict[str, Any]:
         return {
             "jsonrpc": "2.0", "id": request_id,
             "error": {"code": code, "message": message},
         }
 
 
-def _diagnostic(error_message: str, line: int, severity: int) -> Dict[str, Any]:
+def _diagnostic(error_message: str, line: int, severity: int) -> dict[str, Any]:
     return {
         "range": {
             "start": {"line": max(0, line), "character": 0},
@@ -196,8 +196,8 @@
 _HEADER_TERMINATOR = "\r\n\r\n"
 
 
-def _read_message(stdin: TextIO) -> Optional[Dict[str, Any]]:
-    headers: Dict[str, str] = {}
+def _read_message(stdin: TextIO) -> dict[str, Any] | None:
+    headers: dict[str, str] = {}
     while True:
         line = stdin.readline()
         if line == "":
@@ -224,16 +224,16 @@
         raise ActionLspError(f"body is not JSON: {error}") from error
 
 
-def _write_message(stdout: TextIO, message: Dict[str, Any]) -> None:
+def _write_message(stdout: TextIO, message: dict[str, Any]) -> None:
     body = json.dumps(message, ensure_ascii=False)
     stdout.write(f"Content-Length: {len(body.encode('utf-8'))}\r\n\r\n{body}")
     stdout.flush()
 
 
 def serve_stdio(
-    stdin: Optional[TextIO] = None,
-    stdout: Optional[TextIO] = None,
-    server: Optional[ActionLspServer] = None,
+    stdin: TextIO | None = None,
+    stdout: TextIO | None = None,
+    server: ActionLspServer | None = None,
 ) -> None:
     """Run the LSP loop until stdin EOF or an ``exit`` notification."""
     in_stream = stdin or sys.stdin