copy webqa-agent file

.github/md-link-config.json

@@ -0,0 +1,26 @@
+{
+  "ignorePatterns": [
+    {
+      "pattern": "^http://localhost"
+    },
+    {
+      "pattern": "^http://0.0.0.0"
+    },
+    {
+      "pattern": "^https://github.com/user-attachments/assets/"
+    }
+  ],
+  "httpHeaders": [
+    {
+      "urls": ["https://github.com/", "https://guides.github.com/", "https://help.github.com/", "https://docs.github.com/"],
+      "headers": {
+        "Accept-Encoding": "zstd, br, gzip, deflate"
+      }
+    }
+  ],
+  "timeout": "20s",
+  "retryOn429": true,
+  "retryCount": 5,
+  "fallbackRetryDelay": "30s",
+  "aliveStatusCodes": [200, 206, 429]
+}

.github/workflows/build-and-push.yml

@@ -0,0 +1,135 @@
+name: Build and Push Docker Images
+
+on:
+  push:
+    tags:
+      - "v*"
+
+env:
+  DOCKERHUB_USERNAME: mmmay0722
+  DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+  REGISTRY: docker.io
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ env.DOCKERHUB_USERNAME }}
+          password: ${{ env.DOCKERHUB_TOKEN }}
+
+      - name: Extract tag name
+        id: extract_tag
+        run: |
+          if [[ $GITHUB_REF == refs/tags/* ]]; then
+            TAG_NAME=${GITHUB_REF#refs/tags/}
+            echo "is_tag=true" >> $GITHUB_OUTPUT
+          else
+            TAG_NAME="latest"
+            echo "is_tag=false" >> $GITHUB_OUTPUT
+          fi
+          echo "tag_name=$TAG_NAME" >> $GITHUB_OUTPUT
+          echo "Extracted tag: $TAG_NAME"
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        timeout-minutes: 30
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: |
+            ${{ env.REGISTRY }}/${{ env.DOCKERHUB_USERNAME }}/webqa-agent:${{ steps.extract_tag.outputs.tag_name }}
+            ${{ env.REGISTRY }}/${{ env.DOCKERHUB_USERNAME }}/webqa-agent:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          platforms: linux/amd64
+          provenance: false
+          sbom: false
+
+  create-release:
+    needs: build-and-push
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: write
+      discussions: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Extract tag name
+        id: extract_tag
+        run: |
+          TAG_NAME=${GITHUB_REF#refs/tags/}
+          echo "tag_name=$TAG_NAME" >> $GITHUB_OUTPUT
+          echo "Current tag: $TAG_NAME"
+
+      - name: Generate changelog
+        id: changelog
+        run: |
+          CURRENT_TAG=${{ steps.extract_tag.outputs.tag_name }}
+          PREVIOUS_TAG=$(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || echo "")
+
+          echo "## 🚀 Release $CURRENT_TAG" > CHANGELOG.md
+          echo "" >> CHANGELOG.md
+          echo "### 📦 Docker Images" >> CHANGELOG.md
+          echo "- \`${{ env.DOCKERHUB_USERNAME }}/webqa-agent:$CURRENT_TAG\`" >> CHANGELOG.md
+          echo "- \`${{ env.DOCKERHUB_USERNAME }}/webqa-agent:latest\`" >> CHANGELOG.md
+          echo "" >> CHANGELOG.md
+
+          if [ -n "$PREVIOUS_TAG" ]; then
+            echo "### 📝 Changes since $PREVIOUS_TAG" >> CHANGELOG.md
+            git log --pretty=format:"- %s (%h)" $PREVIOUS_TAG..$CURRENT_TAG >> CHANGELOG.md
+          else
+            echo "### 📝 Initial Release" >> CHANGELOG.md
+            echo "This is the initial release of WebQA Agent." >> CHANGELOG.md
+          fi
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: ${{ steps.extract_tag.outputs.tag_name }}
+          name: Release ${{ steps.extract_tag.outputs.tag_name }}
+          body_path: CHANGELOG.md
+          draft: false
+          prerelease: false
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  notify:
+    needs: [build-and-push, create-release]
+    runs-on: ubuntu-latest
+    if: always()
+
+    steps:
+      - name: Notify build status
+        run: |
+          if [ "${{ needs.build-and-push.result }}" == "success" ]; then
+            echo "✅ Docker images built and pushed successfully!"
+            echo "✅ Both versioned tag and latest tag have been updated!"
+          else
+            echo "❌ Docker image build failed!"
+            exit 1
+          fi
+
+          if [ "${{ needs.create-release.result }}" == "success" ] || [ "${{ needs.create-release.result }}" == "skipped" ]; then
+            echo "✅ Release process completed successfully!"
+          else
+            echo "❌ Release process failed!"
+          fi

.pre-commit-config.yaml

@@ -0,0 +1,90 @@
+repos:
+# -   repo: https://github.com/psf/black
+#     rev: 25.1.0
+#     hooks:
+#     -   id: black
+#         args: ["--line-length=120"]
+-   repo: https://github.com/PyCQA/flake8
+    rev: 7.2.0
+    hooks:
+    -   id: flake8
+        args: [
+          "--select=E,F",
+          "--ignore=E741,E731,E722,E721,E501,E402,E266,E265,E262,E203,F403,F405",
+          "--exclude=**/__init__.py",
+          "--max-line-length=120"
+        ]
+-   repo: https://github.com/PyCQA/isort
+    rev: 6.0.1
+    hooks:
+    -   id: isort
+-   repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+    -   id: codespell
+        args: ["--skip=*.po,*.ts,*.css", "--ignore-regex=\\b\\w{2,3}\\b"]
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.3.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: check-yaml
+    -   id: end-of-file-fixer
+    -   id: requirements-txt-fixer
+    -   id: double-quote-string-fixer
+    -   id: check-merge-conflict
+    -   id: fix-encoding-pragma
+        args: ["--remove"]
+    -   id: mixed-line-ending
+        args: ["--fix=lf"]
+    -   id: detect-private-key
+    -   id: check-json
+-   repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.9
+    hooks:
+    -   id: mdformat
+        args: ["--number", "--table-width", "200"]
+        additional_dependencies:
+            - mdformat-openmmlab
+            - mdformat_frontmatter
+            - linkify-it-py
+-   repo: https://github.com/myint/docformatter
+    rev: v1.7.7
+    hooks:
+    -   id: docformatter
+        language: python
+        args: ["--in-place", "--wrap-descriptions", "79"]
+-   repo: https://github.com/jackdewinter/pymarkdown
+    rev: v0.9.30
+    hooks:
+    -   id: pymarkdown
+        args: [fix]
+-   repo: https://github.com/gitleaks/gitleaks
+    rev: v8.27.0
+    hooks:
+    -   id: gitleaks
+        entry: "gitleaks dir"
+        args: [
+          "--verbose",
+          "--redact=50"
+        ]
+-   repo: https://github.com/PyCQA/pylint/
+    rev: v3.3.7
+    hooks:
+    -   id: pylint
+        name: pylint
+        entry: pylint
+        language: system
+        types: [python]
+        require_serial: false
+        args:
+            [   "--jobs=4",
+                "--disable=all",
+                "--enable=E,F",
+                "--disable=E0401,E0402,E0102,E1101",
+                "-sn"
+            ]
+-   repo: https://github.com/tcort/markdown-link-check
+    rev: v3.12.2
+    hooks:
+    -   id: markdown-link-check
+        args: [-q,-c, ./.github/md-link-config.json]

Dockerfile

@@ -1,10 +1,28 @@
-FROM mmmay0722/webqa-agent:latest
+FROM mcr.microsoft.com/playwright/python:v1.52.0-noble
 
+# Set working directory
 WORKDIR /app
 
-COPY app.py .
-COPY app_gradio/ ./app_gradio/
+# Install Node.js, npm, and necessary tools
+RUN apt-get update && apt-get install -y \
+    curl \
+    unzip \
+    wget \
+    && curl -fsSL https://deb.nodesource.com/setup_18.x | bash - \
+    && apt-get install -y nodejs \
+    && rm -rf /var/lib/apt/lists/*
 
-EXPOSE 7860
+# Optimize pip configuration and network settings
+RUN pip config set global.index-url https://pypi.org/simple && \
+    pip config set global.timeout 300 && \
+    pip config set global.retries 5
 
-CMD ["/usr/bin/python3", "app.py"]
+# Copy Python dependency file and install
+COPY requirements.txt /app/
+RUN pip install --no-cache-dir --default-timeout=300 -r requirements.txt
+
+# Copy project files
+COPY . /app
+
+# Set to run app.py for Gradio interface
+CMD ["python", "app.py"]

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -1,21 +1,3 @@
----
-title: WebQA Agent
-emoji: 🤖
-colorFrom: blue
-colorTo: purple
-sdk: docker
-pinned: false
-license: apache-2.0
-tags:
-  - web-testing
-  - vibecoding
-  - automation
-  - qa
-  - llm
-  - gradio
----
-
-
 # WebQA Agent
 
 <!-- badges -->

README_zh-CN.md

@@ -0,0 +1,175 @@
+# WebQA Agent
+
+<!-- badges -->
+<p align="left">
+  <a href="https://github.com/MigoXLab/webqa-agent/blob/main/LICENSE"><img src="https://img.shields.io/github/license/MigoXLab/webqa-agent" alt="License"></a>
+  <a href="https://github.com/MigoXLab/webqa-agent/stargazers"><img src="https://img.shields.io/github/stars/MigoXLab/webqa-agent" alt="GitHub stars"></a>
+  <a href="https://github.com/MigoXLab/webqa-agent/network/members"><img src="https://img.shields.io/github/forks/MigoXLab/webqa-agent" alt="GitHub forks"></a>
+  <a href="https://github.com/MigoXLab/webqa-agent/issues"><img src="https://img.shields.io/github/issues/MigoXLab/webqa-agent" alt="GitHub issues"></a>
+  <a href="https://deepwiki.com/MigoXLab/webqa-agent"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
+</p>
+
+[English](README.md) · [简体中文](README_zh-CN.md) 
+
+**WebQA Agent** 是全自动网页评估测试 Agent，一键诊断性能、安全、功能与交互体验
+
+## 🚀 核心特性
+
+### 🧭 功能介绍
+
+<p>
+  <img src="docs/images/webqa.svg" alt="WebQA Agent 业务功能图" />
+</p>
+
+### 📋 特性概览
+
+- **🤖 AI智能测试**：WebQA-Agent能够自主进行网站测试，从页面抓取、用例生成与执行，实现端到端功能测试自动化
+- **📊 多维度评估**：覆盖功能、性能、用户体验、安全等核心测试场景，评估页面加载速度、设计细节和链接，全面保障系统质量
+- **🎯 精准诊断**：基于真实浏览器环境的深度测试，提供可操作的优化建议
+- **📈 可视化报告**：生成详细的HTML测试报告，多维度、可视化展示测试结果，便于分析与追踪
+
+## 📌 测试案例
+
+<p align="center">
+  <img src="https://github.com/user-attachments/assets/b75f18bf-8b92-498e-b5e1-7c4dc5cd33f5" alt="AI 功能测试" width="45%"/>
+  &nbsp;
+  <img src="https://github.com/user-attachments/assets/560cd99d-1213-47b9-82dc-52d3f2d1c1e7" alt="其他测试" width="45%"/>
+</p>
+
+<p align="center">
+  <b>左：AI 智能测试 全自动执行流程</b>　|　<b>右：覆盖多类测试场景</b>
+</p>
+
+## 安装与配置
+
+### 🚀 Docker一键启动
+
+在开始之前，请确保已安装 Docker。如未安装，请参考官方安装指南：[Docker 安装指南](https://docs.docker.com/get-started/get-docker/)。
+
+```bash
+# 1. 下载配置文件模板
+mkdir -p config && curl -fsSL https://raw.githubusercontent.com/MigoXLab/webqa-agent/main/config/config.yaml.example -o config/config.yaml
+
+# 2. 编辑配置文件
+# 设置 target.url、llm_config.api_key 等参数
+
+# 3. 一键启动
+curl -fsSL https://raw.githubusercontent.com/MigoXLab/webqa-agent/main/start.sh | bash
+```
+
+### 源码安装
+
+```bash
+git clone https://github.com/MigoXLab/webqa-agent.git
+cd webqa-agent
+```
+
+安装 Python >= 3.10，运行以下命令：
+
+```bash
+pip install -r requirements.txt
+playwright install
+
+```
+
+性能测试 - Lighthouse 安装（可选）
+
+```bash
+# 需要 Node.js >= 18.0.0 package.json
+npm install
+
+```
+
+安全测试 - Nuclei 安装（可选）
+
+下载地址： [Nuclei Releases](https://github.com/projectdiscovery/nuclei/releases/)
+
+```bash
+# MacOS
+brew install nuclei
+
+# 其他系统请从上述下载地址获取对应架构的版本
+
+# 安装后更新模板并验证
+nuclei -ut -v          # 更新 Nuclei 模板
+nuclei -version        # 验证安装成功
+
+```
+
+参考“使用说明 > 测试配置”进行 `config/config.yaml` 配置后，运行下方命令。
+
+```bash
+python webqa-agent.py
+```
+
+## 在线演示
+
+进入ModelScope体验：[WebQA-Agent on ModelScope](https://modelscope.cn/studios/mmmmei22/WebQA-Agent/summary)
+
+## 使用说明
+
+### 测试配置
+
+`webqa-agent` 通过 YAML 配置测试运行参数：
+
+```yaml
+target:
+  url: https://example.com/                       # 需要测试的网站URL
+  description: example description
+
+test_config:                                      # 测试项配置
+  function_test:                                  # 功能测试
+    enabled: True
+    type: ai                                      # default or ai
+    business_objectives: example business objectives  # 建议加入测试范围，如：测试搜索功能
+  ux_test:                                        # 用户体验测试
+    enabled: True
+  performance_test:                               # 性能测试
+    enabled: False
+  security_test:                                  # 安全测试
+    enabled: False
+
+llm_config:                                       # 视觉模型配置，当前仅支持 OpenAI SDK 兼容格式
+  model: gpt-4.1                                  # 推荐使用
+  api_key: your_api_key
+  base_url: https://api.example.com/v1
+
+browser_config:
+  viewport: {"width": 1280, "height": 720}
+  headless: False                                 # Docker环境会自动覆盖为True
+  language: zh-CN
+  cookies: []
+```
+
+在配置和运行测试时，请注意以下重要事项：
+
+#### 1. 功能测试说明
+
+- **AI模式**：当在配置文件中指定生成测试用例的数量时，系统可能会根据实际测试情况进行代理重新规划和调整。这可能导致最终执行的测试用例数量与初始设定存在一定出入，以确保测试的准确性和有效性。
+
+- **Default模式**：功能测试的 `default` 模式主要验证UI元素的点击行为是否成功执行，包括按钮点击、链接跳转等基本交互功能。
+
+#### 2. 用户体验测试说明
+
+UX（用户体验）测试专注于评估网站的交互设计、可用性和用户友好程度。测试结果中包含的模型输出内容是基于用户体验最佳实践提供的改进建议，供开发和设计团队参考优化。
+
+## 查看结果
+
+在 `reports` 目录会生成本次测试的文件夹，打开其中的 HTML 报告即可查看结果。
+
+## RoadMap
+
+1. AI功能测试持续优化：提升覆盖率与准确性
+2. 功能遍历与页面校验：校验业务逻辑正确性与数据完整性
+3. 交互与可视化：用例可视化与本地服务实时展示推理过程
+4. 能力扩展：多模型接入与更多评估维度集成
+
+## 致谢
+
+- [natbot](https://github.com/nat/natbot): 通过GPT-3驱动浏览器
+- [Midscene.js](https://github.com/web-infra-dev/midscene/)：Web、Android、自动化和测试的AI Operator
+- [browser-use](https://github.com/browser-use/browser-use/)：用于浏览器控制的AI Agent
+
+## 开源许可证
+
+该项目采用 [Apache 2.0 开源许可证](LICENSE)。

config/config.yaml.example

@@ -0,0 +1,35 @@
+target:
+  url: https://baidu.com
+  description: Test search functionality
+  # max_concurrent_tests: 2  # Optional, default parallel 2
+
+test_config: # Test configuration
+  function_test:
+    enabled: True
+    type: ai  # default or ai
+    business_objectives: Test Baidu search functionality, generate 3 test cases
+  ux_test:
+    enabled: True
+  performance_test:
+    enabled: False
+  security_test:
+    enabled: False
+
+llm_config: # LLM configuration, currently only supports OpenAI SDK compatible format
+  model: gpt-4.1  # Recommended
+  api_key: your_api_key
+  base_url:  https://api.example.com/v1
+  temperature: 0.1   # Optional, default 0.1
+  # top_p: 0.9       # Optional, if not set, this parameter will not be passed
+
+browser_config:
+  viewport: {"width": 1280, "height": 720}
+  headless: False  # Docker environment will automatically override to True
+  language: zh-CN
+  cookies: []
+
+report:
+  language: en-US # zh-CN, en-US
+
+log:
+  level: info

package.json

@@ -0,0 +1,19 @@
+{
+  "name": "webqa-agent",
+  "version": "0.1.0",
+  "description": "WebQA Agent - 全自动网页评估测试",
+  "dependencies": {
+    "chrome-launcher": "^1.2.0",
+    "lighthouse": "^12.8.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "MigoXLab with ❤",
+  "license": "ISC"
+}

requirements.txt

@@ -0,0 +1,15 @@
+html2text
+jinja2
+langchain
+langchain-openai
+langgraph
+openai
+playwright==1.52.0
+pydantic
+pytest
+pytest-asyncio
+python-dotenv
+requests
+pillow
+gradio
+pyyaml

tests/conftest.py

@@ -0,0 +1,16 @@
+import pytest
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    parser.addoption(
+        '--url',
+        action='store',
+        default=None,
+        help='Target URL for crawling tests (overrides default)',
+    )
+
+
+@pytest.fixture
+def test_url(request: pytest.FixtureRequest) -> str:
+    # Priority: CLI --url > env WEBQA_TEST_URL > default example.com
+    return request.config.getoption('--url') or 'https://google.com'

tests/mocks/action_mocks.json

@@ -0,0 +1,576 @@
+{
+  "Tap": [
+    {
+      "url": "https://google.com",
+      "actions": [
+        {
+          "type": "Tap",
+          "locate": {"id": "11"}
+        }
+      ],
+      "id_map": {
+        "11": {
+            "node": "ref: <Node>",
+            "tagName": "a",
+            "className": "pHiOh",
+            "type": null,
+            "placeholder": null,
+            "innerText": "关于 Google",
+            "attributes": [
+              {
+                "name": "class",
+                "value": "pHiOh"
+              },
+              {
+                "name": "href",
+                "value": "https://about.google/?utm_source=google-ZZ&utm_medium=referral&utm_campaign=hp-footer&fg=1"
+              },
+              {
+                "name": "ping",
+                "value": "/url?sa=t&rct=j&source=webhp&url=https://about.google/%3Futm_source%3Dgoogle-ZZ%26utm_medium%3Dreferral%26utm_campaign%3Dhp-footer%26fg%3D1&ved=0ahUKEwiCiufHjYePAxXZEDQIHXHeNyEQkNQCCBQ&opi=89978449"
+              }
+            ],
+            "viewport": {
+              "x": 20,
+              "y": 670,
+              "width": 107.046875,
+              "height": 50
+            },
+            "center_x": 73.5234375,
+            "center_y": 695,
+            "isVisible": true,
+            "isInteractive": true,
+            "isValidText": false,
+            "isTopElement": true,
+            "isInViewport": true,
+            "isParentHighlighted": false,
+            "xpath": "/html[1]/body[1]/div[2]/div[7]/div[1]/div[1]/div[1]/a[1]",
+            "selector": "a.pHiOh",
+            "highlightIndex": 11
+          }
+      }
+    },
+    {
+      "url": "https://arxiv.org/search/",
+      "actions": [
+        {
+          "type": "Tap",
+          "locate": {"id": "18"}
+        },
+        {
+          "type": "Tap",
+          "locate": {"id": "14"}
+        }
+      ],
+      "id_map": {
+        "14": {
+          "node": "ref: <Node>",
+          "tagName": "button",
+          "className": "button is-link is-medium",
+          "type": null,
+          "placeholder": null,
+          "innerText": "Search",
+          "attributes": [
+            {
+              "name": "class",
+              "value": "button is-link is-medium"
+            }
+          ],
+          "viewport": {
+            "x": 1103.828125,
+            "y": 280.203125,
+            "width": 83.671875,
+            "height": 39.375
+          },
+          "center_x": 1145.6640625,
+          "center_y": 299.890625,
+          "isVisible": true,
+          "isInteractive": true,
+          "isValidText": false,
+          "isTopElement": true,
+          "isInViewport": true,
+          "isParentHighlighted": false,
+          "xpath": "/html[1]/body[1]/main[1]/div[2]/form[1]/div[1]/div[3]/button[1]",
+          "selector": "button.button.is-link.is-medium",
+          "highlightIndex": 14
+        },
+        "18": {
+          "node": "ref: <Node>",
+          "tagName": "input",
+          "className": null,
+          "type": "radio",
+          "placeholder": null,
+          "innerText": "hide",
+          "attributes": [
+            {
+              "name": "id",
+              "value": "abstracts-1"
+            },
+            {
+              "name": "name",
+              "value": "abstracts"
+            },
+            {
+              "name": "type",
+              "value": "radio"
+            },
+            {
+              "name": "value",
+              "value": "hide"
+            },
+            {
+              "name": "style",
+              "value": ""
+            }
+          ],
+          "viewport": {
+            "x": 186.8125,
+            "y": 330.078125,
+            "width": 13,
+            "height": 13
+          },
+          "center_x": 193.3125,
+          "center_y": 336.578125,
+          "isVisible": true,
+          "isInteractive": true,
+          "isValidText": false,
+          "isTopElement": true,
+          "isInViewport": true,
+          "isParentHighlighted": true,
+          "xpath": "//*[@id=\"abstracts-1\"]",
+          "selector": "input#abstracts-1",
+          "highlightIndex": 18
+        }
+      }
+    }
+  ],
+  "Hover": [
+    {
+      "url": "https://demo.chat-sdk.dev/",
+      "actions": [
+        {
+          "type": "Hover",
+          "locate": {"id": "6"}
+        }
+      ],
+      "id_map": {
+        "6": {
+          "node": "ref: <Node>",
+          "tagName": "button",
+          "className": "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 border border-input bg-background hover:bg-accent hover:text-accent-foreground h-10 py-2 order-2 md:order-1 md:px-2 px-2 md:h-fit ml-auto md:ml-0",
+          "type": null,
+          "placeholder": null,
+          "innerText": "New Chat",
+          "attributes": [
+            {
+              "name": "class",
+              "value": "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 border border-input bg-background hover:bg-accent hover:text-accent-foreground h-10 py-2 order-2 md:order-1 md:px-2 px-2 md:h-fit ml-auto md:ml-0"
+            },
+            {
+              "name": "data-state",
+              "value": "closed"
+            }
+          ],
+          "viewport": {
+            "x": 50,
+            "y": 6,
+            "width": 34,
+            "height": 34
+          },
+          "center_x": 67,
+          "center_y": 23,
+          "isVisible": true,
+          "isInteractive": true,
+          "isValidText": false,
+          "isTopElement": true,
+          "isInViewport": true,
+          "isParentHighlighted": false,
+          "xpath": "/html[1]/body[1]/div[1]/main[1]/div[1]/header[1]/button[2]",
+          "selector": "button.inline-flex.items-center.justify-center.gap-2.whitespace-nowrap.rounded-md.text-sm.font-medium.ring-offset-background.transition-colors.focus-visible:outline-none.focus-visible:ring-2.focus-visible:ring-ring.focus-visible:ring-offset-2.disabled:pointer-events-none.disabled:opacity-50.[&_svg]:pointer-events-none.[&_svg]:size-4.[&_svg]:shrink-0.border.border-input.bg-background.hover:bg-accent.hover:text-accent-foreground.h-10.py-2.order-2.md:order-1.md:px-2.px-2.md:h-fit.ml-auto.md:ml-0",
+          "highlightIndex": 6
+        }
+      }
+    }
+  ],
+  "Input": [
+    {
+      "url": "https://demo.chat-sdk.dev/",
+      "actions": [
+        {
+          "type": "Input",
+          "locate": {"id": "15"},
+          "param": {
+            "value": "test input",
+            "clear_before_type": true
+          }
+        }
+      ],
+      "id_map": {
+        "15": {
+          "node": "ref: <Node>",
+          "tagName": "textarea",
+          "className": "flex w-full border border-input px-3 py-2 text-base ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 md:text-sm min-h-[24px] max-h-[calc(75dvh)] overflow-hidden resize-none rounded-2xl !text-base bg-muted pb-10 dark:border-zinc-700",
+          "type": null,
+          "placeholder": "Send a message...",
+          "innerText": "",
+          "attributes": [
+            {
+              "name": "class",
+              "value": "flex w-full border border-input px-3 py-2 text-base ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 md:text-sm min-h-[24px] max-h-[calc(75dvh)] overflow-hidden resize-none rounded-2xl !text-base bg-muted pb-10 dark:border-zinc-700"
+            },
+            {
+              "name": "data-testid",
+              "value": "multimodal-input"
+            },
+            {
+              "name": "placeholder",
+              "value": "Send a message..."
+            },
+            {
+              "name": "rows",
+              "value": "2"
+            },
+            {
+              "name": "autofocus",
+              "value": ""
+            },
+            {
+              "name": "style",
+              "value": "height: 98px;"
+            }
+          ],
+          "viewport": {
+            "x": 272,
+            "y": 598,
+            "width": 736,
+            "height": 98
+          },
+          "center_x": 640,
+          "center_y": 647,
+          "isVisible": true,
+          "isInteractive": true,
+          "isValidText": false,
+          "isTopElement": true,
+          "isInViewport": true,
+          "isParentHighlighted": false,
+          "xpath": "/html[1]/body[1]/div[1]/main[1]/div[1]/form[1]/div[1]/textarea[1]",
+          "selector": "textarea.flex.w-full.border.border-input.px-3.py-2.text-base.ring-offset-background.placeholder:text-muted-foreground.focus-visible:outline-none.focus-visible:ring-2.focus-visible:ring-ring.focus-visible:ring-offset-2.disabled:cursor-not-allowed.disabled:opacity-50.md:text-sm.min-h-[24px].max-h-[calc(75dvh)].overflow-hidden.resize-none.rounded-2xl.!text-base.bg-muted.pb-10.dark:border-zinc-700",
+          "highlightIndex": 15
+        }
+      }
+    },
+    {
+      "url": "https://arxiv.org/search/",
+      "actions": [
+        {
+          "type": "Input",
+          "locate": {"id": "12"},
+          "param": {
+            "value": "test input",
+            "clear_before_type": true
+          }
+        }
+      ],
+      "id_map": {
+        "12": {
+          "node": "ref: <Node>",
+          "tagName": "input",
+          "className": "input is-medium",
+          "type": "text",
+          "placeholder": "Search term...",
+          "innerText": "",
+          "attributes": [
+            {
+              "name": "class",
+              "value": "input is-medium"
+            },
+            {
+              "name": "id",
+              "value": "query"
+            },
+            {
+              "name": "name",
+              "value": "query"
+            },
+            {
+              "name": "placeholder",
+              "value": "Search term..."
+            },
+            {
+              "name": "type",
+              "value": "text"
+            },
+            {
+              "name": "value",
+              "value": ""
+            },
+            {
+              "name": "style",
+              "value": ""
+            }
+          ],
+          "viewport": {
+            "x": 77.5,
+            "y": 280.203125,
+            "width": 825.640625,
+            "height": 39.375
+          },
+          "center_x": 490.3203125,
+          "center_y": 299.890625,
+          "isVisible": true,
+          "isInteractive": true,
+          "isValidText": false,
+          "isTopElement": true,
+          "isInViewport": true,
+          "isParentHighlighted": false,
+          "xpath": "//*[@id=\"query\"]",
+          "selector": "input#query",
+          "highlightIndex": 12
+        }
+      }
+    }
+  ],
+  "Scroll": [
+    {
+      "url": "https://arxiv.org/search/",
+      "actions": [
+        {
+          "type": "Scroll",
+          "locate": null,
+          "param": {
+            "direction": "down",
+            "scrollType": "untilBottom",
+            "distance": null
+          }
+        },
+        {
+          "type": "Scroll",
+          "locate": null,
+          "param": {
+            "direction": "up",
+            "scrollType": "untilTop",
+            "distance": null
+          }
+        }
+      ],
+      "id_map": {}
+    },
+    {
+      "url": "https://arxiv.org/list/astro-ph/new",
+      "actions": [
+        {
+          "type": "Scroll",
+          "locate": null,
+          "param": {
+            "direction": "down",
+            "scrollType": "once"
+          }
+        },
+        {
+          "type": "Scroll",
+          "locate": null,
+          "param": {
+            "direction": "down",
+            "scrollType": "once",
+            "distance": 400
+          }
+        },
+        {
+          "type": "Scroll",
+          "locate": null,
+          "param": {
+            "direction": "up",
+            "scrollType": "once",
+            "distance": 200
+          }
+        }
+      ],
+      "id_map": {}
+    }
+  ],
+  "SelectDropdown": [
+    {
+      "url": "https://demo.chat-sdk.dev/",
+      "actions": [
+        {
+          "type": "Tap",
+          "locate": {"id": "3"}
+        },
+        {
+          "type": "SelectDropdown",
+          "locate": {"dropdown_id": "3", "option_id": "5"},
+          "param": {
+            "selection_path": "Reasoning model"
+          }
+        }
+      ],
+      "id_map": {
+        "3": {
+          "node": "ref: <Node>",
+          "tagName": "button",
+          "className": "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 border border-input bg-background hover:bg-accent hover:text-accent-foreground h-10 px-4 py-2 w-fit data-[state=open]:bg-accent data-[state=open]:text-accent-foreground order-1 md:order-2 md:px-2 md:h-[34px]",
+          "type": "button",
+          "placeholder": null,
+          "innerText": "Chat model",
+          "attributes": [
+            {
+              "name": "class",
+              "value": "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 border border-input bg-background hover:bg-accent hover:text-accent-foreground h-10 px-4 py-2 w-fit data-[state=open]:bg-accent data-[state=open]:text-accent-foreground order-1 md:order-2 md:px-2 md:h-[34px]"
+            },
+            {
+              "name": "data-testid",
+              "value": "model-selector"
+            },
+            {
+              "name": "type",
+              "value": "button"
+            },
+            {
+              "name": "id",
+              "value": "radix-«R6l7lelb»"
+            },
+            {
+              "name": "aria-haspopup",
+              "value": "menu"
+            },
+            {
+              "name": "aria-expanded",
+              "value": "false"
+            },
+            {
+              "name": "data-state",
+              "value": "closed"
+            }
+          ],
+          "viewport": {
+            "x": 92,
+            "y": 6,
+            "width": 117.328125,
+            "height": 34
+          },
+          "center_x": 150.6640625,
+          "center_y": 23,
+          "isVisible": true,
+          "isInteractive": true,
+          "isValidText": false,
+          "isTopElement": true,
+          "isInViewport": true,
+          "isParentHighlighted": false,
+          "xpath": "//*[@id=\"radix-«R6l7lelb»\"]",
+          "selector": "button#radix-«R6l7lelb»",
+          "highlightIndex": 3
+        },
+        "5": {
+          "node": "ref: <Node>",
+          "tagName": "button",
+          "className": "relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 gap-4 group/item flex flex-row justify-between items-center w-full",
+          "type": "button",
+          "innerText": "Reasoning model\nUses advanced reasoning",
+          "attributes": [{
+            "name": "type",
+            "value": "button"
+          }, {
+            "name": "class",
+            "value": "relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 gap-4 group/item flex flex-row justify-between items-center w-full"
+          }, {
+            "name": "role",
+            "value": "menuitem"
+          }, {
+            "name": "data-testid",
+            "value": "model-selector-item-chat-model-reasoning"
+          }, {
+            "name": "data-active",
+            "value": "false"
+          }, {
+            "name": "tabindex",
+            "value": "-1"
+          }, {
+            "name": "data-orientation",
+            "value": "vertical"
+          }, {
+            "name": "data-radix-collection-item",
+            "value": ""
+          }],
+          "viewport": {
+            "x": 97,
+            "y": 101,
+            "width": 290,
+            "height": 52
+          },
+          "center_x": 242,
+          "center_y": 127,
+          "xpath": "/html[1]/body[1]/div[2]/div[1]/button[2]",
+          "selector": "button.relative.flex.cursor-default.select-none.items-center.gap-2.rounded-sm.px-2.py-1.5.text-sm.outline-none.transition-colors.focus:bg-accent.focus:text-accent-foreground.data-[disabled]:pointer-events-none.data-[disabled]:opacity-50.[&_svg]:pointer-events-none.[&_svg]:size-4.[&_svg]:shrink-0.gap-4.group/item.flex-row.justify-between.w-full",
+          "highlightIndex": 3
+        }
+      }
+    },
+    {
+      "name": "local dropdowns page (native, ant-select, ant-cascader)",
+      "url": "__LOCAL_DROPDOWN_PAGE__",
+      "id_map": {
+        "13":  { "center_x": 210, "center_y": 116 },
+        "101": { "center_x": 210, "center_y": 217 },
+        "301": { "center_x": 210, "center_y": 317 }
+      },
+      "actions": [
+        { "type": "SelectDropdown", "locate": { "dropdown_id": "13" },  "param": { "selection_path": "Title" } },
+        { "type": "SelectDropdown", "locate": { "dropdown_id": "101" }, "param": { "selection_path": "Reasoning model" } },
+        { "type": "SelectDropdown", "locate": { "dropdown_id": "301" }, "param": { "selection_path": ["Asia", "China", "Beijing"] } }
+      ]
+    },
+    {
+      "url": "https://arxiv.org/search/",
+      "actions": [
+        {
+          "type": "SelectDropdown",
+          "locate": {"dropdown_id": "13"},
+          "param": {
+            "selection_path": "Title"
+          }
+        }
+      ],
+      "id_map": {
+        "13": {
+          "node": "ref: <Node>",
+          "tagName": "select",
+          "className": "is-medium",
+          "type": null,
+          "placeholder": null,
+          "innerText": "All fields\nTitle\nAuthor(s)\nAbstract\nComments\nJournal reference\nACM classification\nMSC classification\nReport number\narXiv identifier\nDOI\nORCID\nLicense (URI)\narXiv author ID\nHelp pages\nFull text",
+          "attributes": [
+            {
+              "name": "class",
+              "value": "is-medium"
+            },
+            {
+              "name": "id",
+              "value": "searchtype"
+            },
+            {
+              "name": "name",
+              "value": "searchtype"
+            }
+          ],
+          "viewport": {
+            "x": 902.140625,
+            "y": 280.203125,
+            "width": 202.6875,
+            "height": 39.375
+          },
+          "center_x": 1003.484375,
+          "center_y": 299.890625,
+          "isVisible": true,
+          "isInteractive": true,
+          "isValidText": false,
+          "isTopElement": true,
+          "isInViewport": true,
+          "isParentHighlighted": false,
+          "xpath": "//*[@id=\"searchtype\"]",
+          "selector": "select#searchtype",
+          "highlightIndex": 13
+        }
+      }
+    }
+  ]
+}

tests/mocks/actions_negative_mocks.json

@@ -0,0 +1,89 @@
+{
+  "SelectDropdown_Negative": [
+    {
+      "name": "native select: option not found",
+      "url": "__LOCAL_DROPDOWN_PAGE__",
+      "id_map": { "13": { "center_x": 210, "center_y": 116 } },
+      "actions": [
+        {
+          "type": "SelectDropdown",
+          "locate": { "dropdown_id": "13" },
+          "param": { "selection_path": "Non-Existing-Option" }
+        }
+      ]
+    },
+    {
+      "name": "ant-select: option not found",
+      "url": "__LOCAL_DROPDOWN_PAGE__",
+      "id_map": { "101": { "center_x": 210, "center_y": 217 } },
+      "actions": [
+        {
+          "type": "SelectDropdown",
+          "locate": { "dropdown_id": "101" },
+          "param": { "selection_path": "Nonexistent Model" }
+        }
+      ]
+    },
+    {
+      "name": "ant-select: option_id missing in buffer, fallback still not found",
+      "url": "__LOCAL_DROPDOWN_PAGE__",
+      "id_map": { "101": { "center_x": 210, "center_y": 217 } },
+      "actions": [
+        {
+          "type": "SelectDropdown",
+          "locate": { "dropdown_id": "101", "option_id": "9999" },
+          "param": { "selection_path": "Nonexistent Model" }
+        }
+      ]
+    },
+    {
+      "name": "cascader: level 1 option not found",
+      "url": "__LOCAL_DROPDOWN_PAGE__",
+      "id_map": { "301": { "center_x": 210, "center_y": 317 } },
+      "actions": [
+        {
+          "type": "SelectDropdown",
+          "locate": { "dropdown_id": "301" },
+          "param": { "selection_path": ["Asia", "Korea"] }
+        }
+      ]
+    },
+    {
+      "name": "cascader: exceeds maximum levels",
+      "url": "__LOCAL_DROPDOWN_PAGE__",
+      "id_map": { "301": { "center_x": 210, "center_y": 317 } },
+      "actions": [
+        {
+          "type": "SelectDropdown",
+          "locate": { "dropdown_id": "301" },
+          "param": { "selection_path": ["Asia", "China", "Beijing", "Street-Not-Exists"] }
+        }
+      ]
+    }
+  ],
+  "Scroll_Negative": [
+    {
+      "url": "https://arxiv.org/list/astro-ph/new",
+      "actions": [
+        {
+          "type": "Scroll",
+          "locate": null,
+          "param": {
+            "direction": "right",
+            "scrollType": "once"
+          }
+        },
+        {
+          "type": "Scroll",
+          "locate": null,
+          "param": {
+            "direction": "down",
+            "scrollType": "untilRight",
+            "distance": null
+          }
+        }
+      ],
+      "id_map": {}
+    }
+  ]
+}

tests/test_action_executor.py

@@ -0,0 +1,300 @@
+import sys
+from pathlib import Path
+
+# Add project root to Python path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import asyncio
+import json
+import os
+import pathlib
+from datetime import datetime
+
+import pytest
+from playwright.async_api import async_playwright
+
+from webqa_agent.actions.action_executor import ActionExecutor
+from webqa_agent.actions.action_handler import ActionHandler
+
+# pytest tests/test_action_executor.py::TestActionExecutor::test_click_action -v -s
+# pytest tests/test_action_executor.py::TestActionExecutor -v -s
+
+
+# Local test pages directory and placeholder map for extensibility
+LOCAL_PAGES_DIR = pathlib.Path(__file__).parent / 'test_pages'
+PLACEHOLDER_LOCAL_PAGES = {
+    '__LOCAL_DROPDOWN_PAGE__': 'dropdown_components.html',
+}
+
+MOCKS_PATH = pathlib.Path(__file__).parent / 'mocks' / 'action_mocks.json'
+MOCKS_PATH_NEGATIVE = pathlib.Path(__file__).parent / 'mocks' / 'actions_negative_mocks.json'
+
+
+class TestActionExecutor:
+    # Results directories for action tests
+    results_dir = pathlib.Path(__file__).parent / 'actions_test_results'
+    screenshots_dir = results_dir / 'screenshots'
+
+    # Global navigation settings
+    GOTO_WAIT_UNTIL = 'networkidle'
+    GOTO_TIMEOUT_MS = 30000
+
+    async def setup_method(self):
+        """Setup method called before each test."""
+        # Ensure directories exist
+        self.results_dir.mkdir(parents=True, exist_ok=True)
+        self.screenshots_dir.mkdir(parents=True, exist_ok=True)
+        self.playwright = await async_playwright().start()
+        self.browser = await self.playwright.chromium.launch(headless=False)
+        self.context = await self.browser.new_context(
+            viewport={'width': 1280, 'height': 720},
+        )
+        self.page = await self.context.new_page()
+
+        # Initialize action handler and executor
+        self.action_handler = ActionHandler()
+        await self.action_handler.initialize(self.page)
+        self.action_executor = ActionExecutor(self.action_handler)
+        await self.action_executor.initialize()
+
+    async def teardown_method(self):
+        """Teardown method called after each test."""
+        if self.context:
+            await self.context.close()
+        if self.browser:
+            await self.browser.close()
+        if self.playwright:
+            await self.playwright.stop()
+
+    def resolve_url(self, url: str) -> str:
+        if url in PLACEHOLDER_LOCAL_PAGES:
+            target = LOCAL_PAGES_DIR / PLACEHOLDER_LOCAL_PAGES[url]
+            return target.resolve().as_uri()
+
+        generic_prefix = '__LOCAL_PAGE__:'
+        if url.startswith(generic_prefix):
+            rel = url[len(generic_prefix) :].strip()
+            rel_path = pathlib.Path(rel)
+            if rel_path.is_absolute() or '..' in rel_path.parts:
+                raise ValueError(f'Invalid local page path: {rel}')
+            target = LOCAL_PAGES_DIR / rel_path
+            return target.resolve().as_uri()
+
+        return url
+
+    async def navigate(self, url: str) -> None:
+        """Navigate to a resolved URL using global navigation settings."""
+        await self.page.goto(
+            self.resolve_url(url),
+            wait_until=self.GOTO_WAIT_UNTIL,
+            timeout=self.GOTO_TIMEOUT_MS,
+        )
+
+    def get_timestamp(self) -> str:
+        return datetime.now().strftime('%Y%m%d_%H%M%S')
+
+    async def take_before_screenshot(self, url: str, param_name: str) -> str:
+        """Take screenshot before action."""
+        timestamp = self.get_timestamp()
+        safe_url = url.replace('://', '_').replace('/', '_')
+        screenshot_path = self.screenshots_dir / f'{param_name}_{safe_url}_before_{timestamp}.png'
+        await self.page.screenshot(path=str(screenshot_path), full_page=False)
+        return str(screenshot_path)
+
+    async def take_after_screenshot(self, url: str, param_name: str) -> str:
+        """Take screenshot after action."""
+        timestamp = self.get_timestamp()
+        safe_url = url.replace('://', '_').replace('/', '_')
+        screenshot_path = self.screenshots_dir / f'{param_name}_{safe_url}_after_{timestamp}.png'
+        await self.page.screenshot(path=str(screenshot_path), full_page=False)
+        return str(screenshot_path)
+
+    @pytest.mark.asyncio
+    async def test_click_action(self):
+        """Test click action."""
+        await self.setup_method()
+        try:
+            # Load mocks and iterate
+            with open(MOCKS_PATH, 'r', encoding='utf-8') as f:
+                mocks = json.load(f)
+            tap_cases = mocks.get('Tap', [])
+            assert len(tap_cases) > 0
+            for i, case in enumerate(tap_cases):
+                await self.navigate(case['url'])
+                self.action_handler.set_page_element_buffer(case['id_map'])
+                before_path = await self.take_before_screenshot(case['url'], 'click')
+
+                # Execute click action
+                for action in case['actions']:
+                    result = await self.action_executor.execute(action)
+                    await asyncio.sleep(2)
+                    elementid = action['locate']['id']
+                    after_path = await self.take_after_screenshot(case['url'], f'click_{elementid}')
+
+                # Verify results
+                assert result['success'] is True
+                assert os.path.exists(before_path)
+                assert os.path.exists(after_path)
+
+        finally:
+            await self.teardown_method()
+
+    @pytest.mark.asyncio
+    async def test_hover_action(self):
+        """Test hover action."""
+        await self.setup_method()
+        try:
+            with open(MOCKS_PATH, 'r', encoding='utf-8') as f:
+                mocks = json.load(f)
+            hover_cases = mocks.get('Hover', [])
+            assert len(hover_cases) > 0
+            for i, case in enumerate(hover_cases):
+                await self.navigate(case['url'])
+                self.action_handler.set_page_element_buffer(case['id_map'])
+                before_path = await self.take_before_screenshot(case['url'], 'hover')
+
+                for action in case['actions']:
+                    result = await self.action_executor.execute(action)
+                    await asyncio.sleep(2)
+                    elementid = action['locate']['id']
+                    after_path = await self.take_after_screenshot(case['url'], f'hover_{elementid}')
+
+                # Verify results
+                assert result['success'] is True
+                assert os.path.exists(before_path)
+                assert os.path.exists(after_path)
+
+        finally:
+            await self.teardown_method()
+
+    @pytest.mark.asyncio
+    async def test_input_action(self):
+        """Test input action."""
+        await self.setup_method()
+        try:
+            with open(MOCKS_PATH, 'r', encoding='utf-8') as f:
+                mocks = json.load(f)
+            input_cases = mocks.get('Input', [])
+            assert len(input_cases) > 0
+            for i, case in enumerate(input_cases):
+                await self.navigate(case['url'])
+                self.action_handler.set_page_element_buffer(case['id_map'])
+                before_path = await self.take_before_screenshot(case['url'], 'input')
+
+                for action in case['actions']:
+                    result = await self.action_executor.execute(action)
+                    await asyncio.sleep(2)
+                    elementid = action['locate']['id']
+                    after_path = await self.take_after_screenshot(case['url'], f'input_{elementid}')
+
+                # Verify results
+                assert result['success'] is True
+                assert os.path.exists(before_path)
+                assert os.path.exists(after_path)
+
+        finally:
+            await self.teardown_method()
+
+    @pytest.mark.asyncio
+    async def test_scroll_action(self):
+        """Test scroll action."""
+        await self.setup_method()
+        try:
+            with open(MOCKS_PATH, 'r', encoding='utf-8') as f:
+                mocks = json.load(f)
+            scroll_cases = mocks.get('Scroll', [])
+            assert len(scroll_cases) > 0
+            for i, case in enumerate(scroll_cases):
+                await self.navigate(case['url'])
+                self.action_handler.set_page_element_buffer(case['id_map'])
+                before_path = await self.take_before_screenshot(case['url'], f'scroll_{i}')
+
+                for j, action in enumerate(case['actions']):
+                    result = await self.action_executor.execute(action)
+                    await asyncio.sleep(2)
+                    after_path = await self.take_after_screenshot(case['url'], f'scroll_{i}_{j}')
+
+                assert result['success'] is True
+                assert os.path.exists(before_path)
+                assert os.path.exists(after_path)
+
+        finally:
+            await self.teardown_method()
+
+    @pytest.mark.asyncio
+    async def test_select_dropdown_action(self):
+        """Test select dropdown action."""
+        await self.setup_method()
+        try:
+            with open(MOCKS_PATH, 'r', encoding='utf-8') as f:
+                mocks = json.load(f)
+            select_dropdown_cases = mocks.get('SelectDropdown', [])
+            assert len(select_dropdown_cases) > 0
+            for i, case in enumerate(select_dropdown_cases):
+                await self.navigate(case['url'])
+                self.action_handler.set_page_element_buffer(case['id_map'])
+                before_path = await self.take_before_screenshot(case['url'], f'select_dropdown_{i}')
+
+                for j, action in enumerate(case['actions']):
+                    result = await self.action_executor.execute(action)
+                    print(f"[SelectDropdown][{case.get('name','case')}]: {result.get('message','')}\n")
+                    await asyncio.sleep(5)
+                    after_path = await self.take_after_screenshot(case['url'], f'select_dropdown_{j}')
+
+                assert result['success'] is True
+                assert os.path.exists(before_path)
+                assert os.path.exists(after_path)
+
+        finally:
+            await self.teardown_method()
+
+    @pytest.mark.asyncio
+    async def test_select_dropdown_action_negative(self):
+        """Negative tests for select dropdown action: expect success == False and print message"""
+        await self.setup_method()
+        try:
+            with open(MOCKS_PATH_NEGATIVE, 'r', encoding='utf-8') as f:
+                mocks = json.load(f)
+            neg_cases = mocks.get('SelectDropdown_Negative', [])
+            assert len(neg_cases) > 0
+
+            for i, case in enumerate(neg_cases):
+                # about:blank is fine without networkidle wait
+                await self.navigate(case['url'])
+                self.action_handler.set_page_element_buffer(case.get('id_map', {}))
+
+                for action in case['actions']:
+                    result = await self.action_executor.execute(action)
+                    print(f"[SelectDropdown_Negative][{case.get('name','case')}]: {result.get('message','')}\n")
+                    assert result.get('success') is False
+
+        finally:
+            await self.teardown_method()
+
+    @pytest.mark.asyncio
+    async def test_scroll_action_negative(self):
+        """Negative tests for scroll action: expect success == False and print message"""
+        await self.setup_method()
+        try:
+            with open(MOCKS_PATH_NEGATIVE, 'r', encoding='utf-8') as f:
+                mocks = json.load(f)
+            scroll_neg_cases = mocks.get('Scroll_Negative', [])
+            assert len(scroll_neg_cases) > 0
+
+            for i, case in enumerate(scroll_neg_cases):
+                await self.page.goto(self.resolve_url(case['url']), wait_until='networkidle', timeout=30000)
+                self.action_handler.set_page_element_buffer(case['id_map'])
+                before_path = await self.take_before_screenshot(case['url'], f'scroll_{i}')
+
+                for j, action in enumerate(case['actions']):
+                    result = await self.action_executor.execute(action)
+                    print(f"[Scroll_Negative][{case.get('name','case')}]: {result.get('message','')}\n")
+                    await asyncio.sleep(2)
+                    after_path = await self.take_after_screenshot(case['url'], f'scroll_{i}_{j}')
+
+                assert result['success'] is False
+                assert os.path.exists(before_path)
+                assert os.path.exists(after_path)
+
+        finally:
+            await self.teardown_method()

tests/test_crawler.py

@@ -0,0 +1,299 @@
+import json
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List
+
+# Add project root to Python path
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+import pytest
+from playwright.async_api import async_playwright
+
+from webqa_agent.crawler.crawl import CrawlHandler
+from webqa_agent.crawler.deep_crawler import DeepCrawler
+
+# pytest tests/test_crawler.py::TestCrawler::test_highlight_crawl -v -s --url https://google.com
+# pytest tests/test_crawler.py -v -s --url https://google.com
+
+
+class TestCrawler:
+    """Test suite for web crawling functionality with different parameters."""
+
+    # Default test URLs (can be overridden)
+    DEFAULT_TEST_URLS = 'https://google.com'
+
+    # Different crawl parameter combinations to test
+    CRAWL_PARAMS = [
+        {'name': 'highlight_crawl', 'highlight': True, 'highlight_text': False, 'viewport_only': True},
+        {'name': 'text_highlight_crawl', 'highlight': True, 'highlight_text': True, 'viewport_only': True},
+        {'name': 'viewport_highlight_crawl', 'highlight': True, 'highlight_text': False, 'viewport_only': True},
+    ]
+
+    # Directories (class attributes; accessible via self)
+    test_results_dir = Path(__file__).parent / 'crawler_test_results'
+    screenshots_dir = test_results_dir / 'screenshots'
+    id_maps_dir = test_results_dir / 'id_maps'
+    crawl_data_dir = test_results_dir / 'crawl_data'
+    clean_id_maps_dir = test_results_dir / 'clean_id_maps'
+
+    async def setup_method(self):
+        """Setup method called before each test."""
+        # Ensure directories exist
+        self.test_results_dir.mkdir(parents=True, exist_ok=True)
+        self.screenshots_dir.mkdir(parents=True, exist_ok=True)
+        self.id_maps_dir.mkdir(parents=True, exist_ok=True)
+        self.crawl_data_dir.mkdir(parents=True, exist_ok=True)
+        self.clean_id_maps_dir.mkdir(parents=True, exist_ok=True)
+        self.playwright = await async_playwright().start()
+        self.browser = await self.playwright.chromium.launch(
+            headless=False,
+            args=[
+                '--no-sandbox',
+                '--disable-setuid-sandbox',
+                '--disable-gpu',
+                '--force-device-scale-factor=1',
+            ],
+        )
+        self.context = await self.browser.new_context(
+            viewport={'width': 1280, 'height': 720},
+        )
+        self.page = await self.context.new_page()
+
+        # Set default timeout
+        self.page.set_default_navigation_timeout(30000)
+        self.page.set_default_timeout(30000)
+
+    async def teardown_method(self):
+        """Teardown method called after each test."""
+        if self.context:
+            await self.context.close()
+        if self.browser:
+            await self.browser.close()
+        if self.playwright:
+            await self.playwright.stop()
+
+    def get_timestamp(self) -> str:
+        """Get timestamp for file naming."""
+        return datetime.now().strftime('%Y%m%d_%H%M%S')
+
+    async def take_before_screenshot(self, url: str, param_name: str) -> str:
+        """Take screenshot before crawling."""
+        timestamp = self.get_timestamp()
+        safe_url = url.replace('://', '_').replace('/', '_')
+        screenshot_path = self.screenshots_dir / f'{param_name}_{safe_url}_before_{timestamp}.png'
+        await self.page.screenshot(path=str(screenshot_path), full_page=True)
+        return str(screenshot_path)
+
+    async def take_after_screenshot(self, url: str, param_name: str) -> str:
+        """Take screenshot after crawling (with possible highlights)"""
+        timestamp = self.get_timestamp()
+        screenshot_path = (
+            self.screenshots_dir / f"{param_name}_{url.replace('://', '_').replace('/', '_')}_after_{timestamp}.png"
+        )
+        await self.page.screenshot(path=str(screenshot_path), full_page=True)
+        return str(screenshot_path)
+
+    def save_id_map(self, url: str, param_name: str, id_map: Dict[str, Any]) -> str:
+        """Save ID map to JSON file."""
+        timestamp = self.get_timestamp()
+        id_map_path = (
+            self.id_maps_dir / f"{param_name}_{url.replace('://', '_').replace('/', '_')}_id_map_{timestamp}.json"
+        )
+
+        with open(id_map_path, 'w', encoding='utf-8') as f:
+            json.dump(id_map, f, ensure_ascii=False, indent=2)
+
+        return str(id_map_path)
+
+    def save_clean_id_map(self, url: str, param_name: str, clean_id_map: Dict[str, Any]) -> str:
+        """Save clean ID map to JSON file."""
+        timestamp = self.get_timestamp()
+        clean_id_map_path = (
+            self.clean_id_maps_dir / f"{param_name}_{url.replace('://', '_').replace('/', '_')}_clean_id_map_{timestamp}.json"
+        )
+
+        with open(clean_id_map_path, 'w', encoding='utf-8') as f:
+            json.dump(clean_id_map, f, ensure_ascii=False, indent=2)
+
+        return str(clean_id_map_path)
+
+    def save_crawl_data(self, url: str, param_name: str, crawl_data: Dict[str, Any]) -> str:
+        """Save crawl data to JSON file."""
+        timestamp = self.get_timestamp()
+        crawl_data_path = (
+            self.crawl_data_dir
+            / f"{param_name}_{url.replace('://', '_').replace('/', '_')}_crawl_data_{timestamp}.json"
+        )
+
+        with open(crawl_data_path, 'w', encoding='utf-8') as f:
+            json.dump(crawl_data, f, ensure_ascii=False, indent=2)
+
+        return str(crawl_data_path)
+
+    def save_test_summary(self, test_results: List[Dict[str, Any]]) -> str:
+        """Save test summary to JSON file."""
+        timestamp = self.get_timestamp()
+        summary_path = self.test_results_dir / f'test_summary_{timestamp}.json'
+
+        with open(summary_path, 'w', encoding='utf-8') as f:
+            json.dump(test_results, f, ensure_ascii=False, indent=2)
+
+        return str(summary_path)
+
+    async def crawl_single_url(self, url: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Crawl a single URL with specified parameters using the current
+        page/context."""
+        await self.page.goto(url, wait_until='networkidle')
+
+        # Take before screenshot
+        before_screenshot = await self.take_before_screenshot(url, params['name'])
+
+        # Initialize crawler and perform crawling
+        crawler = DeepCrawler(self.page)
+        crawl_result = await crawler.crawl(
+            page=self.page,
+            highlight=params['highlight'],
+            highlight_text=params['highlight_text'],
+            viewport_only=params['viewport_only'],
+        )
+        crawl_data = crawl_result.element_tree
+        id_map = crawl_result.raw_dict()
+        clean_id_map = crawl_result.clean_dict()
+
+        # Take after screenshot
+        after_screenshot = await self.take_after_screenshot(url, params['name'])
+
+        # Save results
+        id_map_path = self.save_id_map(url, params['name'], id_map)
+        clean_id_map_path = self.save_clean_id_map(url, params['name'], clean_id_map)
+        crawl_data_path = self.save_crawl_data(url, params['name'], crawl_data)
+
+        # Remove markers if highlights were added
+        if params['highlight']:
+            await crawler.remove_marker(self.page)
+
+        return {
+            'url': url,
+            'parameters': params,
+            'results': {
+                'before_screenshot': before_screenshot,
+                'after_screenshot': after_screenshot,
+                'id_map_path': id_map_path,
+                'clean_id_map_path': clean_id_map_path,
+                'crawl_data_path': crawl_data_path,
+                'success': True,
+            },
+        }
+
+    @pytest.mark.asyncio
+    async def test_crawl_link(self, request):
+        """Test integration with CrawlHandler for link extraction."""
+        await self.setup_method()
+
+        try:
+            # Resolve URL from CLI/env or default
+            test_url = request.config.getoption('--url') or self.DEFAULT_TEST_URLS
+
+            # Navigate to the test URL
+            await self.page.goto(test_url, wait_until='networkidle')
+
+            # Take before screenshot
+            before_screenshot = await self.take_before_screenshot(test_url, 'crawl_handler')
+
+            # Initialize crawl handler
+            crawl_handler = CrawlHandler(test_url)
+
+            # Extract links
+            links = await crawl_handler.extract_links(self.page)
+            print(f'🔗 Found {len(links)} links')
+
+            # Get clickable elements using crawl handler
+            clickable_elements = await crawl_handler.clickable_elements_detection(self.page)
+            print(f'🖱️ Found {len(clickable_elements)} clickable elements')
+
+            # Take after screenshot
+            after_screenshot = await self.take_after_screenshot(test_url, 'crawl_handler')
+
+            # Save results
+            results = {
+                'url': test_url,
+                'links': links,
+                'clickable_elements': clickable_elements,
+                'links_count': len(links),
+                'clickable_elements_count': len(clickable_elements),
+            }
+
+            results_path = self.save_crawl_data(test_url, 'crawl_handler', results)
+
+            # Assertions
+            assert isinstance(links, list)
+            assert isinstance(clickable_elements, list)
+            assert os.path.exists(before_screenshot)
+            assert os.path.exists(after_screenshot)
+            assert os.path.exists(results_path)
+
+            print('CrawlHandler integration test passed')
+
+        finally:
+            await self.teardown_method()
+
+    @pytest.mark.asyncio
+    async def test_highlight_crawl(self, request):
+        """Test highlighted crawl parameters."""
+        await self.setup_method()
+
+        try:
+            test_url = request.config.getoption('--url') or self.DEFAULT_TEST_URLS
+
+            params = self.CRAWL_PARAMS[0]  # highlight_crawl
+            result = await self.crawl_single_url(test_url, params)
+
+            assert result['results']['success']
+            assert os.path.exists(result['results']['before_screenshot'])
+            assert os.path.exists(result['results']['after_screenshot'])
+            assert os.path.exists(result['results']['id_map_path'])
+            assert os.path.exists(result['results']['crawl_data_path'])
+        finally:
+            await self.teardown_method()
+
+    @pytest.mark.asyncio
+    async def test_text_highlight_crawl(self, request):
+        """Test full highlight crawl parameters."""
+        await self.setup_method()
+
+        try:
+            test_url = request.config.getoption('--url') or self.DEFAULT_TEST_URLS
+
+            params = self.CRAWL_PARAMS[1]  # text_highlight_crawl
+            result = await self.crawl_single_url(test_url, params)
+
+            assert result['results']['success']
+            assert os.path.exists(result['results']['before_screenshot'])
+            assert os.path.exists(result['results']['after_screenshot'])
+            assert os.path.exists(result['results']['id_map_path'])
+            assert os.path.exists(result['results']['crawl_data_path'])
+
+        finally:
+            await self.teardown_method()
+
+    @pytest.mark.asyncio
+    async def test_viewport_highlight_crawl(self, request):
+        """Test viewport highlight crawl parameters."""
+        await self.setup_method()
+
+        try:
+            test_url = request.config.getoption('--url') or self.DEFAULT_TEST_URLS
+
+            params = self.CRAWL_PARAMS[2]  # viewport_highlight_crawl
+            result = await self.crawl_single_url(test_url, params)
+
+            assert result['results']['success']
+            assert os.path.exists(result['results']['before_screenshot'])
+            assert os.path.exists(result['results']['after_screenshot'])
+            assert os.path.exists(result['results']['id_map_path'])
+            assert os.path.exists(result['results']['crawl_data_path'])
+
+        finally:
+            await self.teardown_method()

tests/test_loading_animation.py

@@ -0,0 +1,7 @@
+import time
+
+from webqa_agent.utils.loading_animation import LoadingAnimation
+
+with LoadingAnimation("Testing..."):
+    print("This is a test message.")
+    time.sleep(5)

tests/test_pages/dropdown_components.html

@@ -0,0 +1,194 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Dropdown Components Test Page</title>
+  <style>
+    body { font-family: sans-serif; }
+    .section { position: relative; margin: 0; padding: 0; }
+
+    /* Absolute positions to make center_x/center_y predictable */
+    #native-container { position: absolute; left: 100px; top: 100px; width: 220px; height: 32px; }
+    #ant-select-container { position: absolute; left: 100px; top: 200px; width: 220px; height: 34px; }
+    #ant-cascader-container { position: absolute; left: 100px; top: 300px; width: 220px; height: 34px; }
+
+    /* Mimic Ant Design Select */
+    .ant-select { position: relative; display: inline-block; width: 100%; }
+    .ant-select-selector { box-sizing: border-box; width: 100%; height: 34px; border: 1px solid #999; border-radius: 4px; padding: 6px 8px; background: #fff; cursor: pointer; }
+    .ant-select-dropdown { position: absolute; left: 0; top: 36px; width: 100%; border: 1px solid #999; border-radius: 4px; background: #fff; box-shadow: 0 2px 8px rgba(0,0,0,0.15); z-index: 1000; }
+    .ant-select-dropdown-hidden { display: none; }
+    .ant-select-item-option { padding: 6px 8px; cursor: pointer; }
+    .ant-select-item-option:hover { background: #f5f5f5; }
+    .ant-select-item-option-content { display: inline-block; }
+
+    /* Mimic Ant Design Cascader */
+    .ant-cascader { position: relative; display: inline-block; width: 100%; }
+    .ant-cascader-dropdown { position: absolute; left: 0; top: 36px; display: flex; border: 1px solid #999; border-radius: 4px; background: #fff; box-shadow: 0 2px 8px rgba(0,0,0,0.15); z-index: 1000; }
+    .ant-cascader-dropdown-hidden { display: none; }
+    .ant-cascader-menu { min-width: 160px; max-height: 220px; overflow: auto; border-right: 1px solid #eee; }
+    .ant-cascader-menu:last-child { border-right: none; }
+    .ant-cascader-menu-item { padding: 6px 8px; cursor: pointer; white-space: nowrap; }
+    .ant-cascader-menu-item:hover { background: #f5f5f5; }
+    .ant-cascader-menu-item-expand::after { content: ' ▶'; color: #999; }
+  </style>
+</head>
+<body>
+  <h2 style="margin:16px 16px 64px;">Dropdown Components Test Page</h2>
+
+  <!-- Native select (dropdown_id suggestion: 13) -->
+  <div id="native-container" class="section">
+    <label for="native-select" style="display:none;">Native</label>
+    <select id="native-select" class="is-medium" style="width:100%; height:100%;">
+      <option value="all">All fields</option>
+      <option value="title">Title</option>
+      <option value="authors">Author(s)</option>
+    </select>
+  </div>
+
+  <!-- Ant Design Select mimic (dropdown_id suggestion: 101) -->
+  <div id="ant-select-container" class="section">
+    <div class="ant-select" id="ant-select">
+      <div class="ant-select-selector" aria-expanded="false">Select an option</div>
+      <div class="ant-select-dropdown ant-select-dropdown-hidden" id="ant-select-dropdown">
+        <div class="ant-select-item-option" data-value="chat-model">
+          <span class="ant-select-item-option-content">Chat model</span>
+        </div>
+        <div class="ant-select-item-option" data-value="reasoning-model">
+          <span class="ant-select-item-option-content">Reasoning model</span>
+        </div>
+        <div class="ant-select-item-option" data-value="fast-model">
+          <span class="ant-select-item-option-content">Fast model</span>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <!-- Ant Design Cascader mimic (dropdown_id suggestion: 301) -->
+  <div id="ant-cascader-container" class="section">
+    <div class="ant-cascader" id="ant-cascader">
+      <div class="ant-select-selector" aria-expanded="false">Select location</div>
+      <div class="ant-cascader-dropdown ant-cascader-dropdown-hidden" id="ant-cascader-dropdown">
+        <div class="ant-cascader-menu" id="cascader-level-0"></div>
+        <div class="ant-cascader-menu" id="cascader-level-1"></div>
+        <div class="ant-cascader-menu" id="cascader-level-2"></div>
+      </div>
+    </div>
+  </div>
+
+  <script>
+    // Ant Select: toggle dropdown on selector click
+    (function() {
+      const select = document.getElementById('ant-select');
+      if (!select) return;
+      const selector = select.querySelector('.ant-select-selector');
+      const dropdown = document.getElementById('ant-select-dropdown');
+      selector.addEventListener('click', () => {
+        const hidden = dropdown.classList.contains('ant-select-dropdown-hidden');
+        dropdown.classList.toggle('ant-select-dropdown-hidden', !hidden ? true : false);
+        selector.setAttribute('aria-expanded', hidden ? 'true' : 'false');
+      });
+      dropdown.addEventListener('click', (e) => {
+        const item = e.target.closest('.ant-select-item-option');
+        if (item) {
+          selector.textContent = item.querySelector('.ant-select-item-option-content')?.textContent || item.textContent;
+          dropdown.classList.add('ant-select-dropdown-hidden');
+          selector.setAttribute('aria-expanded', 'false');
+        }
+      });
+    })();
+
+    // Ant Cascader: proper cascading behavior (click L0 -> show L1; click L1 -> show L2 or select if leaf)
+    (function() {
+      const cascader = document.getElementById('ant-cascader');
+      if (!cascader) return;
+      const selector = cascader.querySelector('.ant-select-selector');
+      const dropdown = document.getElementById('ant-cascader-dropdown');
+      const menu0 = document.getElementById('cascader-level-0');
+      const menu1 = document.getElementById('cascader-level-1');
+      const menu2 = document.getElementById('cascader-level-2');
+
+      // Data model
+      const data = {
+        'Asia': {
+          'China': ['Beijing', 'Shanghai'],
+          'Japan': []
+        },
+        'Europe': {
+          'Germany': [],
+          'France': []
+        }
+      };
+
+      function clearMenu(menuEl) {
+        while (menuEl.firstChild) menuEl.removeChild(menuEl.firstChild);
+      }
+
+      function renderMenuItems(menuEl, items, hasChildrenFn) {
+        clearMenu(menuEl);
+        items.forEach(text => {
+          const div = document.createElement('div');
+          div.className = 'ant-cascader-menu-item';
+          div.textContent = text;
+          if (hasChildrenFn && hasChildrenFn(text)) {
+            div.classList.add('ant-cascader-menu-item-expand');
+          }
+          menuEl.appendChild(div);
+        });
+      }
+
+      // Initialize level 0 only
+      renderMenuItems(menu0, Object.keys(data), (key) => Object.keys(data[key] || {}).length > 0);
+      clearMenu(menu1);
+      clearMenu(menu2);
+
+      selector.addEventListener('click', () => {
+        const hidden = dropdown.classList.contains('ant-cascader-dropdown-hidden');
+        dropdown.classList.toggle('ant-cascader-dropdown-hidden', !hidden ? true : false);
+        selector.setAttribute('aria-expanded', hidden ? 'true' : 'false');
+      });
+
+      // Level 0 -> render Level 1
+      menu0.addEventListener('click', (e) => {
+        const item = e.target.closest('.ant-cascader-menu-item');
+        if (!item) return;
+        const topKey = item.textContent.trim();
+        const childrenObj = data[topKey] || {};
+        const level1Items = Object.keys(childrenObj);
+        renderMenuItems(menu1, level1Items, (key) => (childrenObj[key] || []).length > 0);
+        clearMenu(menu2);
+      });
+
+      // Level 1 -> render Level 2 or select if leaf
+      menu1.addEventListener('click', (e) => {
+        const item = e.target.closest('.ant-cascader-menu-item');
+        if (!item) return;
+        const secondKey = item.textContent.trim();
+
+        // Find parent (topKey) by scanning data
+        let topKey = null;
+        for (const k of Object.keys(data)) {
+          if (Object.keys(data[k] || {}).includes(secondKey)) { topKey = k; break; }
+        }
+        const level2Items = (topKey && data[topKey] && data[topKey][secondKey]) ? data[topKey][secondKey] : [];
+        if (level2Items.length === 0) {
+          selector.textContent = secondKey;
+          dropdown.classList.add('ant-cascader-dropdown-hidden');
+          selector.setAttribute('aria-expanded', 'false');
+          return;
+        }
+        renderMenuItems(menu2, level2Items, () => false);
+      });
+
+      // Level 2 -> select and close
+      menu2.addEventListener('click', (e) => {
+        const item = e.target.closest('.ant-cascader-menu-item');
+        if (!item) return;
+        selector.textContent = item.textContent.trim();
+        dropdown.classList.add('ant-cascader-dropdown-hidden');
+        selector.setAttribute('aria-expanded', 'false');
+      });
+    })();
+  </script>
+</body>
+</html>

webqa-agent.py

@@ -0,0 +1,406 @@
+#!/usr/bin/env python3
+import argparse
+import asyncio
+import os
+import subprocess
+import sys
+import traceback
+
+import yaml
+from playwright.async_api import Error as PlaywrightError
+from playwright.async_api import async_playwright
+
+from webqa_agent.executor import ParallelMode
+
+
+def find_config_file(args_config=None):
+    """Intelligently find configuration file."""
+    # 1. Command line arguments have highest priority
+    if args_config:
+        if os.path.isfile(args_config):
+            print(f"✅ Using specified config file: {args_config}")
+            return args_config
+        else:
+            raise FileNotFoundError(f"❌ Specified config file not found: {args_config}")
+
+    # 2. Search default locations by priority
+    current_dir = os.getcwd()
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+
+    default_paths = [
+        os.path.join(current_dir, "config", "config.yaml"),  # config in current directory
+        os.path.join(script_dir, "config", "config.yaml"),  # config in script directory
+        os.path.join(current_dir, "config.yaml"),  # compatible location in current directory
+        os.path.join(script_dir, "config.yaml"),  # compatible location in script directory
+        "/app/config/config.yaml",  # absolute path in Docker container
+    ]
+
+    for path in default_paths:
+        if os.path.isfile(path):
+            print(f"✅ Auto-discovered config file: {path}")
+            return path
+
+    # If none found, provide clear error message
+    print("❌ Config file not found, please check these locations:")
+    for path in default_paths:
+        print(f"   - {path}")
+    raise FileNotFoundError("Config file does not exist")
+
+
+def load_yaml(path):
+    if not os.path.isfile(path):
+        print(f"[ERROR] Config file not found: {path}", file=sys.stderr)
+        sys.exit(1)
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return yaml.safe_load(f)
+    except Exception as e:
+        print(f"[ERROR] Failed to read YAML: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+async def check_playwright_browsers_async():
+    try:
+        async with async_playwright() as p:
+            browser = await p.chromium.launch(headless=True)
+            await browser.close()
+        print("✅ Playwright browsers available (Async API startup successful)")
+        return True
+    except PlaywrightError as e:
+        print(f"⚠️ Playwright browsers unavailable (Async API failed): {e}")
+        return False
+    except Exception as e:
+        print(f"❌ Playwright check exception: {e}")
+        return False
+
+
+def check_lighthouse_installation():
+    """Check if Lighthouse is properly installed."""
+    # Get project root directory and current working directory
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    current_dir = os.getcwd()
+
+    # Determine OS type, lighthouse is .cmd file on Windows
+    is_windows = os.name == "nt"
+    lighthouse_exe = "lighthouse.cmd" if is_windows else "lighthouse"
+
+    # Possible lighthouse paths (local installation priority)
+    lighthouse_paths = [
+        os.path.join(current_dir, "node_modules", ".bin", lighthouse_exe),  # local installation in current directory
+        os.path.join(script_dir, "node_modules", ".bin", lighthouse_exe),  # local installation in script directory
+        "lighthouse",  # global installation path (fallback)
+    ]
+
+    # Add Docker path only in non-Windows environments
+    if not is_windows:
+        lighthouse_paths.insert(-1, os.path.join("/app", "node_modules", ".bin", "lighthouse"))
+
+    for lighthouse_path in lighthouse_paths:
+        try:
+            result = subprocess.run([lighthouse_path, "--version"], capture_output=True, text=True, timeout=10)
+            if result.returncode == 0:
+                version = result.stdout.strip()
+                path_type = "Local installation" if "node_modules" in lighthouse_path else "Global installation"
+                print(f"✅ Lighthouse installation successful, version: {version} ({path_type})")
+                return True
+        except subprocess.TimeoutExpired:
+            continue
+        except FileNotFoundError:
+            continue
+        except Exception:
+            continue
+
+    print("❌ Lighthouse not found, checked paths:")
+    for path in lighthouse_paths:
+        print(f"   - {path}")
+    print("Please confirm Lighthouse is properly installed: `npm install lighthouse chrome-launcher`")
+    return False
+
+
+def check_nuclei_installation():
+    """Check if Nuclei is properly installed."""
+    try:
+        # Check if nuclei command is available
+        result = subprocess.run(["nuclei", "-version"], capture_output=True, text=True, timeout=10)
+        if result.returncode == 0:
+            version = result.stdout.strip()
+            print(f"✅ Nuclei installation successful, version: {version}")
+            return True
+        else:
+            print(f"⚠️ Nuclei command execution failed: {result.stderr}")
+            return False
+    except subprocess.TimeoutExpired:
+        print("❌ Nuclei check timeout")
+        return False
+    except FileNotFoundError:
+        print("❌ Nuclei not installed or not in PATH")
+        return False
+    except Exception as e:
+        print(f"❌ Nuclei check exception: {e}")
+        return False
+
+
+def validate_and_build_llm_config(cfg):
+    """Validate and build LLM configuration, environment variables take priority over config file."""
+    # Read from config file
+    llm_cfg_raw = cfg.get("llm_config", {})
+
+    # Environment variables take priority over config file
+    api_key = os.getenv("OPENAI_API_KEY") or llm_cfg_raw.get("api_key", "")
+    base_url = os.getenv("OPENAI_BASE_URL") or llm_cfg_raw.get("base_url", "")
+    model = llm_cfg_raw.get("model", "gpt-4o-mini")
+    # Sampling configuration: default temperature is 0.1; top_p not set by default
+    temperature = llm_cfg_raw.get("temperature", 0.1)
+    top_p = llm_cfg_raw.get("top_p")
+
+    # Validate required fields
+    if not api_key:
+        raise ValueError(
+            "❌ LLM API Key not configured! Please set one of the following:\n"
+            "   - Environment variable: OPENAI_API_KEY\n"
+            "   - Config file: llm_config.api_key"
+        )
+
+    if not base_url:
+        print("⚠️  base_url not set, will use OpenAI default address")
+        base_url = "https://api.openai.com/v1"
+
+    llm_config = {
+        "api": "openai",
+        "model": model,
+        "api_key": api_key,
+        "base_url": base_url,
+        "temperature": temperature,
+    }
+    if top_p is not None:
+        llm_config["top_p"] = top_p
+
+    # Show configuration source (hide sensitive information)
+    api_key_masked = f"{api_key[:8]}...{api_key[-4:]}" if len(api_key) > 12 else "***"
+    env_api_key = bool(os.getenv("OPENAI_API_KEY"))
+    env_base_url = bool(os.getenv("OPENAI_BASE_URL"))
+
+    print("✅ LLM configuration validation successful:")
+    print(f"   - API Key: {api_key_masked} ({'Environment variable' if env_api_key else 'Config file'})")
+    print(f"   - Base URL: {base_url} ({'Environment variable' if env_base_url else 'Config file/Default'})")
+    print(f"   - Model: {model}")
+    print(f"   - Temperature: {temperature}")
+    if top_p is not None:
+        print(f"   - Top_p: {top_p}")
+
+    return llm_config
+
+
+def build_test_configurations(cfg, cookies=None):
+    tests = []
+    tconf = cfg.get("test_config", {})
+
+    # Docker environment detection: force headless mode
+    is_docker = os.getenv("DOCKER_ENV") == "true"
+    config_headless = cfg.get("browser_config", {}).get("headless", True)
+
+    if is_docker and not config_headless:
+        print("⚠️  Docker environment detected, forcing headless mode")
+        headless = True
+    else:
+        headless = config_headless
+
+    base_browser = {
+        "viewport": cfg.get("browser_config", {}).get("viewport", {"width": 1280, "height": 720}),
+        "headless": headless,
+    }
+
+    # function test
+    if tconf.get("function_test", {}).get("enabled"):
+
+        if tconf["function_test"].get("type") == "ai":
+            tests.append(
+                {
+                    "test_type": "ui_agent_langgraph",
+                    "enabled": True,
+                    "browser_config": base_browser,
+                    "test_specific_config": {
+                        "cookies": cookies,
+                        "business_objectives": tconf["function_test"].get("business_objectives", ""),
+                    },
+                }
+            )
+        else:
+            tests += [
+                {
+                    "test_type": "basic_test",
+                    "enabled": True,
+                    "browser_config": base_browser,
+                    "test_specific_config": {},
+                }
+            ]
+
+    # ux test
+    if tconf.get("ux_test", {}).get("enabled"):
+        tests.append(
+            {
+                "test_type": "ux_test",
+                "enabled": True,
+                "browser_config": base_browser,
+                "test_specific_config": {},
+            }
+        )
+  
+    # performance test
+    if tconf.get("performance_test", {}).get("enabled"):
+        tests.append(
+            {
+                "test_type": "performance",
+                "enabled": True,
+                "browser_config": base_browser,
+                "test_specific_config": {},
+            }
+        )
+
+    # security test
+    if tconf.get("security_test", {}).get("enabled"):
+        tests.append(
+            {
+                "test_type": "security",
+                "enabled": True,
+                "browser_config": base_browser,
+                "test_specific_config": {},
+            }
+        )
+
+    return tests
+
+
+async def run_tests(cfg):
+    # 0. Display runtime environment information
+    is_docker = os.getenv("DOCKER_ENV") == "true"
+    print(f"🏃 Runtime environment: {'Docker container' if is_docker else 'Local environment'}")
+    if is_docker:
+        print("🐳 Docker mode: automatically enable headless browser")
+
+    # 1. Check required tools based on configuration
+    tconf = cfg.get("test_config", {})
+
+    # Display enabled test types
+    enabled_tests = []
+    if tconf.get("function_test", {}).get("enabled"):
+        test_type = tconf.get("function_test", {}).get("type", "default")
+        enabled_tests.append(f"Function Test ({test_type})")
+    if tconf.get("ux_test", {}).get("enabled"):
+        enabled_tests.append("User Experience Test")
+    if tconf.get("performance_test", {}).get("enabled"):
+        enabled_tests.append("Performance Test")
+    if tconf.get("security_test", {}).get("enabled"):
+        enabled_tests.append("Security Test")
+
+    if enabled_tests:
+        print(f"📋 Enabled test types: {', '.join(enabled_tests)}")
+        print("🔧 Checking required tools based on configuration...")
+    else:
+        print("⚠️  No test types enabled, please check configuration file")
+        sys.exit(1)
+
+    # Check if browser is needed (most tests require it)
+    needs_browser = any(
+        [
+            tconf.get("function_test", {}).get("enabled"),
+            tconf.get("ux_test", {}).get("enabled"),
+            tconf.get("performance_test", {}).get("enabled"),
+            tconf.get("security_test", {}).get("enabled"),
+        ]
+    )
+
+    if needs_browser:
+        print("🔍 Checking Playwright browsers...")
+        ok = await check_playwright_browsers_async()
+        if not ok:
+            print("Please manually run: `playwright install` to install browser binaries, then retry.", file=sys.stderr)
+            sys.exit(1)
+
+    # Check if Lighthouse is needed (performance test)
+    if tconf.get("performance_test", {}).get("enabled"):
+        print("🔍 Checking Lighthouse installation...")
+        lighthouse_ok = check_lighthouse_installation()
+        if not lighthouse_ok:
+            print("Please confirm Lighthouse is properly installed: `npm install lighthouse chrome-launcher`", file=sys.stderr)
+            sys.exit(1)
+
+    # Check if Nuclei is needed (security test)
+    if tconf.get("security_test", {}).get("enabled"):
+        print("🔍 Checking Nuclei installation...")
+        nuclei_ok = check_nuclei_installation()
+        if not nuclei_ok:
+            print("Please confirm Nuclei is properly installed and in PATH", file=sys.stderr)
+            sys.exit(1)
+
+    # Validate and build LLM configuration
+    try:
+        llm_config = validate_and_build_llm_config(cfg)
+    except ValueError as e:
+        print(f"[ERROR] {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Build test_configurations
+    cookies = []
+    test_configurations = build_test_configurations(cfg, cookies=cookies)
+
+    target_url = cfg.get("target", {}).get("url", "")
+
+    # Call executor
+    try:
+        # Read concurrency from config (default 2), allow users to specify in config.target.max_concurrent_tests
+        raw_concurrency = cfg.get("target", {}).get("max_concurrent_tests", 2)
+        try:
+            max_concurrent_tests = int(raw_concurrency)
+            if max_concurrent_tests < 1:
+                raise ValueError
+        except Exception:
+            print(f"⚠️  Invalid concurrency setting: {raw_concurrency}, fallback to 2")
+            max_concurrent_tests = 2
+
+        print(f"⚙️ Concurrency: {max_concurrent_tests}")
+
+        parallel_mode = ParallelMode([], max_concurrent_tests=max_concurrent_tests)
+        results, report_path, html_report_path, result_count = await parallel_mode.run(
+            url=target_url, llm_config=llm_config, test_configurations=test_configurations,
+            log_cfg=cfg.get("log", {"level": "info"}),
+            report_cfg=cfg.get("report", {"language": "en-US"})
+        )
+        if result_count:
+            print(f"🔢 Total evaluations: {result_count.get('total', 0)}")
+            print(f"✅ Passed: {result_count.get('passed', 0)}")
+            print(f"❌ Failed: {result_count.get('failed', 0)}")
+
+        if html_report_path:
+            print("HTML report path: ", html_report_path)
+        else:
+            print("HTML report generation failed")
+    except Exception:
+        print("Test execution failed, stack trace:", file=sys.stderr)
+        traceback.print_exc()
+        sys.exit(1)
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="WebQA Agent Test Entry Point")
+    parser.add_argument("--config", "-c", help="YAML configuration file path (optional, default auto-search config/config.yaml)")
+    return parser.parse_args()
+
+
+def main():
+    args = parse_args()
+
+    # Intelligently find configuration file
+    try:
+        config_path = find_config_file(args.config)
+        cfg = load_yaml(config_path)
+    except FileNotFoundError as e:
+        print(f"[ERROR] {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Run tests
+    asyncio.run(run_tests(cfg))
+
+
+if __name__ == "__main__":
+    main()

webqa_agent/actions/action_executor.py

@@ -0,0 +1,338 @@
+import asyncio
+import logging
+from typing import Dict, List, Optional
+
+
+class ActionExecutor:
+    def __init__(self, action_handler):
+        self._actions = action_handler
+        self._action_map = {
+            "Tap": self._execute_tap,
+            "Hover": self._execute_hover,
+            "Sleep": self._execute_sleep,
+            "Input": self._execute_input,
+            "Clear": self._execute_clear,
+            "Scroll": self._execute_scroll,
+            "KeyboardPress": self._execute_keyboard_press,
+            "FalsyConditionStatement": self._execute_falsy,
+            "Check": self._execute_check,
+            "GetNewPage": self._execute_get_new_page,
+            "Upload": self._execute_upload,
+            "SelectDropdown": self._execute_select_dropdown,
+            "Drag": self._execute_drag,
+            "GoToPage": self._execute_go_to_page,  # Added missing action
+            "GoBack": self._execute_go_back,  # Added browser back navigation
+        }
+
+    async def initialize(self):
+        return self
+
+    async def execute(self, action):
+        try:
+            # Validate the action
+            action_type = action.get("type")
+            if not action_type:
+                logging.error("Action type is required")
+                return False
+
+            # Get the corresponding execution function
+            execute_func = self._action_map.get(action_type)
+            if not execute_func:
+                logging.error(f"Unknown action type: {action_type}")
+                return False
+
+            # Execute the action
+            logging.debug(f"Executing action: {action_type}")
+            return await execute_func(action)
+
+        except Exception as e:
+            logging.error(f"Action execution failed: {str(e)}")
+            return {"success": False, "message": f"Action execution failed with an exception: {e}"}
+
+    def _validate_params(self, action, required_params):
+        for param in required_params:
+            keys = param.split(".")
+            value = action
+            for key in keys:
+                value = value.get(key)
+                if value is None:
+                    if action["type"] == "Scroll" and key == "distance":
+                        continue
+                    logging.error(f"Missing required parameter: {param}")
+                    return False  # Return False to indicate validation failure
+        return True  # Return True if all parameters are present
+
+    # Individual action execution methods - NO SCREENSHOTS
+    async def _execute_clear(self, action):
+        """Execute clear action on an input field."""
+        if not self._validate_params(action, ["locate.id"]):
+            return {"success": False, "message": "Missing locate.id for clear action"}
+        success = await self._actions.clear(action.get("locate").get("id"))
+        if success:
+            return {"success": True, "message": "Clear action successful."}
+        else:
+            return {"success": False, "message": "Clear action failed. The element might not be clearable."}
+
+    async def _execute_tap(self, action):
+        """Execute tap/click action."""
+        if not self._validate_params(action, ["locate.id"]):
+            return {"success": False, "message": "Missing locate.id for tap action"}
+        success = await self._actions.click(action.get("locate").get("id"))
+        if success:
+            return {"success": True, "message": "Tap action successful."}
+        else:
+            return {"success": False, "message": "Tap action failed. The element might not be clickable."}
+
+    async def _execute_hover(self, action):
+        """Execute hover action."""
+        if not self._validate_params(action, ["locate.id"]):
+            return {"success": False, "message": "Missing locate.id for hover action"}
+        success = await self._actions.hover(action.get("locate").get("id"))
+        if success:
+            return {"success": True, "message": "Hover action successful."}
+        else:
+            return {"success": False, "message": "Hover action failed. The element might not be hoverable."}
+
+    async def _execute_sleep(self, action):
+        """Execute sleep/wait action."""
+        if not self._validate_params(action, ["param.timeMs"]):
+            return {"success": False, "message": "Missing param.timeMs for sleep action"}
+        time_ms = action.get("param").get("timeMs")
+        await asyncio.sleep(time_ms / 1000)
+        return {"success": True, "message": f"Slept for {time_ms}ms."}
+
+    async def _execute_input(self, action):
+        """Execute input/type action."""
+        if not self._validate_params(action, ["locate.id", "param.value"]):
+            return {"success": False, "message": "Missing locate.id or param.value for input action"}
+        try:
+            value = action.get("param").get("value")
+            clear_before_type = action.get("param").get("clear_before_type", False)  # Default is False
+            success = await self._actions.type(
+                action.get("locate").get("id"), value, clear_before_type=clear_before_type
+            )
+            if success:
+                return {"success": True, "message": "Input action successful."}
+            else:
+                return {
+                    "success": False,
+                    "message": "Input action failed. The element might not be available for typing.",
+                }
+        except Exception as e:
+            logging.error(f"Action '_execute_input' execution failed: {str(e)}")
+            return {"success": False, "message": f"Input action failed with an exception: {e}"}
+
+    async def _execute_scroll(self, action):
+        """Execute scroll action."""
+        if not self._validate_params(action, ["param.direction", "param.scrollType", "param.distance"]):
+            return {"success": False, "message": "Missing parameters for scroll action"}
+        direction = action.get("param").get("direction", "down")
+        scroll_type = action.get("param").get("scrollType", "once")
+        distance = action.get("param").get("distance", None)
+
+        success = await self._actions.scroll(direction, scroll_type, distance)
+        if success:
+            return {"success": True, "message": f"Scrolled {direction} successfully."}
+        else:
+            return {"success": False, "message": "Scroll action failed."}
+
+    async def _execute_keyboard_press(self, action):
+        """Execute keyboard press action."""
+        if not self._validate_params(action, ["param.value"]):
+            return {"success": False, "message": "Missing param.value for keyboard press action"}
+        success = await self._actions.keyboard_press(action.get("param").get("value"))
+        if success:
+            return {"success": True, "message": "Keyboard press successful."}
+        else:
+            return {"success": False, "message": "Keyboard press failed."}
+
+    async def _execute_falsy(self, action):
+        """Execute falsy condition statement."""
+        return {"success": True, "message": "Falsy condition met."}
+
+    async def _execute_check(self, action):
+        """Execute check action."""
+        return {"success": True, "message": "Check action completed."}
+
+    async def _execute_get_new_page(self, action):
+        """Execute get new page action."""
+        success = await self._actions.get_new_page()
+        if success:
+            return {"success": True, "message": "Successfully switched to new page."}
+        else:
+            return {"success": False, "message": "Failed to get new page."}
+
+    async def _execute_upload(self, action, file_path):
+        """Execute upload action."""
+        if not self._validate_params(action, ["locate.id"]):
+            return {"success": False, "message": "Missing locate.id for upload action"}
+        success = await self._actions.upload_file(action.get("locate").get("id"), file_path)
+        if success:
+            return {"success": True, "message": "File upload successful."}
+        else:
+            return {"success": False, "message": "File upload failed."}
+
+    async def _execute_select_dropdown(self, action):
+        """Execute select dropdown action."""
+        locate = action.get("locate", {})
+        dropdown_id = locate.get("dropdown_id")
+        option_id = locate.get("option_id")
+        selection_path_param = action.get("param", {}).get("selection_path")
+
+        if dropdown_id is None or selection_path_param is None:
+            logging.error("dropdown_id and selection_path are required for SelectDropdown")
+            return {"success": False, "message": "dropdown_id and selection_path are required for SelectDropdown"}
+
+        if isinstance(selection_path_param, str):
+            selection_path = [selection_path_param]
+        elif isinstance(selection_path_param, list) and selection_path_param:
+            selection_path = selection_path_param
+        else:
+            logging.error("selection_path must be a non-empty string or list")
+            return {"success": False, "message": "selection_path must be a non-empty string or list"}
+
+        try:
+            # choose option_id directly
+            if option_id is not None and len(selection_path) == 1:
+                logging.debug(f"Directly clicking option_id {option_id} for dropdown_id {dropdown_id}")
+                return await self._actions.select_dropdown_option(dropdown_id, selection_path[0], option_id=option_id)
+
+            # multi-level cascade or no option_id, use original logic
+            if len(selection_path) == 1:
+                return await self._execute_simple_selection(dropdown_id, selection_path[0])
+            else:
+                # multi-level cascade
+                for level, option_text in enumerate(selection_path):
+                    select_result = await self._actions.select_cascade_level(dropdown_id, option_text, level=level)
+                    if not select_result.get("success"):
+                        logging.error(f"Failed to select level {level} option: {select_result.get('message')}")
+                        return {
+                            "success": False,
+                            "message": f"Failed at cascade level {level}: {select_result.get('message')}",
+                        }
+                    if level < len(selection_path) - 1:
+                        await asyncio.sleep(0.5)
+                logging.debug(f"Successfully completed cascade selection: {' -> '.join(selection_path)}")
+                return {"success": True, "message": "Cascade selection completed successfully"}
+
+        except Exception as e:
+            logging.error(f"Error in dropdown selection: {str(e)}")
+            return {"success": False, "message": f"An exception occurred during dropdown selection: {str(e)}"}
+
+    async def _execute_simple_selection(self, element_id, option_text):
+        """Execute simple single-level dropdown selection."""
+        try:
+            # get all options of dropdown
+            logging.debug(f"Getting dropdown options for element {element_id}")
+            options_result = await self._actions.get_dropdown_options(element_id)
+
+            if not options_result.get("success"):
+                logging.error(f"Failed to get dropdown options: {options_result.get('message')}")
+                return {"success": False, "message": f"Failed to get dropdown options: {options_result.get('message')}"}
+
+            options = options_result.get("options", [])
+            if not options:
+                logging.error("No options found in dropdown")
+                return {"success": False, "message": "No options found in dropdown"}
+
+            logging.debug(f"Found {len(options)} options in dropdown")
+
+            # use default simple decision logic
+            def _default_selection_logic(options: List[Dict], criteria: str) -> Optional[str]:
+                criteria_lower = criteria.lower()
+
+                for option in options:
+                    if option["text"].lower() == criteria_lower:
+                        logging.debug(f"Found exact match: {option['text']}")
+                        return option["text"]
+
+                for option in options:
+                    if criteria_lower in option["text"].lower():
+                        logging.debug(f"Found contains match: {option['text']}")
+                        return option["text"]
+
+                for option in options:
+                    if option["text"].lower() in criteria_lower:
+                        logging.debug(f"Found partial match: {option['text']}")
+                        return option["text"]
+
+                # if no match, return None
+                logging.warning(f"No match found for criteria: {criteria}")
+                return None
+
+            selected_option = _default_selection_logic(options, option_text)
+
+            if not selected_option:
+                logging.error(f"Could not decide which option to select based on criteria: {option_text}")
+                available_options = [opt["text"] for opt in options]
+                logging.debug(f"Available options: {available_options}")
+                return {"success": False, "message": "No matching option found", "available_options": available_options}
+
+            logging.debug(f"Selected option: {selected_option}")
+
+            # execute select operation
+            select_result = await self._actions.select_dropdown_option(element_id, selected_option)
+
+            if select_result.get("success"):
+                logging.debug(f"Successfully completed dropdown selection: {selected_option}")
+                return {"success": True, "message": "Option selected successfully"}
+            else:
+                logging.error(f"Failed to select option: {selected_option}")
+                return {"success": False, "message": f"Failed to select option: {select_result.get('message')}"}
+
+        except Exception as e:
+            logging.error(f"Error in simple dropdown selection: {str(e)}")
+            return {"success": False, "message": f"An exception occurred: {str(e)}"}
+
+    async def _execute_drag(self, action):
+        """Execute drag action."""
+        if not self._validate_params(action, ["param.sourceCoordinates", "param.targetCoordinates"]):
+            return {"success": False, "message": "Missing coordinates for drag action"}
+        success = await self._actions.drag(
+            action.get("param").get("sourceCoordinates"), action.get("param").get("targetCoordinates")
+        )
+        if success:
+            return {"success": True, "message": "Drag action successful."}
+        else:
+            return {"success": False, "message": "Drag action failed."}
+
+    async def _execute_go_to_page(self, action):
+        """Execute go to page action - the missing navigation action."""
+        url = action.get("param", {}).get("url")
+        if not url:
+            return {"success": False, "message": "Missing URL parameter for go to page action"}
+
+        try:
+            # Use smart navigation if available
+            if hasattr(self._actions, 'smart_navigate_to_page'):
+                page = getattr(self._actions, 'page', None)
+                if page:
+                    navigation_performed = await self._actions.smart_navigate_to_page(page, url)
+                    message = "Navigated to page" if navigation_performed else "Already on target page"
+                    return {"success": True, "message": message}
+
+            # Fallback to regular navigation
+            if hasattr(self._actions, 'go_to_page') and hasattr(self._actions, 'page'):
+                await self._actions.go_to_page(self._actions.page, url)
+                return {"success": True, "message": "Successfully navigated to page"}
+
+            return {"success": False, "message": "Navigation method not available"}
+
+        except Exception as e:
+            logging.error(f"Go to page action failed: {str(e)}")
+            return {"success": False, "message": f"Navigation failed: {str(e)}", "playwright_error": str(e)}
+
+    async def _execute_go_back(self, action):
+        """Execute browser back navigation action."""
+        try:
+            if hasattr(self._actions, 'go_back'):
+                success = await self._actions.go_back()
+                if success:
+                    return {"success": True, "message": "Successfully navigated back to previous page"}
+                else:
+                    return {"success": False, "message": "Go back navigation failed"}
+            else:
+                return {"success": False, "message": "Go back action not supported by action handler"}
+        except Exception as e:
+            logging.error(f"Go back action failed: {str(e)}")
+            return {"success": False, "message": f"Go back failed: {str(e)}", "playwright_error": str(e)}

webqa_agent/actions/action_handler.py

@@ -0,0 +1,1431 @@
+import asyncio
+import base64
+import json
+import os
+import re
+from typing import Any, Dict, List, Optional, Union
+
+from playwright.async_api import Page
+
+from webqa_agent.browser.driver import *
+
+
+class ActionHandler:
+    def __init__(self):
+        self.page_data = {}
+        self.page_element_buffer = {}  # page element buffer
+        self.driver = None
+        self.page = None
+
+    async def initialize(self, page: Page | None = None, driver=None):
+        if page is not None:
+            self.page = page
+            if driver is not None:
+                self.driver = driver
+            return self
+        return self
+
+    async def update_element_buffer(self, new_element):
+        """Update page_element_buffer :param new_buffer: CrawlerHandler fetched
+        latest element buffer."""
+        self.page_element_buffer = new_element
+
+    async def go_to_page(self, page: Page, url: str, cookies=None):
+        # if not self.driver:
+        #     self.driver = await Driver.getInstance()
+        self.page = page
+        if cookies:
+            try:
+                cookies = json.loads(cookies)
+                await self.page.context.add_cookies(cookies)
+            except Exception as e:
+                raise Exception(f'add context cookies error: {e}')
+
+        await self.page.goto(url=url, wait_until='domcontentloaded')
+        await self.page.wait_for_load_state('networkidle', timeout=60000)
+
+    async def smart_navigate_to_page(self, page: Page, url: str, cookies=None) -> bool:
+        """Smart navigation to target page, avoiding redundant navigation.
+
+        Args:
+            page: Playwright page object
+            url: Target URL
+            cookies: Optional cookies
+
+        Returns:
+            bool: Whether navigation operation was performed
+        """
+        try:
+            # Get current page URL
+            current_url = page.url
+            logging.debug(f'Smart navigation check - Current URL: {current_url}, Target URL: {url}')
+
+            # Enhanced URL normalization function to handle various domain variations
+            def normalize_url(u):
+                from urllib.parse import urlparse
+
+                try:
+                    parsed = urlparse(u)
+                    # Handle domain variations: remove www prefix, unify lowercase
+                    netloc = parsed.netloc.lower()
+                    if netloc.startswith('www.'):
+                        netloc = netloc[4:]  # Remove www.
+
+                    # Standardize path: remove trailing slash
+                    path = parsed.path.rstrip('/')
+
+                    # Build normalized URL
+                    normalized = f'{parsed.scheme}://{netloc}{path}'
+                    return normalized
+                except Exception:
+                    # If parsing fails, return lowercase version of original URL
+                    return u.lower()
+
+            current_normalized = normalize_url(current_url)
+            target_normalized = normalize_url(url)
+
+            logging.debug(f'Normalized URLs - Current: {current_normalized}, Target: {target_normalized}')
+
+            if current_normalized == target_normalized:
+                logging.debug('Already on target page (normalized match), skipping navigation')
+                return False
+
+            # More flexible URL matching: if domain is same and path is similar, also consider as match
+            def extract_domain(u):
+                try:
+                    from urllib.parse import urlparse
+
+                    parsed = urlparse(u)
+                    domain = parsed.netloc.lower()
+                    if domain.startswith('www.'):
+                        domain = domain[4:]
+                    return domain
+                except Exception:
+                    return ''
+
+            def extract_path(u):
+                try:
+                    from urllib.parse import urlparse
+
+                    parsed = urlparse(u)
+                    return parsed.path.rstrip('/')
+                except Exception:
+                    return ''
+
+            current_domain = extract_domain(current_url)
+            target_domain = extract_domain(url)
+            current_path = extract_path(current_url)
+            target_path = extract_path(url)
+
+            # If domain is same and path is exactly same, or homepage variant
+            if current_domain == target_domain and (
+                current_path == target_path
+                or current_path == ''
+                and target_path == ''
+                or current_path == '/'
+                and target_path == ''
+                or current_path == ''
+                and target_path == '/'
+            ):
+                logging.debug(f'Domain and path match detected ({current_domain}{current_path}), skipping navigation')
+                return False
+
+            # Check if page is still valid
+            try:
+                await page.title()  # Simple check if page responds
+                logging.debug(f'Page is responsive, proceeding with navigation from {current_url} to {url}')
+            except Exception as e:
+                logging.warning(f'Page check failed: {e}, forcing navigation')
+
+            # Need to perform navigation
+            await self.go_to_page(page, url, cookies)
+            logging.debug(f'Successfully navigated to {url}')
+            return True
+
+        except Exception as e:
+            logging.error(f'Smart navigation failed: {e}, falling back to regular navigation')
+            # Perform regular navigation on error
+            await self.go_to_page(page, url, cookies)
+            return True
+
+    async def set_overflow_hidden(self):
+        await self.page.evaluate("document.body.style.overflow = 'hidden'")
+
+    async def close_page(self) -> None:
+        """Close the current page."""
+        if self.page:
+            try:
+                await self.page.close()
+                logging.debug('Page closed successfully')
+            except Exception as e:
+                logging.error(f'Error closing page: {e}')
+
+    def set_page_element_buffer(self, element_buffer: Dict[int, Dict]) -> None:
+        """Set the page element buffer for action execution."""
+        self.page_element_buffer = element_buffer
+
+    async def scroll(self, direction: str = 'down', scrollType: str = 'once', distance: Optional[int] = None) -> bool:
+        """Scroll page.
+        Args:
+            direction: 'up' or 'down'
+            scrollType: 'once' or 'untilBottom' or 'untilTop'
+            distance: None or Number
+
+        Returns:
+            bool: Whether scroll operation was performed
+        """
+        logging.debug('Start scrolling page')
+
+        # Validate inputs to avoid silent no-ops
+        allowed_directions = {'up', 'down'}
+        allowed_scroll_types = {'once', 'untilBottom', 'untilTop'}
+
+        if direction not in allowed_directions:
+            logging.error(f"Invalid direction '{direction}'. Allowed: {sorted(list(allowed_directions))}")
+            return False
+
+        if scrollType not in allowed_scroll_types:
+            logging.error(f"Invalid scrollType '{scrollType}'. Allowed: {sorted(list(allowed_scroll_types))}")
+            return False
+
+        if distance is not None:
+            try:
+                distance = int(distance)
+            except (TypeError, ValueError):
+                logging.error(f"Invalid distance '{distance}'. Must be an integer or None")
+                return False
+            if distance < 0:
+                logging.error(f"Invalid distance '{distance}'. Must be >= 0")
+                return False
+
+        async def perform_scroll():  # Execute scroll operation
+            if direction == 'up':
+                await self.page.evaluate(f'(document.scrollingElement || document.body).scrollTop -= {distance};')
+            elif direction == 'down':
+                await self.page.evaluate(f'(document.scrollingElement || document.body).scrollTop += {distance};')
+
+        if not distance:
+            distance = int(await self.page.evaluate('window.innerHeight') / 2)
+            logging.debug(f'Scrolling distance: {distance}')
+
+        if scrollType == 'once':
+            await perform_scroll()
+            return True
+
+        elif scrollType == 'untilBottom':
+            prev_scroll = -1  # Record last scroll position, avoid stuck
+
+            while True:
+                # Get current scroll position and page total height
+                current_scroll = await self.page.evaluate('window.scrollY')
+                current_scroll_height = await self.page.evaluate('document.body.scrollHeight')
+
+                # Check if page is scrolled to the bottom
+                if current_scroll == prev_scroll:
+                    logging.debug('No further scroll possible, reached the bottom.')
+                    break
+
+                # Until bottom
+                if current_scroll + distance >= current_scroll_height:
+                    distance = current_scroll_height - current_scroll
+                    logging.debug(f'Adjusting last scroll distance to {distance}')
+
+                prev_scroll = current_scroll
+                await perform_scroll()
+                await asyncio.sleep(1)
+
+            return True
+
+        elif scrollType == 'untilTop':
+            prev_scroll = -1
+
+            while True:
+                current_scroll = await self.page.evaluate('window.scrollY')
+
+                # If already at top or no progress, stop
+                if current_scroll <= 0 or current_scroll == prev_scroll:
+                    logging.debug('No further scroll possible, reached the top.')
+                    break
+
+                # Adjust last scroll to not go past top
+                if current_scroll - distance <= 0:
+                    distance = current_scroll
+                    logging.debug(f'Adjusting last scroll distance to {distance}')
+
+                prev_scroll = current_scroll
+                await perform_scroll()
+                await asyncio.sleep(1)
+
+            return True
+
+    async def click(self, id) -> bool:
+        # Inject JavaScript into the page to remove the target attribute from all links
+        js = """
+        links = document.getElementsByTagName("a");
+        for (var i = 0; i < links.length; i++) {
+            links[i].removeAttribute("target");
+        }
+        """
+        await self.page.evaluate(js)
+
+        try:
+            id = str(id)
+            element = self.page_element_buffer.get(id)
+            if not element:
+                logging.error(f'Element with id {id} not found in buffer for click action.')
+                return False
+
+            logging.debug(
+                f"Attempting to click element: id={id}, tagName='{element.get('tagName')}', innerText='{element.get('innerText', '').strip()[:50]}', selector='{element.get('selector')}'"
+            )
+
+        except Exception as e:
+            logging.error(f'failed to get element {id}, element: {self.page_element_buffer.get(id)}, error: {e}')
+            return False
+
+        return await self.click_using_coordinates(element, id)
+
+    async def click_using_coordinates(self, element, id) -> bool:
+        """Helper function to click using coordinates."""
+        x = element.get('center_x')
+        y = element.get('center_y')
+        try:
+            if x is not None and y is not None:
+                logging.debug(f'mouse click at element {id}, coordinate=({x}, {y})')
+                try:
+                    await self.page.mouse.click(x, y)
+                except Exception as e:
+                    logging.error(f'mouse click error: {e}\nwith coordinates:  ({x}, {y})')
+                return True
+            else:
+                logging.error('Coordinates not found in element data')
+                return False
+        except Exception as e:
+            logging.error(f'Error clicking using coordinates: {e}')
+            return False
+
+    async def hover(self, id) -> bool:
+        element = self.page_element_buffer.get(str(id))
+        if not element:
+            logging.error(f'Element with id {id} not found in buffer for hover action.')
+            return False
+
+        logging.debug(
+            f"Attempting to hover over element: id={id}, tagName='{element.get('tagName')}', innerText='{element.get('innerText', '').strip()[:50]}', selector='{element.get('selector')}'"
+        )
+
+        scroll_y = await self.page.evaluate('() => window.scrollY')
+
+        x = element.get('center_x')
+        y = element.get('center_y')
+        if x is not None and y is not None:
+            y = y - scroll_y
+            logging.debug(f'mouse hover at ({x}, {y})')
+            await self.page.mouse.move(x, y)
+            await asyncio.sleep(0.5)
+            return True
+        else:
+            logging.error('Coordinates not found in element data')
+            return False
+
+    async def wait(self, timeMs) -> bool:
+        """Wait for specified time.
+
+        Args:
+            timeMs: wait time (milliseconds)
+
+        Returns:
+            bool: True if success, False if failed
+        """
+        logging.debug(f'wait for {timeMs} milliseconds')
+        await asyncio.sleep(timeMs / 1000)
+        logging.debug(f'wait for {timeMs} milliseconds done')
+        return True
+
+    async def type(self, id, text, clear_before_type: bool = False) -> bool:
+        """Types text into the specified element, optionally clearing it
+        first."""
+        try:
+            element = self.page_element_buffer.get(str(id))
+            if not element:
+                logging.error(f'Element with id {id} not found in buffer for type action.')
+                return False
+
+            logging.debug(
+                f"Attempting to type into element: id={id}, tagName='{element.get('tagName')}', innerText='{element.get('innerText', '').strip()[:50]}', selector='{element.get('selector')}', clear_before_type={clear_before_type}"
+            )
+
+            if clear_before_type:
+                if not await self.clear(id):
+                    logging.warning(f'Failed to clear element {id} before typing, but will attempt to type anyway.')
+
+            # click element to get focus
+            try:
+                if not await self.click(str(id)):
+                    return False
+            except Exception as e:
+                logging.error(f"Error 'type' clicking using coordinates: {e}")
+                logging.error(f'id type {type(id)}, id: {id}')
+                return False
+
+            await asyncio.sleep(1)
+            # Type text with CSS validation and XPath fallback
+            selector = element['selector']
+
+            # First validate CSS selector format
+            if self._is_valid_css_selector(selector):
+                try:
+                    # Try using CSS selector
+                    await self.page.locator(selector).fill(text)
+                    logging.debug(f"Typed '{text}' into element {id} using CSS selector: {selector}")
+                except Exception as css_error:
+                    logging.warning(f'CSS selector type failed for element {id}: {css_error}')
+                    # CSS selector failed, try XPath
+                    xpath = element.get('xpath')
+                    if xpath:
+                        try:
+                            await self.page.locator(f'xpath={xpath}').fill(text)
+                            logging.debug(f"Typed '{text}' into element {id} using XPath fallback: {xpath}")
+                        except Exception as xpath_error:
+                            logging.error(
+                                f'Both CSS and XPath type failed for element {id}. CSS error: {css_error}, XPath error: {xpath_error}'
+                            )
+                            return False
+                    else:
+                        logging.error(f'CSS selector type failed and no XPath available for element {id}')
+                        return False
+            else:
+                logging.warning(f'Invalid CSS selector format for element {id}: {selector}')
+                # CSS selector format invalid, use XPath directly
+                xpath = element.get('xpath')
+                if xpath:
+                    try:
+                        await self.page.locator(f'xpath={xpath}').fill(text)
+                        logging.debug(f"Typed '{text}' into element {id} using XPath: {xpath}")
+                    except Exception as xpath_error:
+                        logging.error(f'XPath type failed for element {id}: {xpath_error}')
+                        return False
+                else:
+                    logging.error(f'Invalid CSS selector and no XPath available for element {id}')
+                    return False
+
+            await asyncio.sleep(1)
+            return True
+        except Exception as e:
+            logging.error(f'Failed to type into element {id}: {e}')
+            return False
+
+    @staticmethod
+    def _is_valid_css_selector(selector: str) -> bool:
+        """Validate if CSS selector format is valid.
+
+        Args:
+            selector: CSS selector string
+
+        Returns:
+            bool: True if selector format is valid, False otherwise
+        """
+        if not selector or not isinstance(selector, str):
+            return False
+
+        # Basic CSS selector format validation
+        # Check for invalid characters or format
+        try:
+            # Remove whitespace
+            selector = selector.strip()
+            if not selector:
+                return False
+
+            # Basic CSS selector syntax check
+            # Cannot start with a number (unless it's a pseudo-selector)
+            if re.match(r'^[0-9]', selector) and not selector.startswith(':'):
+                return False
+
+            # Check basic CSS selector pattern
+            # Allow: tag names, class names, IDs, attributes, pseudo-classes, pseudo-elements, combinators, etc.
+            css_pattern = r'^[a-zA-Z_\-\[\]().,:#*>+~\s="\'0-9]+$'
+            if not re.match(css_pattern, selector):
+                return False
+
+            # Check bracket matching
+            if selector.count('[') != selector.count(']'):
+                return False
+            if selector.count('(') != selector.count(')'):
+                return False
+
+            return True
+
+        except Exception:
+            return False
+
+    async def clear(self, id) -> bool:
+        """Clears the text in the specified input element."""
+        try:
+            element_to_clear = self.page_element_buffer.get(str(id))
+            if not element_to_clear:
+                logging.error(f'Element with id {id} not found in buffer for clear action.')
+                return False
+
+            logging.debug(
+                f"Attempting to clear element: id={id}, tagName='{element_to_clear.get('tagName')}', innerText='{element_to_clear.get('innerText', '').strip()[:50]}', selector='{element_to_clear.get('selector')}'"
+            )
+
+            # First, click the element to ensure it has focus
+            if not await self.click(str(id)):
+                logging.warning(f'Could not focus element {id} before clearing, but proceeding anyway.')
+
+            # Get the selector for the element
+            if 'selector' not in element_to_clear:
+                logging.error(f'Element {id} has no selector for clearing.')
+                return False
+
+            selector = element_to_clear['selector']
+
+            # Clear input with CSS validation and XPath fallback
+            # First validate CSS selector format
+            if self._is_valid_css_selector(selector):
+                try:
+                    # Try using CSS selector
+                    await self.page.locator(selector).fill('')
+                    logging.debug(f'Cleared input for element {id} using CSS selector: {selector}')
+                except Exception as css_error:
+                    logging.warning(f'CSS selector clear failed for element {id}: {css_error}')
+                    # CSS selector failed, try XPath
+                    xpath = element_to_clear.get('xpath')
+                    if xpath:
+                        try:
+                            await self.page.locator(f'xpath={xpath}').fill('')
+                            logging.debug(f'Cleared input for element {id} using XPath fallback: {xpath}')
+                        except Exception as xpath_error:
+                            logging.error(
+                                f'Both CSS and XPath clear failed for element {id}. CSS error: {css_error}, XPath error: {xpath_error}'
+                            )
+                            return False
+                    else:
+                        logging.error(f'CSS selector clear failed and no XPath available for element {id}')
+                        return False
+            else:
+                logging.warning(f'Invalid CSS selector format for element {id}: {selector}')
+                # CSS selector format invalid, use XPath directly
+                xpath = element_to_clear.get('xpath')
+                if xpath:
+                    try:
+                        await self.page.locator(f'xpath={xpath}').fill('')
+                        logging.debug(f'Cleared input for element {id} using XPath: {xpath}')
+                    except Exception as xpath_error:
+                        logging.error(f'XPath clear failed for element {id}: {xpath_error}')
+                        return False
+                else:
+                    logging.error(f'Invalid CSS selector and no XPath available for element {id}')
+                    return False
+
+            await asyncio.sleep(0.5)
+            return True
+        except Exception as e:
+            logging.error(f'Failed to clear element {id}: {e}')
+            return False
+
+    async def keyboard_press(self, key) -> bool:
+        """Press keyboard key.
+
+        Args:
+            key: key name
+
+        Returns:
+            bool: True if success, False if failed
+        """
+        await self.page.keyboard.press(key)
+        await asyncio.sleep(1)
+        return True
+
+    async def b64_page_screenshot(self, full_page=False, file_path=None, file_name=None, save_to_log=True):
+        """Get page screenshot (Base64 encoded)
+
+        Args:
+            full_page: whether to capture the whole page
+            file_path: screenshot save path (optional)
+            file_name: screenshot file name (optional)
+            save_to_log: whether to save to log system (default True)
+
+        Returns:
+            tuple: (screenshot base64 encoded, screenshot file path)
+        """
+        # get screenshot
+        screenshot_bytes = await self.take_screenshot(self.page, full_page=full_page, timeout=30000)
+
+        # convert to Base64
+        screenshot_base64 = base64.b64encode(screenshot_bytes).decode('utf-8')
+        base64_data = f'data:image/png;base64,{screenshot_base64}'
+        return base64_data
+
+    async def take_screenshot(
+        self,
+        page: Page,
+        full_page: bool = False,
+        file_path: str | None = None,
+        timeout: float = 120000,
+    ) -> bytes:
+        """Get page screenshot (binary)
+
+        Args:
+            page: page object
+            full_page: whether to capture the whole page
+            file_path: screenshot save path (only used for direct saving, not recommended in test flow)
+            timeout: timeout
+
+        Returns:
+            bytes: screenshot binary data
+        """
+        try:
+            try:
+                await page.wait_for_load_state(timeout=60000)
+            except Exception as e:
+                logging.warning(f'wait_for_load_state before screenshot failed: {e}; attempting screenshot anyway')
+            logging.debug('Page is fully loaded or skipped wait; taking screenshot')
+
+            # Directly capture screenshot as binary data
+            if file_path:
+                screenshot: bytes = await page.screenshot(
+                    path=file_path,
+                    full_page=full_page,
+                    timeout=timeout,
+                )
+            else:
+                screenshot: bytes = await page.screenshot(
+                    full_page=full_page,
+                    timeout=timeout,
+                )
+
+            return screenshot
+
+        except Exception as e:
+            logging.warning(f'Page screenshot attempt failed: {e}; trying fallback capture')
+            raise
+
+    async def go_back(self) -> bool:
+        """Navigate back to the previous page."""
+        try:
+            await self.page.go_back()
+            logging.debug('Navigated back to the previous page.')
+            return True
+        except Exception as e:
+            logging.error(f'Failed to navigate back: {e}')
+            return False
+
+    async def get_new_page(self):
+        try:
+            if self.driver:
+                self.page = await self.driver.get_new_page()
+            else:
+                # If no driver, check current context page list
+                pages = self.page.context.pages if self.page else []
+                if len(pages) > 1:
+                    self.page = pages[-1]
+            return True
+        except Exception as e:
+            logging.error(f'Failed to get new page: {e}')
+            return False
+
+    async def upload_file(self, id, file_path: Union[str, List[str]]) -> bool:
+        """File upload function.
+
+        Args:
+            id (str): element ID (not used for matching)
+            file_path (str or list): file path or path list to upload
+
+        Returns:
+            bool: True if success, False if failed
+        """
+        try:
+            # Support single file and multiple files
+            if isinstance(file_path, str):
+                file_paths = [file_path]
+            elif isinstance(file_path, list):
+                file_paths = file_path
+            else:
+                logging.error(f'file_path must be str or list, got {type(file_path)}')
+                return False
+
+            valid_file_paths = []
+            for fp in file_paths:
+                if not fp or not isinstance(fp, str):
+                    continue
+                if not os.path.exists(fp):
+                    logging.error(f'File not found: {fp}')
+                    continue
+                valid_file_paths.append(fp)
+
+            if not valid_file_paths:
+                logging.error('No valid files to upload.')
+                return False
+
+            # Get file extension for accept check
+            file_extension = os.path.splitext(valid_file_paths[0])[1].lower() if valid_file_paths else ''
+
+            # Find all file input elements and get more detailed selector
+            file_inputs = await self.page.evaluate(
+                """(fileExt) => {
+                return Array.from(document.querySelectorAll('input[type=\"file\"]'))
+                    .map(input => {
+                        const accept = input.getAttribute('accept') || '';
+                        let selector = `input[type=\"file\"]`;
+
+                        if (input.name) {
+                            selector += `[name=\"${input.name}\"]`;
+                        }
+
+                        if (accept) {
+                            selector += `[accept=\"${accept}\"]`;
+                        }
+
+                        return {
+                            selector: selector,
+                            accept: accept,
+                            acceptsFile: accept ? accept.toLowerCase().includes(fileExt) : true
+                        };
+                    });
+            }""",
+                file_extension,
+            )
+
+            if not file_inputs:
+                logging.error('No file input elements found')
+                return False
+
+            # Find compatible input elements
+            logging.debug(f'file_inputs: {file_inputs}')
+            compatible_inputs = [input_elem for input_elem in file_inputs if input_elem.get('acceptsFile')]
+
+            # If compatible input elements are found, use the first one, otherwise fallback to the first available
+            logging.debug(f'compatible_inputs: {compatible_inputs}')
+            selected_input = compatible_inputs[0] if compatible_inputs else file_inputs[0]
+            logging.debug(f'selected_input: {selected_input}')
+
+            # Upload files (support batch)
+            selector = selected_input.get('selector')
+            logging.debug(f'Uploading files {valid_file_paths} to: {selector}')
+            await self.page.set_input_files(selector, valid_file_paths)
+
+            await asyncio.sleep(1)
+            return True
+
+        except Exception as e:
+            logging.error(f'Upload failed: {str(e)}')
+            return False
+
+    async def get_dropdown_options(self, id) -> Dict[str, Any]:
+        """Get all options of various type selectors.
+
+        supported selector types:
+        - native <select> element
+        - Ant Design Select (.ant-select)
+        - Ant Design Cascader (.ant-cascader)
+        - other custom dropdown components
+
+        Args:
+            id: element ID
+
+        Returns:
+            Dict: dictionary containing option information, format:
+                {
+                    'success': bool,
+                    'options': List[Dict] or None,
+                    'message': str,
+                    'selector_type': str  # selector type
+                }
+        """
+        element = self.page_element_buffer.get(str(id))
+        if not element:
+            return {
+                'success': False,
+                'options': None,
+                'message': f'Element with id {id} not found in buffer',
+                'selector_type': 'unknown',
+            }
+
+        try:
+            # use JavaScript to detect selector type and get options
+            js_code = """
+            (elementData) => {
+                // find element by coordinates
+                const centerX = elementData.center_x;
+                const centerY = elementData.center_y;
+                const element = document.elementFromPoint(centerX, centerY);
+
+                if (!element) {
+                    return { success: false, message: 'Element not found at coordinates', selector_type: 'unknown' };
+                }
+
+                let selectElement = element.closest('select');
+                if (selectElement) {
+                    const options = Array.from(selectElement.options).map((opt, index) => ({
+                        text: opt.text,
+                        value: opt.value,
+                        index: index,
+                        selected: opt.selected
+                    }));
+
+                    return {
+                        success: true,
+                        options: options,
+                        selector_type: 'native_select',
+                        selectInfo: {
+                            id: selectElement.id,
+                            name: selectElement.name,
+                            multiple: selectElement.multiple,
+                            selectedIndex: selectElement.selectedIndex,
+                            optionCount: selectElement.options.length
+                        }
+                    };
+                }
+
+                let antSelect = element.closest('.ant-select');
+                if (antSelect && !antSelect.classList.contains('ant-cascader')) {
+                    // click to expand options
+                    const selector = antSelect.querySelector('.ant-select-selector');
+                    if (selector) {
+                        selector.click();
+
+                        // wait for options to appear
+                        return new Promise((resolve) => {
+                            setTimeout(() => {
+                                const dropdown = document.querySelector('.ant-select-dropdown:not(.ant-select-dropdown-hidden)');
+                                if (dropdown) {
+                                    const options = Array.from(dropdown.querySelectorAll('.ant-select-item-option')).map((opt, index) => {
+                                        const textEl = opt.querySelector('.ant-select-item-option-content');
+                                        return {
+                                            text: textEl ? textEl.textContent.trim() : opt.textContent.trim(),
+                                            value: opt.getAttribute('data-value') || opt.textContent.trim(),
+                                            index: index,
+                                            selected: opt.classList.contains('ant-select-item-option-selected'),
+                                            disabled: opt.classList.contains('ant-select-item-option-disabled')
+                                        };
+                                    });
+
+                                    resolve({
+                                        success: true,
+                                        options: options,
+                                        selector_type: 'ant_select',
+                                        selectInfo: {
+                                            multiple: antSelect.classList.contains('ant-select-multiple'),
+                                            allowClear: antSelect.classList.contains('ant-select-allow-clear'),
+                                            optionCount: options.length
+                                        }
+                                    });
+                                } else {
+                                    resolve({
+                                        success: false,
+                                        message: 'Could not find dropdown options after clicking',
+                                        selector_type: 'ant_select'
+                                    });
+                                }
+                            }, 500);
+                        });
+                    }
+                }
+
+                // check if it is Ant Design Cascader
+                let antCascader = element.closest('.ant-cascader');
+                if (antCascader) {
+                    // click to expand options
+                    const selector = antCascader.querySelector('.ant-select-selector');
+                    if (selector) {
+                        selector.click();
+
+                        // wait for cascader options to appear
+                        return new Promise((resolve) => {
+                            setTimeout(() => {
+                                const dropdown = document.querySelector('.ant-cascader-dropdown:not(.ant-cascader-dropdown-hidden)');
+                                if (dropdown) {
+                                    // get first level options
+                                    const firstLevelOptions = Array.from(dropdown.querySelectorAll('.ant-cascader-menu:first-child .ant-cascader-menu-item')).map((opt, index) => {
+                                        return {
+                                            text: opt.textContent.trim(),
+                                            value: opt.getAttribute('data-path-key') || opt.textContent.trim(),
+                                            index: index,
+                                            selected: opt.classList.contains('ant-cascader-menu-item-active'),
+                                            hasChildren: opt.classList.contains('ant-cascader-menu-item-expand'),
+                                            level: 0
+                                        };
+                                    });
+
+                                    resolve({
+                                        success: true,
+                                        options: firstLevelOptions,
+                                        selector_type: 'ant_cascader',
+                                        selectInfo: {
+                                            multiple: antCascader.classList.contains('ant-select-multiple'),
+                                            allowClear: antCascader.classList.contains('ant-select-allow-clear'),
+                                            optionCount: firstLevelOptions.length,
+                                            isExpanded: true
+                                        }
+                                    });
+                                } else {
+                                    resolve({
+                                        success: false,
+                                        message: 'Could not find cascader dropdown after clicking',
+                                        selector_type: 'ant_cascader'
+                                    });
+                                }
+                            }, 500);
+                        });
+                    }
+                }
+
+                // check other possible dropdown components
+                let customDropdown = element.closest('[role="combobox"], [role="listbox"], .dropdown, .select');
+                if (customDropdown) {
+                    // try generic method to get options
+                    const options = Array.from(customDropdown.querySelectorAll('option, [role="option"], .option, .item')).map((opt, index) => ({
+                        text: opt.textContent.trim(),
+                        value: opt.getAttribute('value') || opt.getAttribute('data-value') || opt.textContent.trim(),
+                        index: index,
+                        selected: opt.hasAttribute('selected') || opt.classList.contains('selected') || opt.getAttribute('aria-selected') === 'true'
+                    }));
+
+                    if (options.length > 0) {
+                        return {
+                            success: true,
+                            options: options,
+                            selector_type: 'custom_dropdown',
+                            selectInfo: {
+                                optionCount: options.length
+                            }
+                        };
+                    }
+                }
+
+                // if no match, return failure
+                return {
+                    success: false,
+                    message: 'No supported dropdown type found. Element classes: ' + element.className,
+                    selector_type: 'unsupported'
+                };
+            }
+            """
+
+            result = await self.page.evaluate(js_code, element)
+
+            if result.get('success'):
+                logging.debug(f"Found {len(result['options'])} options in {result.get('selector_type')} dropdown")
+                return {
+                    'success': True,
+                    'options': result['options'],
+                    'selector_type': result.get('selector_type'),
+                    'selectInfo': result.get('selectInfo'),
+                    'message': f"Successfully retrieved {len(result['options'])} options from {result.get('selector_type')}",
+                }
+            else:
+                logging.error(f"Failed to get dropdown options: {result.get('message')}")
+                return {
+                    'success': False,
+                    'options': None,
+                    'selector_type': result.get('selector_type', 'unknown'),
+                    'message': result.get('message', 'Unknown error'),
+                }
+
+        except Exception as e:
+            logging.error(f'Error getting dropdown options: {str(e)}')
+            return {'success': False, 'options': None, 'selector_type': 'error', 'message': f'Error: {str(e)}'}
+
+    async def select_dropdown_option(self, dropdown_id, option_text, option_id=None):
+        """Priority option_id, otherwise use dropdown_id to expand and
+        select."""
+        # priority option_id
+        if option_id is not None:
+            element = self.page_element_buffer.get(str(option_id))
+            if element:
+                x = element.get('center_x')
+                y = element.get('center_y')
+                await self.page.mouse.click(x, y)
+                logging.debug(f'Clicked option_id {option_id} ({option_text}) directly.')
+                return {
+                    'success': True,
+                    'message': f"Clicked dropdown option '{option_text}' directly.",
+                    'selected_value': element.get('innerText'),
+                    'selector_type': 'ant_select_option',
+                }
+            else:
+                logging.warning(f'option_id {option_id} not found in buffer, fallback to dropdown_id.')
+
+        # fallback: use dropdown_id to expand and select
+        element = self.page_element_buffer.get(str(dropdown_id))
+        if not element:
+            return {
+                'success': False,
+                'message': f'dropdown_id {dropdown_id} not found in buffer',
+                'selected_value': None,
+                'selector_type': 'unknown',
+            }
+
+        try:
+            # use JavaScript to detect selector type and select option
+            js_code = """
+            (params) => {
+                const elementData = params.elementData;
+                const targetText = params.targetText;
+
+                // find element by coordinates
+                const centerX = elementData.center_x;
+                const centerY = elementData.center_y;
+                const element = document.elementFromPoint(centerX, centerY);
+
+                if (!element) {
+                    return { success: false, message: 'Element not found at coordinates', selector_type: 'unknown' };
+                }
+
+                // 1. handle native select element
+                let selectElement = element.closest('select');
+                if (selectElement) {
+                    // find matching options
+                    let targetOption = null;
+                    for (let i = 0; i < selectElement.options.length; i++) {
+                        const option = selectElement.options[i];
+                        if (option.text === targetText || option.text.includes(targetText) || targetText.includes(option.text)) {
+                            targetOption = option;
+                            break;
+                        }
+                    }
+
+                    if (!targetOption) {
+                        const availableOptions = Array.from(selectElement.options).map(opt => opt.text);
+                        return {
+                            success: false,
+                            message: `Option "${targetText}" not found in native select. Available: ${availableOptions.join(', ')}`,
+                            selector_type: 'native_select',
+                            availableOptions: availableOptions
+                        };
+                    }
+
+                    // select option
+                    selectElement.selectedIndex = targetOption.index;
+                    targetOption.selected = true;
+
+                    // trigger event
+                    selectElement.dispatchEvent(new Event('change', { bubbles: true }));
+                    selectElement.dispatchEvent(new Event('input', { bubbles: true }));
+
+                    return {
+                        success: true,
+                        message: `Successfully selected option: "${targetOption.text}"`,
+                        selectedValue: targetOption.value,
+                        selectedText: targetOption.text,
+                        selector_type: 'native_select'
+                    };
+                }
+
+                // 2. handle Ant Design Select
+                let antSelect = element.closest('.ant-select');
+                if (antSelect && !antSelect.classList.contains('ant-cascader')) {
+                    // ensure dropdown is expanded (idempotent)
+                    const selector = antSelect.querySelector('.ant-select-selector');
+                    if (selector) {
+                        const ensureExpanded = () => {
+                            const visible = document.querySelector('.ant-select-dropdown:not(.ant-select-dropdown-hidden)');
+                            if (visible) return Promise.resolve(visible);
+                            selector.click();
+                            return new Promise(res => setTimeout(() => {
+                                res(document.querySelector('.ant-select-dropdown:not(.ant-select-dropdown-hidden)'));
+                            }, 300));
+                        };
+
+                        return new Promise((resolve) => {
+                            ensureExpanded().then((dropdown) => {
+                                if (dropdown) {
+                                    // find matching options
+                                    const options = Array.from(dropdown.querySelectorAll('.ant-select-item-option'));
+                                    let targetOption = null;
+
+                                    for (let option of options) {
+                                        const textEl = option.querySelector('.ant-select-item-option-content');
+                                        const optionText = textEl ? textEl.textContent.trim() : option.textContent.trim();
+
+                                        if (optionText === targetText ||
+                                            optionText.includes(targetText) ||
+                                            targetText.includes(optionText)) {
+                                            targetOption = option;
+                                            break;
+                                        }
+                                    }
+
+                                    if (!targetOption) {
+                                        const availableOptions = options.map(opt => {
+                                            const textEl = opt.querySelector('.ant-select-item-option-content');
+                                            return textEl ? textEl.textContent.trim() : opt.textContent.trim();
+                                        });
+                                        resolve({
+                                            success: false,
+                                            message: `Option "${targetText}" not found in ant-select. Available: ${availableOptions.join(', ')}`,
+                                            selector_type: 'ant_select',
+                                            availableOptions: availableOptions
+                                        });
+                                        return;
+                                    }
+
+                                    // click option
+                                    targetOption.click();
+
+                                    // trigger event
+                                    antSelect.dispatchEvent(new Event('change', { bubbles: true }));
+
+                                    const selectedText = targetOption.querySelector('.ant-select-item-option-content')?.textContent.trim() || targetOption.textContent.trim();
+                                    const selectedValue = targetOption.getAttribute('data-value') || selectedText;
+
+                                    resolve({
+                                        success: true,
+                                        message: `Successfully selected ant-select option: "${selectedText}"`,
+                                        selectedValue: selectedValue,
+                                        selectedText: selectedText,
+                                        selector_type: 'ant_select'
+                                    });
+                                } else {
+                                    resolve({
+                                        success: false,
+                                        message: 'Could not find ant-select dropdown after clicking',
+                                        selector_type: 'ant_select'
+                                    });
+                                }
+                            });
+                        });
+                    }
+                }
+
+                // 3. handle Ant Design Cascader
+                let antCascader = element.closest('.ant-cascader');
+                if (antCascader) {
+                    // ensure cascader is expanded (idempotent)
+                    const selector = antCascader.querySelector('.ant-select-selector');
+                    if (selector) {
+                        const ensureExpanded = () => {
+                            const visible = document.querySelector('.ant-cascader-dropdown:not(.ant-cascader-dropdown-hidden)');
+                            if (visible) return Promise.resolve(visible);
+                            selector.click();
+                            return new Promise(res => setTimeout(() => {
+                                res(document.querySelector('.ant-cascader-dropdown:not(.ant-cascader-dropdown-hidden)'));
+                            }, 300));
+                        };
+
+                        return new Promise((resolve) => {
+                            ensureExpanded().then((dropdown) => {
+                                if (dropdown) {
+                                    // find matching options in first level
+                                    const firstLevelOptions = Array.from(dropdown.querySelectorAll('.ant-cascader-menu:first-child .ant-cascader-menu-item'));
+                                    let targetOption = null;
+
+                                    for (let option of firstLevelOptions) {
+                                        const optionText = option.textContent.trim();
+                                        if (optionText === targetText ||
+                                            optionText.includes(targetText) ||
+                                            targetText.includes(optionText)) {
+                                            targetOption = option;
+                                            break;
+                                        }
+                                    }
+
+                                    if (!targetOption) {
+                                        const availableOptions = firstLevelOptions.map(opt => opt.textContent.trim());
+                                        resolve({
+                                            success: false,
+                                            message: `Option "${targetText}" not found in cascader first level. Available: ${availableOptions.join(', ')}`,
+                                            selector_type: 'ant_cascader',
+                                            availableOptions: availableOptions
+                                        });
+                                        return;
+                                    }
+
+                                    // click option
+                                    targetOption.click();
+
+                                    // if it is leaf node (no sub options), trigger select event and close dropdown
+                                    if (!targetOption.classList.contains('ant-cascader-menu-item-expand')) {
+                                        antCascader.dispatchEvent(new Event('change', { bubbles: true }));
+
+                                        // close dropdown
+                                        setTimeout(() => {
+                                            document.body.click();
+                                        }, 100);
+                                    }
+
+                                    const selectedText = targetOption.textContent.trim();
+                                    const selectedValue = targetOption.getAttribute('data-path-key') || selectedText;
+
+                                    resolve({
+                                        success: true,
+                                        message: `Successfully selected cascader option: "${selectedText}"`,
+                                        selectedValue: selectedValue,
+                                        selectedText: selectedText,
+                                        selector_type: 'ant_cascader'
+                                    });
+                                } else {
+                                    resolve({
+                                        success: false,
+                                        message: 'Could not find cascader dropdown after clicking',
+                                        selector_type: 'ant_cascader'
+                                    });
+                                }
+                            });
+                        });
+                    }
+                }
+
+                // 4. handle other custom dropdown components
+                let customDropdown = element.closest('[role="combobox"], [role="listbox"], .dropdown, .select');
+                if (customDropdown) {
+                    // try to click to expand
+                    customDropdown.click();
+
+                    setTimeout(() => {
+                        const options = Array.from(document.querySelectorAll('[role="option"], .option, .item'));
+                        let targetOption = null;
+
+                        for (let option of options) {
+                            const optionText = option.textContent.trim();
+                            if (optionText === targetText ||
+                                optionText.includes(targetText) ||
+                                targetText.includes(optionText)) {
+                                targetOption = option;
+                                break;
+                            }
+                        }
+
+                        if (targetOption) {
+                            targetOption.click();
+                            customDropdown.dispatchEvent(new Event('change', { bubbles: true }));
+
+                            return {
+                                success: true,
+                                message: `Successfully selected custom dropdown option: "${targetOption.textContent.trim()}"`,
+                                selectedValue: targetOption.getAttribute('value') || targetOption.textContent.trim(),
+                                selectedText: targetOption.textContent.trim(),
+                                selector_type: 'custom_dropdown'
+                            };
+                        }
+                    }, 300);
+                }
+
+                // if no match, return failure
+                return {
+                    success: false,
+                    message: 'No supported dropdown type found for selection. Element classes: ' + element.className,
+                    selector_type: 'unsupported'
+                };
+            }
+            """
+
+            result = await self.page.evaluate(js_code, {'elementData': element, 'targetText': option_text})
+
+            if result.get('success'):
+                logging.debug(f"Successfully selected {result.get('selector_type')} option: {option_text}")
+                return {
+                    'success': True,
+                    'message': result['message'],
+                    'selected_value': result.get('selectedValue'),
+                    'selected_text': result.get('selectedText'),
+                    'selector_type': result.get('selector_type'),
+                }
+            else:
+                logging.error(f"Failed to select dropdown option: {result.get('message')}")
+                return {
+                    'success': False,
+                    'message': result.get('message', 'Unknown error'),
+                    'selected_value': None,
+                    'selector_type': result.get('selector_type', 'unknown'),
+                    'available_options': result.get('availableOptions'),
+                }
+
+        except Exception as e:
+            logging.error(f'Error selecting dropdown option: {str(e)}')
+            return {'success': False, 'message': f'Error: {str(e)}', 'selected_value': None, 'selector_type': 'error'}
+
+    async def select_cascade_level(self, id, option_text: str, level: int = 0) -> Dict[str, Any]:
+        """Select cascade selector specific level option.
+
+        Args:
+            id: element ID
+            option_text: option text to select
+            level: cascade level (0 for first level, 1 for second level, etc.)
+
+        Returns:
+            Dict: operation result
+        """
+        element = self.page_element_buffer.get(str(id))
+        if not element:
+            return {
+                'success': False,
+                'message': f'Element with id {id} not found in buffer',
+                'selector_type': 'unknown',
+            }
+
+        try:
+            # use JavaScript to perform cascade selection
+            js_code = """
+            (params) => {
+                const elementData = params.elementData;
+                const targetText = params.targetText;
+                const level = params.level;
+
+                // find element by coordinates
+                const centerX = elementData.center_x;
+                const centerY = elementData.center_y;
+                const element = document.elementFromPoint(centerX, centerY);
+
+                if (!element) {
+                    return { success: false, message: 'Element not found at coordinates', selector_type: 'unknown' };
+                }
+
+                // check if it is Ant Design Cascader
+                let antCascader = element.closest('.ant-cascader');
+                if (antCascader) {
+                    return new Promise((resolve) => {
+                        // if it is first level, need to click to open dropdown
+                        if (level === 0) {
+                            const selector = antCascader.querySelector('.ant-select-selector');
+                            if (selector) {
+                                selector.click();
+                            }
+                        }
+
+                        setTimeout(() => {
+                            const dropdown = document.querySelector('.ant-cascader-dropdown:not(.ant-cascader-dropdown-hidden)');
+                            if (!dropdown) {
+                                resolve({
+                                    success: false,
+                                    message: `Could not find cascader dropdown for level ${level}`,
+                                    selector_type: 'ant_cascader'
+                                });
+                                return;
+                            }
+
+                            // select corresponding menu by level
+                            const menus = dropdown.querySelectorAll('.ant-cascader-menu');
+                            if (level >= menus.length) {
+                                resolve({
+                                    success: false,
+                                    message: `Level ${level} not available, only ${menus.length} levels found`,
+                                    selector_type: 'ant_cascader'
+                                });
+                                return;
+                            }
+
+                            const targetMenu = menus[level];
+                            const options = Array.from(targetMenu.querySelectorAll('.ant-cascader-menu-item'));
+                            let targetOption = null;
+
+                            // find matching options
+                            for (let option of options) {
+                                const optionText = option.textContent.trim();
+                                if (optionText === targetText ||
+                                    optionText.includes(targetText) ||
+                                    targetText.includes(optionText)) {
+                                    targetOption = option;
+                                    break;
+                                }
+                            }
+
+                            if (!targetOption) {
+                                const availableOptions = options.map(opt => opt.textContent.trim());
+                                resolve({
+                                    success: false,
+                                    message: `Option "${targetText}" not found in level ${level}. Available: ${availableOptions.join(', ')}`,
+                                    selector_type: 'ant_cascader',
+                                    availableOptions: availableOptions
+                                });
+                                return;
+                            }
+
+                            // click option
+                            targetOption.click();
+
+                            const selectedText = targetOption.textContent.trim();
+                            const selectedValue = targetOption.getAttribute('data-path-key') || selectedText;
+
+                            // if it is last level or no sub options, trigger select event and close dropdown
+                            if (!targetOption.classList.contains('ant-cascader-menu-item-expand')) {
+                                setTimeout(() => {
+                                    antCascader.dispatchEvent(new Event('change', { bubbles: true }));
+                                    // close dropdown
+                                    document.body.click();
+                                }, 100);
+                            }
+
+                            resolve({
+                                success: true,
+                                message: `Successfully selected level ${level} option: "${selectedText}"`,
+                                selectedValue: selectedValue,
+                                selectedText: selectedText,
+                                selector_type: 'ant_cascader',
+                                level: level
+                            });
+                        }, level === 0 ? 500 : 300); // first level needs more time to wait for dropdown to open
+                    });
+                }
+
+                // handle other types of cascade selectors
+                return {
+                    success: false,
+                    message: 'Only Ant Design Cascader is supported for cascade selection',
+                    selector_type: 'unsupported'
+                };
+            }
+            """
+
+            result = await self.page.evaluate(
+                js_code, {'elementData': element, 'targetText': option_text, 'level': level}
+            )
+
+            if result.get('success'):
+                logging.debug(f'Successfully selected level {level} option: {option_text}')
+                return {
+                    'success': True,
+                    'message': result['message'],
+                    'selected_value': result.get('selectedValue'),
+                    'selected_text': result.get('selectedText'),
+                    'selector_type': result.get('selector_type'),
+                    'level': level,
+                }
+            else:
+                logging.error(f"Failed to select level {level} option: {result.get('message')}")
+                return {
+                    'success': False,
+                    'message': result.get('message', 'Unknown error'),
+                    'selector_type': result.get('selector_type', 'unknown'),
+                    'available_options': result.get('availableOptions'),
+                    'level': level,
+                }
+
+        except Exception as e:
+            logging.error(f'Error selecting cascade level {level} option: {str(e)}')
+            return {'success': False, 'message': f'Error: {str(e)}', 'selector_type': 'error', 'level': level}
+
+    async def drag(self, source_coords, target_coords):
+        """Execute drag action."""
+
+        source_x = source_coords.get('x')
+        source_y = source_coords.get('y')
+        target_x = target_coords.get('x')
+        target_y = target_coords.get('y')
+
+        try:
+
+            # move to start position
+            await self.page.mouse.move(source_x, source_y)
+            await asyncio.sleep(0.1)
+
+            # press mouse
+            await self.page.mouse.down()
+            await asyncio.sleep(0.1)
+
+            # drag to target position
+            await self.page.mouse.move(target_x, target_y)
+            await asyncio.sleep(0.1)
+
+            # release mouse
+            await self.page.mouse.up()
+            await asyncio.sleep(0.2)
+
+            logging.debug(f'Drag completed from ({source_x}, {source_y}) to ({target_x}, {target_y})')
+            return True
+
+        except Exception as e:
+            logging.error(f'Drag action failed: {str(e)}')
+            return False

webqa_agent/actions/click_handler.py

@@ -0,0 +1,339 @@
+import asyncio
+import logging
+from typing import Any, Dict, Optional
+
+from playwright.async_api import Page
+
+from webqa_agent.actions.action_handler import ActionHandler
+
+
+class ClickHandler:
+    """Enhanced click handler with multiple locating strategies."""
+
+    def __init__(self):
+        self.console_errors = []
+        self.network_errors = []
+        self.response_errors = []
+
+    async def setup_listeners(self, page: Page):
+        """Setup console and network error listeners."""
+
+        # Console error listener
+        async def on_console(msg):
+            if msg.type in ["error", "warning"]:
+                error_info = {
+                    "type": msg.type,
+                    "text": msg.text,
+                    "location": msg.location,
+                    "timestamp": asyncio.get_event_loop().time(),
+                }
+                self.console_errors.append(error_info)
+                logging.debug(f"Console {msg.type}: {msg.text}")
+
+        # Network error listener
+        async def on_request_failed(request):
+            IGNORE_ERRORS = [
+                "net::ERR_ABORTED",
+                "net::ERR_CACHE_MISS",
+            ]
+            if request.failure not in IGNORE_ERRORS:
+                error_info = {
+                    "url": request.url,
+                    "method": request.method,
+                    "failure": request.failure,
+                }
+                self.network_errors.append(error_info)
+                logging.debug(f"Network error: {request.url} - {request.failure}")
+
+        # Response error listener (4xx, 5xx)
+        async def on_response(response):
+            if response.status >= 400:
+                error_info = {
+                    "url": response.url,
+                    "status": response.status,
+                    "status_text": response.status_text,
+                }
+                self.response_errors.append(error_info)
+                logging.debug(f"Response error: {response.url} - {response.status}")
+
+        # Attach listeners
+        page.on("console", on_console)
+        page.on("requestfailed", on_request_failed)
+        page.on("response", on_response)
+
+    async def click_and_screenshot(
+        self, page: Page, element_info: Dict[str, Any], element_index: int = 0
+    ) -> Dict[str, Any]:
+        """Click an element and monitor for errors.
+
+        Args:
+            page: Playwright page object
+            element_info: Element information from clickable_elements_detection
+            element_index: Index of the element being tested
+
+        Returns:
+            Dictionary containing click result and any errors
+        """
+
+        # Clear previous errors
+        action_handler = ActionHandler()
+        action_handler.page = page
+
+        click_result = {
+            "element": element_info,
+            "success": False,
+            "error": None,
+            "console_errors": [],
+            "network_errors": [],
+            "response_errors": [],
+            "screenshot_before": None,
+            "screenshot_after": None,
+            "new_page_screenshot": None,
+            "click_method": None,
+            "click_coordinates": None,
+            "has_new_page": False,
+        }
+
+        selector = element_info.get("selector")
+        xpath = element_info.get("xpath")
+        click_success = False
+
+        logging.debug(f"Clicking element: {element_info}")
+
+        context = page.context
+        new_page = None
+
+        def handle_new_page(page_obj):
+            nonlocal new_page
+            new_page = page_obj
+            logging.debug(f"New page detected: {page_obj.url}")
+
+        context.on("page", handle_new_page)
+
+        click_success = await self._perform_click(page, selector, xpath, click_result)
+
+        if click_success:
+            click_result["success"] = True
+            await asyncio.sleep(2)
+            if new_page:
+                click_result["has_new_page"] = True
+                try:
+                    await new_page.wait_for_load_state("networkidle", timeout=30000)
+
+                    new_page_action_handler = ActionHandler()
+                    new_page_action_handler.page = new_page
+                    screenshot_b64 = await new_page_action_handler.b64_page_screenshot(
+                        file_name=f"element_{element_index}_new_page"
+                    )
+                    click_result["new_page_screenshot"] = screenshot_b64
+                    logging.debug("New page screenshot saved")
+
+                except Exception as e:
+                    click_result["error"] = f"Failed to handle new page: {e}"
+                    logging.warning(f"Failed to handle new page: {e}")
+
+                await page.wait_for_load_state("networkidle", timeout=30000)
+            else:
+                screenshot_b64 = await action_handler.b64_page_screenshot(
+                    file_name=f"element_{element_index}_after_click"
+                )
+                click_result["screenshot_after"] = screenshot_b64
+                logging.debug("After click screenshot saved")
+
+        else:
+            click_result["error"] = f"Failed to click element with all strategies. Element: '{element_info}'"
+            logging.warning(f"Failed to click element: '{element_info}'")
+
+        context.remove_listener("page", handle_new_page)
+        await self._close_popups(page)
+
+        return click_result
+
+    async def _perform_click(
+        self, page: Page, selector: Optional[str], xpath: Optional[str], click_result: Dict
+    ) -> bool:
+        click_timeout = 10000
+
+        if xpath:
+            locator_str = f"xpath={xpath}"
+            try:
+                await self._scroll_into_view_safely(page, locator_str)
+                await page.click(locator_str, timeout=click_timeout)
+                click_result["click_method"] = locator_str
+                logging.debug(f"Successfully clicked using xpath: {xpath}")
+                return True
+            except Exception as e:
+                logging.debug(f"XPath click failed: {e}")
+                click_result["error"] = str(e)
+
+        if selector:
+            try:
+                await self._scroll_into_view_safely(page, selector)
+                await page.click(selector, timeout=click_timeout)
+                click_result["click_method"] = selector
+                logging.debug(f"Successfully clicked using selector: {selector}")
+                return True
+            except Exception as e:
+                logging.debug(f"Selector click failed: {e}")
+                click_result["error"] = str(e)
+
+        try:
+            element_handle = None
+            if selector:
+                try:
+                    element_handle = await page.query_selector(selector)
+                except Exception as e:
+                    logging.debug(f"query_selector failed for selector: {e}")
+
+            if not element_handle and xpath:
+                try:
+                    element_handle = await page.query_selector(f"xpath={xpath}")
+                except Exception as e:
+                    logging.debug(f"query_selector failed for xpath: {e}")
+
+            if element_handle:
+                await page.evaluate("el => el.click()", element_handle)
+                click_result["click_method"] = f"js_evaluate_click:{selector or xpath}"
+                logging.debug("Successfully clicked using JS evaluate")
+                return True
+            else:
+                click_result["error"] = "No element handle found for JS click"
+
+        except Exception as e:
+            logging.debug(f"JS click failed: {e}")
+            click_result["error"] = f"All click strategies failed. Last error: {e}"
+
+        return False
+
+    @staticmethod
+    async def _scroll_into_view_safely(page: Page, locator: str):
+        try:
+            await page.locator(locator).scroll_into_view_if_needed(timeout=3000)
+        except Exception as e:
+            logging.debug(f"scroll_into_view_if_needed failed for {locator}: {e}")
+
+    async def _close_popups(self, page: Page):
+        try:
+            popup_detected = await self._detect_popup(page)
+
+            if not popup_detected:
+                logging.debug("No popup detected, skipping close operation")
+                return
+
+            logging.debug("Popup detected, attempting to close...")
+
+            close_selectors = [
+                '[data-dismiss="modal"]',
+                '[data-bs-dismiss="modal"]',
+                ".modal-close",
+                ".close",
+                ".btn-close",
+                ".fa-times",
+                ".fa-close",
+                ".icon-close",
+                ".icon-x",
+                '[aria-label*="close"]',
+                '[aria-label*="Close"]',
+                '[title*="close"]',
+                '[title*="Close"]',
+                'button:has-text("×")',
+                'button:has-text("✕")',
+                'button:has-text("Close")',
+                'button:has-text("关闭")',
+                ".modal-backdrop",
+                ".overlay",
+            ]
+
+            popup_closed = False
+            for selector in close_selectors:
+                try:
+                    element = await page.query_selector(selector)
+                    if element:
+                        is_visible = await element.is_visible()
+                        if is_visible:
+                            await element.click(timeout=2000)
+                            logging.debug(f"Closed popup using selector: {selector}")
+                            popup_closed = True
+                            await asyncio.sleep(0.3)  # Wait for close animation
+                            break
+                except Exception:
+                    continue
+
+            if not popup_closed:
+                try:
+                    await page.keyboard.press("Escape")
+                    logging.debug("Attempted to close popup with ESC key")
+                    await asyncio.sleep(0.3)
+                except Exception:
+                    pass
+
+        except Exception as e:
+            logging.debug(f"Popup close attempt failed: {e}")
+
+    async def _detect_popup(self, page: Page):
+        try:
+            popup_selectors = [
+                ".modal.show",
+                ".modal.in",
+                '.modal[style*="display: block"]',
+                ".dialog",
+                ".popup",
+                ".overlay.show",
+                '.overlay[style*="display: block"]',
+                '[role="dialog"]',
+                '[role="alertdialog"]',
+                ".fancybox-overlay",
+                ".ui-dialog",
+                ".sweet-alert",
+                ".swal-overlay",
+                '[style*="z-index"]',
+            ]
+
+            for selector in popup_selectors:
+                try:
+                    element = await page.query_selector(selector)
+                    if element:
+                        is_visible = await element.is_visible()
+                        if is_visible:
+                            bbox = await element.bounding_box()
+                            if bbox and bbox["width"] > 100 and bbox["height"] > 100:
+                                logging.debug(f"Popup detected with selector: {selector}")
+                                return True
+                except Exception:
+                    continue
+
+            backdrop_selectors = [".modal-backdrop", ".overlay", '[class*="backdrop"]']
+
+            for selector in backdrop_selectors:
+                try:
+                    element = await page.query_selector(selector)
+                    if element:
+                        is_visible = await element.is_visible()
+                        if is_visible:
+                            logging.debug(f"Backdrop detected with selector: {selector}")
+                            return True
+                except Exception:
+                    continue
+
+            return False
+
+        except Exception as e:
+            logging.debug(f"Popup detection failed: {e}")
+            return False
+
+    def get_error_summary(self) -> Dict[str, Any]:
+        """Get a summary of all errors collected."""
+        return {
+            "total_console_errors": len(self.console_errors),
+            "total_network_errors": len(self.network_errors),
+            "total_response_errors": len(self.response_errors),
+            "console_errors": self.console_errors,
+            "network_errors": self.network_errors,
+            "response_errors": self.response_errors,
+        }
+
+    def reset_errors(self):
+        """Reset all error collections."""
+        self.console_errors.clear()
+        self.network_errors.clear()
+        self.response_errors.clear()

webqa_agent/actions/scroll_handler.py

@@ -0,0 +1,365 @@
+import asyncio
+import logging
+import time
+
+from playwright.async_api import Page
+
+from webqa_agent.actions.action_handler import ActionHandler
+
+
+class ScrollHandler:
+    def __init__(self, page: Page):
+        self.page = page
+        self.id_counter = 1
+
+        self._action_handler = ActionHandler()
+        self._action_handler.page = page
+
+    async def detect_scrollable_containers(self):
+        scrollable_containers_script = """
+        (function() {
+            function findScrollableContainers() {
+                const elements = document.querySelectorAll('*');
+                const scrollableContainers = [];
+
+                for (let element of elements) {
+                    if (element === document.body || element === document.documentElement) {
+                        continue;
+                    }
+
+                    const style = window.getComputedStyle(element);
+                    const hasScrollableContent = element.scrollHeight > element.clientHeight ||
+                                               element.scrollWidth > element.clientWidth;
+                    const hasScrollableStyle = style.overflow === 'auto' ||
+                                             style.overflow === 'scroll' ||
+                                             style.overflowY === 'auto' ||
+                                             style.overflowY === 'scroll' ||
+                                             style.overflowX === 'auto' ||
+                                             style.overflowX === 'scroll';
+
+                    if (hasScrollableContent && hasScrollableStyle) {
+                        const rect = element.getBoundingClientRect();
+                        if (rect.width > 0 && rect.height > 0) {
+                            scrollableContainers.push({
+                                tagName: element.tagName,
+                                className: element.className,
+                                id: element.id,
+                                scrollHeight: element.scrollHeight,
+                                clientHeight: element.clientHeight,
+                                scrollWidth: element.scrollWidth,
+                                clientWidth: element.clientWidth,
+                                rect: {
+                                    top: rect.top,
+                                    left: rect.left,
+                                    width: rect.width,
+                                    height: rect.height
+                                }
+                            });
+                        }
+                    }
+                }
+
+                return scrollableContainers.sort((a, b) =>
+                    (b.rect.width * b.rect.height) - (a.rect.width * a.rect.height)
+                );
+            }
+
+            return findScrollableContainers();
+        })()
+        """
+
+        try:
+            containers = await self.page.evaluate(scrollable_containers_script)
+            logging.debug(f"Found {len(containers)} scrollable containers")
+            return containers
+        except Exception as e:
+            logging.error(f"Error detecting scrollable containers: {e}")
+            return []
+
+    async def can_global_scroll(self):
+        can_scroll_script = """
+        (function() {
+            function canGlobalScroll() {
+                const documentHeight = Math.max(
+                    document.body.scrollHeight,
+                    document.body.offsetHeight,
+                    document.documentElement.clientHeight,
+                    document.documentElement.scrollHeight,
+                    document.documentElement.offsetHeight
+                );
+                const windowHeight = window.innerHeight;
+                const currentScrollY = window.scrollY;
+
+                return {
+                    canScroll: documentHeight > windowHeight,
+                    documentHeight: documentHeight,
+                    windowHeight: windowHeight,
+                    currentScrollY: currentScrollY,
+                    maxScrollY: documentHeight - windowHeight
+                };
+            }
+
+            return canGlobalScroll();
+        })()
+        """
+
+        try:
+            scroll_info = await self.page.evaluate(can_scroll_script)
+            logging.debug(f"Global scroll info: {scroll_info}")
+            return scroll_info
+        except Exception as e:
+            logging.error(f"Error checking global scroll capability: {e}")
+            return {"canScroll": False, "documentHeight": 0, "windowHeight": 0, "currentScrollY": 0, "maxScrollY": 0}
+
+    async def scroll_global(self, max_scrolls: int = 10, capture_screenshots: bool = True, page_identifier: str = ""):
+        logging.debug("Executing global page scrolling")
+
+        viewport_height = await self.page.evaluate("window.innerHeight")
+        screenshot_image_list = []
+
+        async def capture_viewport(screenshot_counter=0):
+            if capture_screenshots:
+                timestamp = time.strftime("%Y%m%d%H%M%S")
+                processed_filename = f"{timestamp}_{page_identifier}_global_viewport_{screenshot_counter}"
+
+                screenshot_base64 = await self._action_handler.b64_page_screenshot(file_name=processed_filename)
+
+                if screenshot_base64:
+                    screenshot_image_list.append(screenshot_base64)
+
+        scroll_count = 0
+        await capture_viewport(scroll_count)
+
+        while scroll_count < max_scrolls:
+            current_scroll_y = await self.page.evaluate("window.scrollY")
+            document_height = await self.page.evaluate("document.documentElement.scrollHeight")
+
+            if current_scroll_y + viewport_height >= document_height:
+                logging.debug("Reached bottom of the page.")
+                break
+
+            await self.page.evaluate(f"window.scrollBy(0, {viewport_height})")
+            await asyncio.sleep(2)
+            scroll_count += 1
+            logging.info(f"Global scrolling down... count: {scroll_count}")
+            await capture_viewport(scroll_count)
+
+        return screenshot_image_list
+
+    async def scroll_container(
+        self,
+        container_selector: str,
+        max_scrolls: int = 10,
+        capture_screenshots: bool = True,
+        page_identifier: str = "",
+    ):
+        logging.debug(f"Executing container scrolling for: {container_selector}")
+
+        safe_selector = self._escape_selector(container_selector)
+        if safe_selector != container_selector:
+            logging.warning(f"Selector escaped from '{container_selector}' to '{safe_selector}'")
+
+        screenshot_image_list = []
+
+        async def capture_viewport(screenshot_counter=0):
+            if capture_screenshots:
+                timestamp = time.strftime("%Y%m%d%H%M%S")
+                processed_filename = f"{timestamp}_{page_identifier}_container_viewport_{screenshot_counter}"
+
+                screenshot_base64 = await self._action_handler.b64_page_screenshot(file_name=processed_filename)
+
+                if screenshot_base64:
+                    screenshot_image_list.append(screenshot_base64)
+
+        try:
+            container_exists = await self.page.evaluate(
+                f"""
+            (function() {{
+                try {{
+                    return !!document.querySelector('{safe_selector}');
+                }} catch(e) {{
+                    console.error('Selector error:', e);
+                    return false;
+                }}
+            }})()
+            """
+            )
+        except Exception as e:
+            logging.error(f"Error checking container existence: {e}")
+            return screenshot_image_list
+
+        if not container_exists:
+            logging.error(f"Container with selector '{safe_selector}' not found")
+            return screenshot_image_list
+
+        scroll_count = 0
+        await capture_viewport(scroll_count)
+
+        while scroll_count < max_scrolls:
+
+            try:
+                scroll_info = await self.page.evaluate(
+                    f"""
+                (function() {{
+                    try {{
+                        const container = document.querySelector('{safe_selector}');
+                        if (!container) return null;
+
+                        return {{
+                            scrollTop: container.scrollTop,
+                            scrollHeight: container.scrollHeight,
+                            clientHeight: container.clientHeight,
+                            canScroll: container.scrollHeight > container.clientHeight
+                        }};
+                    }} catch(e) {{
+                        console.error('Scroll info error:', e);
+                        return null;
+                    }}
+                }})()
+                """
+                )
+            except Exception as e:
+                logging.error(f"Error getting scroll info: {e}")
+                break
+
+            if not scroll_info or not scroll_info["canScroll"]:
+                logging.debug("Container cannot scroll or reached bottom")
+                break
+
+            if scroll_info["scrollTop"] + scroll_info["clientHeight"] >= scroll_info["scrollHeight"]:
+                logging.debug("Reached bottom of the container")
+                break
+
+            # scroll container
+            scroll_amount = scroll_info["clientHeight"]
+            try:
+                await self.page.evaluate(
+                    f"""
+                (function() {{
+                    try {{
+                        const container = document.querySelector('{safe_selector}');
+                        if (container) {{
+                            container.scrollBy(0, {scroll_amount});
+                        }}
+                    }} catch(e) {{
+                        console.error('Scroll error:', e);
+                    }}
+                }})()
+                """
+                )
+            except Exception as e:
+                logging.error(f"Error scrolling container: {e}")
+                break
+
+            await asyncio.sleep(2)
+            scroll_count += 1
+            logging.info(f"Container scrolling down... count: {scroll_count}")
+            await capture_viewport(scroll_count)
+
+        return screenshot_image_list
+
+    def _safe_selector(self, element_info):
+        if element_info.get("id") and element_info["id"].strip():
+            element_id = element_info["id"].strip()
+            if element_id and not any(c in element_id for c in [" ", '"', "'", "\\", "/"]):
+                return f"#{element_id}"
+
+        if element_info.get("className") and element_info["className"].strip():
+            class_names = element_info["className"].strip().split()
+            for class_name in class_names:
+                if class_name and all(c.isalnum() or c in ["-", "_"] for c in class_name):
+                    return f".{class_name}"
+
+        tag_name = element_info.get("tagName", "div").lower()
+        return tag_name
+
+    def _escape_selector(self, selector):
+
+        if any(c in selector for c in ['"', "'", "\\", "/"]):
+            return "div"
+        return selector
+
+    async def scroll_and_crawl(
+        self,
+        scroll: bool = True,
+        max_scrolls: int = 10,
+        capture_screenshots: bool = True,
+        page_identifier: str = "",
+        prefer_container: bool = True,
+    ):
+
+        screenshot_image_list = []
+
+        # if not scroll, exit after initial capture
+        if not scroll:
+            logging.debug("Scrolling disabled, exiting after initial capture.")
+            timestamp = time.strftime("%Y%m%d%H%M%S")
+            processed_filename = f"{timestamp}_{page_identifier}_initial"
+            screenshot_base64 = await self._action_handler.b64_page_screenshot(file_name=processed_filename)
+            if screenshot_base64:
+                screenshot_image_list.append(screenshot_base64)
+            return screenshot_image_list
+
+        try:
+            # check global scroll ability
+            global_scroll_info = await self.can_global_scroll()
+
+            if global_scroll_info["canScroll"]:
+                logging.debug("Global scrolling is possible, using global scroll")
+                screenshot_image_list = await self.scroll_global(max_scrolls, capture_screenshots, page_identifier)
+            else:
+                logging.debug("Global scrolling not possible, checking for scrollable containers")
+
+                # detect scrollable containers
+                containers = await self.detect_scrollable_containers()
+
+                if containers:
+                    # select the largest container for scrolling
+                    main_container = containers[0]
+                    logging.debug(
+                        f"Using main container: {main_container['tagName']} (class: {main_container.get('className', 'N/A')})"
+                    )
+
+                    # build safe selector
+                    selector = self._safe_selector(main_container)
+                    logging.debug(f"Using selector: {selector}")
+
+                    screenshot_image_list = await self.scroll_container(
+                        selector, max_scrolls, capture_screenshots, page_identifier
+                    )
+
+                    # if first container scrolling failed, try other containers
+                    if len(screenshot_image_list) <= 1 and len(containers) > 1:
+                        logging.debug("Main container scrolling failed, trying other containers")
+                        for i, container in enumerate(containers[1:], 1):
+                            logging.debug(
+                                f"Trying container {i+1}: {container['tagName']} (class: {container.get('className', 'N/A')})"
+                            )
+
+                            selector = self._safe_selector(container)
+                            logging.debug(f"Using selector: {selector}")
+
+                            container_screenshots = await self.scroll_container(
+                                selector, max_scrolls, capture_screenshots, page_identifier
+                            )
+                            if len(container_screenshots) > 1:
+                                screenshot_image_list = container_screenshots
+                                break
+                else:
+                    logging.debug("No scrollable containers found, taking single screenshot")
+                    timestamp = time.strftime("%Y%m%d%H%M%S")
+                    processed_filename = f"{timestamp}_{page_identifier}_no_scroll"
+                    screenshot_base64 = await self._action_handler.b64_page_screenshot(file_name=processed_filename)
+                    if screenshot_base64:
+                        screenshot_image_list.append(screenshot_base64)
+
+        except Exception as e:
+            logging.error(f"Error in smart scroll: {e}")
+            # if error, at least take one screenshot
+            timestamp = time.strftime("%Y%m%d%H%M%S")
+            processed_filename = f"{timestamp}_{page_identifier}_error_fallback"
+            screenshot_base64 = await self._action_handler.b64_page_screenshot(file_name=processed_filename)
+            if screenshot_base64:
+                screenshot_image_list.append(screenshot_base64)
+
+        return screenshot_image_list

webqa_agent/browser/check.py

@@ -0,0 +1,300 @@
+import json
+from datetime import datetime
+
+from playwright.async_api import Page
+
+
+class NetworkCheck:
+    def __init__(self, page: Page):
+        self.page = page
+        self.network_messages = {"failed_requests": [], "responses": [], "requests": []}
+        self._response_callback = self._handle_response()
+        self._request_callback = self._handle_request()
+        self._requestfinished_callback = self._handle_request_finished()
+        self._setup_listeners()
+
+    def _setup_listeners(self):
+        # 1. listen to request
+        self.page.on("request", self._request_callback)
+        # 2. listen to response
+        self.page.on("response", self._response_callback)
+        # 3. listen to request finished
+        self.page.on("requestfinished", self._requestfinished_callback)
+
+    def _handle_request(self):
+        async def request_callback(request):
+            request_data = {
+                "url": request.url,
+                "method": request.method,
+                "timestamp": datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f"),
+                "has_response": False,
+                "completed": False,
+                "failed": False,
+                "is_sse": False,
+                "sse_messages": [],  # list for storing SSE messages
+            }
+            self.network_messages["requests"].append(request_data)
+
+        return request_callback
+
+    def _handle_response(self):
+        async def response_callback(response):
+            response_url = response.url
+            try:
+                current_request = None
+                for request in self.network_messages["requests"]:
+                    if request["url"] == response_url:
+                        request["has_response"] = True
+                        current_request = request
+                        break
+
+                if not current_request:
+                    return
+
+                # Get response headers
+                try:
+                    headers = await response.all_headers()
+                    content_type = headers.get("content-type", "")
+                except Exception:
+                    # logging.warning(f"Unable to get headers for {response_url}: {str(e)}")
+                    content_type = ""
+                    headers = {}
+
+                # Create response data structure
+                response_data = {
+                    "url": response_url,
+                    "status": response.status,
+                    "method": response.request.method,
+                    "content_type": content_type,
+                    "timestamp": datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f"),
+                    "headers": headers,  # 保存响应头信息
+                    "sse_messages": [],
+                }
+
+                if response.status >= 400:
+                    response_data["error"] = f"HTTP {response.status}"
+                    self.network_messages["responses"].append(response_data)
+                    return
+
+                if "text/event-stream" in content_type:
+                    current_request["is_sse"] = True
+                    response_data["is_sse"] = True
+
+                    try:
+                        response_data["sse_pending"] = True
+                    except Exception as e:
+                        response_data["error"] = str(e)
+
+                else:
+                    try:
+                        if any(
+                            bin_type in content_type.lower()
+                            for bin_type in [
+                                "image/",
+                                "audio/",
+                                "video/",
+                                "application/pdf",
+                                "application/octet-stream",
+                                "font/",
+                                "application/x-font",
+                            ]
+                        ):
+                            response_data["body"] = f"<{content_type} binary data>"
+                            response_data["size"] = len(await response.body())
+
+                        elif "application/json" in content_type:
+                            try:
+                                body = await response.json()
+                                response_data["body"] = body
+                            except Exception as e:
+                                response_data["error"] = f"JSON parse error: {str(e)}"
+
+                        elif any(
+                            text_type in content_type.lower()
+                            for text_type in [
+                                "text/",
+                                "application/javascript",
+                                "application/xml",
+                                "application/x-www-form-urlencoded",
+                            ]
+                        ):
+                            try:
+                                text_body = await response.text()
+                                response_data["body"] = text_body
+                            except Exception as e:
+                                response_data["error"] = f"Text decode error: {str(e)}"
+
+                        else:
+                            response_data["body"] = f"<{content_type} data>"
+                            response_data["size"] = len(await response.body())
+
+                    except Exception as e:
+                        response_data["error"] = str(e)
+
+                self.network_messages["responses"].append(response_data)
+
+            except Exception:
+                pass
+
+        return response_callback
+
+    def _parse_sse_chunk(self, chunk):
+        """Parse SSE data chunk."""
+        messages = []
+        current_message = {}
+
+        for line in chunk.split("\n"):
+            line = line.strip()
+            if not line:
+                if current_message:
+                    messages.append(current_message)
+                    current_message = {}
+                continue
+
+            if line.startswith("data:"):
+                data = line[5:].strip()
+                try:
+                    # try to parse JSON data
+                    json_data = json.loads(data)
+                    if "data" not in current_message:
+                        current_message["data"] = json_data
+                    else:
+                        # if there is data, append new data to existing data
+                        if isinstance(current_message["data"], list):
+                            current_message["data"].append(json_data)
+                        else:
+                            current_message["data"] = [current_message["data"], json_data]
+                except json.JSONDecodeError:
+                    if "data" not in current_message:
+                        current_message["data"] = data
+                    else:
+                        current_message["data"] += "\n" + data
+        if current_message:
+            messages.append(current_message)
+
+        return messages
+
+    def _handle_request_finished(self):
+        async def request_finished_callback(request):
+            try:
+                response = await request.response()
+                if not response:
+                    # logging.warning(f"No response object for request: {request.url}")
+                    return
+                # logging.debug(f"Response object for request: {request.url}")
+                for req in self.network_messages["requests"]:
+                    if req["url"] == request.url:
+                        req["completed"] = True
+
+                        if req.get("is_sse"):
+                            try:
+                                body = await response.body()
+                                text = body.decode("utf-8", errors="replace")
+
+                                # handle SSE messages
+                                messages = []
+
+                                # process SSE data by line
+                                for line in text.split("\n"):
+                                    if not line:
+                                        continue
+
+                                    if not line.startswith("data:"):
+                                        continue
+
+                                    # extract data content
+                                    sse_data = line[5:].strip()  # remove 'data:' prefix
+                                    if not sse_data:
+                                        continue
+
+                                    try:
+                                        # parse JSON data
+                                        json_data = json.loads(sse_data)
+                                        messages.append(
+                                            {
+                                                "data": json_data,
+                                            }
+                                        )
+                                    except json.JSONDecodeError:
+                                        # if not JSON, store original text
+                                        messages.append(
+                                            {
+                                                "data": sse_data,
+                                            }
+                                        )
+
+                                req["sse_messages"] = messages
+
+                                for resp in self.network_messages["responses"]:
+                                    if resp["url"] == request.url:
+                                        resp["sse_messages"] = messages
+                                        resp["sse_completed"] = True
+                                        break
+
+                            except Exception:
+                                pass
+                        break
+
+            except Exception:
+                pass
+
+        return request_finished_callback
+
+    def get_messages(self):
+        return self.network_messages
+
+    def _on_request_failed(self, request):
+        # find and update request status
+        for req in self.network_messages["requests"]:
+            if req["url"] == request.url:
+                req["failed"] = True
+                break
+
+        error_data = {"url": request.url, "error": request.failure}
+        self.network_messages["failed_requests"].append(error_data)
+
+    def remove_listeners(self):
+        # Prefer Playwright's off() which understands internal wrapper mapping
+        listeners = [
+            ("request", self._request_callback),
+            ("response", self._response_callback),
+            ("requestfinished", self._requestfinished_callback),
+        ]
+        for event_name, handler in listeners:
+            try:
+                if hasattr(self.page, "off"):
+                    self.page.off(event_name, handler)
+                else:
+                    # Fallback for environments exposing remove_listener
+                    self.page.remove_listener(event_name, handler)
+            except Exception:
+                # Silently ignore if already removed or not found
+                pass
+
+
+class ConsoleCheck:
+    def __init__(self, page):
+        self.page = page
+        self.console_messages = []
+        self._setup_listeners()
+
+    def _setup_listeners(self):
+        self.page.on("console", self._handle_console)
+
+    def _handle_console(self, msg):
+        if msg.type == "error":
+            error_message = msg.text
+            error_location = getattr(msg, "location", None)
+            self.console_messages.append({"msg": error_message, "location": error_location})
+
+    def get_messages(self):
+        return self.console_messages
+
+    def remove_listeners(self):
+        try:
+            if hasattr(self.page, "off"):
+                self.page.off("console", self._handle_console)
+            else:
+                self.page.remove_listener("console", self._handle_console)
+        except Exception:
+            pass

webqa_agent/browser/config.py

@@ -0,0 +1,17 @@
+SUPPORTED_BROWSERS = ["chromium", "firefox", "webkit"]
+HEADLESS = [True, False]
+# SUPPORTED_BROWSERS = ["firefox"]
+
+SUPPORTED_RESOLUTIONS = [
+    {"width": 1366, "height": 768},
+    # {"width": 1440, "height": 900},
+    {"width": 1920, "height": 1080},
+    # {"width": 2560, "height": 1440},
+]
+
+DEFAULT_CONFIG = {
+    "browser_type": "chromium",
+    "viewport": {"width": 1280, "height": 720},
+    "headless": True,
+    "language": "en-US",
+}

webqa_agent/browser/driver.py

@@ -0,0 +1,137 @@
+import asyncio
+import logging
+
+from playwright.async_api import async_playwright
+
+
+class Driver:
+    # Lock used to ensure thread-safety when multiple coroutines create Driver instances concurrently
+    __lock = asyncio.Lock()
+
+    @staticmethod
+    async def getInstance(browser_config, *args, **kwargs):
+        """Returns the singleton instance of the Driver class. If the instance
+        is closed, creates a new one.
+
+        Args:
+            browser_config (dict, optional): Browser configuration options.
+        """
+        logging.debug(f"Driver.getInstance called with browser_config: {browser_config}")
+
+        # Always create a *new* Driver instance – singleton restriction removed to
+        # allow multiple browsers to run in parallel.  Keeping the public API
+        # unchanged ensures existing call-sites keep working.
+        async with Driver.__lock:
+            driver = Driver(browser_config=browser_config)
+            await driver.create_browser(browser_config=browser_config)
+            return driver
+
+    def __init__(self, browser_config=None, *args, **kwargs):
+        # Each call constructs an independent browser driver.
+        self._is_closed = False
+        self.page = None
+        self.browser = None
+        self.context = None
+        self.playwright = None
+
+    def is_closed(self):
+        """Check if the browser instance is closed."""
+        return getattr(self, "_is_closed", True)
+
+    async def create_browser(self, browser_config):
+        """Creates a new browser instance and sets up the page.
+
+        Args:
+            browser_config (dict, optional): Browser configuration containing:
+                - headless (bool): Whether to run browser in headless mode
+                - viewport_width (int): Browser viewport width
+                - viewport_height (int): Browser viewport height
+                - device_scale_factor (float): Device scale factor
+
+        Returns:
+            None
+        """
+        try:
+            # logging.debug(f"Driver create_browser called with browser_config: {browser_config}")
+
+            self.playwright = await async_playwright().start()
+            self.browser = await self.playwright.chromium.launch(
+                headless=browser_config["headless"],
+                args=[
+                    "--disable-dev-shm-usage",  # Mitigate shared memory issues in Docker
+                    "--no-sandbox",
+                    "--disable-setuid-sandbox",
+                    "--disable-gpu",
+                    "--force-device-scale-factor=1",
+                    f'--window-size={browser_config["viewport"]["width"]},{browser_config["viewport"]["height"]}',
+                ],
+            )
+
+            # 创建新的上下文，使用配置的视口大小
+            self.context = await self.browser.new_context(
+                viewport={"width": browser_config["viewport"]["width"], "height": browser_config["viewport"]["height"]},
+                device_scale_factor=1,
+                is_mobile=False,
+                locale=browser_config["language"],
+            )
+            # await self.context.tracing.start(screenshots=True, snapshots=True)
+            self.page = await self.context.new_page()
+            browser_config["browser"] = "Chromium"
+            self.config = browser_config
+
+            logging.debug(f"Browser instance created successfully with config: {browser_config}")
+            return self.page
+
+        except Exception as e:
+            logging.error("Failed to create browser instance.", exc_info=True)
+            raise
+
+    def get_context(self):
+        try:
+            return self.context
+        except Exception as e:
+            logging.error("Failed to get context: %s", e, exc_info=True)
+            raise
+
+    def get_page(self):
+        """Returns the current page instance.
+
+        Returns:
+            Page: The current page instance.
+        """
+        try:
+            return self.page
+        except Exception as e:
+            logging.error("Failed to get Driver instance: %s", e, exc_info=True)
+            raise
+
+    async def get_new_page(self):
+        """Switches to the most recently opened page in the browser.
+
+        Returns:
+            Page: The new page instance.
+        """
+        try:
+            pages = self.context.pages
+            logging.debug(f"page number: {len(pages)}")
+            if len(pages) > 1:
+                logging.debug("New page detected.")
+                self.page = pages[-1]
+                return self.page
+            else:
+                return self.page
+        except Exception as e:
+            logging.error("Failed to get new page: %s", e, exc_info=True)
+            raise
+
+    async def close_browser(self):
+        """Closes the browser instance and stops Playwright."""
+        try:
+            if not self.is_closed():
+                await self.browser.close()
+                await self.playwright.stop()
+                self._is_closed = True  # mark closed
+                logging.debug("Browser instance closed successfully.")
+        except Exception as e:
+            logging.error("Failed to close browser instance.", exc_info=True)
+            raise

webqa_agent/browser/session.py

@@ -0,0 +1,195 @@
+import asyncio
+import json
+import logging
+import uuid
+from typing import Any, Dict, Optional, Union
+
+from playwright.async_api import BrowserContext, Page
+
+from webqa_agent.browser.config import DEFAULT_CONFIG
+
+# Browser creation is now delegated to Driver to ensure a single entry-point.
+from webqa_agent.browser.driver import Driver
+
+
+class BrowserSession:
+    """Browser session manager for parallel test execution."""
+
+    def __init__(self, session_id: str = None, browser_config: Dict[str, Any] = None):
+        self.session_id = session_id or str(uuid.uuid4())
+        self.browser_config = {**DEFAULT_CONFIG, **(browser_config or {})}
+        self.driver: Optional[Driver] = None
+        # Driver will own browser, context, page and playwright instances
+        self._playwright = None  # retained only for backward compatibility when needed
+        self._is_closed = False
+        self._lock = asyncio.Lock()
+
+    async def initialize(self):
+        """Initialize browser session."""
+        async with self._lock:
+            if self._is_closed:
+                raise RuntimeError("Browser session is closed")
+
+            logging.debug(f"Initializing browser session {self.session_id} with config: {self.browser_config}")
+
+            try:
+                # Use Driver as the single browser creation entry-point.
+                self.driver = await Driver.getInstance(browser_config=self.browser_config)
+
+                # Keep reference if external code needs direct access (optional)
+                self._playwright = self.driver.playwright
+
+                logging.debug(f"Browser session {self.session_id} initialized successfully via Driver")
+
+            except Exception as e:
+                logging.error(f"Failed to initialize browser session {self.session_id}: {e}")
+                await self._cleanup()
+                raise
+
+    async def navigate_to(self, url: str, cookies: Optional[Union[str, list]] = None, **kwargs):
+        """Navigate to URL."""
+        if self._is_closed or not self.driver:
+            raise RuntimeError("Browser session not initialized or closed")
+
+        logging.debug(f"Session {self.session_id} navigating to: {url}")
+        kwargs.setdefault("timeout", 60000)
+        kwargs.setdefault("wait_until", "domcontentloaded")
+
+        page = self.driver.get_page()
+
+        # Normalize cookies into list[dict] as required by Playwright.
+        if cookies:
+            try:
+                cookie_list: list
+                if isinstance(cookies, str):
+                    cookie_list = json.loads(cookies)
+                elif isinstance(cookies, dict):
+                    cookie_list = [cookies]
+                elif isinstance(cookies, (list, tuple)):
+                    cookie_list = list(cookies)
+                else:
+                    raise TypeError("Unsupported cookies type; expected str, dict or list")
+
+                if not isinstance(cookie_list, list):
+                    raise ValueError("Parsed cookies is not a list")
+
+                await page.context.add_cookies(cookie_list)
+                logging.debug("Cookies added success")
+            except Exception as e:
+                logging.error(f"Failed to add cookies: {e}")
+
+        # Navigate to the target URL and wait until DOM is ready
+        try:
+            await page.goto(url, **kwargs)
+            await page.wait_for_load_state("networkidle", timeout=60000)
+            is_blank = await page.evaluate("!document.body || document.body.innerText.trim().length === 0")
+            logging.debug(f"Page content check: is_blank={is_blank}")
+        except Exception as e:
+            logging.warning(f"Error while page load after navigation: {e}")
+            is_blank = False  # Fail open – don't block execution if evaluation fails
+
+        if is_blank:
+            raise RuntimeError(f"Page load timeout or blank content after navigation to {url}, Please check the url and try again.")
+
+    def get_page(self) -> Page:
+        """Return current page via Driver."""
+        if self._is_closed or not self.driver:
+            raise RuntimeError("Browser session not initialized or closed")
+        return self.driver.get_page()
+
+    def get_context(self) -> BrowserContext:
+        if self._is_closed or not self.driver:
+            raise RuntimeError("Browser session not initialized or closed")
+        return self.driver.get_context()
+
+    def is_closed(self) -> bool:
+        """Check if session is closed."""
+        return self._is_closed
+
+    async def _cleanup(self):
+        """Internal cleanup method."""
+        try:
+            # Delegate cleanup to Driver if available
+            if self.driver and not self.driver.is_closed():
+                await self.driver.close_browser()
+
+        except Exception as e:
+            logging.error(f"Error during cleanup: {e}")
+        finally:
+            self.driver = None
+            self._playwright = None
+
+    async def close(self):
+        """Close browser session."""
+        async with self._lock:
+            if self._is_closed:
+                return
+
+            logging.debug(f"Closing browser session {self.session_id}")
+            self._is_closed = True
+            await self._cleanup()
+            logging.debug(f"Browser session {self.session_id} closed")
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        await self.initialize()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.close()
+
+
+class BrowserSessionManager:
+    """Manager for multiple browser sessions."""
+
+    def __init__(self):
+        self.sessions: Dict[str, BrowserSession] = {}
+        self._lock = asyncio.Lock()
+
+    async def browser_session(self, browser_config: Dict[str, Any] = None) -> BrowserSession:
+        """Create a new browser session."""
+        session = BrowserSession(browser_config=browser_config)
+        return session
+
+    async def create_session(self, browser_config: Dict[str, Any] = None) -> BrowserSession:
+        """Create a new browser session."""
+        session = BrowserSession(browser_config=browser_config)
+        await session.initialize()
+
+        async with self._lock:
+            self.sessions[session.session_id] = session
+
+        logging.debug(f"Created browser session: {session.session_id}")
+        return session
+
+    async def get_session(self, session_id: str) -> Optional[BrowserSession]:
+        """Get session by ID."""
+        async with self._lock:
+            return self.sessions.get(session_id)
+
+    async def close_session(self, session_id: str):
+        """Close and remove session."""
+        async with self._lock:
+            session = self.sessions.pop(session_id, None)
+            if session:
+                await session.close()
+                logging.debug(f"Closed session: {session_id}")
+
+    async def close_all_sessions(self):
+        """Close all sessions."""
+        async with self._lock:
+            sessions = list(self.sessions.values())
+            self.sessions.clear()
+
+        # Close sessions in parallel
+        if sessions:
+            await asyncio.gather(*[session.close() for session in sessions], return_exceptions=True)
+            logging.debug(f"Closed {len(sessions)} browser sessions")
+
+    def list_sessions(self) -> Dict[str, Dict[str, Any]]:
+        """List all active sessions."""
+        return {
+            session_id: {"browser_config": session.browser_config, "is_closed": session.is_closed()}
+            for session_id, session in self.sessions.items()
+        }

webqa_agent/crawler/crawl.py

@@ -0,0 +1,97 @@
+import logging
+from typing import List
+from urllib.parse import urljoin, urlparse
+
+from playwright.async_api import Page
+
+from webqa_agent.crawler.deep_crawler import DeepCrawler, ElementKey
+
+
+class CrawlHandler:
+    """Extract links and clickable elements from web pages."""
+
+    def __init__(self, base_url: str):
+        self.base_url = base_url
+        self.base_domain = urlparse(base_url).netloc
+
+    async def extract_links(self, page: Page) -> List[str]:
+        try:
+            links = await page.eval_on_selector_all("a", "elements => elements.map(el => el.href)")
+            script_links = await page.eval_on_selector_all("script[src]", "elements => elements.map(el => el.src)")
+            link_tags = await page.eval_on_selector_all("link[href]", "elements => elements.map(el => el.href)")
+
+            all_links = set(links + script_links + link_tags)
+
+            filtered_links = [
+                link
+                for link in all_links
+                if not (
+                    link.endswith(".js")
+                    or link.endswith(".css")
+                    or link.endswith((".jpg", ".jpeg", ".png", ".gif", ".bmp", ".svg"))
+                    or link.endswith((".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx"))
+                    or link.startswith("#")
+                    or link.startswith("mailto:")
+                    or link.startswith("tel:")
+                )
+            ]
+
+            absolute_links = [urljoin(self.base_url, link) for link in filtered_links]
+            return absolute_links
+
+        except Exception as e:
+            logging.error(f"Error extracting links: {str(e)}")
+            raise
+
+    def _normalize_link(self, link: str) -> str:
+        """Normalize a link URL."""
+        if not link:
+            return ""
+
+        # Handle relative URLs
+        if link.startswith("/"):
+            return urljoin(self.base_url, link)
+        elif link.startswith("#"):
+            # Skip anchor links
+            return ""
+        elif link.startswith("javascript:") or link.startswith("mailto:") or link.startswith("tel:"):
+            # Skip javascript, mailto and tel links
+            return ""
+
+        return link
+
+    def _is_valid_link(self, link: str) -> bool:
+        """Check if a link is valid for testing."""
+        if not link:
+            return False
+
+        try:
+            parsed = urlparse(link)
+
+            # Must have a scheme (http/https)
+            if parsed.scheme not in ["http", "https"]:
+                return False
+
+            # Skip file downloads
+            if any(link.lower().endswith(ext) for ext in [".pdf", ".doc", ".docx", ".xls", ".xlsx", ".zip", ".rar"]):
+                return False
+
+            # Only test links from the same domain (optional - can be configured)
+            if parsed.netloc and parsed.netloc != self.base_domain:
+                return False
+
+            return True
+
+        except Exception:
+            return False
+
+    async def clickable_elements_detection(self, page: Page):
+        try:
+            dp = DeepCrawler(page)
+            result = await dp.crawl()
+            clickable_elements = result.clean_dict([str(ElementKey.XPATH), str(ElementKey.SELECTOR)])
+            return clickable_elements
+
+        except Exception as e:
+            logging.error(f"Error detecting clickable elements on {self.base_url}: {str(e)}")
+            return []

webqa_agent/crawler/deep_crawler.py

@@ -0,0 +1,519 @@
+import asyncio
+import datetime
+import json
+import time
+import logging
+import re
+
+from pathlib import Path
+from playwright.async_api import Page, async_playwright
+from webqa_agent.crawler.dom_tree import DomTreeNode as dtree
+from webqa_agent.crawler.dom_cacher import DomCacher
+from typing import List, Dict, Optional, Any, Tuple, TypedDict, Union, Iterable
+from pydantic import BaseModel, Field
+from enum import Enum
+from itertools import groupby
+
+
+# ============================================================================
+# UTILITY FUNCTIONS
+# ============================================================================
+
+def get_time() -> str:
+    """
+    Get the current time as a formatted string.
+    Timestamp format: YYYYMMDD_HH_MM_SS
+    """
+    return datetime.datetime.now().strftime("%Y%m%d_%H_%M_%S")
+
+
+def _normalize_keys(template: Optional[Iterable[Union[str, "ElementKey"]]]) -> Optional[List[str]]:
+    """
+    Normalize template keys to string format.
+    
+    Args:
+        template: Template containing ElementKey enums or strings.
+        
+    Returns:
+        List of normalized string keys, or None if template is None.
+    """
+    if template is None:
+        return None
+
+    normalized = []
+    for key in template:
+        try:
+            # Handle both Enum and string types
+            normalized.append(key.value if hasattr(key, "value") else str(key))
+        except Exception:
+            normalized.append(str(key))
+    return normalized
+
+
+# ============================================================================
+# ENUMS AND CONSTANTS
+# ============================================================================
+
+class ElementKey(Enum):
+    """Enumeration for element attribute keys."""
+    NODE = "node"
+    TAG_NAME = "tagName"
+    CLASS_NAME = "className"
+    INNER_TEXT = "innerText"
+    ATTRIBUTES = "attributes"
+    VIEWPORT = "viewport"
+    CENTER_X = "center_x"
+    CENTER_Y = "center_y"
+    IS_VISIBLE = "isVisible"
+    IS_INTERACTIVE = "isInteractive"
+    IS_VALID_TEXT = "isValidText"
+    IS_TOP_ELEMENT = "isTopElement"
+    IS_IN_VIEWPORT = "isInViewport"
+    XPATH = "xpath"
+    SELECTOR = "selector"
+
+    def __str__(self) -> str:
+        """Return the string representation of the enum value."""
+        return self.value
+
+
+DEFAULT_OUTPUT_TEMPLATE = [
+    ElementKey.TAG_NAME.value,
+    ElementKey.INNER_TEXT.value,
+    ElementKey.CENTER_X.value,
+    ElementKey.CENTER_Y.value
+]
+
+
+# ============================================================================
+# DATA MODELS
+# ============================================================================
+
+class ElementMap(BaseModel):
+    """A wrapper for a dictionary of elements that provides a cleansing method."""
+    data: Dict[str, Any] = Field(default_factory=dict)
+
+    def clean(self, output_template: Optional[List[str]] = None) -> Dict[str, Any]:
+        """
+        Cleanses the element map, returning a new dictionary with filtered attributes.
+    
+        This method filters element data based on the output template and applies
+        additional cleaning logic to remove unwanted attributes like 'class' from
+        the attributes field.
+    
+        Args:
+            output_template: A list of keys to include in the cleansed output.
+                             If None, DEFAULT_OUTPUT_TEMPLATE is used.
+    
+        Returns:
+            A dictionary with the cleansed element data.
+        """
+        if output_template is None:
+            output_template = DEFAULT_OUTPUT_TEMPLATE
+    
+        def to_key(k):
+            """Convert key to string format."""
+            return k.value if hasattr(k, "value") else str(k)
+    
+        def clean_attributes(attrs):
+            """Remove 'class' key from attributes."""
+            if not isinstance(attrs, dict):
+                return attrs
+            
+            # Create a copy and remove 'class' key
+            cleaned_attrs = {k: v for k, v in attrs.items() if k != 'class'}
+            return cleaned_attrs
+    
+        keys = [to_key(k) for k in output_template]
+        result = {}
+    
+        for e_id, element_data in self.data.items():
+            cleaned_element = {}
+    
+            for key in keys:
+                value = element_data.get(key)
+                if value is not None:
+                    # Apply special cleaning for attributes field
+                    if key == str(ElementKey.ATTRIBUTES):
+                        cleaned_element[key] = clean_attributes(value)
+                    else:
+                        cleaned_element[key] = value
+    
+            # Only include elements that have at least one valid field
+            if cleaned_element:
+                result[e_id] = cleaned_element
+    
+        return result
+
+
+class CrawlResultModel(BaseModel):
+    """Model for crawl results containing flattened and hierarchical element data."""
+    element_tree: Dict[str, Any] = Field(default_factory=dict)
+    flat_element_map: ElementMap = Field(default_factory=ElementMap)
+    diff_element_map: ElementMap = Field(default_factory=ElementMap)
+
+    def raw_dict(self) -> Dict[str, Any]:
+        """Get raw flattened element data with all fields."""
+        return self.flat_element_map.data
+
+    def clean_dict(self, template: Optional[Iterable[Union[str, "ElementKey"]]] = None) -> Dict[str, Any]:
+        """Get cleaned flattened element data with fields filtered by template."""
+        return self.flat_element_map.clean(output_template=_normalize_keys(template))
+
+    def diff_dict(self, template: Optional[Iterable[Union[str, "ElementKey"]]] = None) -> Dict[str, Any]:
+        """Get DOM difference element data with specified template."""
+        return self.diff_element_map.clean(output_template=_normalize_keys(template))
+
+    def to_llm_json(self, template: Optional[Iterable[Union[str, "ElementKey"]]] = None) -> str:
+        """Convert filtered elements to LLM-compatible JSON format."""
+        return json.dumps(self.clean_dict(template=template), ensure_ascii=False, separators=(",", ":"))
+
+
+# ============================================================================
+# MAIN CRAWLER CLASS
+# ============================================================================
+
+class DeepCrawler:
+    """
+    A deep crawler for recursively extracting structured element data from web pages.
+
+    This class injects JavaScript payloads into Playwright pages to build hierarchical
+    DOM element trees, capturing properties such as visibility, interactivity, and
+    positioning. It supports element highlighting for debugging and provides comprehensive
+    DOM change detection capabilities.
+
+    Key functionalities:
+    - Recursive DOM crawling with structured data extraction
+    - Interactive element identification and filtering
+    - Visual element highlighting for debugging purposes
+    - DOM change detection between crawl operations
+    - Screenshot capture and result serialization
+    """
+
+    # Class-level constants for file and directory paths
+    default_dir = Path(__file__).parent
+
+    # JavaScript injection files
+    DETECTOR_JS = default_dir / "js" / "element_detector.js"
+    REMOVER_JS = default_dir / "js" / "marker_remover.js"
+
+    # Output directories
+    RESULTS_DIR = default_dir / "results"
+    SCREENSHOTS_DIR = default_dir / "screenshots"
+
+    def __init__(self, page: Page, depth: int = 0):
+        """
+        Initialize the DeepCrawler instance.
+    
+        Args:
+            page: The Playwright Page object to crawl.
+            depth: The current crawling depth level.
+            
+        Raises:
+            ValueError: If page is not a valid Playwright Page object.
+        """
+        if not isinstance(page, Page):
+            raise ValueError("Crawler page must be a Playwright Page object")
+
+        self.page = page
+        self.depth = depth
+        self.element_tree = None  # Hierarchical element tree structure
+        self.dom_cacher = DomCacher()  # DOM change detection manager
+        self._cached_element_tree = None  # Cached DOM tree for comparison
+        self._last_crawl_time = None  # Timestamp of last crawl operation
+
+    # ------------------------------------------------------------------------
+    # CORE CRAWLING METHODS
+    # ------------------------------------------------------------------------
+
+    async def crawl(
+            self,
+            page: Optional[Page] = None,
+            highlight: bool = False,
+            highlight_text: bool = False,
+            viewport_only: bool = False,
+            include_styles: bool = False,
+            cache_dom: bool = False,
+    ) -> CrawlResultModel:
+        """Inject JavaScript to crawl the page and return structured element
+        data.
+
+        This method executes the element detector script in the browser context,
+        building a hierarchical representation of the DOM with detailed element
+        properties and optional visual highlighting.
+
+        Args:
+            page: The Playwright Page to crawl. Defaults to instance page.
+            highlight: Whether to visually highlight detected elements.
+            highlight_text: Whether to highlight text nodes (requires highlight=True).
+            viewport_only: Whether to restrict detection to current viewport.
+            include_styles: Whether to include styles in the result.
+            cache_dom: Whether to cache the DOM tree for change detection.
+
+        Returns:
+            CrawlResultModel containing the structured crawl data.
+        """
+        if page is None:
+            page = self.page
+
+        try:
+            # Build JavaScript payload for element detection
+            payload = (
+                f"(() => {{"
+                f"window._highlight = {str(highlight).lower()};"
+                f"window._highlightText = {str(highlight_text).lower()};\n"
+                f"window._viewportOnly = {str(viewport_only).lower()};\n"
+                f"window._includeStyles = {str(include_styles).lower()};\n"
+                f"\n{self.read_js(self.DETECTOR_JS)}"
+                f"\nreturn buildElementTree();"
+                f"}})()"
+            )
+
+            # Execute JavaScript and extract results
+            self.element_tree, flat_elements = await page.evaluate(payload)
+
+            # Create result model with extracted data
+            result = CrawlResultModel(
+                flat_element_map=ElementMap(data=flat_elements or {}),
+                element_tree=self.element_tree or {}
+            )
+
+            # Perform DOM change detection if caching is enabled
+            if cache_dom and self.element_tree:
+                dom_tree = dtree.build_root(self.element_tree)
+                self._cached_element_tree = dom_tree
+                self._last_crawl_time = time.time()
+
+                diff_elements = self.dom_cacher.detect_dom_diff(
+                    current_tree=dom_tree,
+                    current_url=page.url
+                )
+
+                logging.debug(f"DOM change result: {diff_elements}")
+
+                result.diff_element_map = ElementMap(data=self.extract_interactive_elements(get_new_elems=True))
+
+            return result
+
+        except Exception as e:
+            logging.error(f"JavaScript injection failed during element detection: {e}")
+            return CrawlResultModel()
+
+    def extract_interactive_elements(self, get_new_elems: bool = False) -> Dict:
+        """
+        Extract interactive elements with comprehensive attribute information.
+
+        Filters DOM nodes based on interactivity, visibility, and positioning
+        criteria to identify actionable elements on the page.
+
+        Args:
+            get_new_elems: Whether to return only newly detected elements.
+            
+        Returns:
+            Dictionary mapping element IDs to their attribute dictionaries.
+        """
+        # Determine data source based on operation mode
+        if get_new_elems:
+            if not self._cached_element_tree:
+                return {}
+            root = self._cached_element_tree
+        else:
+            if not self.element_tree:
+                return {}
+            root = dtree.build_root(self.element_tree)
+
+        elements = {}
+
+        if root:
+            for node in root.pre_iter():
+                # Apply basic element filtering criteria
+                if not all([
+                    node.isInteractive,
+                    node.isVisible,
+                    node.isTopElement,
+                    node.center_x is not None,
+                    node.center_y is not None
+                ]):
+                    continue
+
+                # Filter for new elements when requested
+                if get_new_elems and not node.is_new:
+                    continue
+
+                # Validate viewport dimensions
+                viewport = node.viewport or {}
+                if viewport.get("width") is None or viewport.get("height") is None:
+                    continue
+
+                # Build comprehensive element attribute dictionary
+                elements[str(node.highlightIndex)] = {
+                    str(ElementKey.TAG_NAME): node.tagName,
+                    str(ElementKey.CLASS_NAME): node.className,
+                    str(ElementKey.INNER_TEXT): node.innerText[:200],
+                    str(ElementKey.ATTRIBUTES): node.attributes,
+                    str(ElementKey.VIEWPORT): node.viewport,
+                    str(ElementKey.CENTER_X): node.center_x,
+                    str(ElementKey.CENTER_Y): node.center_y,
+                    str(ElementKey.IS_VISIBLE): node.isVisible,
+                    str(ElementKey.IS_INTERACTIVE): node.isInteractive,
+                    str(ElementKey.IS_TOP_ELEMENT): node.isTopElement,
+                    str(ElementKey.IS_IN_VIEWPORT): node.isInViewport,
+                    str(ElementKey.XPATH): node.xpath,
+                    str(ElementKey.SELECTOR): node.selector
+                }
+
+        return elements
+
+    def get_text(self, fmt: str = "json") -> str:
+        """
+        Extract and concatenate all text content from the crawled DOM tree.
+        
+        This method intelligently filters text content to avoid duplicates and wrapper nodes,
+        collecting only meaningful leaf text nodes and deduplicating consecutive identical texts.
+        
+        Args:
+            fmt: Output format, currently supports "json" (default).
+            
+        Returns:
+            JSON string containing array of extracted text content.
+        """
+
+        def _normalize_text(s: str) -> str:
+            """Normalize text by collapsing whitespace and trimming."""
+            s = re.sub(r'\s+', ' ', s).strip()
+            return s
+
+        def _has_text(n) -> bool:
+            """Check if a node has meaningful text content."""
+            return bool(getattr(n, "innerText", None) and n.innerText.strip())
+
+        def _is_leaf_text_node(n) -> bool:
+            """Determine if a node is a leaf text node (no children with text)."""
+            children = getattr(n, "children", None) or []
+            return not any(_has_text(c) for c in children)
+
+        def _dedupe_consecutive(seq):
+            """Remove consecutive duplicate items from sequence."""
+            return [k for k, _ in groupby(seq)]
+
+        # Early return if no element tree available
+        if not self.element_tree:
+            return ""
+
+        # Build DOM tree from hierarchical data
+        root = dtree.build_root(self.element_tree)
+        if root is None:
+            return ""
+
+        # Collect only leaf text nodes and skip wrapper nodes
+        items = []
+        for n in root.pre_iter():
+            # Skip nodes without meaningful text
+            if not _has_text(n):
+                continue
+
+            # For non-leaf nodes, check if they're wrapper nodes
+            if not _is_leaf_text_node(n):
+                # Skip "wrapper" nodes: parent text identical to any direct child text
+                normalized_text = _normalize_text(n.innerText)
+                child_texts = [
+                    _normalize_text(c.innerText)
+                    for c in (n.children or [])
+                    if _has_text(c)
+                ]
+                # Skip if parent text matches any child text (wrapper node)
+                if normalized_text in child_texts:
+                    continue
+
+            # Add normalized text to collection
+            items.append(_normalize_text(n.innerText))
+
+        # Final deduplication: collapse adjacent duplicates
+        items = _dedupe_consecutive(items)
+
+        # Return as compact JSON array
+        return json.dumps(items, ensure_ascii=False, separators=(",", ":"))
+
+    # ------------------------------------------------------------------------
+    # DOM CACHE MANAGEMENT
+    # ------------------------------------------------------------------------
+
+    def clear_dom_cache(self) -> None:
+        """Clear the DOM change detection cache and reset internal state."""
+        self.dom_cacher.clear_cache()
+        self._cached_element_tree = None
+        self._last_crawl_time = None
+
+    # ------------------------------------------------------------------------
+    # UTILITY METHODS
+    # ------------------------------------------------------------------------
+
+    @staticmethod
+    def read_js(file_path: Path) -> str:
+        """
+        Read and return the content of a JavaScript file.
+        
+        Args:
+            file_path: Path to the JavaScript file.
+            
+        Returns:
+            The content of the JavaScript file as a string.
+        """
+        with open(file_path, "r", encoding="utf-8") as file:
+            return file.read()
+
+    @staticmethod
+    def dump_json(node: Dict[str, Any], path: Path) -> None:
+        """
+        Serialize a dictionary to a JSON file with proper formatting.
+        
+        Args:
+            node: The dictionary to serialize.
+            path: The output file path.
+        """
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, 'w', encoding='utf-8') as f:
+            json.dump(node, f, ensure_ascii=False, indent=2)
+
+    # ------------------------------------------------------------------------
+    # VISUAL DEBUGGING METHODS
+    # ------------------------------------------------------------------------
+
+    async def remove_marker(self, page: Optional[Page] = None) -> None:
+        """
+        Remove visual highlight markers from the page.
+        
+        Args:
+            page: The Playwright Page to clean. Defaults to instance page.
+        """
+        if page is None:
+            page = self.page
+        try:
+            script = self.read_js(self.REMOVER_JS)
+            await page.evaluate(script)
+        except Exception as e:
+            logging.error(f"Failed to remove highlight markers: {e}")
+
+    async def take_screenshot(
+            self,
+            page: Optional[Page] = None,
+            screenshot_path: Optional[str] = None
+    ) -> None:
+        """
+        Capture a full-page screenshot and save it to disk.
+        
+        Args:
+            page: The Playwright Page to screenshot. Defaults to instance page.
+            screenshot_path: Custom path for the screenshot. Auto-generated if None.
+        """
+        if page is None:
+            page = self.page
+
+        if screenshot_path:
+            path = Path(screenshot_path)
+        else:
+            path = self.SCREENSHOTS_DIR / f"{get_time()}_marker.png"
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+        await page.screenshot(path=str(path), full_page=True)
+        logging.debug(f"Screenshot saved to {path}")

webqa_agent/crawler/dom_cacher.py

@@ -0,0 +1,94 @@
+from dataclasses import dataclass
+from typing import Set, Optional, Dict, Any
+from webqa_agent.crawler.dom_tree import DomTreeNode
+import time
+
+
+@dataclass
+class CachedDomState:
+    """
+    DOM state cache class.
+    
+    Used to store DOM state snapshots for change detection.
+    """
+    url: str
+    clickable_element_hashes: Set[str]
+    timestamp: float
+
+
+class DomCacher:
+    """
+    DOM change detector.
+    
+    Provides DOM state comparison and change detection functionality.
+    """
+
+    def __init__(self):
+        self._cached_state: Optional[CachedDomState] = None
+
+    def detect_dom_diff(self,
+                        current_tree: DomTreeNode,
+                        current_url: str) -> Dict[str, Any]:
+        """
+        Detect DOM changes.
+
+        Args:
+            current_tree: Current DOM tree.
+            current_url: Current page URL.
+
+        Returns:
+            Dict[str, Any]: Change detection results.
+        """
+
+        # Get current clickable element hashes
+        current_hashes = current_tree.get_clickable_elements_hashes()
+
+        result = {
+            'has_changes': False,
+            'new_elements_count': 0,
+            'removed_elements_count': 0,
+            'total_elements': len(current_hashes)
+        }
+
+        # If cached state exists and URL matches, perform comparison
+        if self._cached_state and self._cached_state.url == current_url:
+            cached_hashes = self._cached_state.clickable_element_hashes
+
+            # Calculate new and removed elements
+            new_hashes = current_hashes - cached_hashes
+            removed_hashes = cached_hashes - current_hashes
+
+            result.update({
+                'has_changes': len(new_hashes) > 0 or len(removed_hashes) > 0,
+                'new_elements_count': len(new_hashes),
+                'removed_elements_count': len(removed_hashes),
+                # 'new_element_hashes': new_hashes,
+                # 'removed_element_hashes': removed_hashes
+            })
+
+            # Mark new elements
+            current_tree.mark_new_elements(cached_hashes)
+
+        # Update cached state
+        self._cached_state = CachedDomState(
+            url=current_url,
+            clickable_element_hashes=current_hashes,
+            timestamp=time.time()
+        )
+
+        return result
+
+    def clear_cache(self) -> None:
+        """
+        Clear cached state.
+        """
+        self._cached_state = None
+
+    def get_cached_state(self) -> Optional[CachedDomState]:
+        """
+        Get cached state.
+
+        Returns:
+            Optional[CachedDomState]: Cached DOM state.
+        """
+        return self._cached_state

webqa_agent/crawler/dom_tree.py

@@ -0,0 +1,353 @@
+import json
+import copy
+import hashlib
+import logging
+from dataclasses import dataclass, field
+from typing import List, Dict, Optional, Any, Set
+from collections import Counter
+
+
+@dataclass
+class DomTreeNode:
+    """
+    A data class representing a node in a simplified Document Object Model (DOM) tree.
+
+    This class captures essential information about a DOM element, including its identity,
+    attributes, layout, and state (e.g., visibility, interactivity). It also maintains
+    the tree structure through parent-child relationships.
+
+    Attributes:
+        id (Optional[int]): A unique identifier for the element, generated from HTML.
+        highlightIndex (Optional[int]): An index used for highlighting the element on the page.
+        tagName (Optional[str]): The HTML tag name of the element (e.g., 'div', 'a').
+        className (Optional[str]): The 'class' attribute of the element.
+        innerText (str): The trimmed text content of the element.
+        element_type (Optional[str]): The 'type' attribute, typically for <input> elements.
+        placeholder (Optional[str]): The 'placeholder' attribute of the element.
+        attributes (Dict[str, str]): A dictionary of all HTML attributes of the element.
+        selector (str): A generated CSS selector for the element.
+        xpath (str): A generated XPath for the element.
+        viewport (Dict[str, float]): A dictionary containing the element's bounding box relative to the viewport.
+        center_x (Optional[float]): The horizontal center coordinate of the element.
+        center_y (Optional[float]): The vertical center coordinate of the element.
+        isVisible (Optional[bool]): A flag indicating if the element is visible.
+        isInteractive (Optional[bool]): A flag indicating if the element is interactive.
+        isTopElement (Optional[bool]): A flag indicating if the element is the topmost element at its center.
+        isInViewport (Optional[bool]): A flag indicating if the element is within the current viewport.
+        parent (Optional['DomTreeNode']): A reference to the parent node in the tree.
+        children (List['DomTreeNode']): A list of child nodes.
+        depth (int): The depth of the node in the tree (root is at depth 0).
+        subtree (Dict[str, Any]): A copy of the raw subtree data from the crawler, if any.
+
+    """
+
+    # Mapped from original node fields
+    id: Optional[int] = None
+    highlightIndex: Optional[int] = None
+    tagName: Optional[str] = None
+    className: Optional[str] = None
+    innerText: str = ""
+    element_type: Optional[str] = None
+    placeholder: Optional[str] = None
+
+    # Attributes converted from a list to a dictionary
+    attributes: Dict[str, str] = field(default_factory=dict)
+
+    # Added selector, xpath
+    selector: str = ""
+    xpath: str = ""
+
+    # Layout information
+    viewport: Dict[str, float] = field(default_factory=dict)
+    center_x: Optional[float] = None
+    center_y: Optional[float] = None
+
+    # boolean flags
+    isVisible: Optional[bool] = None
+    isInteractive: Optional[bool] = None
+    isTopElement: Optional[bool] = None
+    isInViewport: Optional[bool] = None
+
+    # Parent node
+    parent: Optional['DomTreeNode'] = None
+    # Child nodes
+    children: List['DomTreeNode'] = field(default_factory=list)
+    # Depth
+    depth: int = 0
+    # Sub DOM tree
+    subtree: Dict[str, Any] = field(default_factory=dict)
+
+    def __repr__(self):
+        """Returns a string representation of the DomTreeNode."""
+        return f"<DomTreeNode id={self.id!r} tag={self.tagName!r} depth={self.depth}>"
+
+    def add_child(self, child: 'DomTreeNode') -> None:
+        """
+        Adds a child node to self.children and sets its parent and depth.
+        """
+        child.parent = self
+        child.depth = self.depth + 1
+        self.children.append(child)
+
+    def find_by_tag(self, tag_name: str) -> List['DomTreeNode']:
+        """
+        Recursively finds all nodes matching the tag_name.
+        """
+        matches: List['DomTreeNode'] = []
+        if self.tagName == tag_name:
+            matches.append(self)
+        for c in self.children:
+            matches.extend(c.find_by_tag(tag_name))
+        return matches
+
+    def find_by_id(self, target_id: int) -> Optional['DomTreeNode']:
+        """
+        Performs a depth-first search to find the first node with id == target_id.
+        Returns None if not found.
+        """
+        if self.highlightIndex == target_id:
+            return self
+
+        for c in self.children:
+            result = c.find_by_id(target_id)
+            if result is not None:
+                return result
+
+        return None
+
+    @classmethod
+    def build_root(cls, data: Dict[str, Any]) -> 'DomTreeNode':
+        """
+        Constructs a DomTreeNode tree from a raw dictionary, typically from JSON.
+
+        This class method serves as the primary entry point for creating a tree from
+        the data returned by the crawler. It handles cases where the input data might
+        not have a single root 'node' by wrapping it in a synthetic root.
+
+        Args:
+            data: The raw dictionary representing the DOM subtree.
+
+        Returns:
+            The root DomTreeNode of the constructed tree.
+        """
+        if data.get('node') is None:
+            fake_node = {
+                'node': {
+                    'id': None,
+                    'highlightIndex': None,
+                    'tagName': '__root__',
+                    'className': None,
+                    'innerText': '',
+                    'type': None,
+                    'placeholder': None,
+                    'attributes': [],
+                    'selector': None,
+                    'xpath': None,
+                    'viewport': {},
+                    'center_x': None,
+                    'center_y': None,
+                    'isVisible': True,
+                    'isInteractive': False,
+                    'isTopElement': False,
+                    'isInViewport': True
+                },
+                'children': [data],
+                'subtree': []
+            }
+
+            data = fake_node
+
+        def build_dom_tree(data: Dict[str, Any],
+                           parent: Optional['DomTreeNode'] = None,
+                           depth: int = 0) -> List['DomTreeNode']:
+            """
+            Builds a list of DomTreeNode from the injected JS result (nested dict).
+            Returns a list of top-level (or multi-root) nodes.
+            """
+            nodes: List[DomTreeNode] = []
+            node_data = data.get('node')
+            children_data = data.get('children', [])
+            subtree_data = copy.deepcopy(data.get("subtree", {}))
+
+            if node_data:
+                attrs = {a['name']: a['value'] for a in node_data.get('attributes', [])}
+
+                node = cls(
+                    id=node_data.get('id'),
+                    highlightIndex=node_data.get('highlightIndex'),
+                    tagName=(node_data.get('tagName') or '').lower() or None,
+                    className=node_data.get('className'),
+                    innerText=(node_data.get('innerText') or '').strip(),
+                    element_type=node_data.get('type'),
+                    placeholder=node_data.get('placeholder'),
+
+                    attributes=attrs,
+                    selector=node_data.get('selector'),
+                    xpath=node_data.get('xpath'),
+                    viewport=node_data.get('viewport', {}),
+                    center_x=node_data.get('center_x'),
+                    center_y=node_data.get('center_y'),
+
+                    isVisible=node_data.get('isVisible'),
+                    isInteractive=node_data.get('isInteractive'),
+                    isTopElement=node_data.get('isTopElement'),
+                    isInViewport=node_data.get('isInViewport'),
+
+                    subtree=subtree_data,
+                    parent=parent,
+                    depth=depth
+                )
+
+                for cd in children_data:
+                    for child in build_dom_tree(cd, parent=node, depth=depth + 1):
+                        node.add_child(child)
+
+                nodes.append(node)
+
+            else:
+                for cd in children_data:
+                    nodes.extend(build_dom_tree(cd, parent=parent, depth=depth))
+
+            return nodes
+
+        roots = build_dom_tree(data)
+
+        return roots[0]
+
+    def pre_iter(self) -> List['DomTreeNode']:
+        """Performs a pre-order traversal and returns a list of nodes."""
+        nodes = [self]
+        for c in self.children:
+            nodes.extend(c.pre_iter())
+        return nodes
+
+    def post_iter(self) -> List['DomTreeNode']:
+        """Performs a post-order traversal and returns a list of nodes."""
+        nodes: List['DomTreeNode'] = []
+        for c in self.children:
+            nodes.extend(c.post_iter())
+        nodes.append(self)
+        return nodes
+
+    def count_depth(self) -> Dict[int, int]:
+        """Counts the number of nodes at each depth level."""
+        counts = Counter(n.depth for n in self.pre_iter())
+        return dict(counts)
+
+    # Change detection related fields
+    is_new: Optional[bool] = None  # Mark if element is new
+    element_hash: Optional[str] = None  # Element hash value
+
+    def calculate_element_hash(self) -> str:
+        """
+        Calculate unique hash value for the element.
+
+        Hash is generated based on:
+        - Parent path
+        - Element attributes  
+        - XPath
+
+        Returns:
+            str: SHA256 hash value of the element.
+        """
+        # Get parent path
+        parent_path = self._get_parent_branch_path()
+        parent_path_str = '/'.join(parent_path)
+
+        # Get attributes string
+        # attrs_str = ''.join(f'{k}={v}' for k, v in sorted(self.attributes.items()))
+
+        # Combine hash source
+        # hash_source = f"{parent_path_str}|{attrs_str}|{self.xpath}"
+        hash_source = f"{parent_path_str}|{self.xpath}"
+        # logging.debug(f"hash_source of elem {self.highlightIndex} ({self.innerText}):\nparent_path_str: {parent_path_str}\nxpath: {self.xpath}")
+
+        # Calculate SHA256 hash
+        self.element_hash = hashlib.sha256(hash_source.encode()).hexdigest()
+        return self.element_hash
+
+    def _get_parent_branch_path(self) -> List[str]:
+        """
+        Get parent path from root node to current node.
+
+        Returns:
+            List[str]: List of parent tag names.
+        """
+        path = []
+        current = self
+        while current.parent is not None:
+            path.append(current.tagName or '')
+            current = current.parent
+        path.reverse()
+        return path
+
+    def get_clickable_elements(self) -> List['DomTreeNode']:
+        """
+        Get all clickable elements.
+
+        Returns:
+            List[DomTreeNode]: List of clickable elements.
+        """
+        clickable_elements = []
+
+        # 检查当前节点是否可点击
+        if (self.isInteractive and
+                self.isVisible and
+                self.isTopElement and
+                self.highlightIndex is not None):
+            clickable_elements.append(self)
+
+        # 递归检查子节点
+        for child in self.children:
+            clickable_elements.extend(child.get_clickable_elements())
+
+        return clickable_elements
+
+    def get_clickable_elements_hashes(self) -> Set[str]:
+        """
+        Get hash set of all clickable elements.
+
+        Returns:
+            Set[str]: Hash set of clickable elements.
+        """
+        clickable_elements = self.get_clickable_elements()
+        return {elem.calculate_element_hash() for elem in clickable_elements}
+
+    def find_element_by_hash(self, target_hash: str) -> Optional['DomTreeNode']:
+        """
+        Find element by hash value.
+
+        Args:
+            target_hash: Target element hash value.
+
+        Returns:
+            Optional[DomTreeNode]: Found element node, None if not found.
+        """
+        if self.calculate_element_hash() == target_hash:
+            return self
+
+        for child in self.children:
+            result = child.find_element_by_hash(target_hash)
+            if result is not None:
+                return result
+
+        return None
+
+    def mark_new_elements(self, cached_hashes: Set[str]) -> None:
+        """
+        Mark newly appeared elements.
+
+        Args:
+            cached_hashes: Cached element hash set.
+        """
+        # 标记当前元素
+        if (self.isInteractive and
+                self.isVisible and
+                self.isTopElement and
+                self.highlightIndex is not None):
+            current_hash = self.calculate_element_hash()
+            self.is_new = current_hash not in cached_hashes
+
+        # 递归标记子元素
+        for child in self.children:
+            child.mark_new_elements(cached_hashes)

webqa_agent/crawler/js/element_detector.js

@@ -0,0 +1,1030 @@
+// This file is modified from:
+// https://github.com/browser-use/browser-use/browser_use/dom/dom_tree/index.js
+//
+// Copyright (c) 2024 Gregor Zunic
+//
+// Licensed under the MIT License
+
+/**
+ * DOM Element Detection and Highlighting System
+ *
+ * This module provides comprehensive functionality for detecting, analyzing, and highlighting
+ * interactive elements and meaningful text content within web pages. It includes:
+ *
+ * - Interactive element detection with heuristic analysis
+ * - Text element validation and extraction
+ * - Visual highlighting with overlay rendering
+ * - DOM tree construction with filtering capabilities
+ * - Viewport-aware element processing
+ * - Event listener detection and cursor analysis
+ *
+ * Key Features:
+ * - Supports both interactive element and text content highlighting modes
+ * - Handles nested elements with distinct interaction boundary detection
+ * - Provides robust visibility and top-element checking
+ * - Includes performance optimizations with caching mechanisms
+ * - Supports iframe and Shadow DOM contexts
+ */
+
+(function () {
+        window._highlight = window._highlight ?? true;                          // RenderHighlight Switch
+        window._highlightText = window._highlightText ?? false;                 // RenderTextHighlight Switch
+        window._viewportOnly = window._viewportOnly ?? false;                   // Viewport Highlight Only
+        let idCounter = 1;
+        let highlightIndex = 1;
+        const elementToId = new WeakMap();
+        const highlightMap = new WeakMap();
+        let highlightIdMap = new WeakMap();
+        const styleCache = new WeakMap();
+        const _elementHighlightColorMap = new WeakMap();
+        const INTERACTIVE_TAGS = new Set(['a', 'button', 'input', 'select', 'textarea', 'summary', 'details', 'label', 'option']);
+        const INTERACTIVE_ROLES = new Set(['button', 'link', 'menuitem', 'menuitemradio', 'menuitemcheckbox', 'radio', 'checkbox', 'tab', 'switch', 'slider', 'spinbutton', 'combobox', 'searchbox', 'textbox', 'listbox', 'option', 'scrollbar']);
+        const palette = ['#e6194b', '#3cb44b', '#ffe119', '#4363d8', '#f58231', '#911eb4', '#46f0f0', '#f032e6', '#bcf60c', '#fabebe', '#008080', '#e6beff'];  // highlighting colors
+        const overlayContainer = document.getElementById('__marker_container__') || (() => {  // highlight container
+            const c = document.createElement('div');
+            c.id = '__marker_container__';
+            Object.assign(c.style, {
+                position: 'fixed',
+                top: '0',
+                left: '0',
+                width: '100vw',
+                height: '100vh',
+                pointerEvents: 'none',
+                zIndex: '2147483647'
+            });
+            document.body.appendChild(c);
+            return c;
+        })();
+
+        // ============================= Element Information Extraction =============================
+        /**
+         * Retrieves a unique identifier for a given HTML element.
+         *
+         * If the element does not already have a 'id' attribute, this function assigns a new,
+         * auto-incrementing ID to it. This ensures that every element can be uniquely identified
+         * during the crawling process.
+         *
+         * @param {HTMLElement} elem The HTML element for which to get the ID.
+         * @returns {number} The unique integer ID of the element.
+         */
+        function getElementId(elem) {
+            if (!elementToId.has(elem)) elementToId.set(elem, idCounter++);
+            return elementToId.get(elem);
+        }
+
+        /**
+         * Retrieves the computed CSS style for an element, using a cache to avoid redundant calculations.
+         *
+         * This function fetches the `CSSStyleDeclaration` object for an element. To optimize performance,
+         * it caches the result based on the element's unique ID. Subsequent calls for the same element
+         * will return the cached style object, reducing layout reflows.
+         *
+         * @param {HTMLElement} elem The HTML element to get the style for.
+         * @returns {CSSStyleDeclaration} The computed style object.
+         */
+        function getCachedStyle(elem) {
+            if (!styleCache.has(elem)) {
+                styleCache.set(elem, window.getComputedStyle(elem));
+            }
+            return styleCache.get(elem);
+        }
+
+        /**
+         * Return a compact subset of computed styles for model consumption
+         */
+        function getStyleSubset(elem) {
+            if (!window._includeStyles) return null;
+            try {
+                const s = getCachedStyle(elem);
+                return {
+                    display: s.display,
+                    visibility: s.visibility,
+                    opacity: s.opacity,
+                    position: s.position,
+                    zIndex: s.zIndex,
+                    overflowX: s.overflowX,
+                    overflowY: s.overflowY,
+                    textOverflow: s.textOverflow,
+                    whiteSpace: s.whiteSpace,
+                    wordBreak: s.wordBreak,
+                    wordWrap: s.wordWrap,
+                    fontSize: s.fontSize,
+                    fontWeight: s.fontWeight,
+                    lineHeight: s.lineHeight,
+                    color: s.color,
+                    backgroundColor: s.backgroundColor,
+                    pointerEvents: s.pointerEvents,
+                    cursor: s.cursor,
+                    // 布局相关
+                    width: s.width,
+                    height: s.height,
+                    maxWidth: s.maxWidth,
+                    maxHeight: s.maxHeight,
+                    margin: s.margin,
+                    padding: s.padding,
+                    // 对齐相关
+                    textAlign: s.textAlign,
+                    verticalAlign: s.verticalAlign,
+                    justifyContent: s.justifyContent,
+                    alignItems: s.alignItems,
+                    flexDirection: s.flexDirection,
+                    gap: s.gap,
+                    // 边框和背景
+                    border: s.border,
+                    borderColor: s.borderColor,
+                    borderWidth: s.borderWidth,
+                    outline: s.outline,
+                    backgroundImage: s.backgroundImage,
+                    backgroundSize: s.backgroundSize,
+                    objectFit: s.objectFit,
+                };
+            } catch (e) {
+                return null;
+            }
+        }
+
+        /**
+         * Determines if an element is heuristically interactive based on various signals.
+         *
+         * This function uses heuristic analysis to identify elements that may be interactive
+         * even if they don't have explicit interactive attributes. It checks for:
+         * 1. Interactive attributes (role, tabindex, onclick)
+         * 2. Semantic class names suggesting interactivity
+         * 3. Placement within known interactive containers
+         * 4. Presence of visible children
+         * 5. Avoids top-level body children (likely layout containers)
+         *
+         * @param {HTMLElement} element The element to evaluate for heuristic interactivity.
+         * @returns {boolean} `true` if the element appears to be heuristically interactive, otherwise `false`.
+         */
+        function isHeuristicallyInteractive(element) {
+            if (!element || element.nodeType !== Node.ELEMENT_NODE) return false;
+
+            // Skip non-visible elements early for performance
+            if (!isVisible(element)) return false;
+
+            // Check for common attributes that often indicate interactivity
+            const hasInteractiveAttributes =
+                element.hasAttribute('role') ||
+                element.hasAttribute('tabindex') ||
+                element.hasAttribute('onclick') ||
+                typeof element.onclick === 'function';
+
+            // Check for semantic class names suggesting interactivity
+            const hasInteractiveClass = /\b(btn|clickable|menu|item|entry|link)\b/i.test(element.className || '');
+
+            // Determine whether the element is inside a known interactive container
+            const isInKnownContainer = Boolean(
+                element.closest('button,a,[role="button"],.menu,.dropdown,.list,.toolbar')
+            );
+
+            // Ensure the element has at least one visible child (to avoid marking empty wrappers)
+            const hasVisibleChildren = [...element.children].some(isVisible);
+
+            // Avoid highlighting elements whose parent is <body> (top-level wrappers)
+            const isParentBody = element.parentElement && element.parentElement.isSameNode(document.body);
+
+            return (
+                (isInteractiveElement(element) || hasInteractiveAttributes || hasInteractiveClass) &&
+                hasVisibleChildren &&
+                isInKnownContainer &&
+                !isParentBody
+            );
+        }
+
+        /**
+         * Determines if an element represents a distinct interaction boundary.
+         *
+         * An element is considered a distinct interaction boundary if it is interactive itself,
+         * but none of its ancestor elements are. This helps identify the outermost interactive
+         * element in a nested structure, which is often the primary target for user actions.
+         * For example, in `<a><div>Click me</div></a>`, the `<a>` tag is the distinct boundary.
+         *
+         * @param {HTMLElement} element The element to evaluate.
+         * @returns {boolean} `true` if the element is a distinct interaction boundary, otherwise `false`.
+         */
+        function isElementDistinctInteraction(element) {
+            if (!element || element.nodeType !== Node.ELEMENT_NODE) {
+                return false;
+            }
+
+            const tagName = element.tagName.toLowerCase();
+            const role = element.getAttribute('role');
+
+            // Check if it's an iframe - always distinct boundary
+            if (tagName === 'iframe') {
+                return true;
+            }
+
+            // Check tag name
+            if (INTERACTIVE_TAGS.has(tagName)) {
+                return true;
+            }
+            // Check interactive roles
+            if (role && INTERACTIVE_ROLES.has(role)) {
+                return true;
+            }
+            // Check contenteditable
+            if (element.isContentEditable || element.getAttribute('contenteditable') === 'true') {
+                return true;
+            }
+            // Check for common testing/automation attributes
+            if (element.hasAttribute('data-testid') || element.hasAttribute('data-cy') || element.hasAttribute('data-test')) {
+                return true;
+            }
+            // Check for explicit onclick handler (attribute or property)
+            if (element.hasAttribute('onclick') || typeof element.onclick === 'function') {
+                return true;
+            }
+            // Check for other common interaction event listeners
+            try {
+                const getEventListenersForNode = element?.ownerDocument?.defaultView?.getEventListenersForNode || window.getEventListenersForNode;
+                if (typeof getEventListenersForNode === 'function') {
+                    const listeners = getEventListenersForNode(element);
+                    const interactionEvents = ['click', 'mousedown', 'mouseup', 'keydown', 'keyup', 'submit', 'change', 'input', 'focus', 'blur'];
+                    for (const eventType of interactionEvents) {
+                        for (const listener of listeners) {
+                            if (listener.type === eventType) {
+                                return true; // Found a common interaction listener
+                            }
+                        }
+                    }
+                }
+                // Fallback: Check common event attributes if getEventListeners is not available (getEventListenersForNode doesn't work in page.evaluate context)
+                const commonEventAttrs = ['onmousedown', 'onmouseup', 'onkeydown', 'onkeyup', 'onsubmit', 'onchange', 'oninput', 'onfocus', 'onblur'];
+                if (commonEventAttrs.some(attr => element.hasAttribute(attr))) {
+                    return true;
+                }
+            } catch (e) {
+                // console.warn(`Could not check event listeners for ${element.tagName}:`, e);
+                // If checking listeners fails, rely on other checks
+            }
+
+            // if the element is not strictly interactive but appears clickable based on heuristic signals
+            if (isHeuristicallyInteractive(element)) {
+                return true;
+            }
+            return false;
+        }
+
+        /**
+         * Determines if an element is considered interactive.
+         *
+         * An element is deemed interactive if it meets any of the following criteria:
+         * 1. Is an inherently interactive HTML tag (e.g., <a>, <button>, <input>).
+         * 2. Has an ARIA role that implies interactivity (e.g., 'button', 'link').
+         * 3. Is focusable via a non-negative `tabindex`.
+         * 4. Has specific event listeners attached (e.g., 'click', 'keydown').
+         * 5. Has a 'pointer' cursor style, suggesting it's clickable.
+         * 6. Is content-editable.
+         *
+         * @param {HTMLElement} element The element to evaluate.
+         * @returns {boolean} `true` if the element is interactive, otherwise `false`.
+         */
+        function isInteractiveElement(element) {
+            if (!element || element.nodeType !== Node.ELEMENT_NODE) {
+                return false;
+            }
+
+            // Cache the tagName and style lookups
+            const tagName = element.tagName.toLowerCase();
+            const style = getCachedStyle(element);
+
+
+            // Define interactive cursors
+            const interactiveCursors = new Set([
+                'pointer',    // Link/clickable elements
+                'move',       // Movable elements
+                'text',       // Text selection
+                'grab',       // Grabbable elements
+                'grabbing',   // Currently grabbing
+                'cell',       // Table cell selection
+                'copy',       // Copy operation
+                'alias',      // Alias creation
+                'all-scroll', // Scrollable content
+                'col-resize', // Column resize
+                'context-menu', // Context menu available
+                'crosshair',  // Precise selection
+                'e-resize',   // East resize
+                'ew-resize',  // East-west resize
+                'help',       // Help available
+                'n-resize',   // North resize
+                'ne-resize',  // Northeast resize
+                'nesw-resize', // Northeast-southwest resize
+                'ns-resize',  // North-south resize
+                'nw-resize',  // Northwest resize
+                'nwse-resize', // Northwest-southeast resize
+                'row-resize', // Row resize
+                's-resize',   // South resize
+                'se-resize',  // Southeast resize
+                'sw-resize',  // Southwest resize
+                'vertical-text', // Vertical text selection
+                'w-resize',   // West resize
+                'zoom-in',    // Zoom in
+                'zoom-out'    // Zoom out
+            ]);
+
+            // Define non-interactive cursors
+            const nonInteractiveCursors = new Set([
+                'not-allowed', // Action not allowed
+                'no-drop',     // Drop not allowed
+                'wait',        // Processing
+                'progress',    // In progress
+                'initial',     // Initial value
+                'inherit'      // Inherited value
+                //? Let's just include all potentially clickable elements that are not specifically blocked
+                // 'none',        // No cursor
+                // 'default',     // Default cursor
+                // 'auto',        // Browser default
+            ]);
+
+            function doesElementHaveInteractivePointer(element) {
+                if (element.tagName.toLowerCase() === "html") return false;
+
+                if (interactiveCursors.has(style.cursor)) return true;
+
+                return false;
+            }
+
+            let isInteractiveCursor = doesElementHaveInteractivePointer(element);
+
+            // Genius fix for almost all interactive elements
+            if (isInteractiveCursor) {
+                return true;
+            }
+
+            const interactiveElements = new Set([
+                "a",          // Links
+                "button",     // Buttons
+                "input",      // All input types (text, checkbox, radio, etc.)
+                "select",     // Dropdown menus
+                "textarea",   // Text areas
+                "details",    // Expandable details
+                "summary",    // Summary element (clickable part of details)
+                "label",      // Form labels (often clickable)
+                "option",     // Select options
+                "optgroup",   // Option groups
+                "fieldset",   // Form fieldsets (can be interactive with legend)
+                "legend",     // Fieldset legends
+            ]);
+
+            // Define explicit disable attributes and properties
+            const explicitDisableTags = new Set([
+                'disabled',           // Standard disabled attribute
+                // 'aria-disabled',      // ARIA disabled state
+                'readonly',          // Read-only state
+                // 'aria-readonly',     // ARIA read-only state
+                // 'aria-hidden',       // Hidden from accessibility
+                // 'hidden',            // Hidden attribute
+                // 'inert',             // Inert attribute
+                // 'aria-inert',        // ARIA inert state
+                // 'tabindex="-1"',     // Removed from tab order
+                // 'aria-hidden="true"' // Hidden from screen readers
+            ]);
+
+            // handle inputs, select, checkbox, radio, textarea, button and make sure they are not cursor style disabled/not-allowed
+            if (interactiveElements.has(tagName)) {
+                // Check for non-interactive cursor
+                if (nonInteractiveCursors.has(style.cursor)) {
+                    return false;
+                }
+
+                // Check for explicit disable attributes
+                for (const disableTag of explicitDisableTags) {
+                    if (element.hasAttribute(disableTag) ||
+                        element.getAttribute(disableTag) === 'true' ||
+                        element.getAttribute(disableTag) === '') {
+                        return false;
+                    }
+                }
+
+                // Check for disabled property on form elements
+                if (element.disabled) {
+                    return false;
+                }
+
+                // Check for readonly property on form elements
+                if (element.readOnly) {
+                    return false;
+                }
+
+                // Check for inert property
+                if (element.inert) {
+                    return false;
+                }
+
+                return true;
+            }
+
+            const role = element.getAttribute("role");
+            const ariaRole = element.getAttribute("aria-role");
+
+            // Check for contenteditable attribute
+            if (element.getAttribute("contenteditable") === "true" || element.isContentEditable) {
+                return true;
+            }
+
+            // Added enhancement to capture dropdown interactive elements
+            if (element.classList && (
+                element.classList.contains("button") ||
+                element.classList.contains('dropdown-toggle') ||
+                element.getAttribute('data-index') ||
+                element.getAttribute('data-toggle') === 'dropdown' ||
+                element.getAttribute('aria-haspopup') === 'true'
+            )) {
+                return true;
+            }
+
+            const interactiveRoles = new Set([
+                'button',           // Directly clickable element
+                'link',            // Clickable link
+                'menu',            // Menu container (ARIA menus)
+                'menubar',         // Menu bar container
+                'menuitem',        // Clickable menu item
+                'menuitemradio',   // Radio-style menu item (selectable)
+                'menuitemcheckbox', // Checkbox-style menu item (toggleable)
+                'radio',           // Radio button (selectable)
+                'checkbox',        // Checkbox (toggleable)
+                'tab',             // Tab (clickable to switch content)
+                'switch',          // Toggle switch (clickable to change state)
+                'slider',          // Slider control (draggable)
+                'spinbutton',      // Number input with up/down controls
+                'combobox',        // Dropdown with text input
+                'searchbox',       // Search input field
+                'textbox',         // Text input field
+                'listbox',         // Selectable list
+                'option',          // Selectable option in a list
+                'scrollbar'        // Scrollable control
+            ]);
+
+            // Basic role/attribute checks
+            const hasInteractiveRole =
+                interactiveElements.has(tagName) ||
+                (role && interactiveRoles.has(role)) ||
+                (ariaRole && interactiveRoles.has(ariaRole));
+
+            if (hasInteractiveRole) return true;
+
+
+            // check whether element has event listeners by window.getEventListeners
+            try {
+                if (typeof getEventListeners === 'function') {
+                    const listeners = getEventListeners(element);
+                    const mouseEvents = ['click', 'mousedown', 'mouseup', 'dblclick'];
+                    for (const eventType of mouseEvents) {
+                        if (listeners[eventType] && listeners[eventType].length > 0) {
+                            return true; // Found a mouse interaction listener
+                        }
+                    }
+                }
+
+                const getEventListenersForNode = element?.ownerDocument?.defaultView?.getEventListenersForNode || window.getEventListenersForNode;
+                if (typeof getEventListenersForNode === 'function') {
+                    const listeners = getEventListenersForNode(element);
+                    const interactionEvents = ['click', 'mousedown', 'mouseup', 'keydown', 'keyup', 'submit', 'change', 'input', 'focus', 'blur'];
+                    for (const eventType of interactionEvents) {
+                        for (const listener of listeners) {
+                            if (listener.type === eventType) {
+                                return true; // Found a common interaction listener
+                            }
+                        }
+                    }
+                }
+                // Fallback: Check common event attributes if getEventListeners is not available (getEventListeners doesn't work in page.evaluate context)
+                const commonMouseAttrs = ['onclick', 'onmousedown', 'onmouseup', 'ondblclick'];
+                for (const attr of commonMouseAttrs) {
+                    if (element.hasAttribute(attr) || typeof element[attr] === 'function') {
+                        return true;
+                    }
+                }
+            } catch (e) {
+                // console.warn(`Could not check event listeners for ${element.tagName}:`, e);
+                // If checking listeners fails, rely on other checks
+            }
+
+            return false
+        }
+
+        /**
+         * Validates if an element is a meaningful text container suitable for extraction.
+         *
+         * An element is considered a valid text element if it meets all the following conditions:
+         * 1. It is visible (i.e., not `display: none` or `visibility: hidden`).
+         * 2. It contains non-empty, trimmed text content.
+         * 3. It is not a tag typically used for scripting or non-visual content (e.g., <script>, <style>).
+         * 4. Its dimensions are not trivially small (e.g., less than 3x3 pixels) and not too large.
+         * 5. It is not an interactive element, as those are handled separately.
+         *
+         * @param {HTMLElement} element The element to validate.
+         * @returns {boolean} `true` if the element is a valid text container, otherwise `false`.
+         */
+        function isValidTextElement(element) {
+            if (!element || element.nodeType !== Node.ELEMENT_NODE) {
+                return false;
+            }
+
+            // Cache tagName and computed style for performance
+            const tagName = element.tagName.toLowerCase();
+            const style = getCachedStyle(element);
+
+            // 1. Visibility check - element must be visible
+            if (
+                style.display === 'none' ||
+                style.visibility === 'hidden' ||
+                parseFloat(style.opacity) === 0
+            ) {
+                return false;
+            }
+
+            // 2. Must contain non-whitespace text content
+            const text = (element.innerText || element.textContent || '').trim();
+            if (!text) return false;
+
+            // 3. Exclude common structural containers (usually don't display user-relevant text)
+            const structuralTags = new Set([
+                'html', 'body', 'section', 'header', 'footer', 'main', 'nav', 'article', 'aside', 'template', 'iframe'
+            ]);
+            if (structuralTags.has(tagName)) {
+                return false;
+            }
+
+            // 4. Exclude large containers that occupy most of the viewport (likely layout or whitespace areas)
+            const rect = element.getBoundingClientRect();
+            const vw = window.innerWidth, vh = window.innerHeight;
+            const areaRatio = (rect.width * rect.height) / (vw * vh);
+            if (areaRatio > 0.6) return false;  // Adjust threshold as needed
+
+            // 5. If element is interactive, let isInteractiveElement handle it to avoid duplicate processing
+            // if (isInteractiveElement(element) && !isElementDistinctInteraction(element)) {
+            if (isInteractiveElement(element)) return false;
+
+            // 6. Final validation - this is considered a meaningful text information node
+            return true;
+        }
+
+        /**
+         * Checks if an element is the top-most element at its center point.
+         *
+         * This function determines if the given element is the one that would receive a click
+         * at its geometric center. It is useful for filtering out occluded or overlaid elements.
+         *
+         * @param {HTMLElement} element The element to check.
+         * @returns {boolean} `true` if the element is on top, otherwise `false`.
+         */
+        function isTopElement(element) {
+            if (!window._viewportOnly) {
+                return true;
+            }
+            const viewportExpansion = 0;
+
+            const rects = element.getClientRects(element); // Replace element.getClientRects()
+
+            if (!rects || rects.length === 0) {
+                return false; // No geometry, cannot be top
+            }
+
+            let isAnyRectInViewport = false;
+            for (const rect of rects) {
+                // Use the same logic as isInExpandedViewport check
+                if (rect.width > 0 && rect.height > 0 && !( // Only check non-empty rects
+                    rect.bottom < -viewportExpansion ||
+                    rect.top > window.innerHeight + viewportExpansion ||
+                    rect.right < -viewportExpansion ||
+                    rect.left > window.innerWidth + viewportExpansion
+                )) {
+                    isAnyRectInViewport = true;
+                    break;
+                }
+            }
+
+            if (!isAnyRectInViewport) {
+                return false; // All rects are outside the viewport area
+            }
+
+
+            // Find the correct document context and root element
+            let doc = element.ownerDocument;
+
+            // If we're in an iframe, elements are considered top by default
+            if (doc !== window.document) {
+                return true;
+            }
+
+            // For shadow DOM, we need to check within its own root context
+            const shadowRoot = element.getRootNode();
+            if (shadowRoot instanceof ShadowRoot) {
+                const centerX = rects[Math.floor(rects.length / 2)].left + rects[Math.floor(rects.length / 2)].width / 2;
+                const centerY = rects[Math.floor(rects.length / 2)].top + rects[Math.floor(rects.length / 2)].height / 2;
+
+                try {
+                    const topEl = shadowRoot.elementFromPoint(centerX, centerY);
+                    if (!topEl) return false;
+
+                    let current = topEl;
+                    while (current && current !== shadowRoot) {
+                        if (current === element) return true;
+                        current = current.parentElement;
+                    }
+                    return false;
+                } catch (e) {
+                    return true;
+                }
+            }
+
+            const margin = 10
+            const rect = rects[Math.floor(rects.length / 2)];
+
+            // For elements in viewport, check if they're topmost. Do the check in the
+            // center of the element and at the corners to ensure we catch more cases.
+            const checkPoints = [
+                // Initially only this was used, but it was not enough
+                {x: rect.left + rect.width / 2, y: rect.top + rect.height / 2},
+                {x: rect.left + margin, y: rect.top + margin},        // top left
+                {x: rect.right - margin, y: rect.top + margin},    // top right
+                {x: rect.left + margin, y: rect.bottom - margin},  // bottom left
+                {x: rect.right - margin, y: rect.bottom - margin},    // bottom right
+            ];
+
+            return checkPoints.some(({x, y}) => {
+                try {
+                    const topEl = document.elementFromPoint(x, y);
+                    if (!topEl) return false;
+
+                    let current = topEl;
+                    while (current && current !== document.documentElement) {
+                        if (current === element) return true;
+                        current = current.parentElement;
+                    }
+                    return false;
+                } catch (e) {
+                    return true;
+                }
+            });
+        }
+
+        /**
+         * Checks if an element is currently visible in the DOM.
+         *
+         * Visibility is determined by the element's dimensions (width and height > 0) and
+         * its CSS properties (`display`, `visibility`, `opacity`).
+         *
+         * @param {HTMLElement} element The element to check.
+         * @returns {boolean} `true` if the element is visible, otherwise `false`.
+         */
+        function isVisible(element) {
+            const style = getComputedStyle(element);
+            return (
+                element.offsetWidth > 0 &&
+                element.offsetHeight > 0 &&
+                style?.visibility !== "hidden" &&
+                style?.display !== "none"
+            );
+        }
+
+        /**
+         * Generates a simplified CSS selector for an element.
+         *
+         * This function creates a selector based on the element's tag name, ID (if available),
+         * and class names. It is not guaranteed to be unique but is useful for providing
+         * a human-readable identifier.
+         *
+         * @param {HTMLElement} elem The element for which to generate a selector.
+         * @returns {string | null} A CSS selector string, or `null` if the element is invalid.
+         */
+        function generateSelector(elem) {
+            if (!elem) return null;
+
+            let sel = elem.tagName.toLowerCase();
+
+            // use id first
+            if (elem.id) {
+                sel += `#${elem.id}`;
+                return sel;
+            }
+
+            // try to get class from classList, fallback to getAttribute if not existed
+            let classes = [];
+            if (elem.classList && elem.classList.length > 0) {
+                classes = Array.from(elem.classList);
+            } else {
+                const raw = elem.getAttribute('class') || '';
+                classes = raw.trim().split(/\s+/).filter(Boolean);
+            }
+
+            if (classes.length > 0) {
+                sel += `.${classes.join('.')}`;
+            }
+
+            return sel;
+        }
+
+        /**
+         * Generates a robust XPath for an element.
+         *
+         * This function constructs an XPath by traversing up the DOM tree from the element.
+         * It prefers using an ID if available, otherwise it builds a path based on tag names
+         * and sibling indices, making the XPath stable and unique.
+         *
+         * @param {HTMLElement} elem The element for which to generate the XPath.
+         * @returns {string} The generated XPath string.
+         */
+        function generateXPath(elem) {
+            if (!(elem instanceof Element)) return '';
+            if (elem.id) return `//*[@id=\"${elem.id}\"]`;
+            const parts = [];
+            while (elem && elem.nodeType === Node.ELEMENT_NODE) {
+                let idx = 1;
+                let sib = elem.previousElementSibling;
+                while (sib) {
+                    if (sib.nodeName === elem.nodeName) idx++;
+                    sib = sib.previousElementSibling;
+                }
+                parts.unshift(elem.nodeName.toLowerCase() + `[${idx}]`);
+                elem = elem.parentElement;
+            }
+            return '/' + parts.join('/');
+        }
+
+        /**
+         * Gathers comprehensive information about a DOM element.
+         *
+         * This function collects a wide range of properties for an element, including its identity,
+         * attributes, layout, visibility, interactivity, and position. This data is used to
+         * build the DOM tree and determine which elements to highlight.
+         *
+         * @param {HTMLElement} elem The element to gather information from.
+         * @param {boolean} isParentHighlighted A flag indicating if an ancestor of this element is highlighted.
+         * @returns {object} An object containing detailed information about the element.
+         */
+        function getElementInfo(elem, isParentHighlighted) {
+            const r = elem.getBoundingClientRect();
+            const sx = window.pageXOffset || document.documentElement.scrollLeft;
+            const sy = window.pageYOffset || document.documentElement.scrollTop;
+            let txt = '';
+
+            elem.childNodes.forEach(c => {
+                if (c.nodeType === Node.TEXT_NODE) txt += c.textContent.trim();
+            });
+
+            return {
+                // id: getElementId(elem),
+                node: elem,
+                tagName: elem.tagName.toLowerCase(),
+                className: elem.getAttribute('class') || null,
+                type: elem.getAttribute('type') || null, placeholder: elem.getAttribute('placeholder') || null,
+                innerText: txt || (elem.innerText || elem.value || '').trim(),
+                attributes: Array.from(elem.attributes).map(a => ({name: a.name, value: a.value})),
+
+                viewport: {x: r.left + sx, y: r.top + sy, width: r.width, height: r.height},
+                center_x: r.left + r.width / 2 + sx,
+                center_y: r.top + r.height / 2 + sy,
+
+                isVisible: isVisible(elem),
+                isInteractive: isInteractiveElement(elem),
+                isValidText: isValidTextElement(elem),
+                isTopElement: isTopElement(elem),
+                isInViewport: !(r.bottom < 0 || r.top > window.innerHeight || r.right < 0 || r.left > window.innerWidth),
+
+                isParentHighlighted: isParentHighlighted,
+                xpath: generateXPath(elem),
+                selector: generateSelector(elem),
+                styles: getStyleSubset(elem)
+            };
+        }
+
+        // ============================= Highlight Element =============================
+        /**
+         * Selects a random color from a predefined palette.
+         *
+         * @returns {string} A hexadecimal color string.
+         */
+        function randomColor() {
+            return palette[Math.floor(Math.random() * palette.length)];
+        }
+
+        /**
+         * Determines whether an element should be highlighted based on current settings and its properties.
+         *
+         * This function applies a set of rules to decide if an element qualifies for highlighting.
+         * It checks for visibility, viewport presence, interactivity, and text content based on
+         * the global `_viewportOnly` and `_highlightText` flags. It also prevents highlighting
+         * nested non-distinct elements if a parent is already highlighted.
+         *
+         * @param {object} elemInfo The information object for the element, from `getElementInfo`.
+         * @param {HTMLElement} elemObj The actual DOM element.
+         * @param {boolean} isParentHighlighted `true` if an ancestor of this element is already highlighted.
+         * @returns {boolean} `true` if the element should be highlighted, otherwise `false`.
+         */
+        function handleHighlighting(elemInfo, elemObj, isParentHighlighted) {
+            function shouldHighlightElem(nodeInfo) {
+                const role = elemObj.getAttribute('role');
+                const isMenuContainer = role === 'menu' || role === 'menubar' || role === 'listbox';
+                if (isMenuContainer) return true;
+                // if (window._viewportOnly === true && !nodeInfo.isInViewport) return false;
+
+                if (window._highlightText) {
+                    return nodeInfo.isVisible && nodeInfo.isTopElement && nodeInfo.isValidText;
+                } else {
+                    return nodeInfo.isVisible && nodeInfo.isTopElement && nodeInfo.isInteractive;
+                }
+            }
+
+            // 1) basic filter
+            if (!shouldHighlightElem(elemInfo)) return false;
+
+            if (window._highlightText) {
+                if (isParentHighlighted && !elemInfo.isInteractive) return false
+            } else {
+                if (isParentHighlighted && !isElementDistinctInteraction(elemObj)) return false;
+            }
+
+            // 2) skip if parent is highlighted and is not distinct interaction
+            if (isParentHighlighted && !isElementDistinctInteraction(elemObj)) return false;
+
+            // 3) (optional) highlight only within viewport
+            // if (!elemInfo.isInViewport && elemInfo.viewportExpansion !== -1) return false;
+
+            if (highlightMap.has(elemObj)) {
+                elemInfo.highlightIndex = highlightMap.get(elemObj);
+            } else {
+                elemInfo.highlightIndex = highlightIndex;
+                highlightMap.set(elemObj, highlightIndex);
+                highlightIndex += 1;
+            }
+
+            return true;
+        }
+
+        /**
+         * Renders visual highlights for elements in the processed DOM tree.
+         *
+         * This function iterates through the tree and draws colored boxes and labels on an overlay
+         * for each element that has been marked for highlighting. It clears and redraws the
+         * highlights, making it suitable for dynamic updates on scroll or resize.
+         *
+         * @param {object} tree The root of the element tree to render.
+         */
+        function renderHighlights(tree) {
+            overlayContainer.textContent = '';
+            (function walk(node) {
+                if (!node) return;
+
+                if (node.node) {
+                    const info = node.node;
+                    const elem = info.node;
+                    const rects = Array.from(elem.getClientRects()).filter(r => r.width >= 2 && r.height >= 2);
+                    if (rects.length === 0) return;
+
+                    // 1. Color: assign a fixed color for each element
+                    let color = _elementHighlightColorMap.get(elem);
+                    if (!color) {
+                        color = randomColor();
+                        _elementHighlightColorMap.set(elem, color);
+                    }
+
+                    // 2. Draw box for each rect (maintain visual consistency for multi-line/multi-rect elements)
+                    rects.forEach(r => {
+                        const box = document.createElement('div');
+                        Object.assign(box.style, {
+                            position: 'fixed',
+                            top: `${r.top}px`,
+                            left: `${r.left}px`,
+                            width: `${r.width}px`,
+                            height: `${r.height}px`,
+                            outline: `2px dashed ${color}`,
+                            boxSizing: 'border-box',
+                            pointerEvents: 'none'
+                        });
+                        overlayContainer.appendChild(box);
+                    });
+
+                    // 3. Calculate union rect as fallback and external positioning reference
+                    const union = rects.reduce((acc, r) => {
+                        if (!acc) {
+                            return {
+                                top: r.top,
+                                left: r.left,
+                                right: r.right,
+                                bottom: r.bottom
+                            };
+                        }
+                        return {
+                            top: Math.min(acc.top, r.top),
+                            left: Math.min(acc.left, r.left),
+                            right: Math.max(acc.right, r.right),
+                            bottom: Math.max(acc.bottom, r.bottom)
+                        };
+                    }, null);
+                    if (!union) return;
+
+                    // 4. Create label (hidden first for measurement)
+                    const label = document.createElement('div');
+                    label.textContent = info.highlightIndex;
+                    Object.assign(label.style, {
+                        position: 'fixed',
+                        backgroundColor: color,
+                        color: '#fff',
+                        fontSize: '10px',
+                        padding: '1px 2px',
+                        borderRadius: '3px',
+                        pointerEvents: 'none',
+                        visibility: 'hidden',
+                        whiteSpace: 'nowrap',
+                        boxSizing: 'border-box'
+                    });
+                    overlayContainer.appendChild(label);
+                    const labelRect = label.getBoundingClientRect();
+
+                    // 5. Positioning: prioritize placing in the top-right corner of the first rect, with fallback logic from index.js
+                    const firstRect = rects[0];
+                    let labelTop = firstRect.top + 2; // slightly below the internal top
+                    let labelLeft = firstRect.left + firstRect.width - labelRect.width - 2; // right-aligned
+
+                    // If it doesn't fit (first rect is too small), place above the rect, right-aligned
+                    if (firstRect.width < labelRect.width + 4 || firstRect.height < labelRect.height + 4) {
+                        labelTop = firstRect.top - labelRect.height - 2;
+                        labelLeft = firstRect.left + firstRect.width - labelRect.width - 2;
+                    }
+
+                    // Final fallback: if still overflowing or in very crowded scenarios, fallback to union's top-left interior
+                    if (labelLeft < 0 || labelTop < 0 || labelLeft + labelRect.width > window.innerWidth) {
+                        // Inside union's top-left
+                        labelLeft = union.left + 2;
+                        labelTop = union.top + 2;
+                    }
+
+                    // Clamp to viewport
+                    labelTop = Math.max(0, Math.min(labelTop, window.innerHeight - labelRect.height));
+                    labelLeft = Math.max(0, Math.min(labelLeft, window.innerWidth - labelRect.width));
+
+                    label.style.left = `${labelLeft}px`;
+                    label.style.top = `${labelTop}px`;
+                    label.style.visibility = 'visible';
+                }
+
+                node.children.forEach(walk);
+            })(tree, false);
+        }
+
+        // ============================= Build Dom Tree =============================
+        /**
+         * Recursively builds a structured tree representing the DOM.
+         *
+         * This is the core function for crawling the DOM. It starts from a given element (usually the body),
+         * gathers information for each node, determines if it should be highlighted, and recursively
+         * processes its children. The resulting tree contains only the elements that are either
+         * highlighted themselves or contain highlighted descendants.
+         *
+         * @param {HTMLElement} elemObj The DOM element to start building the tree from.
+         * @param {boolean} [wasParentHighlighted=false] A flag passed during recursion to indicate if an ancestor was highlighted.
+         * @returns {object | null} A tree node object, or `null` if the element and its descendants are not relevant.
+         */
+        function buildTree(elemObj, wasParentHighlighted = false) {
+            // 1) get element info
+            const elemInfo = getElementInfo(elemObj, wasParentHighlighted);
+
+            // 2) check node satisfies highlight condition
+            const isCurNodeHighlighted = handleHighlighting(elemInfo, elemObj, wasParentHighlighted)
+            const isParentHighlighted = wasParentHighlighted || isCurNodeHighlighted;
+
+            // 3) recursively build structured dom tree, with 'isParentHighlighted' state
+            const children = [];
+            Array.from(elemObj.children).forEach(child => {
+                const subtree = buildTree(child, isParentHighlighted);
+                if (subtree) children.push(subtree);
+            });
+
+            // 4) highlight filter
+            if (isCurNodeHighlighted) {
+                highlightIdMap[elemInfo.highlightIndex] = elemInfo;     // map highlightIndex to element info
+                return {node: elemInfo, children};                      // keep info if is highlightable
+            } else if (children.length > 0) {
+                return {node: null, children};                          // child node is highlightable
+            } else {
+                return null;                                            // skip
+            }
+        }
+
+        // ============================= Main Function =============================
+        /**
+         * The main entry point for building and processing the element tree.
+         *
+         * This function initializes the process, calls `buildTree` to construct the DOM representation,
+         * and optionally triggers the rendering of highlights. It also sets up event listeners
+         * to re-render highlights on scroll and resize events to keep them in sync with the layout.
+         *
+         * @returns {[object, object]} A tuple containing the generated DOM tree and the map of highlight indices to element info.
+         */
+        window.buildElementTree = function () {
+            highlightIdMap = {};
+            const tree = buildTree(document.body);
+
+            if (window._highlight) {
+                renderHighlights(tree);
+                window.addEventListener('scroll', () => renderHighlights(tree), {passive: true, capture: true});
+                window.addEventListener('resize', () => renderHighlights(tree));
+            }
+            return [tree, highlightIdMap];
+        }
+    }
+)();

webqa_agent/crawler/js/marker_remover.js

@@ -0,0 +1,15 @@
+() => {
+    // 移除标记容器
+    const markerContainer = document.getElementById('__marker_container__');
+    if (markerContainer) {
+        markerContainer.remove();
+    }
+
+    // 清除所有标记元素
+    const markers = document.querySelectorAll('.__marker_element__');
+    markers.forEach(marker => marker.remove());
+
+    // 清除可能残留的样式
+    const styles = document.querySelectorAll('style[data-marker-style]');
+    styles.forEach(style => style.remove());
+}

webqa_agent/crawler/js/text_extractor.js

@@ -0,0 +1,182 @@
+() => {
+    // 基础可见性检查
+    function isVisible(element) {
+        if (!element || !element.getBoundingClientRect) return false;
+        const rect = element.getBoundingClientRect();
+        const style = window.getComputedStyle(element);
+
+        return rect.width > 3 &&
+               rect.height > 3 &&
+               style.display !== 'none' &&
+               style.visibility !== 'hidden' &&
+               style.opacity !== '0' &&
+               parseFloat(style.opacity) > 0;
+    }
+
+    // 检查元素是否是最顶层的（模仿 element_detector.js 的实现）
+    function isTopElement(elem) {
+        const rect = elem.getBoundingClientRect();
+        // 如果元素在视口外，返回 true（处理边界情况）
+        if (rect.right < 0 || rect.left > window.innerWidth || rect.bottom < 0 || rect.top > window.innerHeight) {
+            return true;
+        }
+
+        // 计算元素中心点坐标
+        const cx = rect.left + rect.width / 2;
+        const cy = rect.top + rect.height / 2;
+
+        try {
+            // 获取在该中心点位置的最顶层元素
+            const topEl = document.elementFromPoint(cx, cy);
+            let curr = topEl;
+
+            // 检查该元素或其父级是否包含目标元素
+            while (curr && curr !== document.documentElement) {
+                if (curr === elem) return true;
+                curr = curr.parentElement;
+            }
+            return false;
+        } catch {
+            return true;
+        }
+    }
+
+    // 检查元素是否有实际内容
+    function hasContent(element) {
+        // 文本内容检查
+        const text = element.innerText || '';
+        if (text.trim().length > 1 && !/^\d+$/.test(text.trim())) {
+            return true;
+        }
+
+        // 检查是否是有意义的元素类型
+        const tagName = element.tagName.toLowerCase();
+        if (['a', 'button', 'input', 'select', 'textarea', 'img',
+             'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p', 'li'].includes(tagName)) {
+            return true;
+        }
+
+        // 检查是否有样式类名，表明可能有语义
+        if (element.className && typeof element.className === 'string' && element.className.length > 0) {
+            return true;
+        }
+
+        // 检查是否有交互属性
+        if (element.getAttribute('role') ||
+            element.getAttribute('aria-label') ||
+            element.onclick ||
+            element.getAttribute('onclick') ||
+            element.getAttribute('href') ||
+            element.getAttribute('tabindex') !== null) {
+            return true;
+        }
+
+        return false;
+    }
+
+    // 提取元素文本内容
+    function getElementText(element) {
+        // 如果是输入元素，获取其值或占位符
+        if (element.tagName.toLowerCase() === 'input' ||
+            element.tagName.toLowerCase() === 'textarea') {
+            return element.value || element.placeholder || '';
+        }
+
+        // 优先获取整个元素的innerText，这样可以包含子元素的文本
+        let textContent = element.innerText?.trim() || '';
+
+        // 如果innerText为空，尝试获取元素的直接文本内容
+        if (!textContent) {
+            for (const node of element.childNodes) {
+                if (node.nodeType === Node.TEXT_NODE) {
+                    const trimmed = node.textContent.trim();
+                    if (trimmed) textContent += trimmed + ' ';
+                }
+            }
+            textContent = textContent.trim();
+        }
+
+        return textContent;
+    }
+
+    // 检查文本是否有意义
+    function isMeaningfulText(text) {
+        // 排除只有数字的文本（可能是分页或列表编号）
+        if (/^[0-9]+$/.test(text)) {
+            return false;
+        }
+
+        // 排除太短的文本
+        if (text.length < 3) {
+            return false;
+        }
+
+        return true;
+    }
+
+    // 收集页面上所有可见元素的文本信息
+    function collectTextElements(rootElement) {
+        const textElements = [];
+        const processedTexts = new Set(); // 用于去重
+
+        function processElement(element) {
+            // 检查元素是否可见且是最顶层的
+            if (!element || !isVisible(element) || !isTopElement(element)) return;
+
+            // 获取元素的文本内容
+            const text = getElementText(element);
+
+            // 如果当前元素有有意义的文本内容，收集它并跳过子元素处理
+            if (text && isMeaningfulText(text) && !processedTexts.has(text)) {
+                const rect = element.getBoundingClientRect();
+                processedTexts.add(text);
+
+                textElements.push({
+                    text,
+                    tag: element.tagName.toLowerCase(),
+                    position: {
+                        x: Math.round(rect.left),
+                        y: Math.round(rect.top),
+                        width: Math.round(rect.width),
+                        height: Math.round(rect.height)
+                    }
+                });
+
+                // 如果当前元素有有意义的文本，就不再处理子元素，避免重复
+                return;
+            }
+
+            // 只有当前元素没有有意义的文本时，才递归处理子元素
+            for (const child of element.children) {
+                processElement(child);
+            }
+        }
+
+        processElement(rootElement);
+        return textElements;
+    }
+
+    // 主函数：提取页面内容
+    function extractPageContent() {
+        // 获取页面元数据
+        const metadata = {
+            title: document.title,
+            url: window.location.href,
+            size: {
+                width: window.innerWidth,
+                height: window.innerHeight,
+                scrollHeight: document.documentElement.scrollHeight
+            }
+        };
+
+        // 收集所有文本元素
+        const textElements = collectTextElements(document.body);
+
+        return {
+            metadata,
+            textElements
+        };
+    }
+
+    return extractPageContent();
+}

webqa_agent/data/__init__.py

@@ -0,0 +1,11 @@
+from .test_structures import (
+    ParallelTestSession,
+    TestConfiguration,
+    TestExecutionContext,
+    TestResult,
+    TestStatus,
+    TestType,
+    get_default_test_name,
+)
+
+__all__ = ["TestType", "TestStatus", "TestConfiguration", "TestExecutionContext", "TestResult", "ParallelTestSession", "get_default_test_name"]

webqa_agent/data/test_structures.py

@@ -0,0 +1,333 @@
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel
+
+from webqa_agent.browser.config import DEFAULT_CONFIG
+
+# 侧边栏标题（默认）
+CATEGORY_TITLES: Dict[str, Dict[str, str]] = {
+    "zh-CN": {
+        "function": "功能测试",
+        "ux": "UX测试",
+        "performance": "性能测试",
+        "security": "安全测试",
+    },
+    "en-US": {
+        "function": "Function Test",
+        "ux": "UX Test",
+        "performance": "Performance Test",
+        "security": "Security Test",
+    }
+}
+
+
+class TestCategory(str, Enum):
+    FUNCTION = "function"
+    UX = "ux"
+    SECURITY = "security"
+    PERFORMANCE = "performance"
+
+# 测试类型
+class TestType(str, Enum):
+    """Test type enumeration."""
+
+    UNKNOWN = "unknown"
+    BASIC_TEST = "basic_test"
+    # BUTTON_TEST = "button_test"
+    UI_AGENT_LANGGRAPH = "ui_agent_langgraph"
+    UX_TEST = "ux_test"
+    PERFORMANCE = "performance_test"
+    # WEB_BASIC_CHECK = "web_basic_check"
+    SECURITY_TEST = "security_test"
+    SEO_TEST = "seo_test"
+
+def get_category_for_test_type(test_type: TestType) -> TestCategory:
+    """Map TestType to TestCategory."""
+    mapping = {
+        TestType.UI_AGENT_LANGGRAPH: TestCategory.FUNCTION,
+        TestType.BASIC_TEST: TestCategory.FUNCTION,
+        # TestType.BUTTON_TEST: TestCategory.FUNCTION,
+        # TestType.WEB_BASIC_CHECK: TestCategory.FUNCTION,
+        TestType.UX_TEST: TestCategory.UX,
+        TestType.PERFORMANCE: TestCategory.PERFORMANCE,
+        TestType.SECURITY_TEST: TestCategory.SECURITY,
+        TestType.UNKNOWN: TestCategory.FUNCTION,  # Default to function for unknown types
+    }
+    return mapping.get(test_type, TestCategory.FUNCTION)
+
+
+# 报告子标题栏
+TEST_TYPE_DEFAULT_NAMES: Dict[str, Dict[TestType, str]] = {
+    "zh-CN": {
+        TestType.UI_AGENT_LANGGRAPH: "智能功能测试",
+        TestType.BASIC_TEST: "遍历测试",
+        # TestType.BUTTON_TEST: "功能测试",
+        # TestType.WEB_BASIC_CHECK: "技术健康度检查",
+        TestType.UX_TEST: "用户体验测试",
+        TestType.PERFORMANCE: "性能测试",
+        TestType.SECURITY_TEST: "安全测试",
+    },
+    "en-US": {
+        TestType.UI_AGENT_LANGGRAPH: "AI Function Test",
+        TestType.BASIC_TEST: "Basic Function Test",
+        # TestType.BUTTON_TEST: "Traversal Test",
+        # TestType.WEB_BASIC_CHECK: "Technical Health Check",
+        TestType.UX_TEST: "UX Test",
+        TestType.PERFORMANCE: "Performance Test",
+        TestType.SECURITY_TEST: "Security Test",
+    }
+}
+
+
+def get_default_test_name(test_type: TestType, language: str = "zh-CN") -> str:
+    """Return the internal default test name for a given TestType.
+
+    Names are hardcoded and not user-configurable.
+    """
+    return TEST_TYPE_DEFAULT_NAMES.get(language, {}).get(test_type, test_type.value)
+
+
+class TestStatus(str, Enum):
+    """Test status enumeration."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    PASSED = "passed"
+    WARNING = "warning"
+    INCOMPLETED = "incompleted"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class TestConfiguration(BaseModel):
+    """Test configuration for parallel execution."""
+
+    test_id: Optional[str] = None
+    test_type: Optional[TestType] = TestType.BASIC_TEST
+    test_name: Optional[str] = ""
+    enabled: Optional[bool] = True
+    browser_config: Optional[Dict[str, Any]] = DEFAULT_CONFIG
+    report_config: Optional[Dict[str, Any]] = {"language": "zh-CN"}
+    test_specific_config: Optional[Dict[str, Any]] = {}
+    timeout: Optional[int] = 300  # seconds
+    retry_count: Optional[int] = 0
+    dependencies: Optional[List[str]] = []  # test_ids that must complete first
+
+
+class TestExecutionContext(BaseModel):
+    """Execution context for a single test."""
+
+    test_config: TestConfiguration
+    session_id: str
+    start_time: Optional[datetime] = None
+    end_time: Optional[datetime] = None
+    status: Optional[TestStatus] = TestStatus.PENDING
+    error_message: Optional[str] = ""
+    retry_attempts: Optional[int] = 0
+
+    def start_execution(self):
+        """Mark test as started."""
+        self.start_time = datetime.now().replace(microsecond=0)
+        self.status = TestStatus.RUNNING
+
+    def complete_execution(self, success: bool = True, error_message: str = ""):
+        """Mark test as completed."""
+        self.end_time = datetime.now().replace(microsecond=0)
+        self.status = TestStatus.PASSED if success else TestStatus.FAILED
+        self.error_message = error_message
+
+    @property
+    def duration(self) -> Optional[float]:
+        """Get execution duration in seconds."""
+        if self.start_time and self.end_time:
+            return (self.end_time - self.start_time).total_seconds()
+        return None
+
+
+class SubTestScreenshot(BaseModel):
+    type: str
+    data: str  # base64 encoded image data
+
+
+class SubTestAction(BaseModel):
+    description: Optional[str]
+    index: int
+    success: bool
+
+
+class SubTestStep(BaseModel):
+    id: int
+    screenshots: Optional[List[SubTestScreenshot]] = []
+    modelIO: Optional[str] = ""
+    actions: Optional[List[SubTestAction]] = []
+    description: Optional[str] = ""
+    status: Optional[TestStatus] = TestStatus.PASSED
+    errors: Optional[str] = ""
+
+
+class SubTestReport(BaseModel):
+    title: str
+    issues: str
+
+
+class SubTestResult(BaseModel):
+    """Fine-grained result for a sub test / test case.
+
+    TODO: Update type of `messages`
+    """
+
+    name: str
+    status: Optional[TestStatus] = TestStatus.PENDING
+    metrics: Optional[Dict[str, Any]] = {}
+    steps: Optional[List[SubTestStep]] = []  # Detailed execution steps
+    messages: Optional[Dict[str, Any]] = {}  # Browser monitoring data
+    start_time: Optional[str] = None
+    end_time: Optional[str] = None
+    final_summary: Optional[str] = ""
+    report: Optional[List[SubTestReport]] = []
+
+
+class TestResult(BaseModel):
+    """Isolated test result data."""
+
+    test_id: Optional[str] = ""
+    test_type: Optional[TestType] = TestType.UNKNOWN
+    test_name: Optional[str] = ""
+    module_name: Optional[str] = ""
+    status: Optional[TestStatus] = TestStatus.PENDING
+    # New field to indicate test category (function/ui/performance)
+
+    category: Optional[TestCategory] = TestCategory.FUNCTION
+    start_time: Optional[datetime] = None
+    end_time: Optional[datetime] = None
+    duration: Optional[float] = None
+
+    # Deprecated free-form dict; keep until callers migrated
+    results: Optional[Dict[str, Any]] = {}
+
+    # Structured list replacing the old 'results' field
+    sub_tests: Optional[List[SubTestResult]] = []
+
+    # Artifacts
+    logs: Optional[List[str]] = []
+    traces: Optional[List[str]] = []
+
+    # Error information
+    error_message: Optional[str] = ""
+    error_details: Optional[Dict[str, Any]] = {}
+
+    # Metrics
+    metrics: Optional[Dict[str, Union[int, float, str]]] = {}
+
+    def add_log(self, log_path: str):
+        """Add log file to results."""
+        self.logs.append(log_path)
+
+    def add_metric(self, key: str, value: Union[int, float, str]):
+        """Add metric to results."""
+        self.metrics[key] = value
+
+    def add_data(self, key: str, value: Any):
+        """Add data to results."""
+        self.results[key] = value
+
+
+class ParallelTestSession(BaseModel):
+    """Session data for parallel test execution."""
+
+    session_id: Optional[str] = None
+    target_url: Optional[str] = ""
+    llm_config: Optional[Dict[str, Any]] = {}
+
+    # Test configurations
+    test_configurations: Optional[List[TestConfiguration]] = []
+
+    # Execution tracking
+    test_contexts: Optional[Dict[str, TestExecutionContext]] = {}
+    test_results: Optional[Dict[str, TestResult]] = {}
+
+    # Session metadata
+    start_time: Optional[datetime] = None
+    end_time: Optional[datetime] = None
+
+    # Aggregated results
+    aggregated_results: Optional[Dict[str, Any]] = {}
+    llm_summary: Optional[str] = ""
+    report_path: Optional[str] = ""
+    html_report_path: Optional[str] = ""
+
+    def add_test_configuration(self, test_config: TestConfiguration):
+        """Add test configuration to session."""
+        self.test_configurations.append(test_config)
+
+        # Create execution context
+        context = TestExecutionContext(test_config=test_config, session_id=self.session_id)
+        self.test_contexts[test_config.test_id] = context
+
+        # Initialize result
+        result = TestResult(
+            test_id=test_config.test_id,
+            test_type=test_config.test_type,
+            test_name=test_config.test_name,
+            status=TestStatus.PENDING,
+            category=get_category_for_test_type(test_config.test_type),
+        )
+        self.test_results[test_config.test_id] = result
+
+    def start_session(self):
+        """Start the test session."""
+        self.start_time = datetime.now()
+
+    def complete_session(self):
+        """Complete the test session."""
+        self.end_time = datetime.now()
+
+    def update_test_result(self, test_id: str, result: TestResult):
+        """Update test result."""
+        self.test_results[test_id] = result
+
+    def get_test_by_type(self, test_type: TestType) -> List[TestConfiguration]:
+        """Get all tests of specific type."""
+        return [config for config in self.test_configurations if config.test_type == test_type]
+
+    def get_enabled_tests(self) -> List[TestConfiguration]:
+        """Get all enabled test configurations."""
+        return [config for config in self.test_configurations if config.enabled]
+
+    def get_summary_stats(self) -> Dict[str, Any]:
+        """Get session summary statistics"""
+        return {
+            "session_id": self.session_id,
+            "target_url": self.target_url,
+            "start_time": self.start_time.replace(microsecond=0).isoformat() if self.start_time else None,
+            "end_time": self.end_time.replace(microsecond=0).isoformat() if self.end_time else None,
+        }
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert session to dictionary with grouped test results."""
+        grouped_results: Dict[str, Dict[str, Any]] = {}
+
+        if self.test_configurations and len(self.test_configurations) > 0:
+            language = self.test_configurations[0].report_config.get("language", "zh-CN")
+
+        for cat in TestCategory:
+            key = f"{cat.value}_test_results"
+            grouped_results[key] = {"title": CATEGORY_TITLES[language].get(cat.value, cat.name), "items": []}
+
+        for result in self.test_results.values():
+            key = f"{result.category.value}_test_results"
+            if key not in grouped_results:
+                grouped_results[key] = {
+                    "title": CATEGORY_TITLES[language].get(result.category.value, result.category.name.title()),
+                    "items": [],
+                }
+            grouped_results[key]["items"].append(result.dict())
+
+        return {
+            "session_info": self.get_summary_stats(),
+            "aggregated_results": self.aggregated_results,
+            "test_results": grouped_results,
+            "llm_summary": self.llm_summary,
+        }

webqa_agent/executor/__init__.py

@@ -0,0 +1,20 @@
+from .parallel_executor import ParallelTestExecutor
+from .parallel_mode import ParallelMode
+from .result_aggregator import ResultAggregator
+from .test_runners import (
+    BasicTestRunner,
+    LighthouseTestRunner,
+    UIAgentLangGraphRunner,
+    UXTestRunner
+)
+
+__all__ = [
+    "ParallelMode",
+    "ParallelTestExecutor",
+    "BasicTestRunner",
+    "UIAgentLangGraphRunner",
+    "UXTestRunner",
+    "LighthouseTestRunner",
+    "WebBasicCheckRunner",
+    "ResultAggregator",
+]

webqa_agent/executor/parallel_executor.py

@@ -0,0 +1,354 @@
+import asyncio
+import logging
+import os
+from typing import Dict, List, Optional
+
+# Session ID constants
+SECURITY_TEST_NO_SESSION_ID = "security_test_no_session"
+
+from webqa_agent.browser.session import BrowserSessionManager
+from webqa_agent.data import ParallelTestSession, TestConfiguration, TestResult, TestStatus, TestType
+from webqa_agent.data.test_structures import get_category_for_test_type
+from webqa_agent.executor.result_aggregator import ResultAggregator
+from webqa_agent.executor.test_runners import (
+    BasicTestRunner,
+    LighthouseTestRunner,
+    SecurityTestRunner,
+    UIAgentLangGraphRunner,
+    UXTestRunner,
+)
+from webqa_agent.utils.log_icon import icon
+
+
+class ParallelTestExecutor:
+    """Parallel test execution manager."""
+
+    def __init__(self, max_concurrent_tests: int = 4):
+        self.max_concurrent_tests = max_concurrent_tests
+        self.session_manager = BrowserSessionManager()
+
+        # Test runners mapping
+        self.test_runners = {
+            TestType.UI_AGENT_LANGGRAPH: UIAgentLangGraphRunner(),
+            TestType.UX_TEST: UXTestRunner(),
+            TestType.PERFORMANCE: LighthouseTestRunner(),
+            TestType.BASIC_TEST: BasicTestRunner(),
+            # TestType.WEB_BASIC_CHECK: WebBasicCheckRunner(),
+            # TestType.BUTTON_TEST: ButtonTestRunner(),
+            TestType.SECURITY_TEST: SecurityTestRunner(),
+        }
+
+        # Execution tracking
+        self.running_tests: Dict[str, asyncio.Task] = {}
+        self.completed_tests: Dict[str, TestResult] = {}
+
+    async def execute_parallel_tests(self, test_session: ParallelTestSession) -> ParallelTestSession:
+        """Execute tests in parallel with proper isolation.
+
+        Args:
+            test_session: Session containing test configurations
+
+        Returns:
+            Updated session with results
+        """
+        logging.debug(f"Starting parallel test execution for session: {test_session.session_id}")
+        test_session.start_session()
+
+        try:
+            # Get enabled tests
+            enabled_tests = test_session.get_enabled_tests()
+            if not enabled_tests:
+                logging.warning("No enabled tests found")
+                return test_session
+
+            # Execute tests in batches to respect concurrency limits
+            await self._execute_tests_in_batches(test_session, enabled_tests)
+
+            test_session.complete_session()
+        except asyncio.CancelledError:
+            logging.warning("Parallel test execution cancelled – generating partial report.")
+            raise
+        except Exception as e:
+            logging.error(f"Error in parallel test execution: {e}")
+            raise
+        finally:
+            # Consolidated cleanup, aggregation, and report generation
+            await self._finalize_session(test_session)
+
+        return test_session
+
+    async def _execute_tests_in_batches(
+        self, test_session: ParallelTestSession, enabled_tests: List[TestConfiguration]
+    ):
+        """Execute tests in concurrent batches."""
+
+        # Resolve dependencies and create execution order
+        execution_batches = self._resolve_test_dependencies(enabled_tests)
+        # Get report_config from the first test configuration if available
+        report_config = None
+        if test_session.test_configurations:
+            report_config = test_session.test_configurations[0].report_config
+        self.result_aggregator = ResultAggregator(report_config)
+        
+        for batch_idx, test_batch in enumerate(execution_batches):
+            logging.debug(f"Executing batch {batch_idx + 1}/{len(execution_batches)} with {len(test_batch)} tests")
+
+            # Create semaphore for this batch
+            semaphore = asyncio.Semaphore(min(self.max_concurrent_tests, len(test_batch)))
+
+            # Create tasks for this batch
+            batch_tasks = []
+            for test_config in test_batch:
+                task = asyncio.create_task(self._execute_single_test(test_session, test_config, semaphore))
+                batch_tasks.append(task)
+                self.running_tests[test_config.test_id] = task
+
+            # Wait for batch completion
+            try:
+                try:
+                    results = await asyncio.gather(*batch_tasks, return_exceptions=True)
+                except asyncio.CancelledError:
+                    logging.warning("Batch was cancelled – collecting completed task results.")
+
+                    results = []
+                    for task in batch_tasks:
+                        if task.done():
+                            try:
+                                results.append(task.result())
+                            except Exception as e:
+                                results.append(e)
+                        else:
+                            # Task not finished (still cancelled/pending)
+                            results.append(asyncio.CancelledError())
+                    cancelled_in_batch = True
+                else:
+                    cancelled_in_batch = False
+
+                # Process results
+                for i, result in enumerate(results):
+                    test_config = test_batch[i]
+                    if isinstance(result, Exception):
+                        if isinstance(result, asyncio.CancelledError):
+                            logging.warning(f"Test {test_config.test_name} was cancelled.")
+                            cancelled_result = TestResult(
+                                test_id=test_config.test_id,
+                                test_type=test_config.test_type,
+                                test_name=test_config.test_name,
+                                status=TestStatus.CANCELLED,
+                                category=get_category_for_test_type(test_config.test_type),
+                                error_message="Test was cancelled",
+                            )
+                            test_session.update_test_result(test_config.test_id, cancelled_result)
+                        else:
+                            logging.error(f"Test {test_config.test_name} failed with exception: {result}")
+                            failed_result = TestResult(
+                                test_id=test_config.test_id,
+                                test_type=test_config.test_type,
+                                test_name=test_config.test_name,
+                                status=TestStatus.FAILED,
+                                category=get_category_for_test_type(test_config.test_type),
+                                error_message=str(result),
+                            )
+                            test_session.update_test_result(test_config.test_id, failed_result)
+                    else:
+                        test_session.update_test_result(test_config.test_id, result)
+
+            finally:
+                # Clean up batch tasks
+                for test_config in test_batch:
+                    self.running_tests.pop(test_config.test_id, None)
+
+            logging.debug(f"Batch {batch_idx + 1} completed")
+            if cancelled_in_batch:
+                # Propagate cancellation after processing.
+                raise asyncio.CancelledError()
+
+    async def _execute_single_test(
+        self, test_session: ParallelTestSession, test_config: TestConfiguration, semaphore: asyncio.Semaphore
+    ) -> TestResult:
+        """Execute a single test with proper isolation."""
+
+        async with semaphore:
+            test_context = test_session.test_contexts[test_config.test_id]
+            test_context.start_execution()
+
+            logging.debug(f"Starting test: {test_config.test_name} ({test_config.test_type.value})")
+
+            try:
+                if test_config.test_type in [
+                    TestType.UI_AGENT_LANGGRAPH,
+                    TestType.UX_TEST,
+                    TestType.BASIC_TEST
+                    # TestType.BUTTON_TEST,
+                    # TestType.WEB_BASIC_CHECK,
+                ]:
+
+                    # Create isolated browser session
+                    session = await self.session_manager.create_session(test_config.browser_config)
+                    test_context.session_id = session.session_id
+
+                    # Navigate to target URL
+                    await session.navigate_to(
+                        test_session.target_url, cookies=test_config.test_specific_config.get("cookies", None)
+                    )
+
+                elif test_config.test_type == TestType.SECURITY_TEST:
+                    # Security tests don't need browser sessions, use a placeholder
+                    session = None
+                    test_context.session_id = SECURITY_TEST_NO_SESSION_ID
+
+                else:
+                    session = await self.session_manager.browser_session(test_config.browser_config)
+                    test_context.session_id = session.session_id
+
+                # Get appropriate test runner
+                runner = self.test_runners.get(test_config.test_type)
+                if not runner:
+                    raise ValueError(f"No runner available for test type: {test_config.test_type}")
+
+                # Execute test
+                result = await runner.run_test(
+                    session=session,
+                    test_config=test_config,
+                    llm_config=test_session.llm_config,
+                    target_url=test_session.target_url,
+                )
+
+                # Mark execution outcome according to the returned result status.
+                is_success = result.status == TestStatus.PASSED
+                test_context.complete_execution(
+                    success=is_success, error_message=result.error_message if not is_success else ""
+                )
+                result.start_time = test_context.start_time
+                result.end_time = test_context.end_time
+                result.duration = test_context.duration
+
+                logging.debug(f"Test completed successfully: {test_config.test_name}")
+                return result
+
+            except Exception as e:
+                error_msg = f"Test execution failed: {str(e)}"
+                test_context.complete_execution(success=False, error_message=error_msg)
+
+                # Create failed result
+                result = TestResult(
+                    test_id=test_config.test_id,
+                    test_type=test_config.test_type,
+                    test_name=test_config.test_name,
+                    status=TestStatus.FAILED,
+                    category=get_category_for_test_type(test_config.test_type),
+                    start_time=test_context.start_time,
+                    end_time=test_context.end_time,
+                    duration=test_context.duration,
+                    error_message=error_msg,
+                )
+                return result
+
+            except asyncio.CancelledError:
+                # The task was cancelled (e.g., by cancel_test / KeyboardInterrupt).
+                logging.warning(f"Test cancelled: {test_config.test_name}")
+
+                test_context.complete_execution(success=False, error_message="Test was cancelled")
+
+                cancelled_result = TestResult(
+                    test_id=test_config.test_id,
+                    test_type=test_config.test_type,
+                    test_name=test_config.test_name,
+                    status=TestStatus.CANCELLED,
+                    category=get_category_for_test_type(test_config.test_type),
+                    start_time=test_context.start_time,
+                    end_time=test_context.end_time,
+                    duration=test_context.duration,
+                    error_message="Test was cancelled",
+                )
+
+                return cancelled_result
+
+            finally:
+                # Clean up browser session
+                if test_context.session_id and test_context.session_id != SECURITY_TEST_NO_SESSION_ID:
+                    await self.session_manager.close_session(test_context.session_id)
+
+    def _resolve_test_dependencies(self, tests: List[TestConfiguration]) -> List[List[TestConfiguration]]:
+        """Resolve test dependencies and return execution batches.
+
+        Returns:
+            List of test batches where each batch can run in parallel
+        """
+        # dependencies for login
+        independent_tests = [test for test in tests if not test.dependencies]
+        dependent_tests = [test for test in tests if test.dependencies]
+
+        batches = []
+
+        # First batches: independent tests (split by max_concurrent_tests)
+        if independent_tests:
+            # Split independent tests into batches based on max_concurrent_tests
+            for i in range(0, len(independent_tests), self.max_concurrent_tests):
+                batch = independent_tests[i : i + self.max_concurrent_tests]
+                batches.append(batch)
+
+        # Additional batches for dependent tests (also split by max_concurrent_tests)
+        if dependent_tests:
+            for i in range(0, len(dependent_tests), self.max_concurrent_tests):
+                batch = dependent_tests[i : i + self.max_concurrent_tests]
+                batches.append(batch)
+
+        return batches
+
+    async def cancel_test(self, test_id: str):
+        """Cancel a running test."""
+        if test_id in self.running_tests:
+            task = self.running_tests[test_id]
+            task.cancel()
+            logging.debug(f"Test cancelled: {test_id}")
+
+    async def cancel_all_tests(self):
+        """Cancel all running tests."""
+        for test_id in list(self.running_tests.keys()):
+            await self.cancel_test(test_id)
+
+        await self.session_manager.close_all_sessions()
+        logging.debug("All tests cancelled")
+
+    def get_running_tests(self) -> List[str]:
+        """Get list of currently running test IDs."""
+        return list(self.running_tests.keys())
+
+    def get_test_status(self, test_id: str) -> Optional[TestStatus]:
+        """Get status of a specific test."""
+        if test_id in self.running_tests:
+            return TestStatus.RUNNING
+        elif test_id in self.completed_tests:
+            return self.completed_tests[test_id].status
+        return None
+
+    async def _finalize_session(self, test_session: ParallelTestSession):
+        """Close sessions, aggregate results, and generate reports for the given session.
+
+        This helper consolidates cleanup and report generation logic to avoid duplication
+        across normal completion, cancellation, and error paths.
+        """
+        # Ensure all browser sessions are closed
+        await self.session_manager.close_all_sessions()
+
+        # Aggregate results
+        aggregated_results = await self.result_aggregator.aggregate_results(test_session)
+        test_session.aggregated_results = aggregated_results
+
+        # Generate JSON & HTML reports
+        report_path = await self.result_aggregator.generate_json_report(test_session)
+        test_session.report_path = report_path
+
+        report_dir = os.path.dirname(report_path)
+        html_path = self.result_aggregator.generate_html_report_fully_inlined(
+            test_session, report_dir=report_dir
+        )
+        test_session.html_report_path = html_path
+
+        logging.debug(f"Report generated: {report_path}")
+        logging.debug(f"HTML report generated: {html_path}")
+
+        # Mark session as completed if not already done
+        if test_session.end_time is None:
+            test_session.complete_session()

webqa_agent/executor/parallel_mode.py

@@ -0,0 +1,131 @@
+import logging
+import uuid
+import os
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple, Coroutine
+
+from webqa_agent.browser.config import DEFAULT_CONFIG
+from webqa_agent.data import ParallelTestSession, TestConfiguration, TestType, get_default_test_name
+from webqa_agent.executor import ParallelTestExecutor
+from webqa_agent.utils import Display
+from webqa_agent.utils.get_log import GetLog
+from webqa_agent.utils.log_icon import icon
+
+class ParallelMode:
+    """Parallel test mode - runs tests concurrently with data isolation"""
+
+    def __init__(self, tests: List, max_concurrent_tests: int = 4):
+        self.max_concurrent_tests = max_concurrent_tests
+        self.executor = ParallelTestExecutor(max_concurrent_tests)
+
+    async def run(
+        self,
+        url: str,
+        llm_config: Dict[str, Any],
+        browser_config: Optional[Dict[str, Any]] = None,
+        test_configurations: Optional[List[Dict[str, Any]]] = None,
+        log_cfg: Optional[Dict[str, Any]] = None,
+        report_cfg: Optional[Dict[str, Any]] = None
+    ) -> Tuple[Dict[str, Any], str]:
+        """Run tests in parallel mode with configurable test types.
+
+        Args:
+            url: Target URL to test
+            llm_config: Configuration for language models
+            browser_config: Default browser configuration
+            test_configurations: Custom test configurations for parallel execution
+            log_cfg: Configuration for logger
+            report_cfg: Configuration for report
+
+        Returns:
+            Tuple of (aggregated_results, report_path)
+        """
+        try:
+
+            GetLog.get_log(log_level=log_cfg["level"])
+            Display.init(language=report_cfg["language"])
+            Display.display.start()
+
+            logging.info(f"{icon['rocket']} Starting tests for URL: {url}, parallel mode {self.max_concurrent_tests}")
+
+            # Use default config if none provided
+            if not browser_config:
+                browser_config = DEFAULT_CONFIG.copy()
+
+            # Create test session
+            test_session = ParallelTestSession(session_id=str(uuid.uuid4()), target_url=url, llm_config=llm_config)
+
+            # Use a fresh per-task timestamp for reports and keep logs separate
+            report_ts = datetime.now().strftime("%Y-%m-%d_%H-%M-%S_%f")
+            os.environ["WEBQA_REPORT_TIMESTAMP"] = report_ts
+
+            # Configure tests based on input or legacy test objects
+            if test_configurations:
+                self._configure_tests_from_config(test_session, test_configurations, browser_config, report_cfg)
+
+            # Execute tests in parallel
+            completed_session = await self.executor.execute_parallel_tests(test_session)
+
+            result = completed_session.aggregated_results.get("count", {})
+            
+
+            await Display.display.stop()
+            Display.display.render_summary()
+            # Return results in format compatible with existing code
+            return (
+                completed_session.aggregated_results,
+                completed_session.report_path,
+                completed_session.html_report_path,
+                result,
+            )
+
+        except Exception as e:
+            logging.error(f"Error in parallel mode: {e}")
+            raise
+
+    def _configure_tests_from_config(
+        self,
+        test_session: ParallelTestSession,
+        test_configurations: List[Dict[str, Any]],
+        default_browser_config: Dict[str, Any],
+        report_cfg: Dict[str, Any]
+    ):
+        """Configure tests from provided configuration."""
+        for config in test_configurations:
+            test_type_str = config.get("test_type", "basic_test")
+
+            # Map string to TestType enum
+            test_type = self._map_test_type(test_type_str)
+
+            # Merge browser config
+            browser_config = {**default_browser_config, **config.get("browser_config", {})}
+
+            test_config = TestConfiguration(
+                test_id=str(uuid.uuid4()),
+                test_type=test_type,
+                test_name=get_default_test_name(test_type, report_cfg["language"]),
+                enabled=config.get("enabled", True),
+                browser_config=browser_config,
+                report_config=report_cfg,
+                test_specific_config=config.get("test_specific_config", {}),
+                timeout=config.get("timeout", 300),
+                retry_count=config.get("retry_count", 0),
+                dependencies=config.get("dependencies", []),
+            )
+
+            test_session.add_test_configuration(test_config)
+
+    def _map_test_type(self, test_type_str: str) -> TestType:
+        """Map string to TestType enum."""
+        mapping = {
+            "ui_agent_langgraph": TestType.UI_AGENT_LANGGRAPH,
+            "ux_test": TestType.UX_TEST,
+            "performance": TestType.PERFORMANCE,
+            "basic_test": TestType.BASIC_TEST,
+            # "web_basic_check": TestType.WEB_BASIC_CHECK,
+            # "button_test": TestType.BUTTON_TEST,
+            "security": TestType.SECURITY_TEST,
+            "security_test": TestType.SECURITY_TEST,
+        }
+
+        return mapping.get(test_type_str, TestType.BASIC_TEST)

webqa_agent/executor/result_aggregator.py

@@ -0,0 +1,366 @@
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from webqa_agent.data import ParallelTestSession, TestStatus
+from webqa_agent.llm.llm_api import LLMAPI
+from webqa_agent.utils import i18n
+
+class ResultAggregator:
+    """Aggregates and analyzes parallel test results"""
+    
+    def __init__(self, report_config: dict = None):
+        """Initialize ResultAggregator with language support.
+        
+        Args:
+            report_config: Configuration dictionary containing language settings
+        """
+        self.language = report_config.get("language", "zh-CN") if report_config else "zh-CN"
+        self.localized_strings = {
+            'zh-CN': i18n.get_lang_data('zh-CN').get('aggregator', {}),
+            'en-US': i18n.get_lang_data('en-US').get('aggregator', {}),
+        }
+    
+    def _get_text(self, key: str) -> str:
+        """Get localized text for the given key."""
+        return self.localized_strings.get(self.language, {}).get(key, key)
+    
+    async def aggregate_results(self, test_session: ParallelTestSession) -> Dict[str, Any]:
+        """Aggregate all test results into a comprehensive summary.
+
+        Args:
+            test_session: Session containing all test results
+
+        Returns:
+            Aggregated results dictionary
+        """
+        logging.debug(f"Aggregating results for session: {test_session.session_id}")
+        issues = []
+        error_message = await self._get_error_message(test_session)
+        # Generate issue list (LLM powered when possible)
+        llm_issues = await self._generate_llm_issues(test_session)
+        
+        issues.extend(error_message)
+        issues.extend(llm_issues)
+        logging.info(f"Aggregated {len(test_session.test_results)} test results, found {len(issues)} issues")
+        for test_id, result in test_session.test_results.items():
+            sub_tests_count = len(result.sub_tests or [])
+            logging.debug(f"Test {test_id} has {sub_tests_count} sub_tests")
+            if result.sub_tests:
+                for i, sub_test in enumerate(result.sub_tests):
+                    logging.debug(f"Sub-test {i}: status={sub_test.status}")
+        
+        total_sub_tests = sum(len(r.sub_tests or []) for r in test_session.test_results.values())
+        passed_sub_tests = sum(
+            1
+            for r in test_session.test_results.values()
+            for sub in (r.sub_tests or [])
+            if sub.status == TestStatus.PASSED
+        )
+        critical_sub_tests = total_sub_tests - passed_sub_tests  # 未通过即视为关键问题
+        
+        logging.debug(f"Debug: total_sub_tests={total_sub_tests}, passed_sub_tests={passed_sub_tests}, critical_sub_tests={critical_sub_tests}")
+
+        # Build content for executive summary tab
+        executive_content = {
+            "executiveSummary": "",
+            "statistics": [
+                {"label": self._get_text('assessment_categories'), "value": str(total_sub_tests), "colorClass": "var(--warning-color)"},
+                {"label": self._get_text('passed_count'), "value": str(passed_sub_tests), "colorClass": "var(--success-color)"},
+                {"label": self._get_text('failed_count'), "value": str(critical_sub_tests), "colorClass": "var(--failure-color)"},
+            ]
+        }
+
+        aggregated_results_list = [
+            {"id": "subtab-summary-advice", "title": self._get_text('summary_and_advice'), "content": executive_content},
+            {
+                "id": "subtab-issue-tracker",
+                "title": self._get_text('issue_list'),
+                "content": {
+                    "title": self._get_text('issue_tracker_list'),
+                    "note": self._get_text('issue_list_note'),
+                    "issues": issues,
+                },
+            },
+        ]
+
+        # Store additional raw analysis for LLM etc.
+        raw_analysis = {
+            "session_summary": test_session.get_summary_stats(),
+        }
+
+        def dict_to_text(d, indent=0):
+            lines = []
+            for k, v in d.items():
+                if isinstance(v, dict):
+                    lines.append(" " * indent + f"{k}:")
+                    lines.append(dict_to_text(v, indent + 2))
+                else:
+                    lines.append(" " * indent + f"{k}: {v}")
+            return "\n".join(lines)
+
+        executive_content["executiveSummary"] = f"{dict_to_text(raw_analysis['session_summary'])}"
+
+        # Also expose simple counters at the top-level for easy consumption
+        return {
+            "title": self._get_text('assessment_overview'),
+            "tabs": aggregated_results_list,
+            "count":{
+                "total": total_sub_tests,
+                "passed": passed_sub_tests,
+                "failed": critical_sub_tests,
+            }
+        }
+
+    async def _generate_llm_issues(self, test_session: ParallelTestSession) -> List[Dict[str, Any]]:
+        """Use LLM to summarise issues for each sub-test.
+
+        Fallback to heuristic if LLM unavailable.
+        """
+        llm_config = test_session.llm_config or {}
+        use_llm = bool(llm_config)
+        critical_issues: List[Dict[str, Any]] = []
+
+        # Prepare LLM client if configured
+        llm: Optional[LLMAPI] = None
+        if use_llm:
+            try:
+                llm = LLMAPI(llm_config)
+                await llm.initialize()
+            except Exception as e:
+                logging.error(f"Failed to initialise LLM, falling back to heuristic issue extraction: {e}")
+                use_llm = False
+
+        # Iterate over all tests and their sub-tests
+        for test_result in test_session.test_results.values():
+            for sub in test_result.sub_tests or []:
+                try:
+                    # Determine severity strictly based on sub-test status
+                    if sub.status == TestStatus.PASSED:
+                        continue  # No issue for passed sub-tests
+                    if sub.status == TestStatus.WARNING:
+                        severity_level = "low"
+                    elif sub.status == TestStatus.FAILED:
+                        severity_level = "high"
+                    else:
+                        severity_level = "medium"
+
+                    issue_entry = {
+                        "issue_name": self._get_text('test_failed_prefix') + test_result.test_name, 
+                        "issue_type": test_result.test_type.value,
+                        "sub_test_name": sub.name,
+                        "severity": severity_level,
+                    }
+                    if use_llm and llm:
+                        prompt_content = {
+                            "name": sub.name,
+                            "status": sub.status,
+                            "report": sub.report,
+                            "metrics": sub.metrics,
+                            "final_summary": sub.final_summary,
+                        }
+                        prompt = (
+                            f"{self._get_text('llm_prompt_main')}\n\n"
+                            f"{self._get_text('llm_prompt_test_info')}{json.dumps(prompt_content, ensure_ascii=False, default=str)}"
+                        )
+                        logging.debug(f"LLM Issue Prompt: {prompt}")
+                        llm_response_raw = await llm.get_llm_response("", prompt)
+                        llm_response = llm._clean_response(llm_response_raw)
+                        logging.debug(f"LLM Issue Response: {llm_response}")
+                        try:
+                            parsed = json.loads(llm_response)
+                            issue_count = parsed.get("issue_count", parsed.get("count", 1))
+                            if issue_count == 0:
+                                continue
+                            issue_text = parsed.get("issues", "").strip()
+                            if not issue_text:
+                                continue
+                            llm_severity = parsed.get("severity", severity_level)
+                            issue_entry["severity"] = llm_severity
+                            issue_entry["issues"] = issue_text
+                            issue_entry["issue_count"] = issue_count
+                        except Exception as parse_err:
+                            logging.error(f"Failed to parse LLM JSON: {parse_err}; raw: {llm_response}")
+                            continue  # skip if cannot parse
+                    else:
+                        # Heuristic fallback – use final_summary to detect issue presence
+                        summary_text = (sub.final_summary or "").strip()
+                        if not summary_text:
+                            continue
+                        lowered = summary_text.lower()
+                        if any(k in lowered for k in ["error", "fail", "严重", "错误", "崩溃", "无法"]):
+                            issue_entry["severity"] = "high"
+                        elif any(k in lowered for k in ["warning", "警告", "建议", "优化", "改进"]):
+                            issue_entry["severity"] = "low"
+                        else:
+                            issue_entry["severity"] = "medium"
+                        issue_entry["issues"] = summary_text
+                        issue_entry["issue_count"] = 1
+                    # add populated entry
+                    critical_issues.append(issue_entry)
+                except Exception as e:
+                    logging.error(f"Error while generating issue summary for sub-test {sub.name}: {e}")
+                    continue  # skip problematic sub-test
+        # Close LLM client if needed
+        if use_llm and llm:
+            try:
+                await llm.close()
+            except Exception as e:
+                logging.warning(f"Failed to close LLM client: {e}")
+        return critical_issues
+
+    async def _get_error_message(self, test_session: ParallelTestSession) -> str:
+        """Get error message from test session."""
+        error_message = []
+        for test_result in test_session.test_results.values():
+            if test_result.status != TestStatus.PASSED:
+                # Only append if error_message is not empty
+                if test_result.error_message:
+                    error_message.append({
+                        "issue_name": self._get_text('execution_error_prefix') + test_result.test_name,
+                        "issue_type": test_result.test_type.value,
+                        "severity": "high",
+                        "issues": test_result.error_message
+                    })
+        return error_message
+
+    async def generate_json_report(self, test_session: ParallelTestSession, report_dir: str | None = None) -> str:
+        """Generate comprehensive JSON report."""
+        try:
+            # Determine report directory
+            if report_dir is None:
+                timestamp = os.getenv("WEBQA_REPORT_TIMESTAMP") or os.getenv("WEBQA_TIMESTAMP")
+                report_dir = f"./reports/test_{timestamp}"
+            os.makedirs(report_dir, exist_ok=True)
+
+            json_path = os.path.join(report_dir, "test_results.json")
+            with open(json_path, "w", encoding="utf-8") as f:
+                json.dump(test_session.to_dict(), f, indent=2, ensure_ascii=False, default=str)
+
+            absolute_path = os.path.abspath(json_path)
+            if os.getenv("DOCKER_ENV"):
+                host_path = absolute_path.replace("/app/reports", "./reports")
+                logging.debug(f"JSON report generated: {host_path}")
+                return host_path
+            else:
+                logging.debug(f"JSON report generated: {absolute_path}")
+                return absolute_path
+
+        except Exception as e:
+            logging.error(f"Failed to generate JSON report: {e}")
+            return ""
+
+    def _get_static_dir(self) -> Path:
+        """Resolve the static assets directory in a robust way.
+
+        This uses the source file location of this module instead of the working
+        directory to avoid issues on hosted platforms.
+        """
+        # __file__ → .../webqa_agent/executor/result_aggregator.py
+        # static dir → .../webqa_agent/static
+        executor_dir = Path(__file__).resolve().parent
+        static_dir = (executor_dir.parent / "static").resolve()
+        return static_dir
+
+    def _read_css_content(self) -> str:
+        """Read and return CSS content."""
+        try:
+            css_path = self._get_static_dir() / "assets" / "style.css"
+            if css_path.exists():
+                return css_path.read_text(encoding="utf-8")
+        except Exception as e:
+            logging.warning(f"Failed to read CSS file: {e}")
+        return ""
+
+    def _read_js_content(self) -> str:
+        """Read and return JavaScript content based on language."""
+        try:
+            # Choose JS file based on language
+            if self.language == "en-US":
+                js_filename = "index_en-US.js"
+            else:
+                js_filename = "index.js"  # Default to Chinese version
+                
+            js_path = self._get_static_dir() / "assets" / js_filename
+            if js_path.exists():
+                return js_path.read_text(encoding="utf-8")
+            else:
+                # Fallback to default file if language-specific file doesn't exist
+                fallback_path = self._get_static_dir() / "assets" / "index.js"
+                if fallback_path.exists():
+                    logging.warning(f"Language-specific JS file {js_filename} not found, using fallback")
+                    return fallback_path.read_text(encoding="utf-8")
+        except Exception as e:
+            logging.warning(f"Failed to read JS file: {e}")
+        return ""
+
+    def generate_html_report_fully_inlined(self, test_session, report_dir: str | None = None) -> str:
+        """Generate a fully inlined HTML report for the test session."""
+        import re
+        import json
+        import re
+
+        try:
+            template_file = self._get_static_dir() / "index.html"
+
+            template_found = template_file.exists()
+            if template_found:
+                html_template = template_file.read_text(encoding="utf-8")
+            else:
+                logging.warning(
+                    f"Report template not found at {template_file}. Falling back to minimal inline template."
+                )
+
+            datajs_content = (
+                "window.testResultData = " + json.dumps(test_session.to_dict(), ensure_ascii=False, default=str) + ";"
+            )
+
+            if template_found:
+                css_content = self._read_css_content()
+                js_content = self._read_js_content()
+
+                html_out = html_template
+                html_out = re.sub(
+                    r'<link\s+rel="stylesheet"\s+href="/assets/style.css"\s*>',
+                    lambda m: f"<style>\n{css_content}\n</style>",
+                    html_out,
+                )
+                html_out = re.sub(
+                    r'<script\s+src="/data.js"\s*>\s*</script>',
+                    lambda m: f"<script>\n{datajs_content}\n</script>",
+                    html_out,
+                )
+                html_out = re.sub(
+                    r'<script\s+type="module"\s+crossorigin\s+src="/assets/index.js"\s*>\s*</script>',
+                    lambda m: f'<script type="module">\n{js_content}\n</script>',
+                    html_out,
+                )
+
+            if report_dir is None:
+                timestamp = os.getenv("WEBQA_REPORT_TIMESTAMP") or os.getenv("WEBQA_TIMESTAMP")
+                report_dir = f"./reports/test_{timestamp}"
+            # Ensure report dir exists; if creation fails, fallback to tmp
+            try:
+                os.makedirs(report_dir, exist_ok=True)
+                report_dir_path = Path(report_dir).resolve()
+            except Exception as mk_err:
+                logging.warning(f"Cannot create report dir '{report_dir}': {mk_err}. Falling back to /tmp/webqa-reports.")
+                report_dir_path = Path("/tmp/webqa-reports").resolve()
+                report_dir_path.mkdir(parents=True, exist_ok=True)
+
+            html_path = report_dir_path / "test_report.html"
+            html_path.write_text(html_out, encoding="utf-8")
+
+            absolute_path = str(html_path)
+            if os.getenv("DOCKER_ENV"):
+                mapped = absolute_path.replace("/app/reports", "./reports")
+                logging.debug(f"HTML report generated: {mapped}")
+                return mapped
+            else:
+                logging.debug(f"HTML report generated: {absolute_path}")
+                return absolute_path
+        except Exception as e:
+            logging.error(f"Failed to generate fully inlined HTML report: {e}")
+            return ""

webqa_agent/executor/test_runners.py

@@ -0,0 +1,888 @@
+import asyncio
+import json
+import logging
+import time
+from abc import ABC, abstractmethod
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List
+
+from webqa_agent.browser.session import BrowserSession
+from webqa_agent.data import TestConfiguration, TestResult, TestStatus
+from webqa_agent.data.test_structures import (SubTestReport, SubTestResult,
+                                              get_category_for_test_type)
+from webqa_agent.testers import (LighthouseMetricsTest, PageButtonTest,
+                                 PageContentTest, PageTextTest,
+                                 WebAccessibilityTest)
+from webqa_agent.utils import Display
+from webqa_agent.utils.log_icon import icon
+from webqa_agent.utils import i18n
+
+
+class BaseTestRunner(ABC):
+    """Base class for test runners."""
+
+    @abstractmethod
+    async def run_test(
+        self, session: BrowserSession, test_config: TestConfiguration, llm_config: Dict[str, Any], target_url: str
+    ) -> TestResult:
+        """Run the test and return results."""
+        pass
+
+
+class UIAgentLangGraphRunner(BaseTestRunner):
+    """Runner for UIAgent LangGraph tests."""
+
+    async def run_test(
+        self, session: BrowserSession, test_config: TestConfiguration, llm_config: Dict[str, Any], target_url: str
+    ) -> TestResult:
+        """Run UIAgent LangGraph test using LangGraph workflow with
+        ParallelUITester."""
+
+        with Display.display(test_config.test_name):
+            from webqa_agent.testers.case_gen.graph import app as graph_app
+            from webqa_agent.testers.function_tester import UITester
+
+            result = TestResult(
+                test_id=test_config.test_id,
+                test_type=test_config.test_type,
+                test_name=test_config.test_name,
+                status=TestStatus.RUNNING,
+                category=get_category_for_test_type(test_config.test_type),
+            )
+
+            parallel_tester: UITester | None = None
+            try:
+                parallel_tester = UITester(llm_config=llm_config, browser_session=session)
+                await parallel_tester.initialize()
+
+                business_objectives = test_config.test_specific_config.get('business_objectives', '')
+                logging.info(f"{icon['running']} Running test: {test_config.test_name} with business objectives: {business_objectives}")
+
+                cookies = test_config.test_specific_config.get('cookies')
+
+                initial_state = {
+                    'url': target_url,
+                    'business_objectives': business_objectives,
+                    'cookies': cookies,
+                    'completed_cases': [],
+                    'reflection_history': [],
+                    'remaining_objectives': business_objectives,
+                    'ui_tester_instance': parallel_tester,
+                    'current_test_case_index': 0,
+                    'language': test_config.report_config.get('language', 'zh-CN'),
+                }
+
+                graph_config = {'configurable': {'ui_tester_instance': parallel_tester}, 'recursion_limit': 100}
+
+                # Mapping from case name to status obtained from LangGraph aggregate_results
+                graph_case_status_map: Dict[str, str] = {}
+
+                # 执行LangGraph工作流
+                graph_completed = False
+                async for event in graph_app.astream(initial_state, config=graph_config):
+                    # Each event is a dict where keys are node names and values are their outputs
+                    for node_name, node_output in event.items():
+                        if node_name == 'aggregate_results':
+                            # Capture final report to retrieve authoritative case statuses
+                            final_report = node_output.get('final_report', {})
+                            for idx, case_res in enumerate(final_report.get('completed_summary', [])):
+                                case_name = case_res.get('case_name') or case_res.get('name') or f'Case_{idx + 1}'
+                                graph_case_status_map[case_name] = case_res.get('status', 'failed').lower()
+
+                        if node_name == '__end__':
+                            logging.debug('Graph execution completed successfully')
+                            graph_completed = True
+                            break
+                        else:
+                            logging.debug(f"Node '{node_name}' completed")
+
+                    # Break out of the outer loop if we found __end__
+                    if graph_completed:
+                        break
+
+                # === 使用UITester的新数据存储机制 ===
+                sub_tests = []
+                runner_format_report = {}
+
+                if parallel_tester:
+                    # 生成符合runner标准格式的完整报告
+                    test_name = f'UI Agent Test - {target_url}'
+                    runner_format_report = parallel_tester.generate_runner_format_report(
+                        test_id=test_config.test_id, test_name=test_name
+                    )
+
+                    sub_tests_data = runner_format_report.get('sub_tests', [])
+                    logging.debug(f'Generated runner format report with {len(sub_tests_data)} cases')
+
+                    if not sub_tests_data:
+                        logging.warning('No sub_tests data found in runner format report')
+
+                    # 将runner格式的sub_tests转换为TestResult.SubTestResult
+                    for i, case in enumerate(sub_tests_data):
+                        case_name = case.get('name', f"Unnamed test case - {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+                        case_steps = case.get('steps', [])
+
+                        # 验证case数据完整性
+                        logging.debug(f"Processing case {i + 1}: '{case_name}' with {len(case_steps)} steps")
+                        if not case_steps:
+                            logging.warning(f"Case '{case_name}' has no steps data")
+
+                        # Prefer status from graph aggregation if available
+                        sub_status = graph_case_status_map.get(case_name, case.get('status', 'failed')).lower()
+                        status_mapping = {
+                            'pending': TestStatus.PENDING,
+                            'running': TestStatus.RUNNING,
+                            'passed': TestStatus.PASSED,
+                            'completed': TestStatus.WARNING,
+                            'failed': TestStatus.FAILED,
+                            'cancelled': TestStatus.CANCELLED,
+                        }
+                        status_enum = status_mapping.get(sub_status, TestStatus.FAILED)
+
+                        sub_tests.append(
+                            SubTestResult(
+                                name=case_name,
+                                status=status_enum,
+                                metrics={},
+                                steps=case_steps,
+                                messages=case.get('messages', {}),
+                                start_time=case.get('start_time'),
+                                end_time=case.get('end_time'),
+                                final_summary=case.get('final_summary', ''),
+                                report=case.get('report', []),
+                            )
+                        )
+
+                    result.sub_tests = sub_tests
+
+                    # 从runner格式报告提取汇总指标
+                    results_data = runner_format_report.get('results', {})
+                    result.add_metric('test_case_count', results_data.get('total_cases', 0))
+                    result.add_metric('passed_test_cases', results_data.get('passed_cases', 0))
+                    result.add_metric('failed_test_cases', results_data.get('failed_cases', 0))
+                    result.add_metric('total_steps', results_data.get('total_steps', 0))
+                    result.add_metric('success_rate', results_data.get('success_rate', 0))
+
+                    # 从每个case的messages中提取网络和控制台数据并汇总
+                    total_failed_requests = 0
+                    total_requests = 0
+                    total_console_errors = 0
+
+                    for case in runner_format_report.get('sub_tests', []):
+                        case_messages = case.get('messages', {})
+                        if isinstance(case_messages, dict):
+                            network_data = case_messages.get('network', {})
+                            if isinstance(network_data, dict):
+                                failed_requests = network_data.get('failed_requests', [])
+                                responses = network_data.get('responses', [])
+                                total_failed_requests += len(failed_requests)
+                                total_requests += len(responses)
+
+                            console_data = case_messages.get('console', [])
+                            if isinstance(console_data, list):
+                                total_console_errors += len(console_data)
+
+                    result.add_metric('network_failed_requests_count', total_failed_requests)
+                    result.add_metric('network_total_requests_count', total_requests)
+                    result.add_metric('console_error_count', total_console_errors)
+
+                    # 设置整体状态
+                    runner_status = runner_format_report.get('status', 'failed')
+                    if runner_status == 'completed':
+                        result.status = TestStatus.PASSED
+                    else:
+                        result.status = TestStatus.FAILED
+                        result.error_message = runner_format_report.get('error_message', 'Test execution failed')
+
+                else:
+                    logging.error('No UITester instance available for data extraction')
+                    result.status = TestStatus.FAILED
+                    result.error_message = 'No test cases were executed or results were not available'
+
+                logging.info(f"{icon['check']} Test completed: {test_config.test_name}")
+
+            except Exception as e:
+                error_msg = f'AI Functional Test failed: {str(e)}'
+                result.status = TestStatus.FAILED
+                result.error_message = error_msg
+                logging.error(error_msg)
+                raise
+
+            finally:
+                # Cleanup parallel tester
+                if parallel_tester:
+                    try:
+                        # UITester现在已经自动管理监控数据，只需要清理资源
+                        await parallel_tester.cleanup()
+                        logging.debug('UITester cleanup completed')
+                    except Exception as e:
+                        logging.error(f'Error cleaning up UITester: {e}')
+
+            return result
+
+
+class UXTestRunner(BaseTestRunner):
+    """Runner for UX tests using parallel-friendly test classes without GetLog
+    dependencies."""
+
+    async def run_test(
+        self, session: BrowserSession, test_config: TestConfiguration, llm_config: Dict[str, Any], target_url: str
+    ) -> TestResult:
+        """Run UX tests with enhanced screenshot and data collection."""
+
+        with Display.display(test_config.test_name):
+            result = TestResult(
+                test_id=test_config.test_id,
+                test_type=test_config.test_type,
+                test_name=test_config.test_name,
+                status=TestStatus.RUNNING,
+                category=get_category_for_test_type(test_config.test_type),
+            )
+
+            try:
+                logging.info(f"{icon['running']} Running UX test: {test_config.test_name}")
+                page = session.get_page()
+
+                text_test = PageTextTest(llm_config, report_config=test_config.report_config)
+                text_result: SubTestResult = await text_test.run(page=page)
+
+                # Run ParallelPageContentTest
+                content_test = PageContentTest(llm_config, report_config=test_config.report_config)
+                content_results: List[SubTestResult] = await content_test.run(page=page)
+
+                result.sub_tests = content_results + [text_result]
+
+                # Extract metrics
+                content_statuses = [r.status for r in content_results]
+                text_status = text_result.status
+
+                # Determine overall status
+                if text_status == 'passed' and all(status == 'passed' for status in content_statuses):
+                    result.status = TestStatus.PASSED
+                else:
+                    result.status = TestStatus.FAILED
+
+                    # Collect errors from all tests
+                    all_results = content_results + [text_result]
+                    errors = [r.messages['page'] for r in all_results if 'page' in r.messages]
+
+                    if errors:
+                        result.error_message = '; '.join(errors)
+
+                logging.info(f"{icon['check']} Test completed: {test_config.test_name}")
+
+            except Exception as e:
+                error_msg = f'UX test failed: {str(e)}'
+                result.status = TestStatus.FAILED
+                result.error_message = error_msg
+                logging.error(error_msg)
+                raise
+
+            return result
+
+
+class LighthouseTestRunner(BaseTestRunner):
+    """Runner for Lighthouse."""
+
+    async def run_test(
+        self, session: BrowserSession, test_config: TestConfiguration, llm_config: Dict[str, Any], target_url: str
+    ) -> TestResult:
+        """Run Lighthouse tests."""
+
+        with Display.display(test_config.test_name):
+            result = TestResult(
+                test_id=test_config.test_id,
+                test_type=test_config.test_type,
+                test_name=test_config.test_name,
+                status=TestStatus.RUNNING,
+                category=get_category_for_test_type(test_config.test_type),
+            )
+
+            try:
+                logging.info(f"{icon['running']} Running test: {test_config.test_name}")
+                browser_config = session.browser_config
+
+                # Only run Lighthouse on Chromium browsers
+                if browser_config.get('browser_type') != 'chromium':
+                    logging.warning('Lighthouse tests require Chromium browser, skipping')
+                    result.status = TestStatus.INCOMPLETED
+                    result.results = {'skipped': 'Lighthouse requires Chromium browser'}
+                    return result
+
+                # Run Lighthouse test
+                lighthouse_test = LighthouseMetricsTest(report_config=test_config.report_config)
+                lighthouse_results: SubTestResult = await lighthouse_test.run(target_url, browser_config=browser_config)
+
+                result.sub_tests = [lighthouse_results]
+                result.status = lighthouse_results.status
+                logging.info(f"{icon['check']} Test completed: {test_config.test_name}")
+
+            except Exception as e:
+                error_msg = f'Lighthouse test failed: {str(e)}'
+                result.status = TestStatus.FAILED
+                result.error_message = error_msg
+                logging.error(error_msg)
+                raise
+
+            return result
+
+
+class BasicTestRunner(BaseTestRunner):
+    """Runner for Traversal tests."""
+
+    async def run_test(
+        self, session: BrowserSession, test_config: TestConfiguration, llm_config: Dict[str, Any], target_url: str
+    ) -> TestResult:
+        """Run UX tests with enhanced screenshot and data collection."""
+
+        with Display.display(test_config.test_name):
+            result = TestResult(
+                test_id=test_config.test_id,
+                test_type=test_config.test_type,
+                test_name=test_config.test_name,
+                status=TestStatus.RUNNING,
+                category=get_category_for_test_type(test_config.test_type),
+            )
+
+            try:
+                logging.info(f"{icon['running']} Running test: {test_config.test_name}")
+                page = session.get_page()
+                browser_config = session.browser_config
+
+                # Discover clickable elements via crawler
+                from webqa_agent.crawler.crawl import CrawlHandler
+
+                crawler = CrawlHandler(target_url)
+                clickable_elements = await crawler.clickable_elements_detection(page)
+                logging.info(f'Crawled {len(clickable_elements)} clickable elements')
+                if len(clickable_elements) > 50:
+                    from itertools import islice
+                    clickable_elements = dict(islice(clickable_elements.items(), 50))
+                    logging.warning(f'Clickable elements number is too large, only keep the first 50')
+
+                button_test = PageButtonTest(report_config=test_config.report_config)
+                button_test_result = await button_test.run(
+                    target_url, page=page, clickable_elements=clickable_elements, browser_config=browser_config
+                )
+
+                crawler = CrawlHandler(target_url)
+                links = await crawler.extract_links(page)
+                logging.info(f'Crawled {len(links)} links')
+                # WebAccessibilityTest
+                accessibility_test = WebAccessibilityTest(report_config=test_config.report_config)
+                accessibility_result = await accessibility_test.run(target_url, links)
+
+
+                # Combine test results into a list
+                result.sub_tests = [button_test_result, accessibility_result]
+
+                # Extract metrics
+                button_status = button_test_result.status if button_test_result else TestStatus.FAILED
+                accessibility_status = accessibility_result.status if accessibility_result else TestStatus.FAILED
+
+                # Determine overall status
+                if button_status == TestStatus.PASSED and accessibility_status == TestStatus.PASSED:
+                    result.status = TestStatus.PASSED
+                else:
+                    result.status = TestStatus.FAILED
+
+                    # Collect errors from all tests
+                    all_results = [button_test_result, accessibility_result]
+                    errors = [r.messages.get('page') for r in all_results if r and r.messages and 'page' in r.messages]
+
+                    if errors:
+                        result.error_message = '; '.join(errors)
+
+                logging.info(f"{icon['check']} Test completed: {test_config.test_name}")
+
+            except Exception as e:
+                error_msg = f'Button test failed: {str(e)}'
+                result.status = TestStatus.FAILED
+                result.error_message = error_msg
+                logging.error(error_msg)
+                raise
+
+            return result
+
+# class ButtonTestRunner(BaseTestRunner):
+#     """Runner dedicated to button click tests."""
+
+#     async def run_test(
+#         self, session: BrowserSession, test_config: TestConfiguration, llm_config: Dict[str, Any], target_url: str
+#     ) -> TestResult:
+#         """Run Button test."""
+
+#         with Display.display(test_config.test_name):
+#             result = TestResult(
+#                 test_id=test_config.test_id,
+#                 test_type=test_config.test_type,
+#                 test_name=test_config.test_name,
+#                 status=TestStatus.RUNNING,
+#                 category=get_category_for_test_type(test_config.test_type),
+#             )
+
+#             try:
+#                 logging.info(f"{icon['running']} Running test: {test_config.test_name}")
+#                 page = session.get_page()
+#                 browser_config = session.browser_config
+
+#                 # Discover clickable elements via crawler
+#                 from webqa_agent.crawler.crawl import CrawlHandler
+
+#                 crawler = CrawlHandler(target_url)
+#                 clickable_elements = await crawler.clickable_elements_detection(page)
+#                 logging.info(f'Crawled {len(clickable_elements)} clickable elements')
+#                 if len(clickable_elements) > 50:
+#                     from itertools import islice
+#                     clickable_elements = dict(islice(clickable_elements.items(), 50))
+#                     logging.warning(f'Clickable elements number is too large, only keep the first 50')
+
+#                 button_test = PageButtonTest()
+#                 button_test_result = await button_test.run(
+#                     target_url, page=page, clickable_elements=clickable_elements, browser_config=browser_config
+#                 )
+
+#                 # Second subtest: each clickable result? keep detailed reports if needed; here we only include traverse test
+#                 result.sub_tests = [button_test_result]
+
+#                 # Overall metrics/status
+#                 result.status = button_test_result.status
+
+#                 logging.info(f"{icon['check']} Test completed: {test_config.test_name}")
+
+#             except Exception as e:
+#                 error_msg = f'Button test failed: {str(e)}'
+#                 result.status = TestStatus.FAILED
+#                 result.error_message = error_msg
+#                 logging.error(error_msg)
+#                 raise
+
+#             return result
+
+
+# class WebBasicCheckRunner(BaseTestRunner):
+#     """Runner for Web Basic Check tests."""
+
+#     async def run_test(
+#         self, session: BrowserSession, test_config: TestConfiguration, llm_config: Dict[str, Any], target_url: str
+#     ) -> TestResult:
+#         """Run Web Basic Check tests."""
+
+#         with Display.display(test_config.test_name):
+#             result = TestResult(
+#                 test_id=test_config.test_id,
+#                 test_type=test_config.test_type,
+#                 test_name=test_config.test_name,
+#                 status=TestStatus.RUNNING,
+#                 category=get_category_for_test_type(test_config.test_type),
+#             )
+
+#             try:
+#                 logging.info(f"{icon['running']} Running test: {test_config.test_name}")
+#                 page = session.get_page()
+
+#                 # Discover page elements
+#                 from webqa_agent.crawler.crawl import CrawlHandler
+
+#                 crawler = CrawlHandler(target_url)
+#                 links = await crawler.extract_links(page)
+#                 logging.info(f'Crawled {len(links)} links')
+#                 # WebAccessibilityTest
+#                 accessibility_test = WebAccessibilityTest(self.llm_config, report_config=self.report_config)
+#                 accessibility_result = await accessibility_test.run(target_url, links)
+
+#                 result.sub_tests = [accessibility_result]
+#                 result.status = accessibility_result.status
+#                 logging.info(f"{icon['check']} Test completed: {test_config.test_name}")
+
+#             except Exception as e:
+#                 error_msg = f'Web Basic Check test failed: {str(e)}'
+#                 result.status = TestStatus.FAILED
+#                 result.error_message = error_msg
+#                 logging.error(error_msg)
+#                 raise
+
+#             return result
+
+class SecurityTestRunner(BaseTestRunner):
+    """Runner for Security tests using Nuclei-based scanning."""
+
+    def __init__(self):
+        super().__init__()
+        self.language = 'zh-CN'  # Default language
+        self.localized_strings = {
+            'zh-CN': i18n.get_lang_data('zh-CN').get('testers', {}).get('security', {}),
+            'en-US': i18n.get_lang_data('en-US').get('testers', {}).get('security', {}),
+        }
+
+    def _get_text(self, key: str) -> str:
+        """Get localized text for the current language."""
+        return self.localized_strings.get(self.language, {}).get(key, key)
+    
+    def get_scan_tags(self, language: str) -> Dict[str, str]:
+        """Get scan tags with localized descriptions."""
+        return {
+            'cve': self._get_text('cve_scan'),
+            'xss': self._get_text('xss_scan'),
+            'sqli': self._get_text('sqli_scan'),
+            'rce': self._get_text('rce_scan'),
+            'lfi': self._get_text('lfi_scan'),
+            'ssrf': self._get_text('ssrf_scan'),
+            'redirect': self._get_text('redirect_scan'),
+            'exposure': self._get_text('exposure_scan'),
+            'config': self._get_text('config_scan'),
+            'default-login': self._get_text('default_login_scan'),
+            'ssl': self._get_text('ssl_scan'),
+            'dns': self._get_text('dns_scan'),
+            'subdomain-takeover': self._get_text('subdomain_takeover_scan'),
+            'tech': self._get_text('tech_scan'),
+            'panel': self._get_text('panel_scan'),
+        }
+
+    def get_protocol_scans(self, language: str) -> Dict[str, str]:
+        """Get protocol scans with localized descriptions."""
+        return {
+            'http': self._get_text('http_protocol'),
+            'dns': self._get_text('dns_protocol'),
+            'tcp': self._get_text('tcp_protocol'),
+            'ssl': self._get_text('ssl_protocol'),
+        }
+
+    async def run_test(
+        self, session: BrowserSession, test_config: TestConfiguration, llm_config: Dict[str, Any], target_url: str
+    ) -> TestResult:
+        """Run Security tests using Nuclei scanning."""
+
+        self.language = test_config.report_config.get('language', 'zh-CN')
+        with Display.display(test_config.test_name):
+            result = TestResult(
+                test_id=test_config.test_id,
+                test_type=test_config.test_type,
+                test_name=test_config.test_name,
+                status=TestStatus.RUNNING,
+                category=get_category_for_test_type(test_config.test_type),
+            )
+
+            try:
+                # 安全测试不需要浏览器会话，使用Nuclei进行独立扫描
+                logging.info(f"{icon['running']} Running test: {test_config.test_name}")
+
+                # 检查nuclei是否安装
+                nuclei_available = await self._check_nuclei_available()
+
+                if not nuclei_available:
+                    result.status = TestStatus.FAILED
+                    result.error_message = self._get_text('nuclei_not_found')
+                    return result
+
+                # 执行安全扫描
+                scan_results = await self._run_security_scan(target_url, test_config)
+
+                # 处理扫描结果
+                findings = await self._process_scan_results(scan_results)
+
+                # 生成子测试结果
+                sub_tests = []
+
+                # 按严重程度分类结果
+                severity_counts = {}
+                finding_details = []
+
+                for finding in findings:
+                    severity = finding.get('info', {}).get('severity', 'unknown')
+                    severity_counts[severity] = severity_counts.get(severity, 0) + 1
+                    finding_details.append(
+                        {
+                            'template_id': finding.get('template-id', 'unknown'),
+                            'name': finding.get('info', {}).get('name', 'Unknown'),
+                            'severity': severity,
+                            'description': finding.get('info', {}).get('description', ''),
+                            'matched_at': finding.get('matched-at', ''),
+                            'extracted_results': finding.get('extracted-results', []),
+                        }
+                    )
+
+                # 创建按严重程度的子测试
+                for severity in ['critical', 'high', 'medium', 'low', 'info']:
+                    count = severity_counts.get(severity, 0)
+
+                    # 获取该严重程度的具体发现
+                    severity_findings = [f for f in finding_details if f.get('severity') == severity]
+
+                    # 构建报告内容
+                    if count == 0:
+                        issues_text = self._get_text('no_severity_issues').format(severity=severity.upper())
+                    else:
+                        # 取前3个问题的名称作为示例
+                        sample_issues = [f['name'] for f in severity_findings[:3]]
+                        issues_text = self._get_text('found_severity_issues').format(count=count, severity=severity.upper())
+                        if sample_issues:
+                            issues_text += f": {', '.join(sample_issues)}"
+                            if count > 3:
+                                issues_text += f" {self._get_text('and_more')}"
+
+                    sub_tests.append(
+                        SubTestResult(
+                            name=self._get_text('severity_level_scan').format(severity=severity.upper()),
+                            status=TestStatus.PASSED,
+                            metrics={'findings_count': count},
+                            report=[SubTestReport(
+                                title=self._get_text('severity_level_vulnerability').format(severity=severity.upper()),
+                                issues=issues_text
+                            )],
+                        )
+                    )
+
+                # 创建扫描类型的子测试
+                scan_tags = self.get_scan_tags(self.language)
+                protocol_scans = self.get_protocol_scans(self.language)
+                for scan_type, description in {**scan_tags, **protocol_scans}.items():
+                    type_findings = [f for f in finding_details if scan_type in f.get('template_id', '').lower()]
+                    type_count = len(type_findings)
+
+                    # 构建扫描类型报告内容
+                    if type_count == 0:
+                        issues_text = f"{description}: {self._get_text('no_security_issues')}"
+                    else:
+                        # 按严重程度统计该类型的发现
+                        type_severity_counts = {}
+                        for finding in type_findings:
+                            severity = finding.get('severity', 'unknown')
+                            type_severity_counts[severity] = type_severity_counts.get(severity, 0) + 1
+
+                        severity_summary = []
+                        for sev in ['critical', 'high', 'medium', 'low', 'info']:
+                            if type_severity_counts.get(sev, 0) > 0:
+                                severity_summary.append(f"{sev.upper()} {i18n.t(self.language, 'common.level', 'level')} {type_severity_counts[sev]} {i18n.t(self.language, 'common.issues', 'issues')}")
+
+                        issues_text = f"{description}: {self._get_text('found_issues').format(count=type_count)}"
+                        if severity_summary:
+                            issues_text += f" ({', '.join(severity_summary)})"
+
+                        # 添加具体问题示例（最多3个）
+                        if type_findings:
+                            sample_names = [f['name'] for f in type_findings[:2]]
+                            if sample_names:
+                                issues_text += f", {self._get_text('including')}: {', '.join(sample_names)}"
+                                if type_count > 2:
+                                    issues_text += f" {self._get_text('and_more')}"
+
+                    combined_reports = []
+                    if not finding_details:
+                        # No security issues found
+                        combined_reports.append(SubTestReport(
+                            title=self._get_text('security_check'),
+                            issues=self._get_text('no_issues_found')
+                        ))
+                    else:
+                        for fd in finding_details:
+                            title = f"[{fd.get('severity', 'unknown').upper()}] {fd.get('name')}"
+                            details_parts = []
+                            if fd.get('description'):
+                                details_parts.append(fd['description'])
+                            if fd.get('matched_at'):
+                                details_parts.append(f"{self._get_text('matched_at')}: {fd['matched_at']}")
+                            if fd.get('extracted_results'):
+                                details_parts.append(f"{self._get_text('extracted')}: {', '.join(map(str, fd['extracted_results']))}")
+                            issues_text = ' | '.join(details_parts) if details_parts else self._get_text('no_details')
+                            combined_reports.append(SubTestReport(title=title, issues=issues_text))
+
+                    sub_tests = [
+                        SubTestResult(
+                            name=self._get_text('nuclei_check'),
+                            status=TestStatus.PASSED,
+                            metrics={
+                                'total_findings': len(finding_details),
+                                **severity_counts
+                            },
+                            report=combined_reports
+                        )
+                    ]
+
+                    result.sub_tests = sub_tests
+                result.status = TestStatus.PASSED
+
+                # 添加总体指标
+                total_findings = len(findings)
+                critical_findings = severity_counts.get('critical', 0)
+                high_findings = severity_counts.get('high', 0)
+
+                result.add_metric('total_findings', total_findings)
+                result.add_metric('critical_findings', critical_findings)
+                result.add_metric('high_findings', high_findings)
+                result.add_metric('security_score', max(0, 100 - (critical_findings * 20 + high_findings * 10)))
+
+                # 添加详细结果
+                result.add_data('security_findings', finding_details)
+                result.add_data('severity_summary', severity_counts)
+
+                # 清理临时文件
+                await self._cleanup_temp_files(scan_results.get('output_path'))
+
+                logging.info(f"{icon['check']} Test completed: {test_config.test_name}")
+
+            except Exception as e:
+                error_msg = f'Security test failed: {str(e)}'
+                logging.error(error_msg)
+                result.status = TestStatus.FAILED
+                result.error_message = error_msg
+
+                # 即使失败也要清理临时文件
+                try:
+                    scan_results = locals().get('scan_results', {})
+                    await self._cleanup_temp_files(scan_results.get('output_path'))
+                except:
+                    pass
+
+            return result
+
+    async def _check_nuclei_available(self) -> bool:
+        """检查nuclei工具是否可用."""
+        try:
+            process = await asyncio.create_subprocess_exec(
+                'nuclei', '-version', stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+            )
+            stdout, stderr = await process.communicate()
+            logging.debug(f'Nuclei check - return code: {process.returncode}')
+            logging.debug(f'Nuclei check - stdout: {stdout.decode()}')
+            logging.debug(f'Nuclei check - stderr: {stderr.decode()}')
+            return process.returncode == 0
+        except Exception as e:
+            logging.error(f'Error checking nuclei availability: {e}')
+            return False
+
+    async def _run_security_scan(self, target_url: str, test_config: TestConfiguration) -> Dict[str, Any]:
+        """执行安全扫描."""
+        # 创建临时输出目录，使用测试ID确保唯一性
+        import tempfile
+
+        temp_dir = Path(tempfile.gettempdir()) / 'webqa_agent_security' / test_config.test_id
+        temp_dir.mkdir(parents=True, exist_ok=True)
+
+        # 配置扫描任务
+        scan_configs = {'tag': self.get_scan_tags(self.language), 'protocol': self.get_protocol_scans(self.language)}
+
+        # 从测试配置中获取自定义参数
+        custom_config = test_config.test_specific_config or {}
+        include_severity_scans = custom_config.get('include_severity_scans', True)
+
+        if include_severity_scans:
+            scan_configs['severity'] = {
+                'critical': self._get_text('critical_vulnerability'),
+                'high': self._get_text('high_risk_vulnerability'),
+                'medium': self._get_text('medium_risk_vulnerability')
+            }
+
+        # 执行并行扫描
+        scan_results = await self._execute_scan_batch(target_url, scan_configs, temp_dir)
+
+        return {'scan_results': scan_results, 'output_path': str(temp_dir)}
+
+    async def _execute_scan_batch(self, target_url: str, scan_configs: Dict[str, Dict], output_path: Path) -> list:
+        """并行执行一批安全扫描."""
+        tasks = []
+
+        # 创建扫描任务
+        for scan_type, scans in scan_configs.items():
+            for scan_name, description in scans.items():
+                output_file = output_path / f'{scan_type}_{scan_name}_{int(time.time())}.json'
+                task = self._run_nuclei_command(target_url, scan_type, scan_name, output_file)
+                tasks.append(task)
+
+        # 并行执行所有扫描
+        logging.info(f'Start {len(tasks)} security scan tasks...')
+        scan_results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        # 处理结果
+        results = []
+        for result in scan_results:
+            if isinstance(result, Exception):
+                logging.error(f'Scan task failed: {result}')
+                continue
+            results.append(result)
+
+        return results
+
+    async def _run_nuclei_command(
+        self, target_url: str, scan_type: str, scan_name: str, output_file: Path
+    ) -> Dict[str, Any]:
+        """运行单个Nuclei扫描命令."""
+        cmd = ['nuclei', '-target', target_url, '-json-export', str(output_file), '-silent']
+
+        # 根据扫描类型添加参数
+        if scan_type == 'tag':
+            cmd.extend(['-tags', scan_name])
+        elif scan_type == 'protocol':
+            cmd.extend(['-type', scan_name])
+        elif scan_type == 'severity':
+            cmd.extend(['-severity', scan_name])
+
+        try:
+            process = await asyncio.create_subprocess_exec(
+                *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+            )
+
+            stdout, stderr = await process.communicate()
+
+            return {
+                'scan_name': scan_name,
+                'scan_type': scan_type,
+                'stdout': stdout.decode() if stdout else '',
+                'stderr': stderr.decode() if stderr else '',
+                'returncode': process.returncode,
+                'output_file': str(output_file),
+            }
+        except Exception as e:
+            return {
+                'scan_name': scan_name,
+                'scan_type': scan_type,
+                'stdout': '',
+                'stderr': str(e),
+                'returncode': 1,
+                'output_file': str(output_file),
+            }
+
+    async def _process_scan_results(self, scan_results: Dict[str, Any]) -> list:
+        """读取并合并所有扫描结果."""
+        all_results = []
+        output_path = Path(scan_results['output_path'])
+        json_files = list(output_path.glob('*.json'))
+
+        for json_file in json_files:
+            try:
+                with open(json_file, 'r', encoding='utf-8') as f:
+                    content = f.read().strip()
+                    if content:
+                        # 处理JSONL格式（每行一个JSON对象）
+                        for line in content.split('\n'):
+                            if line.strip():
+                                try:
+                                    result = json.loads(line)
+                                    if isinstance(result, dict):
+                                        all_results.append(result)
+                                    elif isinstance(result, list):
+                                        for item in result:
+                                            if isinstance(item, dict):
+                                                all_results.append(item)
+                                except json.JSONDecodeError:
+                                    continue
+            except Exception as e:
+                logging.error(f'Failed to read result file {json_file}: {e}')
+
+        return all_results
+
+    async def _cleanup_temp_files(self, temp_path: str):
+        """清理临时扫描文件."""
+        if not temp_path:
+            return
+
+        try:
+            import shutil
+
+            temp_dir = Path(temp_path)
+            if temp_dir.exists() and temp_dir.is_dir():
+                shutil.rmtree(temp_dir)
+                logging.debug(f'Cleaned up temporary security scan files: {temp_path}')
+        except Exception as e:
+            logging.warning(f'Failed to cleanup temporary files at {temp_path}: {e}')

webqa_agent/llm/llm_api.py

@@ -0,0 +1,135 @@
+import logging
+
+import httpx
+from openai import AsyncOpenAI
+
+
+class LLMAPI:
+    def __init__(self, llm_config) -> None:
+        self.llm_config = llm_config
+        self.api_type = self.llm_config.get("api")
+        self.model = self.llm_config.get("model")
+        self.client = None
+        self._client = None  # httpx client
+
+    async def initialize(self):
+        if self.api_type == "openai":
+            self.api_key = self.llm_config.get("api_key")
+            if not self.api_key:
+                raise ValueError("API key is empty. OpenAI client not initialized.")
+            self.base_url = self.llm_config.get("base_url")
+            # Use AsyncOpenAI client for async operations
+            self.client = AsyncOpenAI(api_key=self.api_key, base_url=self.base_url, timeout=60) if self.base_url else AsyncOpenAI(
+                api_key=self.api_key, timeout=60)
+            logging.debug(f"AsyncOpenAI client initialized with API key: {self.api_key}, Model: {self.model} and base URL: {self.base_url}")
+        else:
+            raise ValueError("Invalid API type or missing credentials. LLM client not initialized.")
+
+        return self
+
+    async def _get_client(self):
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=60.0)
+        return self._client
+
+    async def get_llm_response(self, system_prompt, prompt, images=None, temperature=None, top_p=None):
+        model_input = {"model": self.model, "api_type": self.api_type}
+        if self.api_type == "openai" and self.client is None:
+            await self.initialize()
+
+        try:
+            messages = self._create_messages(system_prompt, prompt)
+            # Handle images
+            if images and self.api_type == "openai":
+                self._handle_images_openai(messages, images)
+                model_input["images"] = "included"
+            # Choose and call API
+            if self.api_type == "openai":
+                # resolve sampling params: prefer method args, fallback to config defaults (default temperature=0.1)
+                resolved_temperature = (
+                    temperature if temperature is not None else self.llm_config.get("temperature", 0.1)
+                )
+                resolved_top_p = top_p if top_p is not None else self.llm_config.get("top_p", None)
+                logging.debug(f"Resolved temperature: {resolved_temperature}, top_p: {resolved_top_p}")
+                result = await self._call_openai(messages, resolved_temperature, resolved_top_p)
+
+            return result
+        except Exception as e:
+            logging.error(f"LLMAPI.get_llm_response encountered error: {e}")
+            raise
+
+    def _create_messages(self, system_prompt, prompt):
+        if self.api_type == "openai":
+            return [
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": [{"type": "text", "text": prompt}]},
+            ]
+        else:
+            raise ValueError("Invalid api_type. Choose 'openai'.")
+
+    def _handle_images_openai(self, messages, images):
+        """Helper to append image data to messages for OpenAI."""
+        try:
+            if isinstance(images, str):
+                if images.startswith("data:image"):
+                    image_message = {"type": "image_url", "image_url": {"url": f"{images}", "detail": "low"}}
+                    messages[1]["content"].append(image_message)
+            elif isinstance(images, list):
+                for image_base64 in images:
+                    image_message = {"type": "image_url", "image_url": {"url": f"{image_base64}", "detail": "low"}}
+                    messages[1]["content"].append(image_message)
+            else:
+                raise ValueError("Invalid type for 'images'. Expected a base64 string or a list of base64 strings.")
+        except Exception as e:
+            logging.error(f"Error while handling images for OpenAI: {e}")
+            raise ValueError(f"Failed to process images for OpenAI. Error: {e}")
+
+    async def _call_openai(self, messages, temperature=None, top_p=None):
+        try:
+            create_kwargs = {
+                "model": self.llm_config.get("model"),
+                "messages": messages,
+                "timeout": 60,
+            }
+            # Always send user/configured temperature when provided (default handled upstream)
+            if temperature is not None:
+                create_kwargs["temperature"] = temperature
+            if top_p is not None:
+                create_kwargs["top_p"] = top_p
+
+            completion = await self.client.chat.completions.create(**create_kwargs)
+            content = completion.choices[0].message.content
+            logging.debug(f"LLM API response: {content}")
+            # Clean response if it's wrapped in JSON code blocks
+            content = self._clean_response(content)
+            return content
+        except Exception as e:
+            logging.error(f"Error while calling LLM API: {e}")
+            raise ValueError(f"{str(e)}")
+
+    def _clean_response(self, response):
+        """Remove JSON code block markers from the response if present."""
+        try:
+            if response and isinstance(response, str):
+                # Check if response starts with ```json and ends with ```
+                if response.startswith("```json") and response.endswith("```"):
+                    # Remove the markers and return the content
+                    logging.debug("Cleaning response: Removing ```json``` markers")
+                    return response[7:-3].strip()
+                # Check if it just has ``` without json specification
+                elif response.startswith("```") and response.endswith("```"):
+                    logging.debug("Cleaning response: Removing ``` markers")
+                    return response[3:-3].strip()
+
+                # Encode response as UTF-8
+                response = response.encode("utf-8").decode("utf-8")
+            return response
+        except Exception as e:
+            logging.error(f"Error while cleaning response: {e}")
+            logging.error(f"Original response: {response}")
+            return response
+
+    async def close(self):
+        if self._client:
+            await self._client.aclose()
+            self._client = None

webqa_agent/llm/prompt.py

@@ -0,0 +1,745 @@
+# Portions of the `planner_system_prompt` and `planner_output_prompt`
+# variations in this file are derived from:
+# https://github.com/web-infra-dev/midscene/packages/core/src/ai-model/prompt/llm-planning.ts
+#
+# Copyright (c) 2024-present Bytedance, Inc. and its affiliates.
+#
+# Licensed under the MIT License
+
+
+class LLMPrompt:
+    planner_system_prompt = """
+    ## Role
+    You are a versatile professional in software UI automation. Your outstanding contributions will impact the user experience of billions of users.
+
+    ## Context Provided
+    - **`pageDescription (interactive elements)`**: A map of all interactive elements on the page, each with a unique ID. Use these IDs for actions.
+    - **`page_structure (full text content)`**: The complete text content of the page, including non-interactive elements.
+    - **`Screenshot`**: A visual capture of the current page state.
+
+    ## Objective
+    - Decompose the user's instruction into a **series of actionable steps**, each representing a single UI interaction.
+    - **Unified Context Analysis**: You MUST analyze BOTH `pageDescription` and `page_structure` together. Use `page_structure` to understand the meaning and context of the interactive elements in `pageDescription` (e.g., matching a label to a nearby input field). This unified view is critical for making correct decisions.
+    - Identify and locate the target element if applicable.
+    - Validate if the planned target matches the user's intent, especially in cases of **duplicate or ambiguous elements**.
+    - Avoid redundant operations such as repeated scrolling or re-executing completed steps.
+    - If the instruction cannot be fully completed, provide a precise `furtherPlan`.
+
+    ## Target Identification & Validation
+    ### Step-by-step validation:
+    1. **Extract User Target**
+       - From the instruction, extract the label/description of the intended target.
+
+    2. **Locate Candidate Elements**
+       - Match label/text from visible elements.
+       - If **duplicates exist**, apply **anchor-based spatial disambiguation**:
+         - Use anchor labels, coordinates, and direction (below/above/left/right).
+         - For 'below', validate:
+           - target.x ≈ anchor.x ±30 pixels
+           - target.y > anchor.y
+         - Sort by ascending y to get N-th below.
+
+    3. **Final Validation**
+       - Ensure the selected target aligns with user's intent.
+       - If validation fails, return:
+         `"Planned element does not match the user's expected target."`
+
+    4. **Thought Requirement (Per Action)**
+       - Explain how the element was selected.
+       - Confirm its match with user intent.
+       - Describe how ambiguity was resolved.
+
+    ## Anchor Usage Rule
+    Anchors are strictly used for reference during disambiguation.
+    **NEVER** interact (Tap/Hover/Check) with anchor elements directly.
+
+    ## Scroll Behavior Constraints
+    - Avoid planning `Scroll` if the page is already at the bottom.
+    - Check prior actions (`WhatHaveBeenDone`) for any `Scroll untilBottom`. If present, treat the page as already scrolled.
+    - If still unable to locate a required element, return:
+      `"Validation Failed"` instead of re-scrolling.
+
+    ## Spatial Direction Definitions
+    Relative to page layout:
+    - 'Above': visually higher than anchor.
+    - 'Below': vertically under anchor, x ≈ anchor.x ±30px, y > anchor.y
+    - 'Left' / 'Right': horizontally beside anchor.
+
+    Use top-down, left-right search order. Default to top-bottom if uncertain.
+
+    ## Workflow
+    1. Receive user's instruction, screenshot, and task state.
+    2. Decompose into sequential steps under `actions`.
+    3. For each action:
+       - If the element is visible, provide `locate` details.
+       - If not visible, halt further planning, set `taskWillBeAccomplished` = false, and describe next steps via `furtherPlan`.
+
+    4. If task is completed with current steps, set `taskWillBeAccomplished` = true.
+    5. Use `furtherPlan` when the task is partially completed.
+
+    ## Constraints
+    - **No redundant scrolls**. If bottom is reached, don't scroll again.
+    - **Trust prior actions** (`WhatHaveBeenDone`). Do not repeat.
+    - All plans must reflect actual context in screenshot.
+    - Always output strict **valid JSON**. No comments or markdown.
+
+    ## Actions
+
+    Each action includes `type` and `param`, optionally with `locate`.
+
+        Each action has a
+        - type: 'Tap', tap the located element
+        * {{ locate: {{ id: string }}, param: null }}
+        - type: 'Hover', move mouse over to the located element
+        * {{ locate: {{ id: string }}, param: null }}
+        - type: 'Input', replace the value in the input field
+        * {{ locate: {{ id: string }}, param: {{ value: string, clear_before_type: boolean (optional) }} }}
+        * `value` is the final required input value based on the existing input. No matter what modifications are required, just provide the final value to replace the existing input value.
+        * For Input actions, if the page or validation message requires a minimum length, the value you generate MUST strictly meet or exceed this length. For Chinese, count each character as 1.
+        * `clear_before_type`: Set to `true` if the instruction explicitly says to 'clear' the field before typing, or if you are correcting a previous failed input. Defaults to `false`.
+        - type: 'KeyboardPress', press a key
+        * {{ param: {{ value: string }} }}
+        - type: 'Upload', upload a file (or click the upload button)
+        * {{ locate: {{ id: string }}, param: null }}
+        * use this action when the instruction is a "upload" statement. locate the input element to upload the file.
+        - type: 'Scroll', scroll up or down.
+        * {{
+            locate: {{ id: string }} | null,
+            param: {{
+                direction: 'down'(default) | 'up',
+                scrollType: 'once' (default) | 'untilBottom' | 'untilTop',
+                distance: null | number
+            }}
+            }}
+            * To scroll some specific element, put the element at the center of the region in the `locate` field. If it's a page scroll, put `null` in the `locate` field.
+            * `param` is required in this action. If some fields are not specified, use direction `down`, `once` scroll type, and `null` distance.
+        - type: 'GetNewPage', get the new page
+        * {{ param: null }}
+        * use this action when the instruction is a "get new page" statement or "open in new tab" or "open in new window".
+        - type: 'GoToPage', navigate directly to a specific URL
+        * {{ param: {{ url: string }} }}
+        * use this action when you need to navigate to a specific web page URL, useful for returning to homepage or navigating to known pages.
+        - type: 'GoBack', navigate back to the previous page
+        * {{ param: null }}
+        * use this action when you need to go back to the previous page in the browser history, similar to clicking the browser's back button.
+        - type: 'Sleep'
+        * {{ param: {{ timeMs: number }} }}
+        - type: 'Check'
+        * {{ param: null }}
+        * use this action when the instruction is a "check" or "verify" or "validate" statement.
+        - type: 'Drag', drag an slider or element from source to target position
+          For Drag action, use the following format:
+            {
+              "type": "Drag",
+              "thought": "Describe why and how you drag, e.g. Drag the slider from value 0 to 50.",
+              "param": {
+                "sourceCoordinates": { "x": number, "y": number },
+                "targetCoordinates": { "x": number, "y": number },
+                "dragType": "coordinate"
+              },
+              "locate": { "id": string } | null
+            }
+          - dragType: always use "coordinate"
+          - Both sourceCoordinates and targetCoordinates must be provided and must be positive numbers.
+          - If coordinates are missing or invalid, the action will fail.
+        - type: 'SelectDropdown'
+        * {{ locate: {{ dropdown_id: int, option_id: int (optional) }}, param: {{ selection_path: string | list }} }}
+        * use this action when the instruction is a "select" or "choose" or "pick" statement. *you should click the dropdown element first.*
+        * dropdown_id is the id of the dropdown container element.
+        * option_id is the id of the option element in the expanded dropdown (if available).
+        * if option_id is provided, you should directly click the option element.
+        * if option_id is not provided, use dropdown_id to expand and select by text.
+        * selection_path is the text of the option to be selected.
+        * if the selection_path is a string, it means the option is the first level of the dropdown.
+        * if the selection_path is a list, it means the option is the nth level of the dropdown.
+
+    ## Further Plan Format
+    If the task isn't completed:
+    "furtherPlan": {
+      "whatHaveDone": "Actions already performed...",
+      "whatToDoNext": "Next steps to reach target..."
+    }
+    ```
+"""
+
+    planner_output_prompt = """
+    ## First, you need to analyze the page dom tree and the screenshot, and complete the test steps.
+
+    ### Element Identification Instructions:
+    In the pageDescription, you will find elements with the following structure:
+    - Each element has an external id (like '1', '2', '3') for easy reference
+    - Each element also has an internal id (like 917, 920, 923) which is the actual DOM element identifier
+    - When creating actions, use the external id (string) in the locate field
+    - Example: if you see element '1' with internal id 917, use "id": "1" in your action
+
+    ### Contextual Decision Making:
+    - **Crucially, use the `page_structure` (full text content) to understand the context of the interactive elements from `pageDescription`**. For example, if `page_structure` shows "Username:" next to an input field, you know that input field is for the username.
+    - If you see error text like "Invalid email format" in `page_structure`, use this information to correct your next action.
+
+    ### Supported Actions:
+    - Tap: Click on a specified page element (such as a button or link). Typically used to trigger a click event.
+    - Scroll: Scroll the page or a specific region. You can specify the direction (down, up), the scroll distance, or scroll to the edge of the page/region.
+    - Input: Enter text into an input field or textarea. This action will replace the current value with the specified final value.
+    - Sleep: Wait for a specified amount of time (in milliseconds). Useful for waiting for page loads or asynchronous content to render.
+    - Upload: Upload a file
+    - KeyboardPress: Simulate a keyboard key press, such as Enter, Tab, or arrow keys.
+    - Drag: Perform a drag-and-drop operation. Moves the mouse from a starting coordinate to a target coordinate, often used for sliders, sorting, or drag-and-drop interfaces. Requires both source and target coordinates.
+    - SelectDropdown: Select an option from a dropdown menu which is user's expected option. The dropdown element is the first level of the dropdown menu. IF You can see the dropdown element, you cannot click the dropdown element, you should directly select the option.
+
+    Please ensure the output is a valid **JSON** object. Do **not** include any markdown, backticks, or code block indicators.
+
+        ### Output **JSON Schema**, **Legal JSON format**:
+        {
+          "actions": [
+            {
+              "thought": "Reasoning for this action and why it's feasible on the current page.",
+              "type": "Tap" | "Scroll" | "Input" | "Sleep" | "Check" | "Upload" | "KeyboardPress" | "Drag" | "SelectDropdown" | "GoToPage" | "GoBack",
+              "param": {...} | null,
+              "locate": {...} | null
+            }
+          ],
+          "taskWillBeAccomplished": true | false,
+          "targetVerified": true | false, // optional, include if task involves target validation
+          "furtherPlan": {
+            "whatHaveDone": string,
+            "whatToDoNext": string
+          } | null,
+          "error": string | null // present only if planning failed or validation failed
+        }
+
+        ---
+
+        ### Output Requirements
+        - Use `thought` field in every action to explain selection & feasibility.
+        - If the task involves matching a user-described target (like "click send button"), you **must validate the target**:
+          - If matched: `targetVerified: true`
+          - If mismatched: `targetVerified: false` and include error: "Planned element does not match the user's expected target"
+        - If an expected element is not found on the page:
+          - For imperative instruction: return `error` and empty actions.
+          - For tolerant instructions like "If popup exists, close it", return `FalsyConditionStatement` action.
+
+        ---
+
+        ### Unified Few-shot Examples
+
+        #### Example 1: Tap + Sleep + Check (task incomplete)
+        "Click send button and wait 50s"
+
+        ====================
+        {pageDescription}
+        ====================
+
+        By viewing the page screenshot and description, you should consider this and output the JSON:
+
+        ```json
+        {
+          "actions": [
+            {
+              "type": "Tap",
+              "thought": "Click the send button to trigger response",
+              "param": null,
+              "locate": { "id": "1" }
+            },
+            {
+              "type": "Sleep",
+              "thought": "Wait for 50 seconds for streaming to complete",
+              "param": { "timeMs": 50000 }
+            }
+          ],
+          "taskWillBeAccomplished": false,
+          "targetVerified": true,
+          "furtherPlan": {
+            "whatHaveDone": "Clicked send and waited 50 seconds",
+            "whatToDoNext": "Verify streaming output is complete"
+          },
+          "error": null
+        }
+        ```
+
+        #### Example 2: Scroll + Check (scroll history aware)
+        ```json
+        {
+          "actions": [
+            {
+              "type": "Scroll",
+              "thought": "Scroll to bottom to reveal more datasets",
+              "param": { "direction": "down", "scrollType": "untilBottom", "distance": null },
+              "locate": null
+            }
+          ],
+          "taskWillBeAccomplished": false,
+          "furtherPlan": {
+            "whatHaveDone": "Scrolled to bottom of page",
+            "whatToDoNext": "Check whether only Strong Reasoning datasets are shown"
+          },
+          "error": null
+        }
+        ```
+
+        #### Example 3: 点击首页button，校验跳转新开页
+        "Click the button on the homepage and verify that a new page opens"
+        ```json
+        {
+          "actions": [
+            {
+              "type": "Tap",
+              "thought": "Click the button on the homepage",
+              "param": null,
+              "locate": { "id": "1" }
+            },
+            {
+              "type": "GetNewPage",
+              "thought": "I get the new page",
+              "param": null
+            }
+          ],
+          "taskWillBeAccomplished": true,
+          "furtherPlan": null,
+          "error": null
+        }
+        ```
+
+        #### Example 4: 上传文件'example.pdf',等待10s
+        "Upload a file and then wait"
+        ```json
+        {
+          "actions": [
+            {
+              "locate": {
+                "id": "41"
+              },
+              "param": null,
+              "thought": "Tap on the area that allows file uploads, as it's currently visible and interactive.",
+              "type": "Upload"
+            },
+            {
+              "param": {
+                "timeMs": 10000
+              },
+              "thought": "Wait for 10 seconds to allow the upload to complete.",
+              "type": "Sleep"
+            }
+          ],
+          "error": null,
+          "furtherPlan": null,
+          "targetVerified": true,
+          "taskWillBeAccomplished": true
+        }
+        ```
+
+        #### Example: Drag slider
+        ```json
+        {
+          "actions": [
+            {
+              "type": "Drag",
+              "thought": "currently set at value 0. To change it to 50, we perform a drag action. Calculated target x for 50 degrees is approximately 300( Give specific calculation formulas ), so drag the slider to 50 by moving from (100, 200) to (300, 200).",
+              "param": {
+                "sourceCoordinates": { "x": 100, "y": 200 },
+                "targetCoordinates": { "x": 300, "y": 200 },
+                "dragType": "coordinate"
+              },
+              "locate": { "id": "1" }
+            }
+          ],
+          "taskWillBeAccomplished": true,
+          "furtherPlan": null,
+          "error": null
+        }
+        ```
+
+        #### Example 5: click AND Select
+        "click the select button and select the option 'Option 2' from the dropdown menu and then select the option 'Option 3' from the dropdown menu"
+        ATTENTION: dropdown_id is the id of the dropdown container element. option_id is the id of the option element in the expanded dropdown (if available).
+        ```json
+        {
+          "actions": [
+            {
+              "type": "Tap",
+              "thought": "Click the select button which id is 5",
+              "param": null,
+              "locate": { "id": "5" }
+            },
+            {
+              "type": "SelectDropdown",
+              "thought": "there is select dropdown id is "5", Select the option 'Option 2' from the dropdown menu and then select the option 'Option 3' from the dropdown menu",
+              "param": { "selection_path": ["Option 2", "Option 3"] },
+              "locate": { dropdown_id: "5", option_id: "2" (optional) }
+            }
+          ],
+          "taskWillBeAccomplished": true,
+          "furtherPlan": null,
+          "error": null
+        }
+        ```
+
+        #### Example 6: Navigate to Homepage using GoToPage
+        \"Go to the homepage to restart the test\"
+        ```json
+        {
+          \"actions\": [
+            {
+              \"type\": \"GoToPage\",
+              \"thought\": \"Navigate to homepage to restart the test from a clean state\",
+              \"param\": { \"url\": \"https://example.com\" },
+              \"locate\": null
+            }
+          ],
+          \"taskWillBeAccomplished\": true,
+          \"furtherPlan\": null,
+          \"error\": null
+        }
+        ```
+
+        #### Example 7: Go Back to Previous Page
+        \"Go back to the previous page and try again\"
+        ```json
+        {
+          \"actions\": [
+            {
+              \"type\": \"GoBack\",
+              \"thought\": \"Return to previous page to retry the operation\",
+              \"param\": null,
+              \"locate\": null
+            }
+          ],
+          \"taskWillBeAccomplished\": false,
+          \"furtherPlan\": {
+            \"whatHaveDone\": \"Navigated back to previous page\",
+            \"whatToDoNext\": \"Retry the failed action from the previous page\"
+          },
+          \"error\": null
+        }
+        ```
+
+        #### Example of what NOT to do
+        - If the action's `locate` is null and element is **not in the screenshot**, don't continue planning. Instead:
+        ```json
+        {
+          "actions": [],
+          "taskWillBeAccomplished": false,
+          "furtherPlan": {
+            "whatHaveDone": "Clicked language switch",
+            "whatToDoNext": "Locate and click English option once it's visible"
+          },
+          "error": "Planned element not visible; task cannot be completed on current page"
+        }
+        ```
+
+        ---
+
+        ### Final Notes
+        - Plan only for **visible, reachable actions** based on current context.
+        - If not all steps can be completed now, push remainder to `furtherPlan`.
+        - Always output strict JSON format — no markdown, no commentary.
+        - Remember to use the external id (string) from the pageDescription in your locate field.
+
+    """
+
+    verification_prompt = """
+      Task instructions: Based on the assertion provided by the user, you need to check final screenshot to determine whether the verification assertion has been completed.
+
+      First, you need to understand the user's assertion, and then determine the elements that need to be verified.
+      Second, you need to check Page Structure and the Marker screenshot to determine whether the elements can be determined.
+      Third, you will give a conclusion based on the screenshot and the assertion.
+
+      ### Few-shot Examples
+
+      #### Example 1: The assertions provided by the user involve the visible or invisible elements as a basis for judgment.
+      the user's assertions: "Verify that InternThinker Streaming Output Completion, if  "stop generating" is not visible, it means the test is passed; if conversation is visible, it means the test is passed.
+      ====================
+      {pageStructure}
+      ====================
+      1. **Step 1 - Determine the "Stop generating" button**: - Check whether there is a button marked "Stop generating" on the page. - If the button does not exist (i.e., it is not visible), this step is considered to be completed correctly.
+      2. **Step 2 - Verify the existence of text information**: - Confirm whether there is a dialog box(that communicates information to the user and prompts them for a response) displayed on the current interface. - Also check whether any text information is output to the screen (i.e., conversation is visible), this step is considered to be completed correctly.
+
+      Only when both the existence of dialog boxes and text information are met can the entire test process be considered successful.
+
+
+      #### Example 2:  Page Navigation & Filter Result Validation
+      1. **Step 1**: Check if the expected content (e.g., search result, category filter result, dataset name) is **already visible**.
+      2. **Step 2**: If not, you may **perform at most one scroll** (e.g., `Scroll: untilBottom`).
+      3. **Step 3**: Recheck whether the expected content is now visible.
+        - If found: return `"Validation Passed"`
+        - If not found: return `"Validation Failed"`
+
+     > Never scroll more than once. Do **not** assume infinite content. Always default to visibility-based validation.
+
+      #### Example 3:  Element Presence Verification
+      the user's assertions: "Verify X is shown"
+      ====================
+      {pageStructure}
+      ====================
+      1. If user instruction specifies checking for an element:
+        - Scan visible UI for that element or its textual representation
+        - If visible: Passed
+        - If not found and no evidence of error: Failed
+
+      ---------------
+      ### Output Format (Strict JSON):
+
+      Please first explain your **step-by-step reasoning process** in a `"Reasoning"` field, then provide the final validation result and step-wise details in the format below.
+
+      Return a single JSON object:
+
+      For passed validation:
+      {
+        "Validation Result": "Validation Passed",
+          "Details": [
+            "Step X: <specific reason for PASS>",
+            ...
+          ]
+      }
+
+      For failed validation:
+      {
+        "Validation Result": "Validation Failed",
+          "Details": [
+          "Step X: <specific reason for Failure>",
+            ...
+          ]
+      }
+
+    """
+
+    verification_system_prompt = """
+    ## Role
+      Think of yourself as a premium model( ChatGPT Plus )
+      You are a web automation testing verification expert. Verify whether the current page meets the user's test cases and determine if the task is completed. Ensure that the output JSON format does not include any code blocks or backticks.
+      Based on the screenshot and available evidence, determine whether the user has successfully completed the test case.
+      Focus exclusively on verifying the completion of the final output rendering.
+
+    ## Notes:
+
+      1. Carefully review each **screenshot** to understand the operation steps and their sequence.
+      2. **Page Structure** is the Dom tree of the page, including the text information of the page.
+      2. Compare the difference between the last screenshot (i.e. the final execution result) with the Page Structure and the target state described by the user.
+      3. Use the following template to give a conclusion: "Based on the analysis of the screenshots you provided, [If consistent, fill in 'Your operation has successfully achieved the expected goal'] [If inconsistent, fill in 'It seems that some steps are not completed/there are deviations, please check... part']."
+      4. If any mismatches are found or further suggestions are needed, provide specific guidance or suggestions to help users achieve their goals.
+      5. Make sure the feedback is concise and clear, and directly evaluate the content submitted by the user.
+
+    """
+
+    # New: Test case generation prompts
+    case_generator_system_prompt = """
+    ## Role
+    You are an expert UI test case generator. Your task is to analyze a webpage and user requirements, then generate comprehensive test cases that thoroughly validate the functionality.
+
+    ## Objective
+    Based on the provided webpage HTML/structure and user requirements, you need to:
+    1. **Understand the webpage structure** and identify key interactive elements
+    2. **Analyze user requirements** to understand what functionality needs to be tested
+    3. **Generate comprehensive test steps** that cover the main user workflow
+    4. **Include appropriate validations** to ensure the functionality works correctly
+    5. **Consider edge cases** and error scenarios when applicable
+
+    ## Test Case Structure
+    Each test case should include:
+    - **name**: A descriptive name for the test case
+    - **steps**: A list of actions and validations
+    - **objective**: What the test case aims to validate
+
+    ## Available Action Types
+    - **action**: Execute an action instruction (click, type, scroll, wait, drag, upload, keyboardPress etc.)
+    - **verify**: Verify expected outcomes or states
+
+    ## Guidelines
+    1. **Logical Flow**: Ensure test steps follow a logical user workflow
+    2. **Comprehensive Coverage**: Test main functionality, edge cases, and error scenarios
+    3. **Clear Validations**: Each test should include proper assertions to verify success
+    4. **Realistic User Behavior**: Steps should mimic real user interactions
+    5. **Wait Times**: Include appropriate wait times for dynamic content
+    6. **File Uploads**: When testing file upload, use appropriate file paths and wait times
+    7. **Navigation**: Test page navigation and state changes
+    8. **Error Handling**: Include tests for error scenarios when applicable
+
+    ## Test Case Categories to Consider
+    - **Core Functionality**: Main features and workflows
+    - **User Interaction**: Form submissions, button clicks, navigation
+    - **Data Validation**: Input validation, error messages
+    - **Dynamic Content**: Loading states, real-time updates
+    - **File Operations**: Upload, download, preview
+    - **Responsive Behavior**: Different screen sizes and devices
+    - **Error Scenarios**: Invalid inputs, network issues, permission errors
+
+    ## Output Format
+    Return a JSON object with the following structure:
+    ```json
+    {
+      "test_cases": [
+        {
+          "name": "descriptive_test_name",
+          "objective": "what this test validates",
+          "steps": [
+            {"action": "action instruction"},
+            {"verify": "validation instruction"},
+            ...
+          ]
+        }
+      ]
+    }
+    ```
+    """
+
+    case_generator_output_prompt = """
+    ## Task: Generate Comprehensive Test Cases
+
+    Based on the provided webpage structure and user requirements, generate detailed test cases that thoroughly validate the functionality.
+
+    ### Webpage Analysis
+    Please analyze the page structure and identify:
+    1. **Interactive Elements**: buttons, forms, links, inputs, etc.
+    2. **Key Features**: main functionalities exposed by the UI
+    3. **User Workflows**: typical user journeys through the interface
+    4. **Validation Points**: where success/failure can be measured
+
+    ### Test Case Generation Rules
+    1. **Start with Basic Flow**: Begin with the most common user workflow
+    2. **Add Edge Cases**: Include boundary conditions and error scenarios
+    3. **Include Proper Waits**: Add appropriate wait times for dynamic content
+    4. **Validate Each Step**: Include assertions to verify expected outcomes
+    5. **Use Realistic Data**: Include realistic test data and file paths
+    6. **Consider User Experience**: Test from an end-user perspective
+
+    Generate comprehensive test cases in the specified JSON format. **Do not include code blocks in the output**
+    """
+
+    page_default_prompt = """
+    You are a web content quality inspector. You need to carefully read the text content of the webpage and complete the task based on the user's test objective. Please ensure that the output JSON format does not contain any code blocks or backticks.
+    """
+    # You are a web content quality inspector. You need to carefully read the text content of the webpage and complete the task based on the user's test objective. Please ensure that the output JSON format does not contain any code blocks or backticks.
+
+    TEXT_USER_CASES = [
+        """Carefully inspect the text on the current page and identify any spelling, grammar, or character errors.
+        Text Accuracy: Spelling errors, grammatical errors, punctuation errors; inconsistent formatting of numbers, units, and currency.
+        Wording & Tone: Consistent wording; consistent terminology and abbreviations; consistent tone of voice with the product.
+        Language Consistency: Inappropriate mixing of languages ​​within the page (e.g., mixing Chinese and English without spacing).
+
+        Notes:
+        - First, verify whether the page content is readable by the user
+        - List all spelling mistakes and grammatical errors separately
+        - For each error, provide:
+          * Location in the text
+          * Current incorrect form
+          * Suggested correction
+          * Type of error (spelling/grammar/punctuation)
+        """
+    ]
+    CONTENT_USER_CASES = [
+        """Rigorously review each screenshot at the current viewport for layout issues, and provide specific, actionable recommendations.
+
+      [Checklist]
+      1. Text alignment: Misaligned headings/paragraphs/lists; inconsistent margins or baselines
+      2. Spacing: Intra- and inter-component spacing too large/too small/uneven; inconsistent spacing in lists or card grids
+      3. Obstruction & overflow: Text/buttons obscured; content overflowing containers causing truncation, awkward wrapping, or unintended ellipses; sticky header/footer covering content; incorrect z-index stacking
+      4. Responsive breakpoints: Broken layout at current width; wrong column count; unexpected line wraps; horizontal scrollbar appearing/disappearing incorrectly
+      5. Visual hierarchy: Important information not prominent; hierarchy confusion; insufficient contrast between headings and content; font size/weight/color not reflecting hierarchy
+      6. Consistency: Uneven card heights breaking grid rhythm; inconsistent button styles/sizes; misaligned keylines
+      7. Readability: Insufficient contrast; font too small; improper line-height; poor paragraph spacing; long words/URLs not breaking and causing layout stretch
+      8. Images & media: Distorted aspect ratio; improper cropping; blurry/pixelated; placeholder not replaced; video container letterboxing
+      9. Text completeness: Words or numbers truncated mid-word due to insufficient container width; missing last characters without ellipsis.
+
+      [Decision & Output Rules]
+      - Base conclusions only on the current screenshot; if uncertain, state the most likely cause and an actionable fix
+      - If multiple layout issues exist in the same screenshot, merge them into a single object and list them in the 'issue' field separated by semicolons
+      - If no issues are found, output strictly None (no explanation)
+      """,
+      """Rigorously check each screenshot for missing key functional/content/navigation elements, loading failures, or display anomalies, and provide fix suggestions.
+
+      [Checklist]
+      1. Functional elements: Buttons/links/inputs/dropdowns/pagination/search etc. missing or misplaced
+      2. Content elements: Images/icons/headings/body text/lists/tables/placeholder copy missing
+      3. Navigation elements: Top nav/sidebar/breadcrumb/back entry/navigation links missing
+      4. Loading/error states: Broken images, 404, blank placeholders, skeleton not replaced, overly long loading, empty states lacking hints/guidance/actions
+      5. Image display: Display anomalies, low-quality/blurry/pixelated, wrong cropping, aspect-ratio distortion, lazy-load failure
+      6. Business-critical: Core CTAs missing/unusable; price/stock/status missing; required form fields missing; no submission feedback
+      7. Interaction usability: Element visible but not clickable/disabled state incorrect; tappable/clickable area too small
+
+      [Decision & Output Rules]
+      - When unsure whether it's not rendered or late loading, still provide the best evidence-based judgment and suggestion
+      - If multiple missing/anomaly issues exist in the same screenshot, merge them into a single object and separate in the 'issue' field with semicolons
+      - If no issues are found, output strictly None (no explanation)
+      """
+    ]
+
+    OUTPUT_FORMAT = """
+    Output Requirements
+
+    **CRITICAL: You must choose ONE of the following two output formats based on your findings:**
+
+    **Format 1: NO ISSUES FOUND**
+    If you find no issues or problems, output exactly this JSON structure:
+    ```json
+    {
+        "status": "no_issues",
+        "message": "No issues detected"
+    }
+    ```
+
+    **Format 2: ISSUES FOUND**
+    If you find any issues, output a JSON array with the following structure:
+    ```json
+    [
+        { "summary": "Concise overall findings across screenshots" },
+        {
+            "screenshotid": <number>, # 0-based index of the input screenshot
+            "element": "<string>", # core element where the issue occurs (e.g., title, button, image, paragraph)
+            "issue": "<string>", # concise problem description stating the exact cause (if multiple issues exist for the same screenshot, summarize them here)
+            "coordinates": [x1, y1, x2, y2], # pixel coordinates on the screenshot. Origin at top-left; integers only; ensure 0 <= x1 <= x2 <= width-1 and 0 <= y1 <= y2 <= height-1. For text or single-line elements, y1 can equal y2.
+            "suggestion": "<string>", # suggestions / expected solutions (multiple points, separated by ";")
+            "confidence": "<high|medium|low>" # confidence level, values: *high* / *medium* / *low*
+        }
+    ]
+    ```
+
+    **⚠️ CRITICAL FORMAT RULES:**
+    - The FIRST object in the array MUST be the summary object: `{ "summary": "..." }`
+    - The summary object CANNOT contain any other fields besides "summary"
+    - All issue objects (with screenshotid, element, issue, coordinates, suggestion, confidence) MUST come AFTER the summary object
+    - NEVER put "summary" field inside issue objects
+
+    **Examples:**
+
+    **Example 1 - No Issues:**
+    ```json
+    {
+        "status": "no_issues",
+        "message": "No issues detected"
+    }
+    ```
+
+    **Example 2 - Issues Found (CORRECT FORMAT):**
+    ```json
+    [
+        { "summary": "Page issues: 1) navbar overlap; 2) grid spacing inconsistent" },
+        {
+            "screenshotid": 2,
+            "element": "Main Navigation Bar",
+            "issue": "Navigation items overlap with the logo, making the text unreadable",
+            "coordinates": [240, 122, 270, 122],
+            "suggestion": "Reduce logo width; add min-width to nav items; adjust flex-wrap",
+            "confidence": "medium"
+        },
+        {
+            "screenshotid": 3,
+            "element": "Product List Card",
+            "issue": "Excess vertical whitespace between cards prevents the first screen from displaying completely",
+            "coordinates": [80, 540, 920, 720],
+            "suggestion": "Normalize card min-height; unify grid gap; reduce top/bottom padding",
+            "confidence": "low"
+        }
+    ]
+    ```
+
+    **Important Rules:**
+    - NEVER output plain text without JSON structure
+    - If no issues are found, use Format 1 with "status": "no_issues"
+    - If issues are found, use Format 2 with the array structure
+    - **MANDATORY: Array structure must be [summary_object, issue_object1, issue_object2, ...]**
+    - **MANDATORY: Summary object must be FIRST and contain ONLY the "summary" field**
+    - **MANDATORY: Issue objects must NOT contain "summary" field**
+    - If multiple issues exist in the same screenshot, merge them into a single object
+    - Coordinates must be measured on the provided screenshot for the current viewport
+    - Keep descriptions concise and actionable
+    - Focus on business logic and user expectations
+    """

webqa_agent/static/assets/style.css

@@ -0,0 +1 @@
+._container_eghx4_1{display:flex;width:100vw;min-height:100vh;min-width:1280px;background-color:#fff}._container_eghx4_1 ._left_eghx4_8{width:200px;display:flex;justify-content:center;background-color:var(----light-bg)}._container_eghx4_1 ._left_eghx4_8 ._webTitle_eghx4_14{font-size:28px;font-weight:600;text-align:left;padding-left:26px;height:56px;line-height:56px;color:#000}._container_eghx4_1 ._right_eghx4_23{flex:1;width:0;background-color:#fff;padding:6px 24px 24px}._diy-scrollbar_12blq_1::-webkit-scrollbar{width:4px;height:4px}._diy-scrollbar_12blq_1::-webkit-scrollbar-track{background-color:transparent}._diy-scrollbar_12blq_1::-webkit-scrollbar-thumb{border-radius:10px;background:#ebecf0}._diy-scrollbar_12blq_1:hover::-webkit-scrollbar-thumb{border-right:1px solid #ebecf0;border-bottom:1px solid #ebecf0;background:#ebecf0}._sContainer_12blq_17{display:flex;flex-direction:column;height:calc(100vh - 126px)}._summary_12blq_22{background-color:var(--warning-bg);padding:8px 12px 12px;font-size:14px;font-weight:400;border-radius:4px;max-height:180px;overflow-y:scroll;border-left:4px solid var(--warning-color)}._summary_12blq_22::-webkit-scrollbar{width:4px;height:4px}._summary_12blq_22::-webkit-scrollbar-track{background-color:transparent}._summary_12blq_22::-webkit-scrollbar-thumb{border-radius:10px;background:#ebecf0}._summary_12blq_22:hover::-webkit-scrollbar-thumb{border-right:1px solid #ebecf0;border-bottom:1px solid #ebecf0;background:#ebecf0}._summary_12blq_22 ._title_12blq_48{color:var(--warning-color);display:block;font-size:28px;font-weight:600;margin-bottom:8px}._summary_12blq_22 ._yellowWords_12blq_55{font-weight:600;color:var(--warning-color)!important}._content_12blq_59{overflow-y:scroll;height:0px;flex:1;margin-top:32px;padding:0 24px 0 0;display:grid;grid-template-columns:repeat(3,1fr);gap:24px;justify-items:center}._content_12blq_59::-webkit-scrollbar{width:4px;height:4px}._content_12blq_59::-webkit-scrollbar-track{background-color:transparent}._content_12blq_59::-webkit-scrollbar-thumb{border-radius:10px;background:#ebecf0}._content_12blq_59:hover::-webkit-scrollbar-thumb{border-right:1px solid #ebecf0;border-bottom:1px solid #ebecf0;background:#ebecf0}._content_12blq_59 ._box_12blq_86{height:fit-content;width:-webkit-fill-available;border-radius:8px;background:var(--light-bg);padding:16px 24px;display:flex;flex-direction:column;gap:16px;justify-content:flex-start;position:relative;align-items:center}._content_12blq_59 ._box_12blq_86:hover{background-color:var(--hover-bg)}._content_12blq_59 ._box_12blq_86 ._label_12blq_102{font-size:32px;font-weight:600}._issuesBox_12blq_106{position:relative}._issuesBox_12blq_106 ._issuesCount_12blq_109{padding:0 4px;width:fit-content;height:16px;border-radius:50%;background-color:var(--failure-color);right:-16px;top:-8px;position:absolute;font-size:12px;font-weight:600;color:#fff;display:none}._issuesBox_12blq_106 ._show_12blq_123{display:flex;align-items:center;justify-content:center}._noResult_12blq_128{font-size:24px;font-weight:400;padding:24px;display:flex;flex-direction:column;align-items:center;justify-content:center;border-radius:8px;height:calc(100vh - 200px);background-color:var(--light-bg);color:var(--words-color)}._noResult_12blq_128 span{height:36px;line-height:36px;display:block;font-size:36px;font-weight:600;margin-bottom:12px}._noResult_12blq_128 ._noIcon_12blq_149{font-size:48px}._diy-scrollbar_xna4e_1::-webkit-scrollbar{width:4px;height:4px}._diy-scrollbar_xna4e_1::-webkit-scrollbar-track{background-color:transparent}._diy-scrollbar_xna4e_1::-webkit-scrollbar-thumb{border-radius:10px;background:#ebecf0}._diy-scrollbar_xna4e_1:hover::-webkit-scrollbar-thumb{border-right:1px solid #ebecf0;border-bottom:1px solid #ebecf0;background:#ebecf0}._reportContent_xna4e_17{height:fit-content;max-height:200px;overflow-y:scroll;border:1px solid var(--border-color);border-radius:4px;padding:0 16px 16px;margin-bottom:8px}._reportContent_xna4e_17::-webkit-scrollbar{width:4px;height:4px}._reportContent_xna4e_17::-webkit-scrollbar-track{background-color:transparent}._reportContent_xna4e_17::-webkit-scrollbar-thumb{border-radius:10px;background:#ebecf0}._reportContent_xna4e_17:hover::-webkit-scrollbar-thumb{border-right:1px solid #ebecf0;border-bottom:1px solid #ebecf0;background:#ebecf0}._reportContent_xna4e_17 ._report_xna4e_17{color:#000;line-height:24px;display:block;font-size:18px;font-weight:600;margin-bottom:20px}._reportContent_xna4e_17 ._title_xna4e_50{margin-top:16px;line-height:24px;display:block;font-size:16px;font-weight:600;margin-bottom:4px;color:#000c}._reportContent_xna4e_17 ._title_xna4e_50 ._icon_xna4e_59{margin-left:8px;display:inline-block;padding:0 6px;border-radius:10px;font-size:12px;font-weight:500}._reportContent_xna4e_17 ._title_xna4e_50 ._success_xna4e_67{background-color:var(--success-color);color:var(--success-bg)}._reportContent_xna4e_17 ._title_xna4e_50 ._warning_xna4e_71{background-color:var(--warning-color);color:var(--warning-bg)}._reportContent_xna4e_17 ._title_xna4e_50 ._fail_xna4e_75{background-color:var(--failure-color);color:var(--failure-bg)}._reportContent_xna4e_17 ._has_issues_xna4e_79{line-height:20px;display:block;font-size:14px;color:#0009}._onlyReportContent_xna4e_85{height:100%!important;max-height:100%!important}._markdown_3p4mr_1{color:var(--words-color)}._markdown_3p4mr_1 table{overflow:hidden;border-radius:16px;border-spacing:0;empty-cells:show;border-collapse:separate;border-bottom:0px;margin-top:8px;margin-bottom:8px}._markdown_3p4mr_1 table thead{background-color:var(--white)!important;color:#121316cc;text-align:left}._markdown_3p4mr_1 table thead th{background-color:#ebecf0!important;vertical-align:middle}._markdown_3p4mr_1 table td,._markdown_3p4mr_1 table th{background-color:var(--white-7);padding:8px 24px;border-width:0 0 0 1px;font-size:inherit;border-bottom:1px solid #EBECF0;margin:0;overflow:visible}._markdown_3p4mr_1 table th{position:relative}._markdown_3p4mr_1 table tr:first-child th:after{top:35%;right:0;content:"";position:absolute;border-right:1px solid #d7d8dd;height:30%}._markdown_3p4mr_1 table tr:first-child th:last-child:after{top:10%;right:0;content:"";position:absolute;border-right:0px!important;height:80%}._markdown_3p4mr_1 pre{font-family:PingFang SC!important;margin-top:4px;margin-bottom:8px}._markdown_3p4mr_1 h1:first-child,._markdown_3p4mr_1 p:first-child,._markdown_3p4mr_1 h2:first-child,._markdown_3p4mr_1 h3:first-child,._markdown_3p4mr_1 h4:first-child,._markdown_3p4mr_1 h5:first-child,._markdown_3p4mr_1 h6:first-child,._markdown_3p4mr_1 ol:first-child{padding-top:0}._markdown_3p4mr_1 h1:last-child{padding-bottom:0}._markdown_3p4mr_1 p:last-child{padding-bottom:0}._markdown_3p4mr_1 h2:last-child{padding-bottom:0}._markdown_3p4mr_1 h3:last-child{padding-bottom:0}._markdown_3p4mr_1 h4:last-child{padding-bottom:0}._markdown_3p4mr_1 h5:last-child{padding-bottom:0}._markdown_3p4mr_1 h6:last-child{padding-bottom:0}._markdown_3p4mr_1 ol:last-child{padding-bottom:0}._markdown_3p4mr_1 p,._markdown_3p4mr_1 h1,._markdown_3p4mr_1 h2,._markdown_3p4mr_1 h3,._markdown_3p4mr_1 h4,._markdown_3p4mr_1 h5,._markdown_3p4mr_1 h6,._markdown_3p4mr_1 ol,._markdown_3p4mr_1 ul,._markdown_3p4mr_1 li{box-sizing:border-box;margin:0;padding-top:4px;padding-bottom:4px}._markdown_3p4mr_1 h1{font-size:20px;line-height:30px;padding-top:20px}._markdown_3p4mr_1 h2{font-size:18px;line-height:28px;padding-top:16px}._markdown_3p4mr_1 h3,._markdown_3p4mr_1 h4,._markdown_3p4mr_1 h5,._markdown_3p4mr_1 h6{font-size:16px;line-height:24px;padding-top:12px}._markdown_3p4mr_1 ul{padding-left:22px}._markdown_3p4mr_1 ul li{list-style-type:circle!important}._markdown_3p4mr_1 ul ol li{list-style-type:decimal!important}._markdown_3p4mr_1 ol{margin-left:36px;margin-inline-start:0px}._markdown_3p4mr_1 ol li{list-style-type:decimal!important}._markdown_3p4mr_1 ol ul li{list-style-type:circle!important}._markdown_3p4mr_1 a{text-decoration:none;color:var(--blue-6)}._markdown_3p4mr_1 hr{margin:24px 0;border:0px;border-bottom:1px solid var(--grey-4)}._markdown_3p4mr_1 code{font-family:SF Mono}._container_t5k03_1{display:flex;flex-direction:column;color:#000}._container_t5k03_1 ._sContainer_t5k03_6{display:flex;flex-direction:column}._subContainer_t5k03_10{display:flex;flex-direction:column;height:calc(100vh - 128px)}._noResult_t5k03_15{font-size:24px;font-weight:400;padding:24px;display:flex;flex-direction:column;align-items:center;justify-content:center;border-radius:8px;height:calc(100vh - 200px);background-color:var(--light-bg);color:var(--words-color)}._noResult_t5k03_15 span{height:36px;line-height:36px;display:block;font-size:36px;font-weight:600;margin-bottom:12px}._noResult_t5k03_15 ._noIcon_t5k03_36{font-size:48px}._badge_t5k03_39{margin-left:8px;display:inline-block;padding:2px 6px;border-radius:10px;font-size:12px;font-weight:500}._badgeSuccess_t5k03_47{background-color:var(--success-bg);color:var(--success-color)}._badgeFailure_t5k03_51{background-color:var(--failure-bg);color:var(--failure-color)}._badgeWarning_t5k03_55{background-color:var(--warning-bg);color:var(--warning-color)}._diy-scrollbar_1kd9e_1::-webkit-scrollbar{width:4px;height:4px}._diy-scrollbar_1kd9e_1::-webkit-scrollbar-track{background-color:transparent}._diy-scrollbar_1kd9e_1::-webkit-scrollbar-thumb{border-radius:10px;background:#ebecf0}._diy-scrollbar_1kd9e_1:hover::-webkit-scrollbar-thumb{border-right:1px solid #ebecf0;border-bottom:1px solid #ebecf0;background:#ebecf0}._container_1kd9e_17{display:flex;gap:20px;height:calc(100% - 218px);flex:1}._container_1kd9e_17 ._badge_1kd9e_23{margin-left:8px;display:inline-block;padding:2px 6px;border-radius:10px;font-size:12px;font-weight:500}._container_1kd9e_17 ._badgeSuccess_1kd9e_31{background-color:var(--success-bg);color:var(--success-color)}._container_1kd9e_17 ._badgeFailure_1kd9e_35{background-color:var(--failure-bg);color:var(--failure-color)}._container_1kd9e_17 ._badgeWarning_1kd9e_39{background-color:var(--warning-bg);color:var(--warning-color)}._container_1kd9e_17 ._screenshots_1kd9e_43{overflow-y:scroll;width:600px;flex:1}._container_1kd9e_17 ._screenshots_1kd9e_43::-webkit-scrollbar{width:4px;height:4px}._container_1kd9e_17 ._screenshots_1kd9e_43::-webkit-scrollbar-track{background-color:transparent}._container_1kd9e_17 ._screenshots_1kd9e_43::-webkit-scrollbar-thumb{border-radius:10px;background:#ebecf0}._container_1kd9e_17 ._screenshots_1kd9e_43:hover::-webkit-scrollbar-thumb{border-right:1px solid #ebecf0;border-bottom:1px solid #ebecf0;background:#ebecf0}._container_1kd9e_17 ._screenshots_1kd9e_43 ._screenshotWrapper_1kd9e_64{margin-bottom:20px;border:1px solid var(--border-color);border-radius:4px;overflow:hidden;scroll-margin-top:20px}._container_1kd9e_17 ._screenshots_1kd9e_43 ._screenshotTitle_1kd9e_71{padding:10px;background-color:var(--light-bg);border-bottom:1px solid var(--border-color);font-weight:500}._container_1kd9e_17 ._screenshots_1kd9e_43 ._screenshot_1kd9e_43{max-width:100%;height:auto;display:block}._container_1kd9e_17 ._left_1kd9e_82{width:250px;min-width:200px;max-width:400px;border:1px solid var(--border-color);overflow-y:auto;padding:10px;border-radius:4px;flex-shrink:0}._container_1kd9e_17 ._left_1kd9e_82::-webkit-scrollbar{width:4px;height:4px}._container_1kd9e_17 ._left_1kd9e_82::-webkit-scrollbar-track{background-color:transparent}._container_1kd9e_17 ._left_1kd9e_82::-webkit-scrollbar-thumb{border-radius:10px;background:#ebecf0}._container_1kd9e_17 ._left_1kd9e_82:hover::-webkit-scrollbar-thumb{border-right:1px solid #ebecf0;border-bottom:1px solid #ebecf0;background:#ebecf0}._container_1kd9e_17 ._left_1kd9e_82 ._stepItem_1kd9e_108{padding:12px 15px;background-color:#fff;border:1px solid var(--border-color);border-radius:4px;margin-bottom:10px;cursor:pointer;transition:all .2s}._container_1kd9e_17 ._left_1kd9e_82 ._stepItem_1kd9e_108:hover{background-color:var(--hover-bg)}._container_1kd9e_17 ._left_1kd9e_82 ._stepItem_1kd9e_108 ._stepNumber_1kd9e_120{font-weight:600;margin-bottom:5px;display:flex;justify-content:space-between;align-items:center}._container_1kd9e_17 ._left_1kd9e_82 ._stepItem_1kd9e_108 ._stepDescription_1kd9e_127{font-size:14px;color:var(--words-color)}._container_1kd9e_17 ._left_1kd9e_82 ._stepItem_1kd9e_108 ._stepTime_1kd9e_131{font-size:12px;color:var(--secondary-color);margin-top:5px}._container_1kd9e_17 ._left_1kd9e_82 ._activeItem_1kd9e_136{border-color:var(--active-color)}._container_1kd9e_17 ._left_1kd9e_82 ._activeItem_1kd9e_136 ._stepNumber_1kd9e_120{color:var(--active-color)!important}._container_1kd9e_17 ._right_1kd9e_142{width:300px;border:1px solid var(--border-color);padding:12px;border-radius:4px;overflow-y:scroll}._container_1kd9e_17 ._right_1kd9e_142::-webkit-scrollbar{width:4px;height:4px}._container_1kd9e_17 ._right_1kd9e_142::-webkit-scrollbar-track{background-color:transparent}._container_1kd9e_17 ._right_1kd9e_142::-webkit-scrollbar-thumb{border-radius:10px;background:#ebecf0}._container_1kd9e_17 ._right_1kd9e_142:hover::-webkit-scrollbar-thumb{border-right:1px solid #ebecf0;border-bottom:1px solid #ebecf0;background:#ebecf0}._container_1kd9e_17 ._right_1kd9e_142 ._actionsList_1kd9e_165{margin-bottom:30px}._container_1kd9e_17 ._right_1kd9e_142 ._actionsList_1kd9e_165 ._actionCard_1kd9e_168{cursor:pointer;transition:background-color .2s}._container_1kd9e_17 ._right_1kd9e_142 ._actionsList_1kd9e_165 ._actionCard_1kd9e_168:hover{background-color:var(--hover-bg)}._container_1kd9e_17 ._right_1kd9e_142 ._actionsList_1kd9e_165 ._success_1kd9e_175{color:var(--success-color);border-color:var(--success-color)}._container_1kd9e_17 ._right_1kd9e_142 ._actionsList_1kd9e_165 ._failure_1kd9e_179{color:var(--failure-color);border-color:var(--failure-color)}._container_1kd9e_17 ._right_1kd9e_142 ._actionsList_1kd9e_165 ._actionHeader_1kd9e_183{padding:10px 15px;display:flex;justify-content:space-between;align-items:center;border-bottom:1px solid var(--border-color)}._container_1kd9e_17 ._right_1kd9e_142 ._actionsList_1kd9e_165 ._actionTitle_1kd9e_190{font-weight:500}._container_1kd9e_17 ._right_1kd9e_142 ._actionsList_1kd9e_165 ._actionResult_1kd9e_193{font-size:13px;font-weight:500}._container_1kd9e_17 ._right_1kd9e_142 ._actionsList_1kd9e_165 ._actionResultSuccess_1kd9e_197{color:var(--success-color)}._container_1kd9e_17 ._right_1kd9e_142 ._actionsList_1kd9e_165 ._actionResultFailure_1kd9e_200{color:var(--failure-color)}._container_1kd9e_17 ._right_1kd9e_142 ._modelIOTitle_1kd9e_203{font-size:16px;font-weight:600;margin-bottom:4px}._container_1tejq_1{display:flex;flex-direction:column}._container_1tejq_1 ._name_1tejq_5{color:#000;font-size:18px;font-weight:600;line-height:60px;height:60px}

webqa_agent/static/i18n/en-US.json

@@ -0,0 +1,127 @@
+{
+  "aggregator": {
+    "assessment_overview": "Overview",
+    "summary_and_advice": "Summary & Advice",
+    "issue_list": "Issue List",
+    "issue_tracker_list": "Issue Tracker List",
+    "issue_list_note": "Note: This list summarizes all detected \"failed\" and \"warning\" items",
+    "assessment_categories": "Test Cases",
+    "passed_count": "Passed",
+    "failed_count": "Failed",
+    "test_failed_prefix": "Test Failed: ",
+    "execution_error_prefix": "Execution Error: ",
+    "llm_prompt_main": "You are an experienced software testing analyst. Please read the following sub-test information and extract [Issue Content], [Issue Count], and [Severity]:\n1) If status = pass, return JSON {\"issue_count\": 0}.\n2) If status != pass, judge based on the specific content of report, metrics, or final_summary:\n   - Extract the most critical one-sentence issue description as issues\n   - Count issue quantity as issue_count (if unable to count accurately, default to 1)\n   - Severity assessment: First check if severity is already marked in the report (like high/medium/low, critical/major/minor, etc.), if so, follow directly; if not clearly marked in report, judge based on issue impact: high (serious impact on functionality/performance), medium (moderate impact), low (minor issues/warnings)\n3) You cannot output any other content or code blocks, only output unified JSON: {\"issue_count\": <number>, \"issues\": \"one-sentence English issue description\", \"severity\": \"high|medium|low\"}.",
+    "llm_prompt_test_info": "Sub-test information: "
+  },
+  "testers": {
+    "basic": {
+      "basic_test_display": "Basic Function Test - ",
+      "accessibility_check": "Accessibility Check",
+      "main_link_check": "Main Link Check",
+      "sub_link_check": "Sub Link Check",
+      "test_results": "Test Results",
+      "clickable_element_check": "Clickable Element Traversal Check",
+      "click_element": "Click Element",
+      "traversal_test_results": "Traversal Test Results",
+      "clickable_elements_count": "Clickable elements",
+      "click_failed_count": ", click actions failed"
+    },
+    "performance": {
+      "core_metrics": "Core Web Vitals",
+      "improve": "Improve",
+      "current_value": "Current value",
+      "target": "Target",
+      "performance_optimization": "Performance Optimization",
+      "potential_savings": "Potential savings",
+      "resource_optimization": "Resource Optimization",
+      "reduce_total_size": "Reduce total page size",
+      "current": "Current",
+      "optimize_third_party": "Optimize third-party resource usage",
+      "performance_diagnosis": "Performance Diagnosis",
+      "seo": "SEO",
+      "images": "images",
+      "links": "links",
+      "example": "e.g.",
+      "overall_score": "Overall Score",
+      "issues_to_improve": "Issues to Improve",
+      "performance_metrics": "Performance Metrics"
+    },
+    "ux": {
+      "ux_test_display": "UX Test - ",
+      "text_check_name": "Text Check",
+      "page_blank_error": "Page is blank, no visible content",
+      "no_issues_found": "No issues found",
+      "report_title": "Text Check",
+      "overall_problem": "**Overall Problem:** ",
+      "issue_details": "### {}. Issue Details\n\n",
+      "location": "**Location:** ",
+      "error_content": "**Current Error:** ",
+      "suggested_fix": "**Suggested Fix:** ",
+      "error_type": "**Error Type:** ",
+      "unknown_location": "Unknown Location",
+      "unknown_type": "Unknown Type",
+      "layout_check_name": "Web Content Check",
+      "element_check_name": "Web Element Check",
+      "report_title_content": "Content Check",
+      "layout_case": "Layout Check",
+      "image_case": "Element Check",
+      "text_case": "Text Typography"
+    },
+    "security": {
+      "cve_scan": "Known CVE Vulnerability Scan",
+      "xss_scan": "Cross-site Scripting Detection",
+      "sqli_scan": "SQL Injection Detection",
+      "rce_scan": "Remote Code Execution Detection",
+      "lfi_scan": "Local File Inclusion Detection",
+      "ssrf_scan": "Server-side Request Forgery Detection",
+      "redirect_scan": "Open Redirect Detection",
+      "exposure_scan": "Sensitive Information Exposure Detection",
+      "config_scan": "Configuration Error Detection",
+      "default_login_scan": "Default Credentials Detection",
+      "ssl_scan": "SSL/TLS Configuration Detection",
+      "dns_scan": "DNS Related Detection",
+      "subdomain_takeover_scan": "Subdomain Takeover Detection",
+      "tech_scan": "Technology Stack Identification",
+      "panel_scan": "Admin Panel Detection",
+      "http_protocol": "HTTP Protocol Scan",
+      "dns_protocol": "DNS Protocol Scan",
+      "tcp_protocol": "TCP Protocol Scan",
+      "ssl_protocol": "SSL Protocol Scan",
+      "critical_vulnerability": "Critical Vulnerability Scan",
+      "high_risk_vulnerability": "High Risk Vulnerability Scan",
+      "medium_risk_vulnerability": "Medium Risk Vulnerability Scan",
+      "no_security_issues": "No related security issues found",
+      "found_issues": "Found {count} issues",
+      "including": "including",
+      "and_more": "and more",
+      "security_check": "Security Check",
+      "no_issues_found": "No issues found",
+      "nuclei_check": "Nuclei Check",
+      "nuclei_not_found": "Nuclei tool not found. Please install nuclei: go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest",
+      "no_severity_issues": "No {severity} level security issues found",
+      "found_severity_issues": "Found {count} {severity} level security issues",
+      "severity_level_scan": "{severity} Level Security Issues Scan",
+      "severity_level_vulnerability": "{severity} Level Security Vulnerability Scan",
+      "matched_at": "Matched at",
+      "extracted": "Extracted",
+      "no_details": "No further details"
+    },
+    "ai_function": {
+        "intelligent_function_test": "Intelligent Function Test"
+    }
+  },
+  "common": {
+    "level": "level",
+    "issues": "issues"
+  },
+  "display": {
+    "completed_tasks": "🎉 Completed Tasks",
+    "running_tasks": "🚀 Running Tasks",
+    "total_time": "⏱️ Total Time",
+    "error_tasks": "⚠️ Error Tasks:",
+    "error_message": "Error Message:",
+    "task_execution_summary": "📊 Task Execution Summary",
+    "no_issues_found": "No issues found"
+  }
+}
+