使用说明

MCPServer-剧作家测试自动化框架

📋 概述

使用Playwright和TypeScript的Sauce Demo电子商务应用程序的全面端到端测试自动化框架。该框架使用自定义夹具实现了页面对象模型（POM）设计模式，并从Excel文件中读取测试数据。

🚀 特性

页面对象模型（POM） -使用可重用方法组织页面类
基页类 -所有页面对象继承的通用方法
定制夹具 -自动页面初始化和身份验证
基于Excel的测试数据 -存储在Excel文件中的凭据和URL
多个测试套件 -登录、产品、排序和购物车场景
默认情况下为头部模式 -在Chromium中执行可视化测试
环境变量 -通过.env文件进行回退配置
MCP集成 -配置为与模型上下文协议（Playwright MCP）集成，以便外部工具和助手与测试运行时交互

📁 项目结构

MCPServer/
├── pages/                      # Page Object Models (UI)
│   ├── BasePage.ts            # Base class with common methods
│   ├── LoginPage.ts           # Login page object
│   ├── ProductsPage.ts        # Products page object
│   └── ShoppingCartPage.ts    # Shopping cart page object
├── src/                        # API & Utilities
│   ├── api/
│   │   ├── models/            # API DTOs/Interfaces
│   │   │   ├── auth.interface.ts
│   │   │   └── booking.interface.ts
│   │   └── services/          # API Service Classes
│   │       ├── BaseApiService.ts
│   │       ├── AuthService.ts
│   │       └── BookingService.ts
│   ├── data/
│   │   ├── api-test-data.xlsx       # Sample Excel test data for API
│   │   └── generate-api-test-data.ts # Excel generator (TypeScript)
│   └── utils/
│       └── excel-reader.ts   # Excel file reader utility
├── tests/                      # Test specifications
│   ├── login.spec.ts          # Login test scenarios (UI)
│   ├── products.spec.ts       # Products page validation (UI)
│   ├── productsSort.spec.ts   # Product sorting (UI)
│   ├── shoppingCart.spec.ts   # Shopping cart (UI)
│   └── api/
│       └── booking-e2e.spec.ts       # API data-driven tests (Restful Booker)
├── fixtures/                   # Custom test fixtures
│   └── pageFixtures.ts        # Page object fixtures
├── testdata/                   # Test data files
│   └── credentials.xlsx       # User credentials and URLs
├── reporters/                  # Custom reporters
│   └── slack-reporter.js      # Slack/Teams notification reporter
├── scripts/                    # Utility scripts
│   ├── sendResultsToN8n.js   # Send Playwright results to n8n
│   ├── generate-api-data.js  # Generate sample API Excel data
│   └── debug-auth.js          # Debug auth requests
├── .github/workflows/          # GitHub Actions CI/CD
│   ├── playwright-notify.yml  # UI tests + Slack notifications
│   └── api-tests.yml          # API tests (separate job)
├── .n8n/workflows/            # n8n workflow exports
│   └── playwright-to-slack.json
├── playwright.config.ts        # Playwright configuration
├── tsconfig.json              # TypeScript configuration
├── package.json               # Dependencies and scripts
├── .env                       # Environment variables (local, ignored)
├── claude_desktop_mcp_config.json  # Claude Desktop MCP config
└── README.md                  # This file

🛠️ 先决条件

Node.js （v16或更高版本）
npm （附带Node.js）

📦 安装

克隆或导航到项目目录：
```
cd /Users/nk2/Desktop/MCPServer
```
安装依赖项：
```
npm install
```
安装Playwright浏览器：
```
npx playwright install chromium
```

🔧 配置

Excel测试数据

凭据存储在 testdata/credentials.xlsx:

图纸名称： 凭证
柱：用户名、密码、baseUrl

环境变量（回退）

创建或更新 .env 文件：

BASE_URL=https://www.saucedemo.com/
USERNAME=standard_user
PASSWORD=secret_sauce
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
SLACK_BOT_TOKEN=xoxb-your-bot-token
TEAMS_WEBHOOK_URL=https://outlook.webhook.office.com/...
BOOKER_BASE_URL=https://restful-booker.herokuapp.com
BOOKER_USER=admin
BOOKER_PASS=password123

安全说明： 存储库不再提交 .env机密应存储在GitHub操作机密（设置→ 秘密和变量→ CI运行的操作。轮换之前提交的任何机密。

剧作家配置

默认浏览器： 铬（头部模式）
基本URL: https://www.saucedemo.com/
屏幕截图： 出现故障时
视频： 失败时保留

🧪 运行测试

运行所有测试：

npm test

运行特定的测试套件：

# Login tests
npx playwright test tests/login.spec.ts --project=chromium

# Products tests
npx playwright test tests/products.spec.ts --project=chromium

# Sort tests
npx playwright test tests/productsSort.spec.ts --project=chromium

# Shopping cart tests
npx playwright test tests/shoppingCart.spec.ts --project=chromium

在无头模式下运行：

npx playwright test --project=chromium --headed=false

使用UI模式运行：

npm run test:ui

调试模式：

npm run test:debug

查看测试报告：

npm run report

🔁 通过n8n将剧作家的结果与Slack集成

该项目包括一个小助手和一个示例n8n工作流，用于将Playwright JSON结果发布到Slack。

生成JSON测试报告：

# run tests and write JSON output
npm run test:json

将结果发送到您的n8n webhook（设置 N8N_WEBHOOK_URL 或通过 --url):

# using env var
N8N_WEBHOOK_URL="https://<your-n8n-host>/webhook/playwright-results" npm run send:results

# or pass as arg
npm run send:results -- --url https://<your-n8n-host>/webhook/playwright-results

导入附带的n8n工作流： .n8n/workflows/playwright-to-slack.json 进入你的n8n实例。

工作流摘要：

Webhook node：从辅助脚本接收POST
Format 功能节点：创建简短摘要消息
Slack 节点：将摘要发布到Slack频道（在n8n中配置凭据）

笔记：

辅助脚本期望JSON文件位于 playwright-report/results.json 默认情况下。
如果您的Playwright JSON布局不同，您可以调整 scripts/sendResultsToN8n.js.

注： npm run send:results 预期 N8N_WEBHOOK_URL （或 --url)如果不提供，将出错。

或者，一位定制的剧作家记者(reporters/slack-reporter.js)每次运行后直接向Slack/Teams发布简洁的摘要：

延迟通知： 通过配置 SLACK_WEBHOOK_URL （传入的webhook）。记者将发布一份简短的结果摘要。
屏幕截图上传： 可选，使用执行 SLACK_BOT_TOKEN （bot代币）。机器人必须拥有 files:write OAuth范围上传截图；没有它，上传将失败 missing_scope 错误。

商店 SLACK_WEBHOOK_URL 和 SLACK_BOT_TOKEN 作为CI的GitHub秘密(SLACK_WEBHOOK_URL, SLACK_BOT_TOKEN).CI工作流程包含在 .github/workflows/playwright-notify.yml 读取这些秘密并运行测试。

📊 测试场景

登录测试（4种场景）

✅ 使用有效凭据成功登录
✅ 带有无效凭据的错误消息
✅ 用户名为空时出现错误消息
✅ 密码为空时出现错误消息

产品页面测试（3种场景）

✅ 验证用户是否在“产品”页面上
✅ 验证库存列表是否可见
✅ 验证是否显示了所有页面元素

产品分类测试（4种场景）

✅ 按名称排序（A-Z）
✅ 按名称排序（Z-A）
✅ 按价格排序（从低到高）
✅ 按价格排序（从高到低）

购物车测试（6个场景）

✅ 将商品添加到购物车并导航
✅ 验证“您的购物车”标题
✅ 验证购物车页面元素（数量、描述、按钮）
✅ 继续购物导航
✅ 从购物车中删除商品
✅ 前往结账

🏗️ 建筑

基本页面图案

所有页面类都扩展 BasePage 其提供了常见的方法：

导航方式
元素交互（点击、填充、获取文本）
等待实用程序
屏幕截图功能

定制夹具

该框架使用自定义Playwright夹具：

loginPage -自动初始化LoginPage实例
productsPage -自动初始化Products Page实例
shoppingCartPage -自动初始化ShoppingCartPage实例
authenticatedPage -测试执行前自动登录

Excel数据管理

这 ExcelReader 实用程序类提供：

按行索引从Excel读取凭据
支持多个测试用户
基本URL配置
易于维护测试数据

📝 编写新测试

示例：创建新测试

import { test, expect } from '../fixtures/pageFixtures';

test.describe('My Test Suite', () => {
    
    test('my test scenario', async ({ page, productsPage, authenticatedPage }) => {
        // Test is already authenticated and on products page
        // Write your test logic here
    });
});

示例：创建新页面对象

import { Page, Locator } from '@playwright/test';
import { BasePage } from './BasePage';

export class MyPage extends BasePage {
    readonly myElement: Locator;

    constructor(page: Page) {
        super(page);
        this.myElement = page.locator('.my-selector');
    }

    async myMethod() {
        await this.click(this.myElement);
    }
}

🔍 故障排除

问题：测试无法读取Excel文件

解决方案： 确保 testdata/credentials.xlsx 存在并且格式正确。

问题：浏览器无法打开

解决方案： 跑 npx playwright install chromium 安装浏览器。

问题：身份验证失败

解决方案： 检查凭据 testdata/credentials.xlsx 或 .env 文件。

问题：Slack通知未显示

检查：

确认 SLACK_WEBHOOK_URL 为测试运行的环境设置（本地导出或添加到GitHub Secrets）。
验证您正在观看的Slack频道的传入webhook帖子（传入webhooks绑定到特定频道/工作区）。
如果您希望上传屏幕截图，请确保使用Slack App bot令牌 SLACK_BOT_TOKEN 拥有 files:write OAuth作用域和应用程序已重新安装。

要在CI日志中获得更多可见性，请在报告器中启用调试日志记录或添加一个小型控制台/日志写入——默认情况下，报告器会打印错误，但不会打印成功的webhook响应。

🔌 API测试（Restful Booker）

该框架包括 服务对象模型 针对 Restful Booker API.

运行API测试

当地：

# Generate sample Excel test data
node scripts/generate-api-data.js

# Run API tests
npx playwright test api/booking-e2e.spec.ts

在CI/CD中：

# GitHub Actions will automatically run API tests via .github/workflows/api-tests.yml
# when you push to main or open a PR

API试验数据

样本测试数据存储在 src/data/api-test-data.xlsx:

柱：名字、姓氏、总价、已付押金、办理入住、结账、其他需求
排： 2个预订样本（John Doe、Alice Smith）
生成人： scripts/generate-api-data.js

要添加更多测试数据，请编辑Excel文件或更新脚本并重新生成。

API体系结构

服务对象模型模式：

BaseApiService -所有API服务的基类；包装剧作家 APIRequestContext
身份验证服务 -处理身份验证(/auth 终点）；返回会话令牌
预订服务 -预订的CRUD操作(/booking 端点）

测试中的使用：

// tests/api/booking-e2e.spec.ts reads Excel data at module load
// For each row, a dynamic test is created with steps:
// 1. Authenticate (get token)
// 2. Create booking
// 3. Get booking (verify creation)
// 4. Update booking (modify details)
// 5. Delete booking (cleanup)

test('Booking Flow - Row 1: John Doe', async ({ request }) => {
  const authService = new AuthService(request);
  const bookingService = new BookingService(request);
  
  const token = await authService.login({ username: '...', password: '...' });
  const bookingId = await bookingService.create({ firstname: 'John', ... });
  // ... continues with get, update, delete
});

API测试的环境变量

BOOKER_BASE_URL -Restful Booker API基本URL（默认值： https://restful-booker.herokuapp.com)
BOOKER_USER -身份验证用户名（可选；当前不用于Restful Booker身份验证）
BOOKER_PASS -身份验证密码（可选；当前不用于Restful Booker身份验证）

示例 .env:

BOOKER_BASE_URL=https://restful-booker.herokuapp.com

测试结果

所有测试运行都会在中生成Playwright报告 playwright-report/:

HTML报告（用浏览器打开）
JSON报告（用于CI集成）
GitHub操作报告（嵌入在PR/commit中）

🧭 导入Claude桌面MCP配置

此存储库包括一个准备导入的Claude Desktop MCP配置文件： claude_desktop_mcp_config.json.

如何导入到Claude Desktop：

打开克劳德桌面并转到设置→ MCP/集成（或等效的MCP配置UI）。
选择导入或添加新MCP服务器的选项，然后选择 claude_desktop_mcp_config.json 从这个存储库。
入口 Playwright MCP (local) 指向 http://localhost:9333 默认情况下，使用以下命令在本地启动MCP服务器：

npm run mcp:start

如果您的MCP服务器侦听其他端口，请编辑 claude_desktop_mcp_config.json 并更新 url 导入前的字段。

验证：

导入后，Claude Desktop应列出服务器，并在MCP运行时指示其处于联机状态。
从Claude运行一个小的MCP操作（例如，让它运行Playwright命令或列出可用功能），以确认端到端的连接。

安全：

仅导入指向的本地MCP配置 localhost 除非您明确打算公开服务器。
不要将生产秘密提交给回购。使用本地环境变量或安全存储。

🤝 贡献

为您的功能创建新分支
遵循现有的代码结构和命名约定
为新功能编写测试
在提交之前，确保所有测试都通过

📄 许可证

国际学生委员会

👤 作者

nk2

📚 文档

最后更新时间： 2025年12月4日