---
name: browser-testing
description: 定义了使用浏览器开发者工具进行端到端（E2E）测试的工作流，测试用例以 Markdown 文件形式记录。
author: github/cafe3310
license: Apache-2.0
---

# 技能: 基于浏览器的端到端测试

## 1. 概述

本技能定义了一套端到端（E2E）测试流程，该流程不依赖传统的单元测试框架，而是通过 `chrome-dev-tools` 或类似的浏览器工具进行手动或半自动化的界面测试。

所有测试用例都以结构化的 Markdown 文件形式进行记录和管理。

## 2. 何时使用

- 当需要为项目中的某个 Space 应用创建或执行测试时。
- 当需要验证一个功能在本地和部署后是否都按预期工作时。
- 当需要记录测试过程和结果以供回顾时。

## 3. 测试流程

1.  **本地测试优先**: 在本地环境中完成开发后，首先在本地运行应用，并根据测试用例执行端到端测试。
2.  **部署测试**: 本地测试全部通过后，将代码推送到 `main` 分支，触发 Hugging Face Spaces 的自动部署。
3.  **验证部署**: 在部署后的 Space 页面上，重复执行测试用例，确保线上功能与本地一致。

## 4. 测试用例规范

### A) 存放位置

每个 Space 应用的测试用例都存放在其各自的 `tests/` 目录下。例如：`some-proj/tests/`。

### B) 文件结构

每个测试用例都是一个独立的 Markdown 文件，其内容结构由模板 `templates/test-case.md.template` 定义。

-   **文件头**:
    -   **创建时间**: 测试用例创建时的时间戳。
    -   **Commit Hash**: 创建时对应的 Git Commit 哈希值。
    -   **Commit Message**: 创建时对应的 Git Commit 消息。
-   **核心定义**:
    -   **测试名称**: 对测试用例的简短描述。
    -   **测试目的**: 详细说明此测试用例要验证的功能或修复的问题。
-   **环境信息**:
    -   **本地运行和部署方式**: 清晰说明如何在本地启动应用以及如何触发部署。
-   **执行与结果**:
    -   **测试步骤**: 一系列清晰、可复现的操作步骤。
    -   **预期结果**: 描述在执行完测试步骤后，系统应该达到的状态。
    -   **通过时的实际结果**: 当测试成功通过后，在此处记录观察到的实际结果，包括：
        -   **截图路径**: 自动截取的关键页面截图的存储路径。
        -   **验证状态**: 截图内容与预期结果描述比对后的验证结果（通过/不通过）。
        -   **口述标准**: 用户口述的预期结果视觉描述。
        这些记录作为测试通过的凭证。

### C) 创建测试用例

1.  使用 `date +'%Y-%m-%d-%H-%M'` 获取当前时间戳。
2.  使用 `git log -1 --pretty=%H%n%s` 获取最新的 Commit 信息。
3.  复制 `browser-testing/templates/test-case.md.template` 模板内容。
4.  填充模板中的占位符，并编写详细的测试步骤和预期结果。
5.  将新创建的测试用例文件保存到对应 Space 的 `tests/` 目录下。
6.  为每个测试用例创建一个同名的子目录，用于存放截图等测试产物。例如：`some-proj/tests/YYYY-MM-DD-HH-mm-测试名称/`。

## 5. 模板资源

-   `templates/test-case.md.template`: 用于创建新测试用例的 Markdown 模板。