Mc Pdemo V1

🎭 Playwright+Cumber BDD测试自动化框架

一个生产就绪、可扩展的测试自动化框架，结合了Playwright的强大功能和Cucumber BDD的可读性。

   ](https://nodejs.org/)

______________________________________________________________________

🧾 申请自动化测试（快速流程）

一个简短、易于遵循的流程，用于向Copilot/MCP或人工审查员请求自动测试。从下面的快速步骤开始立即采取行动，然后按照详细流程获取完整指导。

快速步骤

1. 添加所需的上下文：附加 context/guidelines.txt 以及任何特定功能的上下文文件。
2. 选择适当的提示：使用 prompts/new_feature_prompt.txt 或者为该功能定制提示。
3. 在副驾驶/MCP聊天和参考上下文文件中附加提示（例如。， @context/guidelines.txt).
4. 查看生成的输出：特征文件、页面对象、步骤定义和测试数据。
5. 在本地运行并验证： 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 用于完整的提示、示例场景和人工智能辅助的工作流程。 不确定从哪里开始？使用本指南：

💡 完全初学者？ 别担心！你不需要深入的剧作家或自动化测试知识来开始。只要跟着 快速开始 指南——它是为绝对初学者设计的。

______________________________________________________________________

🧭 项目概述

这解决了什么问题？

传统的UI测试是 易碎、难以维护、难以阅读该框架通过以下方式使测试更容易：

1. BDD/小黄瓜用任何人都能理解的简单英语写测试
2. 页面对象模型：易于维护的有组织、可重用的代码
3. 智能包装：自动重试和回退（更少不稳定的测试！）
4. 丰富的日志记录：出错时用于调试的详细日志
5. 美丽的报道：带有屏幕截图和故障视频的HTML报告

底线： 你花更少的时间修复测试，花更多的时间发现真正的bug。

测试流程示例

例子： 本地代码库中的实际登录测试：

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示例：

# 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：验证设置

# 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)
• 应用程序未运行（请先启动应用程序）
• 测试场景与您的应用程序不匹配（您需要编写自定义测试）

样品测试是为特定应用而设计的。 您需要：

1. 更新中的测试场景 src/tests/features/
2. 更新中的页面对象 src/pages/
3. 更新测试数据 test-data-store/

看 编写新测试 以供指导。

🎉 安装完成！

如果测试成功运行，您就可以编写和执行测试了！

接下来是什么？

• ✅ 测试正在运行？太棒了尝试中的命令 运行测试
• ✅ 想写你的第一个测试吗？跳到 编写新测试
• ✅ 好奇这一切是如何运作的？结账 架构概述

______________________________________________________________________

🏃 如何运行测试

基本命令

# 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）运行测试。

# 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

它是如何工作的：

1. 创建环境文件： src/helpers/env/.env.{ENV_NAME}
2. 集 BASEURL 以及该文件中的其他变量
3. 运行： npm test -- --ENV={ENV_NAME}

示例 .env.staging 文件：

BASEURL=https://staging.yourapp.com
BROWSER=chrome
HEAD=false
LOG_LEVEL=info

基于标签的执行

# 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"

并行执行

# Run tests in parallel (default: auto-detect CPU cores)
npm test -- --parallel 4

# Sequential execution
npm test -- --parallel 1

浏览器选择

# Run in specific browser (configure in playwright.config.ts)
# By default, runs in Chromium

📊 查看测试报告

测试执行后，会自动生成报告：

# 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报告：

# Windows
start test-results/reports/index.html

# macOS
open test-results/reports/index.html

# Linux
xdg-open test-results/reports/index.html

📂 测试工件

每次测试运行后，都会创建以下工件：

🔍 调试失败的测试

# 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
2. 步骤定义: src/tests/steps/yourFeatureSteps.ts
3. 页面对象: src/pages/your-page/yourPage.ts
4. 测试数据: test-data-store/your-feature/data.json

🎯 分步指南

1.️⃣ 创建要素文件

例子： 特征文件（来自 src/tests/features/login.feature):

文件: src/tests/features/login.feature

@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)--框架会自动等待！
• 在场景之间共享状态（导致测试不稳定）

🎨 命名约定

🏷️ 标记策略

例子： 在要素文件中标记：

# 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。

文件夹：

如何使用：

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生成测试。

文件夹：

🚀 人工智能辅助测试生成工作流程

使用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：回顾并运行

# 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扩展
2. ✅ Node.js 18+ 安装
3. ✅ 剧作家浏览器 已安装(npx playwright install)
4. ✅ 这个项目 已安装依赖项(npm install)

启用剧作家MCP服务器

步骤1：配置VS代码设置

打开您的VS代码设置（JSON格式）：

窗户：

# Open Command Palette (Ctrl+Shift+P)
# Type: "Preferences: Open User Settings (JSON)"

或手动编辑：

%APPDATA%\Code\User\settings.json

步骤2：添加MCP配置

将以下内容添加到您的 settings.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服务器安装

# Check if Playwright MCP package is installed
npm list @playwright/mcp

# If not found, install it:
npm install --save-dev @playwright/mcp

步骤4：重新启动VS代码

# Close and reopen VS Code to activate MCP server
# Or use Command Palette: "Developer: Reload Window"

配置选项

浏览器选择

选择MCP服务器应使用的浏览器：

"env": {
  "PLAYWRIGHT_BROWSER": "chromium"  // Options: chromium, firefox, webkit
}

无头模式

在无头模式下运行浏览器（无UI）：

"env": {
  "PLAYWRIGHT_BROWSER": "chromium",
  "PLAYWRIGHT_HEADLESS": "true"     // true = headless, false = headed
}

自定义视口

设置自定义视口大小：

"env": {
  "PLAYWRIGHT_BROWSER": "chromium",
  "PLAYWRIGHT_VIEWPORT_WIDTH": "1920",
  "PLAYWRIGHT_VIEWPORT_HEIGHT": "1080"
}

在GitHub Copilot中使用MCP

Copilot如何使用MCP读取工作区文件

启用MCP后，GitHub Copilot可以：

1. 📂 读取工作区结构 了解项目组织
2. 📖 分析现有页面对象 保持一致性
3. 🔎 检查测试文件 学习你的测试模式
4. 📋 访问测试数据 生成逼真的测试场景
5. 🌐 导航到您的应用程序 检查真实元素

示例：使用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故障排除

问题1:MCP服务器未启动

问题： settings.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浏览器

解决方案：

npx playwright install

问题3:MCP命令不起作用

问题： 副驾驶设置中未启用MCP

解决方案：

// Ensure this is set to true:
"github.copilot.chat.mcp.enabled": true

问题4：拒绝许可

问题： Windows执行策略阻止Node.js

解决方案：

# 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工作正常！ 🎉

______________________________________________________________________

🔧 为您的项目自定义上下文

随着项目的发展，更新上下文文件：

# 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

🌟 示例：完整的人工智能辅助工作流程

# 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中

解决方案：

# Download and install Node.js from:
https://nodejs.org/

# Verify installation
node --version

______________________________________________________________________

问题2： npx playwright install 失败

问题： 网络问题或权限错误

解决：

A） 网络/防火墙：

# Set proxy if behind corporate firewall
$env:HTTPS_PROXY="http://proxy.company.com:8080"

# Then retry
npx playwright install

B） 权限被拒绝（Windows）：

# Run PowerShell as Administrator
# Then retry installation

C） 磁盘空间：

# Check available disk space
Get-PSDrive C

# Playwright needs ~1GB for all browsers

______________________________________________________________________

问题3：测试失败，显示“未找到浏览器”

问题： 未安装Playwright浏览器

解决方案：

# Install all browsers
npx playwright install

# Or specific browser
npx playwright install chromium

______________________________________________________________________

问题4： Cannot find module '@cucumber/cucumber'

问题： 未安装依赖项

解决方案：

# Delete node_modules and package-lock.json
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json

# Reinstall dependencies
npm install

______________________________________________________________________

问题5：测试超时或挂起

问题： 找不到元素或网络延迟

解决：

A） 检查元件定位器：

// Add logging to see what's happening
fixture.logger.info('Waiting for element...');
await fixture.pwWrapper.waitForElementVisible(locator);

B） 增加超时时间：

// In playwright.config.ts
timeout: 60000 // 60 seconds

C） 检查网络：

# Run in headed mode to see what's happening
npm test -- --headed

______________________________________________________________________

问题6：“端口已在使用中”错误

问题： 之前的测试运行没有清理干净

解决方案：

# Find process using port 3000 (example)
Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess

# Kill the process
Stop-Process -Id 
 -Force

______________________________________________________________________

问题7：未生成截图/视频

问题： 配置问题

解决方案：

// In playwright.config.ts, ensure:
use: {
  screenshot: 'only-on-failure',
  video: 'retain-on-failure',
  trace: 'retain-on-failure',
}

______________________________________________________________________

问题8： npm test 因语法错误而失败

问题： TypeScript编译错误

解决方案：

# Check TypeScript errors
npx tsc --noEmit

# Fix errors in reported files
# Then rerun tests
npm test

______________________________________________________________________

问题9：未加载环境变量

问题： .env 找不到文件或格式错误

解决方案：

# 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报告无法打开

问题： 文件路径问题或浏览器默认设置

解决方案：

# 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

______________________________________________________________________

🆘 仍然卡住？

1. 检查日志：

   # View latest scenario log
   ls test-results/logs/ | Sort-Object LastWriteTime -Descending | Select-Object -First 1

1. 在调试模式下运行单个测试：

   npm test -- --name "Your Test" --headed

1. 查看剧作家追踪：

   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中打开项目。
2. 安装并登录到 GitHub Copilot （见下面的先决条件）。
3. 安装 VSCode剧作家测试 （延伸）和 剧作家MCP服务器 （见下一节）。
4. 打开相关上下文文件(context/guidelines.txt 以及任何提示 prompts/)在编辑器中，当工作区中存在上下文文件时，MCP/Copilot的工作效果最佳。
5. 复制提示内容（或打开提示文件）并粘贴到Copilot Chat或MCP聊天输入中。要求Copilot“生成功能、步骤和页面对象”或类似内容。
6. 仔细审查生成的代码，将建议移至适当的位置 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

1. Node.js

• 从以下位置安装Node.js 18+https://nodejs.org/
• 验证： node --version （预计v18.x+）

1. GitHub副本（扩展）和GitHub帐户

• 安装 GitHub Copilot 在VS Code中扩展并使用您的GitHub帐户登录。
• 验证：打开VS Code中的Copilot窗格，确认您已登录。

1. 剧作家（TypeScript）

• 该项目已经包括剧作家devDeps。要确保安装了Playwright+TypeScript：

npm install
npx playwright install

• 验证： npx playwright --version

1. 剧作家VSCode扩展

• 安装名为的扩展 VSCode剧作家测试 来自VS代码扩展市场。

1. 剧作家MCP服务器

• 打开：https://github.com/microsoft/playwright-mcp?tab=readme-ov文件
• 点击 安装服务器VS代码；确认打开VS Code并单击 安装 当VS Code提示您时。
• 或者，如果链接不起作用，请从VS Code中的Extensions视图安装扩展。

1. 黄瓜/小黄瓜模具

• 确保 cucumber-js 在项目依赖关系中可用（仓库使用Cucumber）。通过以下方式进行验证：

npx cucumber-js --version

• 安装VS代码扩展 黄瓜（Gherkin）全力支持 用于语法高亮显示和步骤导航。

快速验证命令

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跟踪进行深度调试：

npx playwright show-trace test-results/traces//trace.zip

______________________________________________________________________

🔁 下一代：下一步

• 移动已生成 .feature 文件进入 src/tests/features/.
• 将建议的步骤实施移到 src/tests/steps/ 并将它们连接到特征文件。
• 在中添加或更新页面对象 src/pages/ 测试数据 test-data-store/.
• 跑 npm test 并迭代。

______________________________________________________________________

🤝 贡献

我们欢迎捐款！以下是如何开始：

1.️⃣ 分叉与克隆

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/playwright_demo.git

2.️⃣ 创建特征分支

git checkout -b feature/your-feature-name

3.️⃣ 进行更改

• 遵循以下编码标准 context/guidelines.txt
• 为新功能编写测试
• 根据需要更新文档

4.️⃣ 运行测试

# Ensure all tests pass
npm test

# Run linting
npm run lint

5.️⃣ 承诺与推动

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教程
• 页面对象模型模式

社区

• 剧作家不和
• 黄瓜社区

______________________________________________________________________

测试愉快！ 🎭✨