使用说明

mcp剧作家

全面的Playwright测试自动化套件，用于EZRouting UAT测试，包括页面对象模型、Allure报告和自动烟雾测试。

特性

纯JavaScript -所有用现代JavaScript编写的测试和页面对象（没有TypeScript）
测试标记系统 -通过@smoke和@sanity标签过滤测试，以实现目标测试执行
综合烟雾测试套件 -登录、学生人数、工作区创建、导航和搜索的组合测试场景
页面对象模型 -按应用程序组织的可重用页面对象（EZRouting、TransAuditor）
诱惑报告 -包含截图和痕迹的丰富测试报告
基于环境的配置 -通过.env进行安全的凭据管理
多种测试场景 -单个测试脚本和组合烟雾测试
自动浏览器管理 -处理浏览器安装和清理
硒化物式定位器 -在构造函数中直接分配定位器，以实现干净、可维护的代码

先决条件

Node.js 18+
npm或纱线

设置

1.安装依赖项

npm install

2.安装Playwright浏览器

npx playwright install chromium

3.配置环境变量

创建 .env 项目根目录中的文件（使用 .env.example 作为模板）：

AUTOMATION_SUPER_USER=your-email@example.com
AUTOMATION_SUPER_PASSWORD=your-password

# Optional: Set test environment (defaults to UAT if not specified)
# Options: DEV, UAT, QA, PROD
ENV=UAT

# Optional: Set default client (defaults to testqa if not specified)
CLIENT=testqa

环境URL：

ENV=DEV → https://routing-dev.transact.com
ENV=UAT → https://routing-uat.transact.com （默认）
ENV=QA → https://routing-qa.transact.com
ENV=PROD → https://www.ezrouting.com

重要提示： 永远不要承诺 .env 文件到版本控制。它已经在里面了 .gitignore.

运行测试

剧作家测试套件（推荐）

使用Playwright测试运行器运行所有测试，以实现并行执行、自动重试和丰富的报告：

# Run all tests headless (default)
npm test

# Run tests with browser visible
npm run test:headed

# Run tagged tests (smoke/sanity)
npm run test:smoke          # Run @smoke tests
npm run test:smoke:headed   # Run @smoke tests with browser visible
npm run test:sanity         # Run @sanity tests
npm run test:sanity:headed  # Run @sanity tests with browser visible

# Run tests and view Allure report
npm run test:allure

# Run specific test suite
npx playwright test tests/students-tests/student-count.spec.js
npx playwright test tests/dashboard-tests/workspace-creation.spec.js
npx playwright test tests/dashboard-tests/navigation.spec.js
npx playwright test tests/students-tests/student-search.spec.js

# Run tests matching a pattern
npx playwright test --grep "Student"

# Run in debug mode
npx playwright test --debug

# Run in UI mode (interactive)
npx playwright test --ui

测试标签（@smoke/@sanity）

测试可以标记为 @smoke 和 @sanity 在测试标题中启用筛选测试执行。这允许您快速运行特定的测试类别，而无需运行整个套件。

运行标记的测试：

# Run all tests tagged with @smoke
npm run test:smoke

# Run all tests tagged with @sanity
npm run test:sanity

# Run with browser visible
npm run test:smoke:headed
npm run test:sanity:headed

# Combine with other Playwright options
npm run test:smoke -- --workers=1
npm run test:sanity -- --reporter=list

向测试添加标签：

标签直接添加到测试标题中：

test('C7204 uat admin login (smoke) @smoke @sanity', async ({ page }) => {
  // Test implementation
});

test('C7211 login page element validation @smoke @sanity', async ({ page }) => {
  // Test implementation
});

当前标记的测试：

所有测试 login-tests/login-uat-admin.spec.js 包括两者 @smoke 和 @sanity 标签
当通过以下任一方式进行筛选时，将运行具有这两个标签的测试 @smoke 或 @sanity

标签命名约定：

使用 @smoke 用于基本功能必须通过的关键路径测试
使用 @sanity 用于快速验证测试，检查核心功能
测试可以有多个标签包含在不同的测试运行中

环境特定测试

使用以下工具对不同环境（DEV、UAT、QA、PROD）运行测试 ENV 环境变量：

# Run tests in DEV environment
ENV=DEV npm run test:smoke

# Run tests in PROD environment
ENV=PROD npm run test:smoke:headed

# Run specific test in QA environment
ENV=QA npx playwright test tests/login-tests/login-uat-admin.spec.js

# Set default environment in .env file
echo "ENV=DEV" >> .env

可用环境：

DEV -发展环境(https://routing-dev.transact.com)
UAT -UAT环境(https://routing-uat.transact.com)-默认值
QA -QA环境(https://routing-qa.transact.com)
PROD -生产环境(https://www.ezrouting.com)

环境参数按以下优先级顺序读取：

ENV 或 TEST_ENV 环境变量
默认为 UAT

客户特定测试

测试可以使用 CLIENT 环境变量。该框架支持具有不同数据集的多个客户端：

# Run tests for clarknv client (ARVILLE DEPOT workspace data)
CLIENT=clarknv npx playwright test

# Run specific test with client
CLIENT=clarknv npx playwright test --grep "ARVILLE DEPOT" --headed

# Run tests via npm script with client
npm run test:headed -- --client=clarknv

# Set default client in .env file
echo "CLIENT=clarknv" >> .env

可用客户端：

testqa -默认测试客户端（410名学生）
clarknv -内华达州克拉克县客户（奥维尔分校，25811名学生）

客户端参数按以下优先级顺序读取：

CLIENT 或 TEST_CLIENT 环境变量
npm配置变量(npm run test -- --client=clarknv)
默认为 testqa

注：有些测试需要特定的客户端。例如， dashboard-tests/workspace-depot-validation.spec.js 要求 clarknv 客户端访问ARVILLE DEPOT数据。


**Available npm scripts:**
- `npm test` - Run all tests headless
- `npm run test:headed` - Run all tests with visible browser
- `npm run test:smoke` - Run all tests tagged with @smoke
- `npm run test:smoke:headed` - Run @smoke tests with visible browser
- `npm run test:sanity` - Run all tests tagged with @sanity
- `npm run test:sanity:headed` - Run @sanity tests with visible browser
- `npm run smoke` - Run comprehensive smoke test suite
- `npm run smoke:headed` - Run comprehensive smoke test with visible browser
- `npm run test:allure` - Run tests and serve Allure report
- `npm run allure:generate` - Generate Allure report
- `npm run allure:serve` - Serve Allure report
- `npm run allure:open` - Open existing Allure report
- `npm run notify:started` - Send Slack notification (test started)
- `npm run notify:completed` - Send Slack notification (test completed)
- `npm run notify:failed` - Send Slack notification (test failed)
- `npm run test:notify` - Run tests with automatic Slack notifications

**Available test suites:**
- `login-tests/login-uat-admin.spec.js` - Admin login and district selection
- `students-tests/student-count.spec.js` - Student count validation (410 / 410)
- `dashboard-tests/workspace-creation.spec.js` - Workspace creation with unique naming
- `dashboard-tests/workspace-depot-validation.spec.js` - Workspace with ARVILLE DEPOT validation (requires clarknv client)
- `dashboard-tests/navigation.spec.js` - Navigation through all main tabs (8 tests)
- `students-tests/student-search.spec.js` - Student search and filter validation (5 tests)
- `students-tests/student-search.spec.js` - Student search, filter validation, and save performance test (includes save time measurement after toggling SPED/WHEELCHAIR)

### Comprehensive Smoke Test Suite

Playwright test suite that runs all scenarios sequentially:

```bash
# Run comprehensive smoke test
npm run smoke

# Run with browser visible
npm run smoke:headed

# Skip specific test sections (via environment variables)
SKIP_WORKSPACE=true npm run smoke
SKIP_STUDENT_COUNT=true npm run smoke
SKIP_NAVIGATION=true npm run smoke

诱惑报告

查看交互式Allure测试报告：

# Generate and serve Allure report
npm run allure:serve

# Generate report only
npm run allure:generate

# Open previously generated report
npm run allure:open

诱惑报告包括：

测试执行时间表
故障截图
详细的分步日志
测试历史和趋势

项目结构

mcp-playwright/
├── pages/                      # Page Object Model (JavaScript)
│   ├── ezr/                   # EZRouting page objects
│   │   ├── LoginPage.js       # Login page locators and actions
│   │   ├── DashboardPage.js   # Dashboard and workspace locators
│   │   ├── StudentsPage.js    # Students page locators
│   │   └── RoutesPage.js      # Routes page locators
│   └── trans-auditor-pages/   # TransAuditor page objects
│       └── TaDashboardPage.js # TransAuditor dashboard page
├── tests/                     # Playwright test specs (17+ tests, JavaScript)
│   ├── login-tests/                 # Login test suite
│   │   └── login-uat-admin.spec.js # Admin login test
│   ├── workspace-creation.spec.js   # Workspace creation
│   ├── dashboard-tests/             # Dashboard and navigation tests
│   │   ├── navigation.spec.js       # Navigation tests (8 tests)
│   │   ├── workspace-creation.spec.js # Workspace creation
│   │   └── workspace-depot-validation.spec.js # Workspace with ARVILLE DEPOT (clarknv)
│   ├── students-tests/               # Student-related tests
│   │   ├── student-count.spec.js    # Student count validation
│   │   ├── student-search.spec.js   # Search and filter tests (5 tests)
│   │   └── show-students-routing-page.spec.js # Show students on routes page
│   ├── fixtures.js                  # Shared test fixtures (network monitoring)
│   └── smoke/                       # Comprehensive smoke test suite
│       └── comprehensive-smoke.spec.js  # Full smoke test (login, count, workspace, nav, search)
├── scripts/                   # Utility scripts
│   ├── extract-students-locators.js # Auto-extract page locators
│   ├── page-inspector.js      # Page element inspector for debugging
│   ├── notify-test-results.js # Auto-notify Slack with test results
├── utils/                     # Shared utilities
│   ├── loadEnv.js            # Environment loader
│   ├── ezrouting-test-config.js  # Client and environment configuration
│   ├── slack-notifier.js      # Slack notification sender
│   └── s3-uploader.js         # S3 uploader for Allure reports
├── documentation/             # Project documentation
│   └── playwright-commands.md # Command reference guide
├── manual-test-cases/         # Generated test reports (markdown)
├── artifacts/                 # Screenshots and debug files
├── allure-results/           # Allure test results (generated)
├── allure-report/            # Allure HTML report (generated)
├── config/                   # Environment configurations
│   └── environments.json     # Environment URLs
├── .env                      # Environment variables (not in git)
├── .env.example             # Example environment file
├── playwright.config.js     # Playwright configuration (ES module)
└── package.json             # Dependencies and scripts

环境配置

环境URL在中配置 config/environments.json:

开发: https://routing-dev.transact.com
问答: https://routing-qa.transact.com
用户验收测试: https://routing-uat.transact.com
生产环境: https://www.ezrouting.com

测试报告

所有测试运行都会生成报告：

冒烟测试：Markdown报告 manual-test-cases/
剧作家测试：通过HTML报告 npx playwright show-report
Allure报告：互动报告通过 npm run allure:serve
截图：已保存到 artifacts/ 测试完成或失败

调试测试

# Run in debug mode
npx playwright test --debug

# Run in UI mode (interactive)
npx playwright test --ui

# View trace for failed tests
npx playwright show-trace

# Generate test code (Codegen)
npx playwright codegen https://routing-uat.transact.com/testqa

# Inspect page elements for finding selectors
node scripts/page-inspector.js students
node scripts/page-inspector.js routes
node scripts/page-inspector.js routes --click 'a:has-text("Show Students")'

页面检查器

使用页面检查器发现任何页面上的选择器和元素：

# Inspect a specific page
node scripts/page-inspector.js <page-name>

# Inspect after clicking an element
node scripts/page-inspector.js <page-name> --click '<selector>'

# Available pages: dashboard, students, schools, vehicles, staff, stops, fieldtrips, routes

检查器显示：

所有带有testId的可见按钮
所有带有testId的链接
所有具有data-testid属性的元素
所有输入字段和表单
所有模块/面板/对话框
截图保存到工件/

文档

有关全面的命令参考，请参见文档/剧作家指令.md

故障排除

浏览器安装问题

如果找不到浏览器，请确保Playwright浏览器路径正确：

npx playwright install chromium --with-deps

环境变量问题

验证您的 .env 文件存在并包含所需变量：

cat .env

测试失败

检查中生成的屏幕截图 artifacts/
查看Allure报告以获取详细日志： npm run allure:serve
在头部模式下运行测试，看看发生了什么： npm run smoke:headed

贡献

添加新测试时：

使用页面对象模型模式（将定位器添加到 pages/ 作为JavaScript类）
遵循现有的命名约定(.spec.js 对于测试， .js 对于页面对象）
使用ES6模块语法(import/export)为了保持一致性
根据需要更新文档
确保测试后进行清理（例如，唯一的工作区名称）

技术栈

剧作家1.59.0-阿尔法：浏览器自动化框架
JavaScript（ES6+）：所有测试和页面对象（无TypeScript）
Node.js：运行时环境
魅力：测试报告框架
@剧作家/mcp：AI辅助浏览器自动化

备注

总共17次测试 横跨6个测试套件
默认情况下，测试并行运行以加快执行速度
默认情况下，所有测试都使用无头模式以实现CI/CD兼容性
工作空间创建使用随机数（1-50）进行唯一命名
学生计数验证在UAT测试qa环境中预期为“410/410”
某些测试需要特定的客户端（例如，工作区仓库验证需要clarknv）
测试完成后浏览器自动关闭
失败时自动截图，重试时跟踪
通过以下方式排除敏感数据（屏幕截图、报告、.env） .gitignore

测试覆盖率

测试套件	测试	描述
登录测试/login-uat-admin.spec.js	1	管理员登录和地区选择
students tests/student-count.spec.js	1	验证学生计数显示“410/410”
仪表板测试/workspace-creation.spec.js	1	创建具有唯一名称的工作区
仪表板测试/workspace-depot-validation.spec.js	1	使用ARVILLE depot（clarknv）创建和激活工作区
仪表板测试/navigation.spec.js	8	测试所有主要导航选项卡
students tests/student-search.spec.js	5	搜索、过滤器下拉菜单和过滤器选项验证
总计	17	全面的UAT验证

Slack通知

测试后执行会自动更新到Slack。

设置

将您的Slack webhook URL添加到 .env:

SLACK_WEBHOOK_DEBUG_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

用法

# Manual notifications
npm run notify:started      # Notify test execution started
npm run notify:completed    # Notify test execution completed
npm run notify:failed       # Notify test execution failed

# Run tests with automatic Slack notifications
npm run test:notify

# Custom notifications
node utils/slack-notifier.js --status started --env uat --client testqa
node utils/slack-notifier.js --status completed --passed 14 --failed 0 --env uat
node utils/slack-notifier.js --status failed --passed 10 --failed 4 --env uat

消息格式

Slack消息包括：

🚀 测试执行状态（开始/完成/失败）
环境（UAT、QA、开发、生产）
客户/地区名称
浏览器类型
Git分支和提交
由（git作者）触发
测试结果（通过/失败/总计）
通过率百分比

CI/CD集成

在CI/CD管道中使用：

# Example GitHub Actions
- name: Notify Slack - Started
  run: npm run notify:started

- name: Run Tests
  run: npm test

- name: Notify Slack - Results
  if: always()
  run: |
    if [ $? -eq 0 ]; then
      npm run notify:completed
    else
      npm run notify:failed
    fi

自动生成的定位器

自动从任何页面提取所有数据testid定位器：

# Extract Students page locators
node scripts/extract-students-locators.js

这将产生：

pages/locators/students-locators.json -包含元数据的完整定位器数据
pages/locators/students-locators.js -用于测试的JavaScript常量

目前，学生页面上有2328个独特的定位器。