AI导哈

API文档验证测试工具

一个基于Playwright的轻量级测试项目，专注于验证APIary文档页面，支持本地和CI环境下的测试运行，并生成可操作的测试报告和截图。

  • by Code-Gabs
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Code-Gabs/playwright-mcp-poc

使用说明

🎯 剧作家mcp poc

验证APIary文档页面的最小、专注的Playwright测试项目（POC）。设计为易于在本地运行，并在CI中生成可操作的工件（HTML报告+屏幕截图）。

🚀 快速链接

  • 测验： tests/
  • 编剧配置： playwright.config.ts
  • CI工作流程： .github/workflows/playwright.yml
  • 报告截图： screenshots/ （git除外）

✨ 特性

  • 编剧测试用 @playwright/test.
  • 主持本地测试（易于可视化调试）。
  • 截图和剧作家报告的附件，用于失败或证据运行。
  • 运行测试和上传的GitHub Actions工作流 playwright-report, screenshots/，以及 test-results/ 失败。

📦 先决条件

  • Node.js（建议使用v16+）
  • Git
  • （可选）Windows上的Git Bash，提供类似Bash的shell体验

🧭 本地设置（Windows）

使用 cmd.exe 或Git Bash，以避免PowerShell脚本执行策略问题。下面的示例命令是针对PowerShell/cmd显示的，但也适用于Git Bash。

  1. 安装项目deps
npm install
  1. 安装浏览器二进制文件（仅限Chromium——更小更快）
npx playwright install --with-deps chromium
  1. 运行完整的测试套件
# headless (default in CI)
npm test

# headed (see the browser)
npx playwright test --project=chromium --headed
  1. 运行单个测试文件
npx playwright test tests/apiary.usuarios.criarusario.chrome.spec.ts --project=chromium --headed
  1. 查看报告者生成的HTML报告
npx playwright show-report

🛠️ PowerShell出错

如果PowerShell阻止 npm/npx 如果出现执行策略错误，请在中运行命令 cmd.exe/Git Bash或放宽用户政策（需要征得同意）：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

✅ 此仓库中测试的最佳实践

  • 更喜欢 getByRole +可访问的名称，而不是脆弱的CSS选择器。例子：
await expect(page.getByRole('heading', { name: /Usuários/i })).toBeVisible();
  • 保持测试幂等性：测试不应依赖或修改外部状态。
  • 捕获屏幕截图并将其附加到报告中以进行快速调试（此存储库已保存屏幕截图并通过 test.info().attach).

🧩 CI（GitHub操作）

  • 工作流程： .github/workflows/playwright.yml --它安装依赖项、安装浏览器、运行 npm test 并在运行失败时上传工件（报告/截图/测试结果）。
  • 工件保留期：7天（可在工作流程中更改）。

📝 贡献

  • 在中添加测试 tests/ 文件夹遵循现有样式（标题友好，使用 getByRole).
  • 保持变化小而集中；使用匹配的提交消息添加/调整测试，如 test(apiary): add criar-usuario doc test.

📞 需要帮助？

  • 我可以：
    • 为示例和代码块添加更严格的断言；
    • 为npm和Playwright浏览器配置CI缓存；
    • 切换到系统Chrome频道（更新 playwright.config.ts 随着 use: { channel: 'chrome' }).

如果你愿意，我还可以添加徽章、GIF演示或带有测试PR模板的CONTRIBUTING.md。

由以下材料制成❤️ 剧作家POC

剧作家mcp poc

这是一个由剧作家mcp制作的Minimal Playwright测试项目，专注于验证APIary文档页面。 这是我POC的一个研究项目

快速入门--本地（Windows）

  1. 安装开发依赖关系
# Recommended: run these in cmd.exe or Git Bash to avoid PowerShell execution policy issues
npm install
  1. 安装Chromium（比安装所有浏览器更小、更快）
npx playwright install --with-deps chromium
  1. 运行完整的测试套件（在CI中默认为headless；使用 --headed 查看浏览器）
# run in cmd.exe or Git Bash
npm test
# or to run headed locally:
npx playwright test --project=chromium --headed
  1. 运行单个测试文件
npx playwright test tests/apiary.usuarios.criarusario.chrome.spec.ts --project=chromium --headed
  1. 查看HTML报告（运行后）
npx playwright show-report

PowerShell说明

  • PowerShell的脚本执行策略可以阻止 npm/npx PowerShell帮助程序脚本。如果您看到类似“此系统上禁用了脚本执行”的错误，请执行以下操作之一：
    • 使用 cmd.exe 或Git Bash来运行npm/npx命令，或
    • 更改执行策略（需要管理员）：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

CI注释

  • 包含的GitHub Actions工作流(.github/workflows/playwright.yml)运行测试，并在失败时上传Playwright工件（HTML报告、屏幕截图和 test-results/).
  • 对于可重复的CI安装，首选提交 package-lock.json；此仓库目前不包括lockfile。如果要进行确定性CI安装，请删除 package-lock.json 从 .gitignore 并承诺。

添加测试

  • 测试使用 @playwright/test.更喜欢 getByRole 查询和可读名称（例如。 getByRole('heading', { name: /Usuários/i }))以避免易碎的选择器。
  • 测试已添加 tests/ 遵循头部/局部友好模式，并附上失败证据的截图。

联系

如果你想让我：

  • 添加更具体的断言或更严格的检查，告诉我应该看到哪些字符串/代码块；
  • 配置CI以在特定节点版本上运行或缓存浏览器工件；
  • 切换到使用 chrome 频道（系统Chrome）而不是捆绑的Chromium——我可以更新 playwright.config.ts.

相关 MCP