Skip to content
GitLab
Commit 2d662da1 authored by liguangyu06's avatar liguangyu06
Browse files

Stop tracking Cursor IDE config; Playwright tests do not need .cursor.

parent 86bbe72c
Pipeline #36420 failed with stage
in 1 second
Hide whitespace changes
Inline Side-by-side
.cursor/mcp.json deleted 100644 → 0
View file @ 86bbe72c
{
"mcpServers": {
"playwright-test": {
"command": "npx",
"args": [
"playwright",
"run-test-mcp-server"
]
}
}
}
.cursor/rules/API-code-rules.mdc deleted 100644 → 0
View file @ 86bbe72c
---
alwaysApply: false
rule_name: API接口自动化测试代码生成规范
version: V2.1
pair_rules:
- API-testcase-csv-rules.mdc
scene: CSV 数据驱动接口自动化、按规范生成/维护可运行项目；CSV 表头与用例编写约束以 pair_rules 为准，本文件侧重目录、代码与运行时行为。
---
# API 接口自动化测试代码生成规则（V2.1）
## 概述
本规范用于根据**标准 CSV 测试用例文件**，自动生成可运行的 **Python + pytest + requests + allure** 接口自动化测试项目。
**与 CSV 规则分工：** 用例文件如何编写（表头、枚举、条数、纯 CSV 输出等）见 **API-testcase-csv-rules.mdc**；本文件规定**如何解析 CSV、项目结构、请求封装、断言与模板代码**。
**核心能力：**
1. 以 CSV 管理接口用例，用例与代码解耦
2. 生成分层架构、配置、核心封装与工具类
3. 按 `module` 拆分测试文件，pytest 数据驱动执行
4. 统一请求封装、多环境、日志、异常重试
5. 分层断言（非全量响应体硬匹配）
6. Allure 报告：用例 ID、优先级、严重级别、标签、模块、步骤
7. 预留前置/后置、JSON 容错、动态变量等扩展
---
## 一、标准 CSV 用例规范（与用例生成规则对齐）
### 1.1 固定列（顺序不可变）
与 **API-testcase-csv-rules.mdc** 中表头**完全一致**，不可增删或调序：
```text
test_case_id,test_case_name,module,api_name,method,url,content_type,headers,request_data,preconditions,postconditions,expected_status_code,expected_key_assert,expected_value_assert,test_type,priority,tags,description
```
### 1.2 字段说明（代码侧解析要点）
| 列名 | 说明 |
|------|------|
| test_case_id | 用例唯一 ID，供 Allure `dynamic.id` |
| test_case_name | 用例名称 |
| module | 业务模块，**与** `test_{module}.py` 及 `get_case_by_module` 过滤**一致** |
| api_name | 接口名称 / Allure story |
| method | GET / POST / PUT / DELETE（大写） |
| url | 相对 `base_url` 的路径 |
| content_type | `json` / `form` / `form-data` |
| headers | JSON 字符串；无则 `""` 或 `"{}"`（`json.loads` 前作空判断，见模板） |
| request_data | JSON 字符串；无则 `""` 或 `"{}"` |
| preconditions | 前置说明；无则填 `无`；`exec_pre_condition` 扩展用 |
| postconditions | 后置说明；无则填 `无`；`exec_post_condition` 扩展用 |
| expected_status_code | 期望 HTTP 状态码（整型） |
| expected_key_assert | 响应 JSON **顶层**需存在的字段；**多个**用英文逗号分隔，模板中**逐字段**断言存在 |
| expected_value_assert | 精准值；`key=value`；**多组**用英文逗号分隔，模板中**逐组**断言（值内避免未转义逗号，或自行加强解析） |
| test_type | positive / negative / boundary |
| priority | high / medium / low，映射 Allure severity |
| tags | 英文逗号分隔，用于 `allure.dynamic.tag` |
| description | 用例描述 |
### 1.3 CSV 与运行态约束
1. 除 preconditions/postconditions 的「无」外，空值统一为**空字符串**；禁止 `null`、`NaN`（与用例规则一致）。
2. `headers` / `request_data` 须为合法 JSON 或空；非法时单条用例内**容错**为**空字典**（`json.JSONDecodeError`），不拖垮整模块加载。
3. `module` 稳定命名，作为**按模块拆分文件**与过滤用例的**唯一键**。
4. 禁止**全量响应体**硬匹配；采用**状态码 + 多字段存在性 + 多组 key=value**（与模板实现一致）。
### 1.4 标准 CSV 示例
```csv
test_case_id,test_case_name,module,api_name,method,url,content_type,headers,request_data,preconditions,postconditions,expected_status_code,expected_key_assert,expected_value_assert,test_type,priority,tags,description
API-USER-001,正常登录成功,user,用户登录,POST,/api/user/login,json,"{}","{""username"":""test"",""password"":""123456""}",无,无,200,code,code=200,positive,high,smoke,正向登录场景
API-USER-002,密码错误登录失败,user,用户登录,POST,/api/user/login,json,"{}","{""username"":""test"",""password"":""error""}",无,无,400,msg,msg=密码错误,negative,medium,login,反向异常场景
```
> 说明：JSON 列在 CSV 中双引号转义为 `""`；**新产用例**的完整约束见 **API-testcase-csv-rules.mdc**。
---
## 二、项目固定目录结构
```text
api_autotest/
├── .env
├── conftest.py
├── pytest.ini
├── requirements.txt
├── config/
│ ├── __init__.py
│ ├── config.yaml
│ └── config.py
├── core/
│ ├── __init__.py
│ ├── api_client.py
│ ├── logger.py
│ └── assertions.py
├── data/
│ └── test_cases.csv
├── testcases/
│ ├── __init__.py
│ ├── conftest.py
│ └── test_xxx.py
└── utils/
├── __init__.py
├── data_handler.py
├── var_render.py
└── common.py
```
---
## 三、配置文件规范
### 3.1 `.env`（环境变量，勿提交真实密钥到版本库）
```env
TEST_ENV=test
LOGIN_USER=test_admin
LOGIN_PASS=123456abc
COMMON_TOKEN=
```
### 3.2 `config/config.yaml`
```yaml
env:
test:
base_url: "http://test-api.example.com"
timeout: 30
dev:
base_url: "http://dev-api.example.com"
timeout: 30
prod:
base_url: "https://api.example.com"
timeout: 30
headers:
Content-Type: "application/json"
User-Agent: "AutoTest-V2.1"
logging:
level: INFO
format: "%(asctime)s | %(levelname)s | %(name)s | %(message)s"
file: "logs/api_test.log"
```
### 3.3 `config/config.py`（单例加载 YAML + dotenv）
```python
import os
import yaml
from dotenv import load_dotenv
from typing import Dict, Any
load_dotenv()
class Config:
_instance = None
_config_data: Dict[str, Any] = {}
def __new__(cls):
if cls._instance is None:
cls._instance = super().__new__(cls)
return cls._instance
def __init__(self):
if not self._config_data:
self.load_config()
def load_config(self):
config_path = os.path.join(os.path.dirname(__file__), "config.yaml")
with open(config_path, "r", encoding="utf-8") as f:
self._config_data = yaml.safe_load(f)
@property
def env(self) -> str:
return os.getenv("TEST_ENV", "test")
@property
def base_url(self) -> str:
return self._config_data["env"][self.env]["base_url"]
@property
def global_headers(self) -> Dict[str, str]:
return self._config_data["headers"]
@property
def timeout(self) -> int:
return self._config_data["env"][self.env]["timeout"]
```
### 3.4 `pytest.ini`
```ini
[pytest]
addopts = -v -s --alluredir=./allure-results --strict-markers
testpaths = testcases
python_files = test_*.py
python_classes = Test*
python_functions = test_*
markers =
smoke: 冒烟测试用例
positive: 正向用例
negative: 反向用例
boundary: 边界用例
high: 高优先级用例
medium: 中优先级用例
low: 低优先级用例
```
### 3.5 `requirements.txt`
```text
pytest>=7.4.0
allure-pytest>=2.13.0
requests>=2.31.0
pyyaml>=6.0.1
pandas>=2.0.0
python-dotenv>=1.0.0
urllib3>=2.0.0
```
---
## 四、核心公共组件
### 4.1 `core/logger.py`
```python
import logging
import os
from config.config import Config
conf = Config()
log_path = conf._config_data["logging"]["file"]
os.makedirs(os.path.dirname(log_path), exist_ok=True)
logging.basicConfig(
level=conf._config_data["logging"]["level"],
format=conf._config_data["logging"]["format"],
handlers=[
logging.FileHandler(log_path, encoding="utf-8"),
logging.StreamHandler()
],
)
logger = logging.getLogger("api_auto_test")
```
### 4.2 `core/api_client.py`
```python
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
from typing import Dict, Any, Optional
from core.logger import logger
from config.config import Config
class ApiClient:
def __init__(self):
self.config = Config()
self.session = requests.Session()
self.session.headers.update(self.config.global_headers)
retry = Retry(total=2, backoff_factor=0.5, status_forcelist=[500, 502, 503, 504])
adapter = HTTPAdapter(max_retries=retry)
self.session.mount("http://", adapter)
self.session.mount("https://", adapter)
def request(
self,
method: str,
url: str,
headers: Optional[Dict[str, str]] = None,
data: Optional[Dict[str, Any]] = None,
content_type: str = "json",
**kwargs,
) -> requests.Response:
full_url = f"{self.config.base_url}{url}"
merge_headers = {**self.session.headers, **(headers or {})}
try:
logger.info(f"【{method.upper()}】{full_url}")
logger.debug(f"请求头：{merge_headers}")
logger.debug(f"请求参数：{data}")
if content_type == "json":
resp = self.session.request(
method=method,
url=full_url,
headers=merge_headers,
json=data,
timeout=self.config.timeout,
**kwargs,
)
else:
resp = self.session.request(
method=method,
url=full_url,
headers=merge_headers,
data=data,
timeout=self.config.timeout,
**kwargs,
)
logger.info(f"响应码：{resp.status_code}")
logger.debug(f"响应内容：{resp.text[:800]}")
return resp
except Exception as e:
logger.error(f"请求异常：{str(e)}")
raise
```
### 4.3 `core/assertions.py`
```python
import allure
from requests import Response
class ApiAssertions:
@staticmethod
@allure.step("校验响应状态码")
def assert_status_code(resp: Response, expect_code: int):
assert resp.status_code == expect_code, (
f"状态码错误，期望：{expect_code}，实际：{resp.status_code}"
)
@staticmethod
@allure.step("校验关键字段存在")
def assert_key_exists(resp: Response, expect_key: str):
res = resp.json()
assert expect_key in res, f"缺失字段：{expect_key}"
@staticmethod
@allure.step("校验字段精准值")
def assert_key_equal(resp: Response, key: str, expect_val):
res = resp.json()
assert res.get(key) == expect_val, f"{key} 期望：{expect_val}，实际：{res.get(key)}"
@staticmethod
@allure.step("校验响应包含文本")
def assert_resp_contains(resp: Response, text: str):
assert text in resp.text, f"响应未包含：{text}"
```
---
## 五、工具类
### 5.1 `utils/data_handler.py`
```python
import pandas as pd
from typing import List, Dict, Any
class DataHandler:
@staticmethod
def load_all_cases(csv_path: str = "data/test_cases.csv") -> pd.DataFrame:
df = pd.read_csv(csv_path, dtype=str)
df = df.fillna("")
return df
@staticmethod
def get_case_by_module(module_name: str) -> List[Dict[str, Any]]:
df = DataHandler.load_all_cases()
filter_df = df[df["module"] == module_name]
return filter_df.to_dict("records")
```
### 5.2 `utils/var_render.py`（动态变量预留）
```python
class VarRender:
@staticmethod
def render_params(data: str, context: dict = None) -> str:
if not context:
context = {}
return data
```
---
## 六、全局 `conftest.py`（根目录）
```python
import pytest
from core.api_client import ApiClient
from utils.data_handler import DataHandler
@pytest.fixture(scope="session")
def api_client():
return ApiClient()
@pytest.fixture(scope="session")
def all_cases_data():
return DataHandler.load_all_cases()
def exec_pre_condition(pre_str: str, client: ApiClient):
if not pre_str.strip():
return
# 预留：登录、造数、调依赖接口等
def exec_post_condition(post_str: str, client: ApiClient):
if not post_str.strip():
return
# 预留：清理数据、登出等
```
---
## 七、按模块测试文件生成模板
**路径：** `testcases/test_{module}.py`
**约定：**
- `pytest.mark.parametrize` **不要**直接参数化 `fixture`；在模块内用 `DataHandler.get_case_by_module` 取列表。
- `headers` / `request_data` 必须 `try/except`，单条用例失败不阻断整模块加载。
- 按 `test_type`、`priority` 可映射为 pytest mark / allure severity（示例见下）。
```python
import pytest
import allure
import json
from core.assertions import ApiAssertions
from utils.data_handler import DataHandler
from conftest import exec_pre_condition, exec_post_condition
CUR_MODULE = "user"
case_list = DataHandler.get_case_by_module(CUR_MODULE)
severity_map = {
"high": allure.severity_level.CRITICAL,
"medium": allure.severity_level.NORMAL,
"low": allure.severity_level.MINOR,
}
@allure.feature(f"{CUR_MODULE} 业务模块接口")
class TestApiUser:
@pytest.mark.parametrize("case", case_list)
def test_api_case(self, api_client, case):
allure.dynamic.id(case["test_case_id"])
allure.dynamic.title(case["test_case_name"])
allure.dynamic.story(case["api_name"])
allure.dynamic.description(case["description"])
allure.dynamic.severity(severity_map.get(case["priority"]))
tag_list = [t.strip() for t in case["tags"].split(",") if t.strip()]
allure.dynamic.tag(*tag_list)
exec_pre_condition(case["preconditions"], api_client)
try:
headers = json.loads(case["headers"]) if case["headers"] else {}
except json.JSONDecodeError:
headers = {}
try:
req_data = json.loads(case["request_data"]) if case["request_data"] else {}
except json.JSONDecodeError:
req_data = {}
with allure.step(f"{case['method']} 请求：{case['url']}"):
resp = api_client.request(
method=case["method"],
url=case["url"],
headers=headers,
data=req_data,
content_type=case["content_type"],
)
ApiAssertions.assert_status_code(resp, int(case["expected_status_code"]))
if case["expected_key_assert"]:
for key in (k.strip() for k in case["expected_key_assert"].split(",") if k.strip()):
ApiAssertions.assert_key_exists(resp, key)
if case["expected_value_assert"]:
for pair in (p.strip() for p in case["expected_value_assert"].split(",") if "=" in p.strip()):
k, v = pair.split("=", 1)
ApiAssertions.assert_key_equal(resp, k.strip(), v.strip())
exec_post_condition(case["postconditions"], api_client)
```
> 多字段/多键值用**英文逗号**分隔；`expected_value_assert` 的**值**中若需含逗号，应调整解析策略或避免在 CSV 中未转义使用。`json` 解析已用 `except json.JSONDecodeError`（上例）。
---
## 八、执行命令
```bash
# 安装依赖
pip install -r requirements.txt
# 全量执行
pytest
# 按标记（如冒烟）
pytest -m smoke
# 本地查看 Allure 报告
allure serve allure-results
```
---
## 九、关键修复与约束（必须遵守）
| 项 | 要求 |
|----|------|
| 参数化与 fixture | 禁止 `parametrize` 直接引用 `fixture`；在代码内读 CSV 并按 `module` 过滤 |
| JSON 解析 | 所有从 CSV 读入的 JSON 串必须异常捕获，避免单条用例导致整段导入失败 |
| 断言策略 | 禁用全量响应断言；使用：状态码 + 字段存在 + 单键值（或少量键值） |
| 凭据与密钥 | 敏感信息放 `.env`；禁止硬编码到测试代码与 CSV（若 CSV 需占位符，走变量渲染扩展） |
| 多环境 | 通过 `TEST_ENV` 切换 `config.yaml` 中 `env` 段 |
| Allure | 自动挂接：用例 ID、名称、故事、描述、严重等级、标签 |
| 扩展 | 预留：动态变量、DB 断言、接口依赖链（`preconditions` / `postconditions` 中实现） |
---
## 十、版本与适用场景
- **版本：** V2.1（与 frontmatter `version` 一致）
- **场景：** 从标准 CSV 生成/维护可运行工程、统一用例与 Allure 报告形态。
**规则冲突时：** 以**用例 CSV 形态、列与枚举**为 **API-testcase-csv-rules.mdc** 优先；**项目结构、请求与断言语义**以本文件优先；若项目内另有 `AGENTS.md` 等更新约定，以**项目内最新**为准。
.cursor/rules/API-testcase-csv-rules.mdc deleted 100644 → 0
View file @ 86bbe72c
---
alwaysApply: true
rule_name: 标准接口测试用例CSV生成规则
version: V1.2
depend_rules:
- API-code-rules.mdc
pair_rules:
- API-code-rules.mdc
scene: 生成与《API接口自动化测试代码生成规范》一致的 CSV；下列条款为强制约束。字段语义与代码解析方式以 pair_rules 中代码规范为准。
---
## 一、规则目标与协作关系
**目标：** 根据接口文档、地址、参数与业务逻辑，生成可直接放入 `data/test_cases.csv` 的标准 UTF-8 CSV，无需改表头结构即可被自动化项目加载。
**协作：** CSV 列定义、枚举取值与 `headers`/`request_data` 的 JSON 格式须与 **API-code-rules.mdc** 中 `DataHandler` + `json.loads` 解析方式一致；生成用例时若存在歧义，以代码规范中的模板与断言逻辑为准。
---
## 二、必须遵守的核心规则（生成 CSV 时强制执行）
生成或补全接口测试用例 CSV 时，**必须**满足下列全部条款；**不得**因用户未复述某条而降低标准。
### 2.1 编码、表头与结构
1. **编码与形态**：输出为标准 **UTF-8** **CSV 纯文本**；禁止附带说明文字、Markdown 表格、注释或前言后记。
2. **表头**：第一行**必须且仅能**为第三节中的一行表头，顺序不可变、列不可缺。
3. **行结构**：每条用例一行；禁止多余空行；字段含逗号、换行时按 **RFC 4180** 用双引号包裹字段。
4. **空值**：除 `preconditions`/`postconditions` 填「无」外，其余列空值统一为 **空字符串** `""`；禁止 `null`、`NaN`、仅空格。
5. **headers / request_data**：须为 **合法 JSON 字符串**（双引号键名与字符串值），以便代码中 `json.loads` 解析；CSV 单元格内双引号转义为 `""`。无请求头填 `"{}"`，无请求体填 `"{}"`（与 API-code-rules 示例一致）。支持占位如 `${token}`。
### 2.2 用例数量与类型
1. 每接口至少 **2** 条：正向（`positive` + `high`）、反向（`negative` + `medium`）。
2. 有长度/范围/格式限制时，**额外**至少 **1** 条边界（`boundary` + `low`）。
3. 覆盖必填、异常、空值、格式错误及边界；`description` 与断言与场景一致。
### 2.3 字段取值摘要（细则见第四节）
| 列 | 强制摘要 |
|----|-----------|
| test_case_id | `API-{module小写}-{3位序号}`，全文件唯一 |
| method | `GET` / `POST` / `PUT` / `DELETE` |
| content_type | `json` / `form` / `form-data` |
| preconditions / postconditions | 无则填 **无**（不用空字符串表示「无」） |
| expected_key_assert | 多个字段名用英文逗号分隔；值内勿含未转义逗号 |
| expected_value_assert | 多组 `key=value`，组间英文逗号分隔；值若含逗号需约定不含或与代码解析策略一致 |
### 2.4 交付形态
1. 默认**只输出可直接保存的 CSV 正文**；用户明确要求「放在代码块里」时可用 Markdown 代码块便于复制。
2. 结果须可直接保存为 `test_cases.csv` 放入项目 `data` 目录，无需改表头。
---
## 三、CSV 固定表头（顺序不可变）
```text
test_case_id,test_case_name,module,api_name,method,url,content_type,headers,request_data,preconditions,postconditions,expected_status_code,expected_key_assert,expected_value_assert,test_type,priority,tags,description
```
---
## 四、字段生成规则（与自动化代码兼容）
1. **test_case_id**：`API-{module}-{序号}`；`module` 与 **module** 列一致；全局不重复。
2. **test_case_name**：**场景 + 结果**，简短可读。
3. **module**：小写英文，与生成文件 `testcases/test_{module}.py` 及 `DataHandler.get_case_by_module` 过滤一致。
4. **api_name**：接口功能，中文，与文档一致。
5. **method**：仅 `GET`、`POST`、`PUT`、`DELETE`。
6. **url**：相对路径，不含域名（`base_url` 在 `config.yaml`）。
7. **content_type**：仅 `json`、`form`、`form-data`，与 `ApiClient.request` 分支一致。
8. **headers**：JSON 字符串；无则 `"{}"`。
9. **request_data**：JSON 字符串；无则 `"{}"`。
10. **preconditions / postconditions**：无则 **无**。
11. **expected_status_code**：整数 HTTP 状态码。
12. **expected_key_assert**：响应 JSON **顶层**字段存在性校验；多个字段名英文逗号分隔（与代码循环断言一致）；无则空字符串。
13. **expected_value_assert**：`key=value`；多组英文逗号分隔；无则空字符串。
14. **test_type**：`positive` / `negative` / `boundary`。
15. **priority**：`high` / `medium` / `low`（默认正向 high、反向 medium、边界 low）。
16. **tags**：英文逗号分隔；无则空字符串。
17. **description**：场景、目的、校验点。
---
## 五、使用者提供接口信息
用户只需提供 **【接口信息】**（地址、Method、`content_type`、参数、模块、约束等）；**不要求**粘贴固定口令。生成方仍须完整执行本节至第四节。
---
## 六、示例（goods 查询）
**接口信息摘要：** `GET` `/api/goods/getDetail`，`json`，参数 `goodsId`（1–99999），模块 `goods`。
```csv
test_case_id,test_case_name,module,api_name,method,url,content_type,headers,request_data,preconditions,postconditions,expected_status_code,expected_key_assert,expected_value_assert,test_type,priority,tags,description
API-GOODS-001,商品ID合法查询详情成功,goods,商品详情查询接口,GET,/api/goods/getDetail,json,"{}","{""goodsId"":12345}",商品已存在,无,200,"code,data,msg","code=200",positive,high,"smoke,goods,query",正向：合法 goodsId，校验状态码与 code
API-GOODS-002,商品ID为空查询失败,goods,商品详情查询接口,GET,/api/goods/getDetail,json,"{}","{""goodsId"":""""}",商品已存在,无,400,"code,msg","code=400",negative,medium,"goods,query",反向：空 goodsId
API-GOODS-003,商品ID超出范围查询失败,goods,商品详情查询接口,GET,/api/goods/getDetail,json,"{}","{""goodsId"":100000}",商品已存在,无,400,"code,msg","code=400",boundary,low,"goods,query,boundary",边界：超出范围
```
---
## 七、闭环与注意事项
1. 生成 CSV → 保存 `data/test_cases.csv` → 按 **API-code-rules.mdc** 生成/维护测试代码 → `pip install -r requirements.txt` → `pytest`，按需 Allure。
2. 接口信息越完整，用例越准；生成后核对表头与列数、RFC 4180 引号。
3. `${token}` 等与 `var_render` 扩展配合；多接口时注意 **test_case_id** 不重复、**module** 命名统一。
.cursor/rules/automation-testcase-design-principles.mdc deleted 100644 → 0
View file @ 86bbe72c
---
alwaysApply: true
---
# UI / API 自动化测试用例设计原则
本规则约定**自动化用例**层面的设计原则（与功能测试 MD 结构化规范、CSV 表头规范分工：前者管人工/文档用例形态，后者管数据驱动契约）。编写或评审 UI/API 自动化脚本时遵循本文。
---
## 第一部分：UI 自动化测试用例设计
### 一、核心设计原则
1. **业务优先级原则**
优先覆盖核心主流程、高频场景、高危场景，放弃边缘低频、临时活动、极少变更页面。自动化只做稳定、高价值的用例，不追求 100% 覆盖。
2. **单一职责原则**
一条用例只验证一个核心业务结果（如：登录成功是否进入首页、加购后数量是否 +1）。用例内部可以有多个操作步骤，但断言只有一个。失败时能立即定位是哪个业务点出了问题。
3. **原子化、可复用原则**
将公共操作（登录、退出、弹窗处理、下拉选择）封装为独立方法。用例层只调用这些方法，不重复编写步骤。一处维护，处处生效。
4. **独立性原则**
每条用例独立执行，互不依赖，不依赖上一条用例的执行结果。可单独运行，也可批量并行，执行顺序不影响结果。用例执行前需保证初始状态一致。
5. **正向优先、兼顾反向原则**
优先覆盖正向正常流程，确保核心功能可用。再补充关键反向异常场景：非法输入、边界值、网络异常、权限不足、重复提交等。
6. **稳定性优先原则**
优先使用稳定定位方式：`id` > `accessibility-id` > 相对 xpath。对于动态元素（随机 ID、时间戳、动态文案），使用包含匹配、正则匹配或向上查找稳定父节点的方式定位。避免绝对 xpath 和固定坐标。
7. **断言精准原则**
每步关键操作后必有断言，不只跑通流程。断言只校验核心关键字段/状态，不做过度断言（如 UI 样式、间距等），避免微小 UI 变更导致误失败。
8. **数据隔离原则**
使用独立测试账号、独立测试数据，支持参数化。用例执行前后做好数据清理/重置（如退出登录、清空购物车），避免数据污染影响其他用例。
9. **可维护性原则（POM）**
采用 Page Object Model 分层设计：
- 元素定位器放在 Page 类顶部
- 操作方法放在 Page 类中
- 用例层只调用 Page 方法
页面改版时，只需修改 Page 类中的定位器，用例代码尽量不改。同时保持用例命名规范、步骤注释清晰。
10. **适配兼容性原则**
设计时考虑多分辨率、多设备、横竖屏切换等场景。避开固定坐标点击，使用相对布局或百分比定位。移动端注意 iOS/Android 的控件差异。
11. **快速失败原则**
每个关键操作后设置超时断言（如 10–15 秒），不要仅依赖全局过长等待。用例执行过程中一旦发现无法继续的失败（如元素找不到），立即抛出明确错误信息，包含：
- 失败步骤名称
- 预期元素定位器
- 当前页面截图
便于快速判断是元素变更还是业务缺陷。
### 二、UI 自动化不适合写用例的场景
| 场景类型 | 原因 |
|---------|------|
| 频繁迭代、页面经常改版的临时功能 | 维护成本高于收益 |
| 纯 UI 展示、无业务逻辑的静态页面 | 价值低，手工目测更快 |
| 复杂验证码、人机校验无法绕过的场景 | 自动化难以处理 |
| 极低频次、几乎不会回归的边缘功能 | 投入产出比低 |
| 视觉细节（像素级配色、字体间距、动画效果） | 适合人工或视觉 diff 工具 |
### 三、原则分组速记（按职责）
| 分组 | 包含原则 | 一句话记忆 |
|------|-----------|------------|
| 选什么 | 1. 业务优先级、10. 适配兼容性 | 只测高价值稳定场景 |
| 怎么写 | 2. 单一职责、3. 原子复用、4. 独立性、5. 正向+反向 | 用例独立、步骤可复用、断言单一 |
| 怎么稳 | 6. 稳定性优先、7. 断言精准、11. 快速失败 | 稳定定位、精准断言、快速失败 |
| 怎么维护 | 8. 数据隔离、9. 可维护性 | 数据独立、POM 分层 |
### 四、一句话总结（UI）
选高价值稳定场景，用例独立且断言单一；步骤原子化复用，POM 分层易维护；动态元素稳定定位，失败时有截图有提示，快速定位根因。
---
## 第二部分：API 自动化测试用例设计
### 一、核心设计原则
1. **业务优先级原则**
优先覆盖核心接口、高频调用、读写操作（POST/PUT/DELETE），其次是查询类接口（GET）。对于低频、内部管理类、即将下线的接口，不优先自动化。
2. **单一职责原则**
一条用例只验证一个接口的一种响应情况（如：正常参数返回 200、缺少参数返回 400）。不要把多个接口、多种断言塞进一条用例。
- 正确示例：`test_login_success`、`test_login_wrong_password`
- 错误示例：`test_login_and_query_and_update`
3. **全链路覆盖原则**（相对 UI 的「原子复用」）
单接口用例保证基础正确性后，需设计业务场景串联用例（如：登录 → 查询 → 更新 → 删除）。每个步骤的响应数据作为下一步的输入参数，验证完整业务流程。
4. **独立性原则**
每条用例独立执行，互不依赖。不假定其他用例先执行，不依赖用例执行顺序。用例执行前需准备好前置数据，执行后清理产生的数据（尤其是写入操作）。
5. **正向优先、兼顾反向原则**
先覆盖正向用例：正常参数、必填参数、正确类型、边界内值。再补充反向用例：参数缺失、参数类型错误；边界值超限、空值、超长字符串；未授权访问、Token 过期、权限不足；重复提交、资源不存在等。
6. **幂等性原则（针对 PUT/DELETE）**
重复执行同一用例多次，结果应一致。不应出现第一次成功、第二次报错的情况。对于非幂等的业务操作（如扣款），需在用例中做好数据重置。
7. **断言精准原则**
不只看 HTTP 状态码（如 200），必须校验响应体关键字段：业务状态码（如 `code`）、返回消息（如 `message`）、核心数据字段（如 `id`、`status`）、数据结构（如数组长度、字段类型）。
**反例**：只断言 `response.status_code == 200`，接口业务错误但状态码仍为 200 时用例仍会通过。
8. **数据隔离原则**
使用独立测试数据，不依赖生产或共享环境数据。每条用例执行前自己创建所需数据（或从隔离库获取），执行后自行清理。避免用例间数据污染。
9. **可维护性原则**
采用分层设计：
- 配置层：环境 URL、超时时间、通用 Header
- 数据层：测试数据与代码分离（JSON/YAML/Excel 等）
- 接口封装层：每个接口封装为独立方法，统一处理请求、日志、重试
- 用例层：只调用封装方法，不出现裸 HTTP 细节散落
10. **环境适配原则**
支持多环境切换（开发/测试/预发/生产），不硬编码 IP 或域名。通过配置文件或环境变量控制；且不在预发/生产环境执行写操作用例。
11. **快速失败原则**
设置合理超时（通常 3–5 秒），不无限等待。断言失败时立即终止用例，并输出：请求 URL + 请求体；响应状态码 + 响应体；期望值 vs 实际值。
### 二、API 自动化不适合写用例的场景
| 场景类型 | 原因 |
|---------|------|
| 一次性接口、临时活动接口 | 开发完即下线，投入无回报 |
| 强依赖第三方、无法 Mock 的接口 | 不稳定、不可控 |
| 纯透传、无业务逻辑的代理接口 | 无验证价值 |
| 需要人工审批/扫码/OTP 的接口 | 无法完全自动化 |
| 接口响应数据结构频繁变更 | 维护成本高 |
### 三、一句话总结（API）
选核心读写接口，用例独立且校验响应体；封装接口方法支持场景串联；数据自建自清保证幂等；失败时输出请求响应详情，快速定位根因。
---
## 与仓库内其他规则的关系
- **功能/结构化 MD 用例**：见 `testcase_structured_witing_specification.mdc`。
- **测试点分析**：见 `test-point-rules.mdc`。
- **接口 CSV 表头与生成约束**：见 `API-testcase-csv-rules.mdc`；**接口自动化代码与解析**：见 `API-code-rules.mdc`。
- 本文不替代上述文件的格式与契约，仅补充**自动化用例设计与选型**层面的原则。
.cursor/rules/knowledge-base-governance.mdc deleted 100644 → 0
View file @ 86bbe72c
---
alwaysApply: false
description: 工作区 knowledge-base 目录结构、全局编号、YAML 元数据强制项、治理流程与各库 INDEX 维护约定；编辑或新建知识库 Markdown 时启用
globs: knowledge-base/**/*.md
---
# 测试与质量知识库（治理规则）
本规则与仓库内 **`knowledge-base/`** 目录一一对应。Agent 或成员在**新建、修改、拆分、索引**该目录下任意 `.md` 时，须遵守本节；细则以 `knowledge-base/09-知识库治理规范/` 下文件为准。
---
## 一、完整目录（须保持文件夹名称一致）
```text
knowledge-base/
├── 01-业务规则库/
│ └── INDEX.md
├── 02-历史缺陷库/
│ └── INDEX.md
├── 03-接口契约库/
│ └── INDEX.md
├── 04-业务流程旅程库/
│ └── INDEX.md
├── 05-测试资产用例库/
│ ├── INDEX.md
│ ├── API用例矩阵/
│ ├── UI-E2E用例/
│ ├── 自动化失败用例登记/
│ └── Flaky不稳定用例治理/
├── 06-测试问题沉淀库/
│ └── INDEX.md
├── 07-测试数据资产库/
│ └── INDEX.md
├── 08-UI专项规范库/
│ └── INDEX.md
└── 09-知识库治理规范/
├── INDEX.md
├── 01-全局编号命名规范.md
├── 02-通用文档元数据模板.md
├── 03-文档变更更新流程.md
└── 04-版本复盘落地机制.md
```
---
## 二、全局固定配置（优先阅读）
| 文档 | 作用 |
|------|------|
| `09-知识库治理规范/01-全局编号命名规范.md` | 各库**编号前缀**、**文件名 = 完整编号.md**、业务域简写、状态枚举、与 CSV 用例 ID 并存时的互链说明 |
| `09-知识库治理规范/02-通用文档元数据模板.md` | **所有** `knowledge-base/**/*.md` 文件头须使用的 **YAML** 模板与字段说明 |
---
## 三、YAML 元数据（强制）
以下键**不可删减**（值可为空字符串 `""`），须出现在每个 `.md` 文件最上方的 YAML front matter 中：
`title`、`module`、`status`、`related_br`、`related_api`、`related_jrn`、`related_tc`、`related_def`、`create_time`、`update_time`、`author`
新建文档：先粘贴 `02-通用文档元数据模板.md` 中的代码块，再写正文。
---
## 四、各库 INDEX 职责
- 每个编号库根下的 **`INDEX.md`** 为**台账**：新增/变更/废弃条目时，**同步更新**表格行与维护人、时间、状态。
- 各库「说明 / 关联指引 / 枚举」以已落盘的 `INDEX.md` 为准；Agent 补全内容时不得删除既有章节标题结构。
---
## 五、治理原则（摘要）
1. 需求变更 → 同步 **业务规则**、**接口契约**、**流程旅程**。
2. Bug 修复 → 新增或关联 **回归用例**（`related_tc`）。
3. 接口迭代 → 同步 **API 用例矩阵** 与 **UI 关联**说明。
4. 每版本结束 → 按 `04-版本复盘落地机制.md` 将结论落入对应库。
流程细节：`03-文档变更更新流程.md`、`04-版本复盘落地机制.md`。
---
## 六、与项目其他规则的衔接
- **API CSV 用例表头与断言**：仍以 `API-testcase-csv-rules.mdc`、`API-code-rules.mdc` 为准；知识库中的 `API-*`、`TC-API-*` 通过 `related_tc` / 文档描述与之**互链**，避免重复定义冲突。
- **自动化用例设计原则**：见 `automation-testcase-design-principles.mdc`。
- **功能结构化用例（MD H1–H6）**：见 `testcase_structured_witing_specification.mdc`；与 `05-测试资产用例库` 可并存，职责不同需在元数据或正文中标明。
---
## 七、Agent 操作约束
1. 在 `knowledge-base/` 下**新建** `.md`：必须使用规范 **文件名**（见 `01-全局编号命名规范.md`）与 **YAML** 头。
2. **禁止**删除各库 `INDEX.md` 中的固定表格列名；无内容时保留空行或用占位说明「暂无」。
3. 修改条目内容时，**必须**更新该文件的 `update_time`；若影响其他库，联动更新对应 `related_*` 与相关 `INDEX.md`。
.cursor/rules/requirements-review-rules.mdc deleted 100644 → 0
View file @ 86bbe72c
---
description: 需求评审规则 - 基于PRD/原型/业务背景开展标准化需求评审，识别歧义、缺失、逻辑冲突、落地风险，输出评审报告与整改清单
globs: *.md
alwaysApply: false
---
# 需求评审规则
## 仓库路径约定（可选落盘，与 UI 自动化同仓）
- 项目根目录命名支持两种方式：**用户自定义项目名称** 或 **由 Agent 自动生成项目名称**；下文统一以 `{项目名称}` 作为占位符。
- 自动生成命名规则（未指定项目名称时）：`{业务域}-{端类型}-automation`（如 `crm-ui-automation`）；命名统一使用小写字母、数字、短横线 `-`，空格转为 `-`，连续分隔符合并为单个 `-`。
- 若将评审产出纳入本工作区 Git 管理，建议目录：**`{项目名称}/docs/requirements-review/`**（可按迭代再分子文件夹）。
- 与测试相关的下游产物路径统一参见：`{项目名称}/testpoint/`、`{项目名称}/testcases/`、`{项目名称}/testcase/`（见对应专项规则），**勿**再使用 `crmeb-ui-e2e/` 等未在本仓库定义的路径。
## 评审目标
依据PRD、产品原型、业务背景、线上现状、技术架构与合规要求，对需求进行全维度标准化评审。
提前识别需求歧义、规则缺失、逻辑矛盾、边界遗漏、交互漏洞、落地风险，输出整改建议、规则补充、风险预警，确保需求**完整、清晰、统一、可落地、可测试、可验收**，为下游测试点拆解、用例设计、研发开发提供稳定依据。
## 评审维度
### 1. 需求完整性
- 核心流程、分支流程、反向流程全覆盖
- 业务约束、数值规则、状态流转、权限规则定义完整
- 正常、边界、异常、极端、兜底场景无缺失
- 上下游模块、数据联动、跨系统交互规则明确
### 2. 需求清晰度
- 功能描述、操作逻辑、约束条件无歧义
- 字段定义、默认值、必填项、选项范围明确
- 角色权限、数据范围、操作限制划分清晰
- 交互逻辑、弹窗提示、二次确认、失败反馈统一说明
### 3. 业务合理性
- 设计贴合实际业务场景与用户操作习惯
- 操作路径精简合理，无冗余步骤与反常识设计
- 风控限制、数据约束、流程管控符合业务目标
- 功能价值匹配迭代诉求，无无效冗余设计
### 4. 逻辑一致性
- 全局状态、文案、按钮、术语、规则统一
- 同字段/同状态在多页面、多操作中逻辑无冲突
- 新增/编辑/删除/审核等通用操作口径一致
- 历史功能、存量数据、旧版本兼容逻辑明确
### 5. 落地可行性
- 适配现有技术架构，无无法实现的过度设计
- 性能、并发、大数据量、多终端兼容风险可控
- UI组件、交互规范、移动端适配可落地
- 开发、测试、运维成本合理可控
### 6. 可测试 & 可验收
- 验收标准量化、可观测、可落地
- 所有规则、条件、状态变更可校验、可复现
- 异常拦截、报错提示、兜底展示有明确定义
### 7. 安全与合规
- 越权访问、重复提交、数据泄露风险可控
- 敏感数据脱敏、权限隔离、操作风控完善
- 符合行业合规、隐私政策与监管要求
## 评审方法
1. 需求通读拆解：梳理业务目标、核心流程、功能范围、变更内容
2. 逐条规则校验：按模块、页面、操作、条件逐条核对需求描述
3. 边界反向推演：覆盖临界值、空数据、中断操作、异常中断场景
4. 跨模块联动校验：核查模块依赖、数据同步、消息联动、状态互通
5. 多视角交叉评估：业务、产品、研发、测试四维视角综合评审
## 评审报告结构
1. 评审概述：范围、版本、依据、整体评价
2. 需求完整度分析：缺失场景、遗漏规则、流程断点汇总
3. 需求质量分析：歧义点、逻辑冲突、口径不统一问题
4. 落地风险评估：技术风险、性能风险、上线风险、合规风险
5. 分级问题清单：严重问题 / 一般问题 / 优化建议
6. 需求补充方案：缺失规则、边界逻辑、异常处理补充
7. 最终评审结论：准入判定、必改项、优化项、后续要求
## 评审分级标准
### 1. 完整性标准
- 核心业务流程：100%覆盖
- 业务规则 & 状态流转：100%明确定义
- 边界/异常兜底场景：≥95%覆盖
### 2. 规范标准
- 无模糊描述、无口头化表述、无逻辑自相矛盾
- 全局交互、文案、状态、校验规则保持统一
### 3. 准入标准
- 严重问题全部整改完成，方可进入测试点拆解与开发排期
- 一般问题可按需优化，体验类建议可迭代优化
## 评审输出物
1. 需求评审报告（MD格式）
2. 分级问题整改清单（可直接同步产品闭环）
3. 需求规则补充文档（合并更新至PRD）
## 标准评审流程
1. 准备阶段：收集PRD、原型、流程图、迭代背景
2. 执行评审：分模块逐项校验+边界反向推演
3. 问题汇总：按严重等级分类，标注影响范围
4. 报告输出：标准化评审报告+整改清单
5. 闭环复核：跟进修改，复审通过后归档
## 注意事项
- 保持客观中立，以规范、业务、落地为核心依据
- 全局视角评审，兼顾存量兼容与跨模块联动
- 需求变更需触发简易复审，保证资料同步更新
- 与《测试点分析规则》《功能测试用例结构化编写规范》保持口径统一
\ No newline at end of file
.cursor/rules/test-point-rules.mdc deleted 100644 → 0
View file @ 86bbe72c
---
description: 测试点分析规则 - 从定稿需求中标准化提取模块/功能/验证点，统一分类、颗粒度、优先级，为结构化测试用例提供输入
globs: *.md
alwaysApply: false
---
# 测试点分析规则
## 仓库路径约定（勿建平行空工程）
- 项目根目录命名支持两种方式：**用户自定义项目名称** 或 **由 Agent 自动生成项目名称**；下文统一以 `{项目名称}` 作为占位符。
- 自动生成命名规则（未指定项目名称时）：`{业务域}-{端类型}-automation`（如 `crm-ui-automation`）；命名统一使用小写字母、数字、短横线 `-`，空格转为 `-`，连续分隔符合并为单个 `-`。
- **测试点 Markdown 输出路径**：`{项目名称}/testpoint/{需求名称}-测试点分析-{序号}.md`（与项目根目录 `{项目名称}` 同仓）。
- **Playwright 自动化**：见 `{项目名称}/tests/`（与 `testpoint` / `testcases` 并列）。
- 禁止脱离该根目录另建 `crmeb-ui-e2e` 等仅放文档的平行工程，除非需求明确要求多仓。
## 概述
本规则用于在**需求评审定稿后**，统一拆解、提取、梳理测试点。
测试点只定义「需要验证什么」，不包含操作步骤、测试数据，作为上游需求、下游测试用例的中间标准载体。
## 核心定义
**测试点**：从规范需求中提炼的独立验证项，用于界定需覆盖的功能、规则、边界、异常、集成校验范围。
- 测试点：回答「要测什么」
- 测试用例：回答「怎么测、用什么数据、预期结果是什么」
## 测试点统一分类
### 1. 功能验证点
核心业务流程、正常操作、数据处理、状态正向变更、基础业务规则。
### 2. 边界验证点
输入长度、数值范围、数量上限、时间区间、分页限制、权限临界条件。
### 3. 异常验证点
非法输入、重复操作、断网、服务异常、无权限、会话过期、错误提示。
### 4. 集成验证点
模块联动、第三方对接、接口回调、跨模块数据同步、消息通知联动。
## 测试点提取统一规则
1. 层级拆分：模块 → 功能点 → 验证类型 → 原子测试点
2. 动作拆解：围绕CRUD、业务操作、状态变更提取验证项
3. 规则拆解：所有条件判断、约束限制、强制校验单独成点
4. 数据拆解：格式、完整性、一致性、唯一性逐一提取
5. 场景拆解：主动推导异常、边界、兜底隐性场景
## 颗粒度与联动规范
- 原子性原则：一个测试点只对应一项独立验证，避免糅合
- 联动关系：1个测试点可向下拆解为多条结构化测试用例
- 优先级对齐：高/中/低 与需求评审、测试用例优先级统一
- 高：主线流程、上线阻断、核心规则
- 中：常规约束、次要功能、分支流程
- 低：边缘场景、兼容兜底、体验优化
## 标准模板与编号规范
- 测试点ID：`TP_模块_功能_序号`
- 固定字段：测试点名称、测试分类、优先级、验证要点、关联需求
## 质量检查清单
- 全覆盖：匹配定稿需求100%业务规则
- 分类准：功能/边界/异常/集成归类无误
- 无重复：通用规则统一归集，避免多模块重复
- 可落地：便于直接转化为结构化测试用例
## 输出格式规范
统一Markdown层级：模块→功能点→四类验证点→列表化测试点，
文件路径：`{项目名称}/testpoint/{需求名称}-测试点分析-{序号}.md`
## 使用流程
需求定稿 → 拆解功能模块 → 提取四类测试点 → 质量自检 → 评审归档 → 输出至用例设计环节
\ No newline at end of file
.cursor/rules/testcase-csv-rules.mdc deleted 100644 → 0
View file @ 86bbe72c
---
alwaysApply: false
description: CSV 格式功能测试用例生成规范 - 与 MD 结构化用例双轨同源
---
# CSV格式功能测试用例生成规范
## 零、仓库路径约定（勿建平行空工程）
- 项目根目录命名支持两种方式：**用户自定义项目名称** 或 **由 Agent 自动生成项目名称**；下文统一以 `{项目名称}` 作为占位符。
- 自动生成命名规则（未指定项目名称时）：`{业务域}-{端类型}-automation`（如 `crm-ui-automation`）；命名统一使用小写字母、数字、短横线 `-`，空格转为 `-`，连续分隔符合并为单个 `-`。
- **本工作区 UI 自动化根目录**：`{项目名称}/`（与 Playwright、`data/`、结构化 MD 用例同仓）。
- **CSV 落盘目录**：`{项目名称}/testcase/`（目录名 `testcase`，与 `testcases/` 区分：后者放 `.md` 结构化用例）。
- **Playwright 代码用例**：在 `{项目名称}/tests/`（`testDir`），与 `testcase` / `testcases` 并列，职责不同。
- 禁止再使用无仓库根的写法（如单独 `/testcase/`、`crmeb-ui-e2e/` 等易误解路径）。
## 一、规范定位与整体联动
本规范为**测试执行层落地规范**，与《需求评审规则》《测试点分析规则》《功能测试用例结构化编写规范》形成完整闭环质量体系。
采用**一套设计源、两套输出物**双轨模式：
1. 设计评审层：以 **MD 结构化测试用例** 为唯一源头标准、评审依据、长期维护载体。
2. 测试执行层：基于定稿 MD 结构化用例，统一转换生成 **CSV 表格用例**。
3. 核心约束：所有业务规则、场景逻辑、验收标准仅在 MD 源文件维护；CSV 只做格式重组、执行字段补充，严禁单独修改业务内容，保证同源一致、无缝双向切换。
## 二、目标要求
当需要输出可落地执行的测试用例时，无需重复编写，直接基于评审通过的结构化 MD 用例，按本规范自动转换生成标准 CSV 文档。
CSV 文件统一存放至 **`{项目名称}/testcase/`** 目录，作为测试执行、结果回填、进度统计、缺陷关联、项目交付、归档留存的标准表格用例。
## 三、文件格式与命名规范
### 3.1 基础文件规则
- 编码格式：UTF-8
- 分隔符：英文逗号 `,`
- 文件格式：`.csv`
- 存放目录：固定 **`{项目名称}/testcase/`**（相对当前 Git 仓库根目录）
### 3.2 文件命名规范
- 命名格式：`[需求名称-测试用例-序号].csv`
- 示例：`{项目名称}/testcase/用户登录功能-测试用例-1.csv`
## 四、CSV固定列结构（9列固定，不可删减）
| 列名 | 说明 | 必填 |
|------|------|------|
| 用例编号 | 按功能模块缩写+三位序号编制，同文件唯一不重复 | 是 |
| 功能模块 | 所属一级业务模块名称，取自MD结构化用例H2标题 | 是 |
| 功能测试点 | 细分功能测试点名称，取自MD结构化用例H3标题 | 是 |
| 用例标题 | 简洁清晰描述单条测试场景，取自MD H5用例场景 | 是 |
| 优先级 | 高/中/低，与MD中P0/P1/P2严格映射 | 是 |
| 前置条件 | 执行当前用例所需前置环境、账号、数据；简单场景可留空 | 否 |
| 测试步骤 | 有序分步操作，序号+换行格式，可直接落地执行 | 是 |
| 预期结果 | 明确、可验证、无歧义的系统表现与数据状态 | 是 |
| 实际结果 | 测试执行阶段回填字段，设计阶段默认留空 | 否 |
## 五、全域统一映射规则
### 5.1 优先级双向对齐
- MD 结构化用例：P0 / P1 / P2
- CSV 执行用例：
- P0 → 高
- P1 → 中
- P2 → 低
### 5.2 内容同源规则
- 功能模块、测试点、用例标题、预期结果：完全复用 MD 原文。
- 测试步骤：由 MD 场景描述拆解细化为标准化分步操作。
- 需求变更、用例优化、缺陷修复：**先更新 MD 源文件，再同步更新 CSV**，杜绝版本分裂。
## 六、用例编号规范
1. 禁止全局统一无意义前缀（如固定 TCC），编号必须关联业务模块。
2. 标准格式：`模块缩写-三位序号`，示例：`LOGIN-001`、`USER-002`、`PAY-003`。
3. 模块缩写：取功能模块名称 2~6 位英文/拼音缩写，多级模块使用短横线连接。
4. 同文件要求：序号连续递增、无跳号、无重复，全局唯一可追溯。
## 七、内容编写格式标准
### 7.1 测试步骤格式
- 统一规范：`1. 操作内容\n2. 操作内容\n3. 操作内容`
- 内容要求：页面路径、按钮操作、输入内容、触发动作描述具体可复现。
### 7.2 预期结果格式
- 整合 MD 多条预期描述，合并为连贯通顺文本。
- 必须包含：页面展示、交互提示、按钮状态、数据落库、业务约束、报错文案。
- 禁止模糊描述，做到可观测、可对比、可验收。
### 7.3 特殊字符转义规则
单元格内容包含**逗号、双引号、换行符、特殊符号、公式字符**时，
整单元格使用英文双引号包裹并自动转义，防止 CSV 解析乱码、列错位。
## 八、测试用例设计方法
转换与设计过程中，必须完整覆盖六大标准测试设计方法，与上游测试点规范统一：
1. **等价类划分**
划分有效等价类、无效等价类，每类至少覆盖一条用例，覆盖合法与非法输入。
2. **边界值分析**
覆盖最大值、最小值、临界值、临界±1、空值、超长字符、数量上限等边界场景。
3. **判定表驱动法**
针对多条件、多规则组合场景，完整覆盖所有条件组合分支。
4. **场景法**
覆盖正常流程、异常流程、编辑修改、重复操作、取消中断等全用户场景。
5. **错误推测法**
基于业务经验补充特殊字符、脚本注入、网络异常、并发操作、权限越权等隐性用例。
6. **状态迁移法**
针对带状态流转功能，覆盖正常转换、异常转换、回退转换全链路。
## 九、MD 转 CSV 标准流程
1. 数据源确认：使用评审通过、定稿归档的 MD 结构化测试用例。
2. 结构提取：依次提取功能模块、功能测试点、用例场景、优先级、预期结果。
3. 内容加工：拆解标准化测试步骤、补充前置条件、编制模块化用例编号。
4. 格式处理：特殊字符转义、换行统一、单元格格式化处理。
5. 文件生成：在 **`{项目名称}/testcase/`** 目录生成 UTF-8 标准 CSV 文件。
6. 自检验收：核对字段完整性、编号唯一性、内容一致性、文件打开可用性。
## 十、质量验收标准
### 10.1 格式验收
- CSV 使用 Excel / WPS / 记事本 打开无乱码、无列偏移、无格式错误。
- 9 列字段完整，编码 UTF-8，分隔符规范。
- 特殊字符、多行内容转义合规，解析正常。
### 10.2 内容验收
- 100% 覆盖 MD 结构化用例全部场景，无遗漏、无删减。
- 用例独立可执行、可重复复现、无依赖耦合。
- 编号规范、优先级准确、步骤清晰、预期结果可验证。
### 10.3 体系联动验收
- 用例范围与需求评审、测试点分析完全匹配，需求覆盖率达标。
- 严格遵循双轨机制，不脱离 MD 源头单独维护 CSV。
## 十一、注意事项
1. 设计评审阶段统一使用 MD 结构化用例，测试执行阶段统一输出 CSV。
2. 所有 CSV 用例统一归档至 **`{项目名称}/testcase/`** 目录，集中管理、便于迭代。
3. 所有需求变更、规则调整、用例优化，严格执行「MD优先、CSV同步」。
4. 对外交付、测试执行、日常测试填表，统一使用 CSV 格式文件。
5. 全程与整套质量规范术语、标准、优先级保持统一，保证团队协作一致性。
\ No newline at end of file
.cursor/rules/testcase_structured_witing_specification.mdc deleted 100644 → 0
View file @ 86bbe72c
---
alwaysApply: false
description: 功能测试用例结构化编写规范 - 基于标准化测试点，统一MD层级、格式、写法、优先级，兼容XMind导入，实现测试点→用例标准化流转
---
# 功能测试用例结构化编写规范
## 仓库路径约定（勿建平行空工程）
- 项目根目录命名支持两种方式：**用户自定义项目名称** 或 **由 Agent 自动生成项目名称**；下文统一以 `{项目名称}` 作为占位符。
- 自动生成命名规则（未指定项目名称时）：`{业务域}-{端类型}-automation`（如 `crm-ui-automation`）；命名统一使用小写字母、数字、短横线 `-`，空格转为 `-`，连续分隔符合并为单个 `-`。
- **结构化 MD 用例**：`{项目名称}/testcases/`（见下文「输出物规范」）。
- **同源 CSV 执行用例**：`{项目名称}/testcase/`（见《CSV格式功能测试用例生成规范》）。
- **测试点分析文档**：`{项目名称}/testpoint/`（见《测试点分析规则》）。
- **Playwright 自动化用例**（`@playwright/test`）：目录名为 **`tests/`**，由 `{项目名称}/playwright.config.ts` 的 **`testDir: './tests'`** 指定，与 Playwright 官方脚手架一致；放 `*.spec.ts`，**不得**与 `testcases/`（人工维护的 H1–H6 结构化 MD）合并或改名混用。
- 上述均相对当前工作区 Git 根目录；勿再使用已废弃的 `crmeb-ui-e2e/` 等易混淆路径。
## 规范目标
基于上游**标准化测试点文档**，统一功能测试用例的结构、层级、描述、预期结果、优先级，
实现：格式统一、内容清晰、XMind兼容、可直接执行、便于评审与维护，打通「需求评审→测试点→测试用例」全链路质量体系。
## 核心结构（固定H1~H6层级，不可改动）
H1 文档标题
H2 功能模块
H3 功能测试点
H4 验证点
H5 用例场景
H6 预期结果
## 用例设计来源
1. 优先基于正式测试点文档一对一/一对多转化
2. 无测试点时，采用等价类、边界值、场景法、错误猜测、状态迁移法补充设计
3. 四类验证点严格对应：
- 功能测试点 → 正向主流程用例
- 边界测试点 → 边界值专项用例
- 异常测试点 → 异常拦截&错误处理用例
- 集成测试点 → 跨模块联调用例
## 编写统一规范
### 1. 用例场景（H5）
简洁描述操作+条件+场景，关键测试数据显性体现，不冗余、不模糊。
### 2. 预期结果（H6）
必须具体、可验证、无模糊话术，覆盖：页面展示、交互反馈、数据落库、状态变更。
### 3. 优先级轻量化标注
统一标注【P0/P1/P2】，与需求评审、测试点优先级完全对齐：
- P0：高优，核心主线，上线必过
- P1：中优，常规业务规则
- P2：低优，边界、异常、兜底兼容
### 4. 复杂场景兼容优化
- 简单场景：仅保留 用例场景 + 预期结果
- 复杂多步骤场景：可**按需增加可选操作步骤**，不新增层级，不破坏原有结构
## 设计方法应用要求
- 必选：等价类划分 + 边界值分析
- 按需：场景法、判定表、状态迁移、错误猜测法补充覆盖
## 输出物规范
- 存放路径：`{项目名称}/testcases/{需求名称}-测试用例-{序号}.md`（与当前 UI 自动化工程同仓；若多项目可再分子目录）
- 格式统一、编号连续、模块分类清晰、便于迭代维护
## 管理与维护
1. 版本化管理，需求变更同步更新用例
2. 定期评审优化，删除冗余、补充缺失场景
3. 全程与需求评审规则、测试点分析规则保持术语、口径、标准统一
\ No newline at end of file
.gitignore
View file @ 2d662da1
......@@ -25,5 +25,5 @@ logs/
reports/*
!reports/README.md
# Cursor Agent Skills 不入库；框架运行不依赖它们。保留 .cursor/rules/
.cursor/skills/
# Cursor 本地配置（rules / skills / mcp），框架运行不依赖
.cursor/
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment