🎭 Playwright+Cumber BDD测试自动化框架
> 一个生产就绪、可扩展的测试自动化框架,结合了Playwright的强大功能和Cucumber BDD的可读性。
🧾 申请自动化测试(快速流程)
一个简短、易于遵循的流程,用于向Copilot/MCP或人工审查员请求自动测试。从下面的快速步骤开始立即采取行动,然后按照详细流程获取完整指导。
快速步骤
- 添加所需的上下文:附加
context/guidelines.txt以及任何特定功能的上下文文件。 - 选择适当的提示:使用
prompts/new_feature_prompt.txt或者为该功能定制提示。 - 在副驾驶/MCP聊天和参考上下文文件中附加提示(例如。,
@context/guidelines.txt). - 查看生成的输出:特征文件、页面对象、步骤定义和测试数据。
- 在本地运行并验证:
npm test -- --name ",检查test-results/reports/index.html,然后迭代。
详细流程
- 添加所需的上下文:包括
context/guidelines.txt,以及描述该功能的任何示例页面或数据文件。 - 选择提示:开始
prompts/new_feature_prompt.txt并附加细节——页面URL、用户流、输入字段、预期结果和标签。 - 将提示附加到副驾驶/MCP:使用以下命令将提示粘贴到聊天和参考上下文文件中
@context/...所以Copilot有项目标准。 - 生成测试:接受或细化生成的测试
src/tests/features/*.feature,添加/更新src/pages/*页面对象,src/tests/steps/*步骤defs,以及test-data-store/*. - 审查并运行:在头部模式下运行目标场景以验证定位器,检查
test-results/reports/index.html,捕获故障的屏幕截图/跟踪,并迭代定位器或步骤实现。
📖 目录
- 这是什么?
- 快速入门(10分钟)
- 项目概述
- 存储库结构
- 建筑与设计
- 先决条件
- 安装和设置
- 运行测试
🤖 使用上下文和提示
简短的使用指南和指示 context/ 和 prompts/ 与GitHub Copilot和剧作家MCP合作。完整示例和高级工作流已移至 docs/prompts.md.
- 快速入门:使用
prompts/new_feature_prompt.txt构建新功能。 - 始终连接
context/guidelines.txt以获得一致的输出。 - 有关深度MCP设置,请参阅
docs/mcp.md.
看 docs/prompts.md 用于完整的提示、示例场景和人工智能辅助的工作流程。
不确定从哪里开始?使用本指南:
| 你的目标 | 阅读内容 | 所需时间 |
|---|---|---|
| 🚀 只是想运行测试吗? | 快速开始 → 运行测试 | 15分钟 |
| 🧪 编写新的测试用例? | 存储库结构 → 写作和扩展测试 | 30分钟 |
| 🏗️ 了解框架设计? | 建筑与设计 | 20分钟 |
| 🤖 使用GitHub Copilot进行测试生成? | 使用上下文和提示 | 15分钟 |
| 🆘 面对错误或问题? | 故障排除 | 根据需要 |
| 🤝 为项目做出贡献? | 贡献 | 10分钟 |
💡 完全初学者? 别担心!你不需要深入的剧作家或自动化测试知识来开始。只要跟着 快速开始 指南——它是为绝对初学者设计的。
🧭 项目概述
这解决了什么问题?
传统的UI测试是 易碎、难以维护、难以阅读该框架通过以下方式使测试更容易:
- BDD/小黄瓜用任何人都能理解的简单英语写测试
- 页面对象模型:易于维护的有组织、可重用的代码
- 智能包装:自动重试和回退(更少不稳定的测试!)
- 丰富的日志记录:出错时用于调试的详细日志
- 美丽的报道:带有屏幕截图和故障视频的HTML报告
底线: 你花更少的时间修复测试,花更多的时间发现真正的bug。
测试流程示例
例子: 本地代码库中的实际登录测试:```gherkin
Feature: User Authentication tests
Background:
Given User navigates to the application
Scenario: Login should pass
And logs-in as "json://LOGIN_USER_DATA#appAdminUser"
Then Login should pass
Scenario: Login should fail
And User enters the username as "invalidUser"
* User enters the password as "pass123"
When User clicks on the login button
But Login should fail
这 **读起来像普通英语** 而是作为可靠的自动化测试执行!
**BDD新手?** 别担心,你几分钟后就能拿到。语法直观明了。
______________________________________________________________________
## 📂 存储库结构说明
以下是每个文件夹包含的内容及其重要性:```
📦 Playwright_demo_frm_sir_updated
├── 📁 config/ # Test runner configurations
## 🔧 Configuring Playwright MCP Server
Advanced MCP setup, configuration options, and troubleshooting have been moved to `docs/mcp.md` to keep this README concise. Follow that document for full VS Code settings, MCP server installation, verification commands, and workflows.
Quick pointers:
- Enable MCP in VS Code settings and point to `node_modules/@playwright/mcp/dist/index.js`.
- Install the package locally with `npm install --save-dev @playwright/mcp` and verify with `npm list @playwright/mcp`.
- If you need step-by-step MCP workflows or troubleshooting, see `docs/mcp.md`.
BASEURL=http://localhost:3000
# Optional: Other settings
BROWSER=chrome
HEAD=true
LOG_LEVEL=info
常见基本URL示例:```env
Local development
BASEURL=http://localhost:3000
Docker container
BASEURL=http://localhost:8080
Remote QA environment
BASEURL=https://qa.yourapp.com
Staging environment
BASEURL=https://staging.yourapp.com
**需要多个环境?** 创建其他文件:
- `.env.QA1` -QA环境1
- `.env.QA2` -QA环境2
- `.env.staging` -分期付款
- `.env.production` -生产(小心使用!)
然后使用以下命令运行测试: `npm test -- --ENV=staging`
### 步骤5:验证设置```powershell
# Run a quick test to verify everything works
npm test
# Or run specific feature
npm test -- --name "Login"
📋 首轮:期待什么
首次运行测试时:
✅ 如果应用程序正在运行,URL是否正确:```
✓ Tests execute against your application
✓ Screenshots/videos saved on failures
✓ HTML report generated automatically
✓ Results in test-results/reports/index.html
**❌ 如果应用程序URL错误/未运行:**```
✗ Tests will fail with connection errors
✗ Error: "net::ERR_CONNECTION_REFUSED"
✗ Error: "Navigation timeout"
修复: 检查 BASEURL 在 .env.QA1 并确保您的应用程序正在运行
⚠️ 如果首次运行测试失败:
这是 正常 如果:
- 未配置应用程序URL(更新
.env.QA1) - 应用程序未运行(请先启动应用程序)
- 测试场景与您的应用程序不匹配(您需要编写自定义测试)
样品测试是为特定应用而设计的。 您需要:
- 更新中的测试场景
src/tests/features/ - 更新中的页面对象
src/pages/ - 更新测试数据
test-data-store/
看 编写新测试 以供指导。
🎉 安装完成!
如果测试成功运行,您就可以编写和执行测试了!
接下来是什么?
- ✅ 测试正在运行?太棒了尝试中的命令 运行测试
- ✅ 想写你的第一个测试吗?跳到 编写新测试
- ✅ 好奇这一切是如何运作的?结账 架构概述
🏃 如何运行测试
基本命令```powershell
Run all tests
npm test
Run tests in headed mode (see browser)
npm test -- --headed
Run specific feature
npm test -- --name "Login"
Run tests with specific tag
npm test -- --tags "@smoke"
Run failed tests only
npm run test:failed
### 先予执行
#### 环境特定执行
**这是什么?** 在不更改代码的情况下,对不同的环境(QA、Staging、Production)运行测试。```powershell
# Run tests against QA1 environment (default)
npm test
# Run tests against QA2 environment
npm test -- --ENV=QA2
# Run tests against custom environment
npm test -- --ENV=staging
它是如何工作的:
- 创建环境文件:
src/helpers/env/.env.{ENV_NAME} - 集
BASEURL以及该文件中的其他变量 - 运行:
npm test -- --ENV={ENV_NAME}
示例 .env.staging 文件:```env
BASEURL=https://staging.yourapp.com
BROWSER=chrome
HEAD=false
LOG_LEVEL=info
#### 基于标签的执行```powershell
# Run only smoke tests
npm test -- --TAGS="@smoke"
# Run regression tests
npm test -- --TAGS="@regression"
# Run multiple tags
npm test -- --TAGS="@smoke or @critical"
# Exclude tags
npm test -- --TAGS="not @slow"
并行执行```powershell
Run tests in parallel (default: auto-detect CPU cores)
npm test -- --parallel 4
Sequential execution
npm test -- --parallel 1
#### 浏览器选择```powershell
# Run in specific browser (configure in playwright.config.ts)
# By default, runs in Chromium
📊 查看测试报告
测试执行后,会自动生成报告:```powershell
HTML Report (most detailed)
test-results/reports/index.html
Cucumber JSON Report
test-results/cucumber-report.json
JUnit XML Report
test-results/junit.xml
**打开HTML报告:**```powershell
# Windows
start test-results/reports/index.html
# macOS
open test-results/reports/index.html
# Linux
xdg-open test-results/reports/index.html
📂 测试工件
每次测试运行后,都会创建以下工件:
| 工件 | 位置 | 目的 |
|---|---|---|
| 日志 | test-results/logs/ |
每个场景的详细执行日志 |
| 截图 | test-results/screenshots/ |
故障截图 |
| 视频 | test-results/videos/ |
完整的测试记录 |
| 痕迹 | test-results/traces/ |
用于调试的Playwright跟踪文件 |
| 报告 | test-results/reports/ |
HTML测试报告 |
🔍 调试失败的测试```powershell
1. Check the HTML report for failure details
start test-results/reports/index.html
2. View logs for specific scenario
Located in: test-results/logs//
3. Open Playwright trace (best for debugging)
npx playwright show-trace test-results/traces//trace.zip
4. Run single test with headed mode
npm test -- --name "Login" --headed
______________________________________________________________________
## ✍️ 写作和扩展测试
### 在哪里添加新测试
1. **特征文件**: `src/tests/features/your-feature.feature`
1. **步骤定义**: `src/tests/steps/yourFeatureSteps.ts`
1. **页面对象**: `src/pages/your-page/yourPage.ts`
1. **测试数据**: `test-data-store/your-feature/data.json`
### 🎯 分步指南
#### 1.️⃣ 创建要素文件
**例子:** 特征文件(来自 `src/tests/features/login.feature`):
**文件**: `src/tests/features/login.feature````gherkin
@login
Feature: User Authentication tests
Background:
Given User navigates to the application
@1
Scenario: Login should pass
And logs-in as "json://LOGIN_USER_DATA#appAdminUser"
Then Login should pass
@2
Scenario: Login should fail
And User enters the username as "invalidUser"
* User enters the password as "pass123"
When User clicks on the login button
But Login should fail
2.️⃣ 创建页面对象、步骤定义和测试数据
完整的代码示例(登录功能, LoginPage, loginSteps.ts,和样本测试数据)被移动到 docs/examples.md 为了使README保持简洁,请参阅 docs/examples.md 获取完整的代码片段和可复制的示例。
📋 最佳实践
不要担心记住这些——当你写测试时,你会自然地学习它们的!
✅ 做:
- 将页面对象模型(POM)用于所有UI交互(见上面的示例)
- 写描述性场景名称(“用户使用有效凭据登录”而不是“测试1”)
- 保持场景独立(每个测试都应该单独运行)
- 使用测试组织标签(例如:
@smoke,@regression) - 添加有意义的日志消息(有助于以后的调试)
- 使用JSON文件的数据驱动方法(更容易更新测试数据)
❌ 不要:
- 使用直接剧作家电话(例如:
page.locator(),page.click())步内定义 - 添加断言(例如:
expect())在页面类中(将它们保留在步骤定义中) - 创建长场景(为了可读性,请保持在10步以内)
- 使用硬编码的等待(例如:
setTimeout)--框架会自动等待! - 在场景之间共享状态(导致测试不稳定)
🎨 命名约定
| 元素 | 惯例 | 示例 |
|---|---|---|
| 特征文件 | kebab-case.feature |
user-login.feature |
| 页面类别 | PascalCase |
LoginPage, DashboardPage |
| 方法 | camelCase 带有动词前缀 |
clickSubmitButton(), enterUsername() |
| 定位器 | camelCase 描述性 |
usernameInput, submitButton |
| 步骤文件 | camelCase + Steps.ts |
loginSteps.ts, dashboardSteps.ts |
🏷️ 标记策略
例子: 在要素文件中标记:```gherkin
Feature-level tags
@login @authentication
Feature: User Login
Scenario-level tags
@smoke @critical
Scenario: Login with valid credentials
...
@negative
Scenario: Login with invalid credentials
...
**常用标签(可选-使用对您的项目有意义的标签):**
- `@smoke` -关键路径测试(在每次发布之前运行)
- `@regression` -完整回归套件(所有测试)
- `@critical` -必须通过测试(核心功能)
- `@wip` -正在进行中(测试正在开发中)
- `@skip` -暂时禁用(已知问题)
- `@slow` -长期运行测试(单独运行)
**你自己决定标签!** 这些只是例子。使用与团队工作流程相匹配的标签。
______________________________________________________________________
## 🤖 使用上下文和提示目录
**这是什么?** 该框架包括 **特殊目录** 旨在与无缝协作 **GitHub Copilot** 和那个 **剧作家MCP(模型上下文协议)服务器** 用于人工智能辅助测试生成。
**简单来说:** 这些文件帮助GitHub Copilot编写更好的测试,自动遵循项目的标准。
**GitHub Copilot新手?** 没关系!您可以按照中的示例手动编写测试 写作测试 部分。当你准备好探索人工智能辅助时,请回到本节。
### 📁 `context/` 目录
包含提供以下内容的文件 **背景和指导方针** 生成测试时,请将测试结果发送到GitHub Copilot。
#### 文件夹:
|文件|目的|
|------|---------|
| **`guidelines.txt`** |全面的编码标准、命名约定、POM规则、BDD标准、定位器策略和验证规则|
| **`webContext.txt`** |Playwright MCP集成说明,使用页面对象模型生成测试的规则|
#### 如何使用:
1. **Copilot聊天中的参考:**
- 附加 `context/guidelines.txt` 当要求Copilot使用文件中的标准生成测试时
- 确保生成的代码符合项目标准
2.**如何使用提示文件**
1. 从提示文件夹中打开所需的提示文件(例如: 提示/new_feature_prompt.txt).
1. 附加所需的上下文文件,以便Copilot/MCP遵循项目标准(例如: 上下文/指南.txt).
1. 复制整个提示文件内容并将其粘贴到Copilot/MCP聊天输入中。将上下文引用放在单独的行上,例如:
示例提示:```
Attached the context file for example: @context/guidelines.txt
📝 prompts/ 目录
包含 示例提示 演示如何让Copilot生成测试。
文件夹:
| 文件 | 目的 |
|---|---|
new_feature_prompt.txt |
提示为功能编写新测试 |
🚀 人工智能辅助测试生成工作流程
使用GitHub Copilot和Playwright MCP:
第一步:提供上下文```
@context/guidelines.txt
@context/webContext.txt
Generate a test for user dashboard navigation following the same pattern.
**步骤2:复制副本生成:**
- ✅ 具有Gherkin语法的特征文件
- ✅ 具有适当结构的页面对象类
- ✅ 将Gherkin链接到代码的步骤定义
- ✅ 遵循定位器策略优先级(数据测试ID→ role → 标签→ CSS)
**步骤3:回顾并运行**```powershell
# Run the generated test
npm test -- --name "Dashboard Navigation"
🎯 副驾驶的示例场景
1.️⃣ 生成新测试```
Using @context/guidelines.txt, create a test for:
Feature: Password Reset
- User requests password reset
- Receives email
- Clicks reset link
- Enters new password
- Confirms reset success
Include feature file, page objects, and step definitions.
#### 2.️⃣ 重构现有测试```
Using @prompts/pom_architecture_updation.txt,
refactor src/tests/steps/checkoutSteps.ts to use Page Object Model.
Create CheckoutPage class with proper locator strategy.
3.️⃣ 添加测试数据```
Using @context/guidelines.txt,
create test data JSON file for e-commerce checkout scenarios:
- Valid credit card
- Expired card
- Invalid CVV
- Missing billing address
Follow naming conventions in guidelines.
### 📚 人工智能辅助开发的最佳实践
#### ✅ 做:
- 始终连接 `context/guidelines.txt` 为了一致性
- 参考示例提示 `prompts/` 目录
- 检查生成的代码是否正确
- 生成后运行并验证测试
- 随着标准的发展更新上下文文件
#### ❌ 不要:
- 生成测试而不提供上下文文件
- 接受生成的代码而不进行审核
- 忽略定位器策略优先级
- 跳过运行生成的测试
______________________________________________________________________
## 🔧 配置Playwright MCP服务器
### 什么是MCP(模型上下文协议)?
**主控程序** 是一种协议,允许GitHub Copilot等人工智能助手与工具和服务进行交互。这 **剧作家MCP服务器** 使Copilot能够:
- 🌐 **浏览网页并与之交互** 实时的
- 📸 **捕获屏幕截图和页面快照** 用于分析
- 🔍 **检查页面元素和结构** 生成精确的定位器
- ✅ **验证测试实现** 针对实时应用程序
- 🤖 **自动生成测试** 基于实际页面行为
### MCP的先决条件
启用MCP之前,请确保:
1. ✅ **VS Code** 已安装GitHub Copilot扩展
1. ✅ **Node.js 18+** 安装
1. ✅ **剧作家浏览器** 已安装(`npx playwright install`)
1. ✅ **这个项目** 已安装依赖项(`npm install`)
### 启用剧作家MCP服务器
#### 步骤1:配置VS代码设置
打开您的VS代码设置(JSON格式):
**窗户:**```powershell
# Open Command Palette (Ctrl+Shift+P)
# Type: "Preferences: Open User Settings (JSON)"
或手动编辑:```
%APPDATA%\Code\User\settings.json
#### 步骤2:添加MCP配置
将以下内容添加到您的 `settings.json`:```json
{
"github.copilot.chat.mcp.enabled": true,
"github.copilot.chat.mcp.servers": {
"playwright": {
"command": "node",
"args": [
"${workspaceFolder}/node_modules/@playwright/mcp/dist/index.js"
],
"env": {
"PLAYWRIGHT_BROWSER": "chromium"
}
}
}
}
步骤3:验证MCP服务器安装```powershell
Check if Playwright MCP package is installed
npm list @playwright/mcp
If not found, install it:
npm install --save-dev @playwright/mcp
#### 步骤4:重新启动VS代码```powershell
# Close and reopen VS Code to activate MCP server
# Or use Command Palette: "Developer: Reload Window"
配置选项
浏览器选择
选择MCP服务器应使用的浏览器:```json
"env": {
"PLAYWRIGHT_BROWSER": "chromium" // Options: chromium, firefox, webkit
}
#### 无头模式
在无头模式下运行浏览器(无UI):```json
"env": {
"PLAYWRIGHT_BROWSER": "chromium",
"PLAYWRIGHT_HEADLESS": "true" // true = headless, false = headed
}
自定义视口
设置自定义视口大小:```json
"env": {
"PLAYWRIGHT_BROWSER": "chromium",
"PLAYWRIGHT_VIEWPORT_WIDTH": "1920",
"PLAYWRIGHT_VIEWPORT_HEIGHT": "1080"
}
### 在GitHub Copilot中使用MCP
#### Copilot如何使用MCP读取工作区文件
启用MCP后,GitHub Copilot可以:
1. **📂 读取工作区结构** 了解项目组织
1. **📖 分析现有页面对象** 保持一致性
1. **🔎 检查测试文件** 学习你的测试模式
1. **📋 访问测试数据** 生成逼真的测试场景
1. **🌐 导航到您的应用程序** 检查真实元素
#### 示例:使用MCP生成测试
**无MCP(手动):**```
You: "Create a login test"
Copilot: [Generates generic login test with placeholder locators]
使用MCP(智能):```
You: "@webContext.txt Navigate to http://localhost:3000/login and create a login test"
Copilot:
1. Opens the URL in browser via MCP
2. Inspects actual page elements
3. Identifies real locators (data-testid, roles, labels)
4. Reads existing Page Objects from workspace
5. Generates test following your project patterns
6. Uses actual element attributes from the page
Result: ✅ Accurate test with real locators, zero manual inspection needed!
#### 副驾驶聊天中的MCP命令
使用以下命令来利用MCP功能:
**1.导航到页面:**```
@workspace Navigate to http://localhost:3000/dashboard using MCP
Show me the page structure
2.检查元件:```
Using MCP, navigate to the login page and tell me the locator for the username field
**3.从实时页面生成测试:**```
@webContext.txt @guidelines.txt
Using MCP:
1. Navigate to http://localhost:3000/checkout
2. Inspect all form fields
3. Generate a complete checkout test with:
- Feature file
- Page Object with real locators
- Step definitions
- Test data
Follow project standards from guidelines.txt
4.验证现有测试:```
Using MCP, validate if src/pages/login/loginPage.ts locators still work on http://localhost:3000/login
Report any broken or changed locators.
**5.从页面创建测试数据:**```
Using MCP, navigate to http://localhost:3000/profile and generate test data JSON for all form fields
MCP工作流示例
场景:创建新的功能测试
第一步:提供上下文```
@guidelines.txt - Found Project Standards
@webContext.txt - Explain Persona
I need to create tests for the new "User Profile" feature.
Application URL: http://localhost:3000/profile
**步骤2:让MCP检查页面**```
Using MCP:
1. Navigate to http://localhost:3000/profile
2. Capture page snapshot
3. List all interactive elements with their locators
4. Identify form fields and buttons
步骤3:副驾驶响应(通过MCP):```
✅ Inspected http://localhost:3000/profile
Found elements:
- First Name: input[data-testid="profile-firstname"]
- Last Name: input[data-testid="profile-lastname"]
- Email: input[type="email"][name="email"]
- Save Button: button[role="button"]:has-text("Save")
- Cancel Button: button.btn-secondary:has-text("Cancel")
Ready to generate test. Proceed?
**步骤4:生成完整测试**```
Yes, generate:
1. Feature file: src/tests/features/profile.feature
2. Page Object: src/pages/profile/profilePage.ts
3. Step definitions: src/tests/steps/profileSteps.ts
4. Test data: test-data-store/profile/users.json
Follow all guidelines.
步骤5:副驾驶生成(利用MCP检查):
✅ 使用创建的所有文件 来自实时页面的精确定位器
✅ 跟踪项目 页面对象模型 结构
✅ 用途 定位策略优先级 (首先找到数据testid!)
✅ 包括适当 错误处理和日志
MCP优势
| 无MCP | 有MCP |
|---|---|
| 😞 手动页面检查 | ✅ 自动页面检查 |
| 😞 猜测定位器 | ✅ 来自实时页面的真实定位器 |
| 😞 试错测试 | ✅ 预先验证的定位器 |
| 😞 过时的文件 | ✅ 当前页面状态 |
| 😞 通用测试模式 | ✅ 项目特定模式 |
MCP故障排除
问题1:MCP服务器未启动
问题:
settings.json 配置不正确
解决方案:```json
// Verify correct path format
"args": [
"${workspaceFolder}/node_modules/@playwright/mcp/dist/index.js"
],
// NOT:
// "${workspaceFolder}\node_modules\@playwright\mcp\dist\index.js" ❌
#### 问题2:浏览器无法打开
**问题:** 未安装Playwright浏览器
**解决方案:**```powershell
npx playwright install
问题3:MCP命令不起作用
问题: 副驾驶设置中未启用MCP
解决方案:```json
// Ensure this is set to true:
"github.copilot.chat.mcp.enabled": true
#### 问题4:拒绝许可
**问题:** Windows执行策略阻止Node.js
**解决方案:**```powershell
# Run as Administrator
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
验证MCP是否正常工作
在Copilot聊天中测试MCP连接:```
@workspace Using MCP, navigate to https://playwright.dev and tell me the page title
**预期响应:**```
✅ Navigated to https://playwright.dev
Page title: "Fast and reliable end-to-end testing for modern web apps | Playwright"
如果你看到这个, MCP工作正常! 🎉
🔧 为您的项目自定义上下文
随着项目的发展,更新上下文文件:```powershell
Add new naming conventions
Edit: context/guidelines.txt
Update locator strategies
Edit: context/guidelines.txt → Section 2
Add new example prompts
Create: prompts/your-new-feature.txt
### 🌟 示例:完整的人工智能辅助工作流程```powershell
# 1. Attach context to Copilot
@context/guidelines.txt
@context/webContext.txt
# 2. Provide specific requirements
Create a test for:
Feature: Multi-step checkout
- Add item to cart
- Proceed to checkout
- Fill shipping information
- Select payment method
- Complete order
- Verify order confirmation
# 3. Copilot generates:
✅ src/tests/features/checkout.feature
✅ src/pages/cart/cartPage.ts
✅ src/pages/checkout/checkoutPage.ts
✅ src/tests/steps/checkoutSteps.ts
✅ test-data-store/checkout/orders.json
# 4. Review and run
npm test -- --name "Multi-step checkout"
# 5. View report
start test-results/reports/index.html
🛠️ 常见错误和故障排除
问题1: node: command not found
问题: Node.js未安装或未在PATH中
解决方案:```powershell
Download and install Node.js from:
https://nodejs.org/
Verify installation
node --version
______________________________________________________________________
### 问题2: `npx playwright install` 失败
**问题:** 网络问题或权限错误
**解决:**
**A) 网络/防火墙:**```powershell
# Set proxy if behind corporate firewall
$env:HTTPS_PROXY="http://proxy.company.com:8080"
# Then retry
npx playwright install
B) 权限被拒绝(Windows):```powershell
Run PowerShell as Administrator
Then retry installation
**C) 磁盘空间:**```powershell
# Check available disk space
Get-PSDrive C
# Playwright needs ~1GB for all browsers
问题3:测试失败,显示“未找到浏览器”
问题: 未安装Playwright浏览器
解决方案:```powershell
Install all browsers
npx playwright install
Or specific browser
npx playwright install chromium
______________________________________________________________________
### 问题4: `Cannot find module '@cucumber/cucumber'`
**问题:** 未安装依赖项
**解决方案:**```powershell
# Delete node_modules and package-lock.json
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
# Reinstall dependencies
npm install
问题5:测试超时或挂起
问题: 找不到元素或网络延迟
解决:
A) 检查元件定位器:```typescript
// Add logging to see what's happening
fixture.logger.info('Waiting for element...');
await fixture.pwWrapper.waitForElementVisible(locator);
**B) 增加超时时间:**```typescript
// In playwright.config.ts
timeout: 60000 // 60 seconds
C) 检查网络:```powershell
Run in headed mode to see what's happening
npm test -- --headed
______________________________________________________________________
### 问题6:“端口已在使用中”错误
**问题:** 之前的测试运行没有清理干净
**解决方案:**```powershell
# Find process using port 3000 (example)
Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess
# Kill the process
Stop-Process -Id -Force
问题7:未生成截图/视频
问题: 配置问题
解决方案:```typescript
// In playwright.config.ts, ensure:
use: {
screenshot: 'only-on-failure',
video: 'retain-on-failure',
trace: 'retain-on-failure',
}
______________________________________________________________________
### 问题8: `npm test` 因语法错误而失败
**问题:** TypeScript编译错误
**解决方案:**```powershell
# Check TypeScript errors
npx tsc --noEmit
# Fix errors in reported files
# Then rerun tests
npm test
问题9:未加载环境变量
问题:
.env 找不到文件或格式错误
解决方案:```powershell
Ensure .env file exists in src/helpers/env/
Check file format:
BASE_URL=http://localhost:3000
TIMEOUT=30000
No quotes, no spaces around =
______________________________________________________________________
### 问题10:HTML报告无法打开
**问题:** 文件路径问题或浏览器默认设置
**解决方案:**```powershell
# Windows - specify browser
start chrome test-results/reports/index.html
# Or navigate manually
# File Explorer → test-results/reports/index.html → Right-click → Open with Chrome
🆘 仍然卡住?
- 检查日志:```powershell
View latest scenario log
ls test-results/logs/ | Sort-Object LastWriteTime -Descending | Select-Object -First 1
1. **在调试模式下运行单个测试:**```powershell
npm test -- --name "Your Test" --headed
- 查看剧作家追踪:```powershell
npx playwright show-trace test-results/traces//trace.zip
1. **查看GitHub问题:**
- 剧作家问题
- 黄瓜问题
______________________________________________________________________
## 🤖 使用上下文和提示(GitHub Copilot+MCP)
该项目包括使用GitHub Copilot(和Playwright MCP服务器)辅助生成功能文件、步骤实现和重构的帮助文件。
### 在哪里看
- 上下文文件(指南和说明): 上下文/指南.txt
- 提示示例: `prompts/` 文件夹。关键文件:
- 提示/new_feature_prompt.txt
### 使用哪个提示——快速指南
- `prompts/new_feature_prompt.txt`:当您希望Copilot(或LLM)创建全新的功能测试时,请使用此选项。它生成一个或多个 `.feature` 文件、建议的步骤定义以及所需页面对象和测试数据条目的列表。生成Gherkin场景和推荐的步骤实现。
### 何时使用提示
- 编写代码前:创建 `.feature` 文件和初始步骤大纲 `new_feature_prompt.txt`.
### 如何使用(循序渐进)
1. 在VS Code中打开项目。
1. 安装并登录到 **GitHub Copilot** (见下面的先决条件)。
1. 安装 **VSCode剧作家测试** (延伸)和 **剧作家MCP服务器** (见下一节)。
1. 打开相关上下文文件(`context/guidelines.txt` 以及任何提示 `prompts/`)在编辑器中,当工作区中存在上下文文件时,MCP/Copilot的工作效果最佳。
1. 复制提示内容(或打开提示文件)并粘贴到Copilot Chat或MCP聊天输入中。要求Copilot“生成功能、步骤和页面对象”或类似内容。
1. 仔细审查生成的代码,将建议移至适当的位置 `src/tests/features/`, `src/tests/steps/`, `src/pages/` 和 `test-data-store/` 位置,然后运行 `npm test`.
### 故障排除提示生成
- 如果建议不符合上下文:打开 `context/guidelines.txt` 以及同一编辑器窗口中的相关提示文件。
- 如果MCP显示连接错误:请确保Playwright MCP服务器扩展已安装并在VS Code中运行。
- 始终手动审查Copilot生成的代码——将其视为脚手架,而不是生产就绪的代码。
______________________________________________________________________
## ✅ 先决条件和重要工具(明确清单)
按照以下步骤准备您的环境。每个项目都包含一个快速验证命令。
1. VS Code
- 从以下位置安装:https://code.visualstudio.com/
- 验证: `code --version`
2. Node.js
- 从以下位置安装Node.js 18+https://nodejs.org/
- 验证: `node --version` (预计v18.x+)
3. GitHub副本(扩展)和GitHub帐户
- 安装 **GitHub Copilot** 在VS Code中扩展并使用您的GitHub帐户登录。
- 验证:打开VS Code中的Copilot窗格,确认您已登录。
4. 剧作家(TypeScript)
- 该项目已经包括剧作家devDeps。要确保安装了Playwright+TypeScript:```powershell
npm install
npx playwright install
- 验证:
npx playwright --version
- 剧作家VSCode扩展
- 安装名为的扩展 VSCode剧作家测试 来自VS代码扩展市场。
- 剧作家MCP服务器
- 打开:https://github.com/microsoft/playwright-mcp?tab=readme-ov文件
- 点击 安装服务器VS代码;确认打开VS Code并单击 安装 当VS Code提示您时。
- 或者,如果链接不起作用,请从VS Code中的Extensions视图安装扩展。
- 黄瓜/小黄瓜模具
- 确保
cucumber-js在项目依赖关系中可用(仓库使用Cucumber)。通过以下方式进行验证:```powershell
npx cucumber-js --version
- 安装VS代码扩展 **黄瓜(Gherkin)全力支持** 用于语法高亮显示和步骤导航。
### 快速验证命令```powershell
node --version
npm --version
code --version
npx playwright --version
npx cucumber-js --version
git --version
常见安装问题和修复
- npm安装失败(网络/代理):
- 重试:
npm cache clean --force然后rm -rf node_modules package-lock.json和npm install. - Playwright浏览器安装失败:
- 在Windows上:运行
npx playwright install再一次。如果权限错误,请以管理员身份重新启动VS Code。 - 在Linux上:运行
npx playwright install --with-deps并确保安装了所需的系统包。 - GitHub Copilot未登录:打开Copilot扩展窗格并按照登录流程进行操作;确保您的GitHub帐户可以访问Copilot。
- MCP服务器无法从浏览器链接安装:打开VS Code中的Extensions视图,搜索“Playwright MCP”并手动安装,或按照GitHub仓库中的服务器README进行安装。
如果第一次运行测试失败
- 确认
BASEURL在src/helpers/env/.env.QA1指向被测应用程序的运行实例。 - 使用以下命令运行单个场景
npm test -- --name "Your Scenario" --headed观察浏览器并调试。 - 使用Playwright跟踪进行深度调试:```powershell
npx playwright show-trace test-results/traces//trace.zip
______________________________________________________________________
## 🔁 下一代:下一步
- 移动已生成 `.feature` 文件进入 `src/tests/features/`.
- 将建议的步骤实施移到 `src/tests/steps/` 并将它们连接到特征文件。
- 在中添加或更新页面对象 `src/pages/` 测试数据 `test-data-store/`.
- 跑 `npm test` 并迭代。
______________________________________________________________________
## 🤝 贡献
我们欢迎捐款!以下是如何开始:
### 1.️⃣ 分叉与克隆```powershell
# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/playwright_demo.git
2.️⃣ 创建特征分支```powershell
git checkout -b feature/your-feature-name
### 3.️⃣ 进行更改
- 遵循以下编码标准 `context/guidelines.txt`
- 为新功能编写测试
- 根据需要更新文档
### 4.️⃣ 运行测试```powershell
# Ensure all tests pass
npm test
# Run linting
npm run lint
5.️⃣ 承诺与推动```powershell
git add .
git commit -m "feat: add new feature"
git push origin feature/your-feature-name
```
6.️⃣ 创建拉取请求
- 转到GitHub
- 从您的分支创建Pull Request
- 描述您的更改
- 等待审核
📏 代码规范
- 代码检查:ESLint与TypeScript
- 格式化:更漂亮
- 命名:camelCase用于函数/变量,PasclCase用于类
- 评论:公共方法的JSDoc
- 测试:所有新功能都必须包括测试
📚 其他资源
文档
- 剧作家文档
- Cucumber文档
- TypeScript手册
- 架构指南 -深入了解框架设计
教程
- 剧作家入门
- 黄瓜BDD教程
- 页面对象模型模式
社区
- 剧作家不和
- 黄瓜社区
测试愉快! 🎭✨
