智能体工作流程管理
UI 元素知识库的利用
Pytest 编码规范的严格遵循

# Playwright 测试生成器提示词

你是一个Playwright 测试生成器，请严格遵循以下规则生成测试代码：  

## 1. 输入场景
我会提供一个测试场景，你需要基于该场景生成对应的 Playwright 测试。  

## 2. 步骤执行与记录
- 在执行场景步骤前，必须先读取 `mana/history_data/step_info.json`，检查是否已有相似的步骤信息。  
- 如果有记录，则直接使用已有步骤信息调用 MCP 工具执行
- 如果没有完全一样的记录，你需要先参考已有的类似记录，优先使用有记录的元素识别方法
- 如果没有记录，则调用 MCP 工具，自行尝试完成步骤，在步骤成功以后，将以下信息追加写入 `mana/history_data/step_info.json`，请严格按照以下json串格式  
  {
      "description": ,
      "action": ,
      "mcp_tool": ,
      "selector": ,
      "parameters": {
        "":""
      },
      "result": ,
      "page_elements": {
        "":""
      }
    },
- 若某个步骤已经被记录过，则无需重复记录。  
- 若某个步骤执行失败，无需记录失败信息，等尝试成功以后再进行记录

## 3. 测试代码生成
- 在所有步骤执行完成后，利用MCP工具操作后的上下文，生成测试代码。  
- 测试代码生成的pytest测试代码需要用allure框架进行报告生成,请严格遵守mana/devlop_standard.md约定的规范

## 4. 测试代码验证与调试
- 生成测试代码以后，使用pytest运行测试代码
- 运行测试代码时，需要添加`--alluredir=allure-results`参数，用于生成allure报告
- 测试代码失败的部分，需要根据错误信息进行调试
- 直到用例可以成功通过后，使用`allure serve allure-results`命令查看报告

# Pytest 自动化测试开发规范

## 1. 项目结构规范
### 1.1 目录结构
```
mana/
├── config.py              # 环境配置文件
├── conftest.py            # pytest配置和fixture定义
├── utils.py               # 工具类和辅助函数
├── test_data/             # 测试数据目录
│   ├── *.csv             # CSV格式测试数据
│   └── DATA_LOADER_USAGE.md
├── history_data/          # 历史数据存储
├── test_*.py             # 测试用例文件
└── promts/               # 提示词模板
```
### 1.2 文件命名规范
- 测试文件：`test_<功能模块>_<具体功能>.py`
- 配置文件：`config.py`
- 工具文件：`utils.py`
- 数据文件：`<功能>_test_data.csv`
## 2. 代码结构规范
### 2.1 导入顺序
```python
# 标准库导入
import pytest
import os
import sys
from pathlib import Path
# 第三方库导入
import allure
from playwright.sync_api import sync_playwright, expect
# 本地模块导入
import config
from utils import MySQLManager
from data_loader import DataLoader
```
### 2.2 测试函数命名
- 函数名：`test_<功能模块>_<具体场景>`
- 使用下划线分隔单词
- 名称要清晰表达测试意图
## 3. Fixture 规范
### 3.1 Fixture 作用域
- `session`：整个测试会话共享（如浏览器实例）
- `function`：每个测试函数独立（如页面实例）
### 3.2 核心 Fixture
```python
@pytest.fixture(scope="session")
def browser(request):
    """浏览器实例fixture"""
    # 配置浏览器参数
    # 返回浏览器实例
@pytest.fixture(scope="function")
def logged_in_page(page):
    """已登录页面fixture"""
    # 执行登录操作
    # 返回已登录的页面实例
@pytest.fixture
def cleanup_mcp_data():
    """数据清理fixture"""
    # 提供数据清理功能
    # 测试后自动清理
```
### 3.3 Fixture 最佳实践
- 使用合适的作用域避免资源浪费
- 提供清理机制确保测试独立性
- 使用描述性的fixture名称
- 在docstring中说明fixture用途
## 4. 测试用例编写规范
### 4.1 测试用例结构
```python
@pytest.mark.smoke  # 测试标记
@allure.title("测试用例标题")
def test_function_name(logged_in_page, cleanup_mcp_data):
    """
    测试用例描述
    
    测试步骤：
    1. 步骤1描述
    2. 步骤2描述
    ...
    """
    page = logged_in_page
    cleanup_mcp_data("test_data_name")
    
    with allure.step("步骤1：具体操作描述"):
        # 具体操作代码
        # 截图记录
        allure.attach(
            page.screenshot(full_page=True),
            name="步骤截图",
            attachment_type=allure.attachment_type.PNG
        )
```
### 4.2 测试步骤规范
- 每个步骤使用 `allure.step()` 包装
- 步骤描述要清晰具体
- 关键步骤后添加截图
- 使用 `page.wait_for_load_state("networkidle")` 等待页面加载
### 4.3 元素定位规范
```python
# 优先使用语义化定位器
page.get_by_role('button', name='登录')
page.get_by_text('MCP 扫描')
page.get_by_test_id('element-id')
# 使用CSS选择器时要精确
page.locator('.specific-class')
page.locator('tbody tr:first-child td:nth-child(2)')
# 添加等待和超时
element.wait_for(timeout=10000)
element.wait_for(state="visible", timeout=5000)
```
## 5. 数据驱动测试规范
### 5.1 数据文件格式
- 使用CSV格式存储测试数据
- 第一行为列标题
- 包含test_id列用于测试标识
### 5.2 数据驱动实现
```python
# 数据加载
loader = DataLoader("mana/test_data/test_data.csv")
test_data, test_ids = loader.get_pytest_params()
# 参数化测试
@pytest.mark.parametrize("test_params", test_data, ids=test_ids)
def test_data_driven(logged_in_page, test_params):
    # 使用test_params中的数据
    pass
```
## 6. 配置管理规范
### 6.1 环境配置
```python
ENVIRONMENTS = {
    'dev': {
        'BASE_URL': 'https://dev.example.com/',
        'USERNAME': 'devuser',
        'PASSWORD': 'devpass',
        'DB_CONFIG': {...}
    },
    # 其他环境配置
}
```
### 6.2 配置使用
- 通过命令行参数 `--env` 指定环境
- 使用 `config.BASE_URL` 等方式访问配置
- 敏感信息考虑使用环境变量
## 7. 错误处理和异常规范
### 7.1 异常处理
```python
try:
    # 可能失败的操作
    element = page.locator("selector")
    element.click()
except Exception as e:
    print(f"操作失败: {e}")
    pytest.skip(f"跳过测试: {e}")
```
### 7.2 测试跳过
- 使用 `pytest.skip()` 跳过无法执行的测试
- 提供清晰的跳过原因
- 在日志中记录跳过信息
## 8. 报告和日志规范
### 8.1 Allure 报告
- 使用 `@allure.title()` 设置测试标题
- 使用 `allure.step()` 记录测试步骤
- 关键步骤添加截图附件
- 使用 `@pytest.mark` 添加测试标记
### 8.2 日志记录
```python
# 使用print进行调试输出
print(f"找到MCP名称: {mcp_name}")
print(f"当前URL: {page.url}")
# 在Allure中记录重要信息
allure.attach(
    f"测试数据: {test_data}",
    name="测试信息",
    attachment_type=allure.attachment_type.TEXT
)
```
## 9. 性能和稳定性规范
### 9.1 等待策略
```python
# 等待网络空闲
page.wait_for_load_state("networkidle")
# 等待元素可见
element.wait_for(state="visible", timeout=10000)
# 固定等待（谨慎使用）
page.wait_for_timeout(2000)
```
### 9.2 超时设置
- 设置合理的超时时间
- 关键操作使用较长超时
- 避免过长的固定等待
## 10. 数据清理规范
### 10.1 测试数据管理
```python
# 注册清理数据
cleanup_mcp_data("test_mcp_name")
# 自动清理实现
@pytest.fixture
def cleanup_mcp_data():
    cleanup_names = []
    def add_cleanup_name(name):
        cleanup_names.append(name)
    yield add_cleanup_name
    # 清理逻辑
```
### 10.2 清理最佳实践
- 每个测试注册需要清理的数据
- 使用fixture自动清理
- 清理失败不影响测试结果
- 记录清理操作日志
## 11. 代码质量规范
### 11.1 代码风格
- 遵循PEP 8编码规范
- 使用有意义的变量名
- 添加适当的注释和文档字符串
- 保持代码简洁和可读性
### 11.2 测试独立性
- 每个测试用例独立运行
- 不依赖其他测试的执行结果
- 使用fixture确保测试环境一致性
- 及时清理测试数据
## 12. 运行和调试规范
### 12.1 命令行运行
```bash
# 运行所有测试
pytest mana/ -v --alluredir=allure-results
# 运行特定测试
pytest mana/test_specific.py::test_function -v
# 指定环境运行
pytest mana/ --env=test -v
# 无头模式运行
pytest mana/ --headless -v
```