使用说明

QA自动化平台

A. 剧作家+皮泰斯特 Sauce Demo的自动化框架，具有全面的UI、API、E2E和BDD测试。

👉 新来的？ 阅读 README_NONTECHNICAL.md 获取完整的非技术指南！

特性

✅ 用户界面测试 --基于页面对象模型的命令式剧作家测试
✅ API测试 --直接后端端点验证
✅ E2E测试 --完成用户旅程工作流
✅ BDD测试 --商业可读的Gherkin场景
✅ 多格式报告 --HTML、JUnit、Allure、截图、视频
✅ 重试逻辑 --瞬态故障时自动重试测试
✅ CI/CD集成 --GitHub操作和Jenkins管道
✅ 数据驱动 --基于JSON的测试数据管理
✅ MCP支持 --可选模型上下文协议集成
✅ 智能包装 --具有显式等待的稳健元素交互

快速开始

# Install dependencies
pip install -r requirements.txt
python -m playwright install

# Run all tests (headless)
pytest

# Run tests with visible browser
pytest --headed

# Run E2E tests only
pytest test_suites/e2e/ --headed -v

运行测试

测试执行模式

命令	模式	用例
`pytest`	无头	快速批量运行，CI/CD管道
`pytest --headed`	Headed	开发、调试、学习
`pytest --headed -v`	详细+有标题	使用可见浏览器进行详细输出
`pytest --headed -s`	详细+打印语句	使用控制台输出进行调试

测试选择

# All tests
pytest

# Specific test file
pytest test_suites/ui/test_sauce_login.py --headed

# Specific test function
pytest test_suites/e2e/test_purchase_flow.py::test_purchase_flow --headed

# By marker
pytest -m smoke --headed          # Only smoke tests
pytest -m e2e --headed            # Only E2E tests
pytest -m api --headed            # Only API tests
pytest -m regression --headed     # Full regression suite

# By keyword
pytest -k "login" --headed        # Only tests with "login" in name
pytest -k "not api" --headed      # All tests except API tests

调试和故障排除

# Short error output
pytest --tb=short

# No traceback
pytest --tb=no

# Full traceback
pytest --tb=long

# Stop on first failure
pytest -x

# Stop after N failures
pytest --maxfail=3

# Re-run failed tests only
pytest --lf

# Run N times (for flaky tests)
pytest --count=3

# Debug mode (headed + video + trace + slowmo)
pytest --debug-mode --headed

测试组织

test_suites/
├── ui/              # User interface tests
├── api/             # Backend API tests
├── e2e/             # End-to-end workflows
└── bdd/             # Business-readable scenarios

为什么这个结构

当前代码库分为四个工作层：

core/ 是可重用的内核。它拥有配置、报告、集成、执行助手和数据服务。
app/ 是应用交互层。它拥有页面对象、可重复使用的UI组件、API客户端和业务工作流。
test_suites/ 是测试意图层。它拥有可运行的测试、BDD功能、粘合文件和共享步骤定义。
tools/ 包含操作帮助程序，如MCP客户端、MCP存根服务器和CLI帮助程序。

重要提示：

原始目标结构使用了一个名为的顶级包 platform/
Python已经发布了一个名为 platform
为了避免导入冲突和pytest启动中断，此实现使用 core/ 相反

结构图

qa-automation-platform/
  core/
    config/
    data_engine/
    engine/
    integrations/
    reporting/
  app/
    ui/
      pages/
      components/
      workflows/
    api/
      clients/
      service_facades/
    domain/
      models/
      validators/
      transformers/
  test_suites/
    ui/
    api/
    bdd/
      features/
        ui/
        api/
      step_definitions/
      hooks/
    conftest.py
  tools/
    cli/
    mcp/
  data/
  environments/
  pipelines/
  .github/workflows/
  Jenkinsfile
  pytest.ini
  README.md

如何阅读：

core/ 是可重复使用的引擎层
app/ 是酱汁演示交互层
test_suites/ 是可运行的测试意图层
tools/ 是操作辅助层

根文件夹指南

core/

测试和自动化对象使用的共享框架代码
这就是可重用内核所在的地方

app/

Sauce Demo的应用程序特定自动化代码
这是页面、组件、工作流、API客户端和域助手所在的位置

test_suites/

所有活动的pytest发现现在都从这里开始
此文件夹包含真正可运行的套件和 conftest.py

tools/

支持框架但本身不是测试用例的操作助手

data/

数据引擎使用的原始JSON测试数据

environments/

环境模板和env样式的配置文件

pipelines/

支持管道注释和占位符
工具原生管道入口点仍然位于工具所期望的位置： .github/workflows/ 和 Jenkinsfile

.github/workflows/

GitHub操作管道定义

Jenkinsfile

Jenkins从SCM到pipeline的管道入口点

pytest.ini

中央pytest发现、标记和报告输出配置

ARCHITECTURE.md

简短说明 core/ 命名决定

传统的重复文件夹，如 src/, config/，以及 scripts/ 被移除。现在，主动实施从 core/, app/, test_suites/，以及 tools/.

详细的文件夹职责

core/config/

runtime_config.py 加载环境变量，公开运行时设置，并充当框架的主要配置对象
environment_manager.py 提供围绕运行时配置创建的便利包装
secrets_resolver.py 是一个轻量级的助手，用于从环境变量中读取机密值

core/data_engine/

data_provider_interface.py 定义基础数据提供者合同
json_data_provider.py 包含夹具和测试流使用的实时JSON支持的提供程序
synthetic_data_factory.py 为未来的扩展提供生成的测试有效载荷
testdata_cache.py 是一个用于数据重用的简单缓存实用程序

core/engine/

browser_engine.py 持有可重用的Playwright发布抽象
session_manager.py 集中浏览器上下文和页面创建助手
execution_controller.py 转换高级套件名称，例如 ui, api，或 smoke 进入pytest参数
retry_orchestrator.py 是框架级重试逻辑的通用重试助手

core/reporting/

telemetry_client.py 提供活动框架记录器
html_report_adapter.py 描述pytest HTML报告位置
allure_adapter.py 描述了Allure结果位置
report_manager.py 集中报告输出元数据

core/integrations/

jira_gateway.py 是Jira适配器
testrail_gateway.py 是TestRail适配器
slack_notifier.py 目前是一个轻量级的通知支架
ci_metadata_provider.py 在可用时收集CI环境元数据

集成状态：

Jira和TestRail现在在未配置时会软失败，而不是尝试使用空凭据调用占位符端点
Jira使用 JIRA_BASE_URL, JIRA_API_TOKEN，以及 JIRA_PROJECT_KEY
TestRail用途 TESTRAIL_BASE_URL, TESTRAIL_API_KEY，以及 TESTRAIL_RUN_ID
Slack现在仍然只是一个脚手架伐木工人；它还没有连接到真正的webhook调用

app/ui/pages/

核心屏幕的页面对象模型：登录、库存、购物车和结账
测试和工作流使用这些类，而不是测试体中的原始Playwright选择器

app/ui/components/

可重用的UI片段，如购物车小部件、结账表单、过滤和排序控件、标题和产品卡
组件有助于避免在页面和测试之间重复小的UI交互逻辑

app/ui/workflows/

业务流程编排层
authentication_workflow.py 拥有登录样式流
cart_workflow.py 拥有以购物车为中心的流量
purchase_workflow.py 拥有结账和购买流程
这一层是多页业务旅程的归属层

app/api/clients/

低级API交互类
base_api_client.py 拥有共享HTTP行为
sauce_demo_api_client.py 拥有Sauce Demo端点特定的方法

app/api/service_facades/

用于位于原始客户端之上的更高级别API编排助手的位置

app/domain/

包含域级帮助程序，如模型、验证器和转换器
当自动化层开始更明确地建模业务对象时，这些功能非常有用

test_suites/ui/

强制性UI测试
适用于无需Gherkin开销的直接验证

test_suites/api/

API强制测试
适用于低摩擦后端验证

test_suites/bdd/features/ui/

UI功能文件及其功能本地粘合模块

test_suites/bdd/features/api/

API BDD功能文件加胶水模块

test_suites/bdd/step_definitions/

通过注册共享的可重用BDD步骤定义 test_suites/conftest.py

test_suites/bdd/hooks/

未来BDD特定钩子逻辑的位置

tools/mcp/

mcp_client.py 拥有MCP执行和回退行为
mcp_stub_server.py 为MCP连接测试提供本地开发存根

tools/cli/run_tests.py

允许执行套件风格，例如 all, ui, api, smoke，以及 regression

框架如何工作

1.启动流程

pytest读取 pytest.ini
pytest从以下位置发现测试 test_suites/
test_suites/conftest.py 加载共享插件、夹具、浏览器设置、数据提供程序和可选集成
core/config/runtime_config.py 读取环境并构建活动运行时配置

2.UI测试流程

测试从 test_suites/ui/ 请求固定装置，如 page, login_page, inventory_page，或 cart_widget
test_suites/conftest.py 创建浏览器、上下文和页面对象
页面对象来自 app/ui/pages/ 执行稳定的UI交互
可重用的UI部件来自 app/ui/components/
更广泛的商务旅行可以转移到 app/ui/workflows/ 保持测试可读性

3.BDD流程

Gherkin特征文件位于 test_suites/bdd/features/
每个功能都有一个本地粘合模块，用于将场景导入pytest
共享BDD步骤 test_suites/bdd/step_definitions/
这些共享步骤模块是通过以下方式注册的 pytest_plugins 在 test_suites/conftest.py
步骤定义使用页面对象、组件、工作流、夹具和提供程序，就像命令式测试一样

4.API流程

测试或BDD步骤调用 app/api/clients/
base_api_client.py 提供会话和请求行为
sauce_demo_api_client.py 公开特定于Sauce Demo的端点方法
可选的高级协调可以存在 app/api/service_facades/

5.MCP流程

MCP通过以下方式选择加入 --use-mcp 或 MCP_ENABLED=true
这 mcp_client 夹具 test_suites/conftest.py 尝试连接到 MCP_SERVER_URL
如果MCP已启用且可访问，则MCP标记的流可以通过MCP路径执行
如果启用了MCP但无法访问，则仅MCP的场景会跳过，而不是使整个套件失败
tools/mcp/mcp_stub_server.py 可以在本地用于模拟MCP连接

6.故障和报告流程

pytest通过以下方式自动写入HTML、JUnit和Allure原始输出 pytest.ini
在失败时， test_suites/conftest.py 捕获屏幕截图和可选痕迹
配置集成时，故障钩子可以将元数据传递给Jira
日志通过 core/reporting/telemetry_client.py 进入 reports/logs/

7.CI流程

GitHub操作使用 .github/workflows/playwright_ci.yml
Jenkins使用 Jenkinsfile
两个管道都对执行pytest test_suites/ 并将生成的报告存档
通过套件名称支持手动套件定位，例如 ui, api, ui-bdd, api-bdd, smoke，以及 regression

设置

创建并激活虚拟环境
从安装依赖项 requirements.txt
安装Playwright浏览器（Chromium/Firefox/WebKit）
复制 .env.example 到 .env
填写您实际使用的任何可选集成值
安装预提交挂钩（可选但推荐）

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
python -m playwright install chromium firefox webkit
copy .env.example .env
pre-commit install  # Optional: install pre-commit hooks

环境值示例：

ENV=staging
BASE_URL=https://www.saucedemo.com
API_URL=
JIRA_BASE_URL=
JIRA_API_TOKEN=
JIRA_PROJECT_KEY=
TESTRAIL_BASE_URL=
TESTRAIL_API_KEY=
TESTRAIL_RUN_ID=
SLACK_WEBHOOK_URL=
MCP_ENABLED=false
MCP_SERVER_URL=ws://localhost:8080
DEFAULT_ACTION_TIMEOUT_MS=10000
DEFAULT_NAVIGATION_TIMEOUT_MS=30000
EMAIL_ENABLED=false
EMAIL_TO=
EMAIL_FROM=
SMTP_HOST=
SMTP_PORT=587
SMTP_USERNAME=
SMTP_PASSWORD=
EMAIL_USE_TLS=true
EMAIL_SUBJECT_PREFIX=Playwright Tests

运行测试

运行完整套件：

python -m pytest

运行单个套件切片：

python -m pytest test_suites\ui -v
python -m pytest test_suites\api -v
python -m pytest test_suites\bdd\features\ui -v
python -m pytest test_suites\bdd\features\api -v

按标记运行：

python -m pytest -m smoke
python -m pytest -m regression
python -m pytest -m api
python -m pytest -m negative
python -m pytest -m edge
python -m pytest -m mcp

有用的命令：

python -m pytest --collect-only -q
python -m pytest --headed -v
python -m pytest --debug-mode -v
python -m pytest -m mcp --use-mcp -v
python tools\cli\run_tests.py all
python tools\cli\run_tests.py ui
python tools\cli\run_tests.py smoke

MCP存根示例：

venv\Scripts\python.exe tools\mcp\mcp_stub_server.py
python -m pytest test_suites\bdd\features\ui\test_end_to_end_purchase.py -k mcpassisted --use-mcp -v

报告

Pytest自动写入报告：

HTML报告： reports/report.html
JUnit XML： reports/junit-report.xml
诱人的原始结果： reports/allure-results/
日志： reports/logs/
截图： reports/screenshots/ 失败时
踪迹： reports/traces/ 启用跟踪时

电子邮件报告（可选）

您可以通过电子邮件发送摘要，并附上生成的报告工件的zip（包括 reports/logs/)在pytest运行结束时。

在您的 .env （复制自 .env.example)通过设置：

EMAIL_ENABLED=true
EMAIL_TO （以逗号分隔的收件人）
SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD

电子邮件由自动发送 pytest_sessionfinish 挂钩时 EMAIL_ENABLED=true.

如果安装了Allure CLI，则生成Allure HTML网站：

allure generate reports\allure-results -o reports\allure-report --clean

CI和CD

GitHub操作：

工作流文件： .github/workflows/qa-automation-ci.yml
运行烟雾测试、回归测试和阶段性E2E测试
将测试结果作为工件上传
支持使用pytest-xlist并行执行

詹金斯：

管道文件： Jenkinsfile
支持Windows和Linux代理
发布JUnit结果并存档报告
安装匹配的插件后，可以发布pytest HTML和Allure数据

环境选择

该框架通过配置文件支持多种环境 environments/ 文件夹：

# Run tests in development environment
pytest --env dev

# Run tests in staging environment
pytest --env staging

# Run tests in production environment
pytest --env prod

环境文件会覆盖基本设置：

environments/base.env --共享默认值
environments/dev.env --开发覆盖
environments/staging.env --分期覆盖
environments/prod.env --生产超控
.env --本地覆盖（未提交；用于令牌/密码等真正的秘密）
.env.example --列出支持的环境变量的模板（复制到 .env 和填充值）

MCP模式（本地/远程E2E）

该框架支持可选的模型上下文协议（MCP）集成，用于AI辅助测试执行：

本地MCP模式

# Start local MCP stub server
python tools/mcp/mcp_stub_server.py

# Run MCP-enabled tests
pytest --use-mcp -v

远程MCP模式

# Configure remote MCP server
echo "MCP_SERVER_URL=ws://your-mcp-server:8080" >> .env
echo "MCP_ENABLED=true" >> .env

# Run tests with remote MCP
pytest --use-mcp -v

MCP功能：

人工智能辅助元素交互
MCP不可用时自动回退到POM
可通过以下方式配置 MCP_ENABLED 和 MCP_SERVER_URL
当MCP服务器无法访问时，性能会下降

报告组织

测试报告按日期和测试用例组织：

reports/
├── 2026-03-24/                    # Date-based folder
│   ├── test_login_standard_user/  # Test case folder
│   │   ├── screenshots/
│   │   │   └── test_login_standard_user_20260324_143015_123.png
│   │   └── videos/
│   │       └── test_login_standard_user_20260324_143015_123.webm
│   ├── test_add_to_cart/
│   │   ├── screenshots/
│   │   │   └── test_add_to_cart_20260324_143020_456.png
│   │   └── videos/
│   │       └── test_add_to_cart_20260324_143020_456.webm
│   └── ...
├── report.html                   # Pytest HTML report
├── junit-report.xml              # JUnit XML for CI
└── allure-results/               # Allure raw data

故障分类步骤

当测试失败时，遵循以下系统方法：

1.检查HTML报告

# Open main report
start reports/report.html

显示测试状态、持续时间和错误消息
截图和视频链接

2.查看截图

位于 reports/YYYY-MM-DD/test_name/screenshots/
测试失败时自动捕获
显示故障点的浏览器状态

3.回顾视频

位于 reports/YYYY-MM-DD/test_name/videos/
完整的测试执行记录
帮助了解用户流量和时间问题

4.检查诱惑报告（如有）

# Generate Allure HTML (requires Allure CLI)
allure generate reports/allure-results -o reports/allure-report --clean
allure open reports/allure-report

详细的测试执行时间表
逐步细分
历史趋势和比较

5.本地调试

# Run failed test with debugging
pytest --lf --headed -v -s

# Run with debug mode (slow motion + tracing)
pytest --debug-mode --headed -k "failed_test_name"

6.常见故障模式

选择器问题：检查中的页面对象 app/ui/pages/
时机问题：审查组件中的等待策略
数据问题：验证测试数据 data/ 文件夹
环境问题：检查 .env 配置
MCP问题：确保MCP服务器正在运行或禁用MCP

预提交设置

安装预提交挂钩以提高代码质量：

pip install pre-commit
pre-commit install

手动运行：

pre-commit run --all-files

预提交检查包括：

黑色：代码格式
Flake8：样式和错误检查
MyPy 的：类型检查
尾部空白：清理
大文件：防止意外犯罪

已知警告

core/integrations/slack_notifier.py 仍然只是一名脚手架伐木工人；它还没有发送真正的webhook请求
Jira和TestRail适配器已准备好集成，但仍需要真正的基本URL和凭据 .env 或CI机密
tools/mcp/mcp_client.py 仍然会发出websocket弃用警告，应在以后的过程中进行清理

当前验证

清理后的最新本地检查：

venv\Scripts\python.exe -m compileall core app tools test_suites 成功
venv\Scripts\python.exe -m pytest --collect-only -q 收集了45个测试
venv\Scripts\python.exe -m pytest -q 结果有27个通过，18个跳过
在以下情况下，预计会跳过测试 API_URL 为空白或MCP未启用

真相的来源

如果文档和代码脱节，请先信任这些文件：

pytest.ini
test_suites/conftest.py
core/config/runtime_config.py
.github/workflows/playwright_ci.yml
Jenkinsfile

使用说明

QA自动化平台

特性

快速开始

运行测试

测试执行模式

测试选择

调试和故障排除

测试组织

为什么这个结构

结构图

根文件夹指南

详细的文件夹职责

框架如何工作

1.启动流程

2.UI测试流程

3.BDD流程

4.API流程

5.MCP流程

6.故障和报告流程

7.CI流程

设置

运行测试

报告

电子邮件报告（可选）

CI和CD

环境选择

MCP模式（本地/远程E2E）

本地MCP模式

远程MCP模式

报告组织

故障分类步骤

1.检查HTML报告

2.查看截图

3.回顾视频

4.检查诱惑报告（如有）

5.本地调试

6.常见故障模式

预提交设置

已知警告

当前验证

真相的来源

相关 MCP

iOS/macOS 构建 MCP 服务器与命令行工具

iOS模拟器交互服务器

网页截图工具

Bruno MCP服务器

代理服务器管理工具

网页无障碍扫描器