@qlover/create-app 0.7.15 → 0.9.0

package/dist/templates/react-app/docs/zh/playwright/overview.md

@@ -0,0 +1,222 @@
+# Playwright E2E 测试指南
+
+## 概述
+
+本项目包含使用 [Playwright](https://playwright.dev/) 的完整端到端（E2E）测试，这是一个现代化的测试框架，能够在所有主流浏览器上进行可靠的测试。
+
+## 功能特性
+
+- ✅ 多浏览器测试（Chromium、Firefox、WebKit）
+- ✅ 移动浏览器模拟
+- ✅ 页面对象模型（POM）架构
+- ✅ 全面的测试覆盖
+- ✅ 失败时自动截图和录制视频
+- ✅ 与 GitHub Actions 的 CI/CD 集成
+- ✅ 可访问性测试
+- ✅ 性能测试
+- ✅ 国际化测试
+
+## 快速开始
+
+### 安装
+
+```bash
+# 如需要，修复 npm 权限问题
+sudo chown -R $(id -u):$(id -g) "$HOME/.npm"
+
+# 安装 Playwright
+npm install -D @playwright/test playwright
+
+# 安装浏览器
+npx playwright install
+```
+
+### 运行测试
+
+```bash
+# 运行所有测试
+npm run test:e2e
+
+# 交互式 UI 模式（推荐）
+npm run test:e2e:ui
+
+# 调试模式
+npm run test:e2e:debug
+
+# 查看报告
+npm run test:e2e:report
+```
+
+## 测试结构
+
+```
+e2e/
+├── fixtures/           # 自定义测试固件
+├── pages/             # 页面对象模型
+├── tests/             # 测试规范
+│   ├── home.spec.ts          # 首页测试
+│   ├── navigation.spec.ts    # 导航测试
+│   ├── auth.spec.ts          # 认证测试
+│   ├── i18n.spec.ts          # 国际化测试
+│   ├── accessibility.spec.ts # 可访问性测试
+│   └── performance.spec.ts   # 性能测试
+└── utils/             # 测试辅助工具
+```
+
+## 测试类别
+
+### 功能测试
+
+- **首页测试**：页面渲染、导航菜单、响应式设计
+- **导航测试**：路由、404 处理、浏览器导航
+- **认证测试**：登录/注册表单、验证
+
+### 质量测试
+
+- **国际化测试**：语言切换、翻译覆盖
+- **可访问性测试**：ARIA 角色、键盘导航、屏幕阅读器支持
+- **性能测试**：加载时间、包大小、内存泄漏
+
+## 编写测试
+
+### 基本测试示例
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('示例测试', async ({ page }) => {
+  await page.goto('/');
+  await expect(page.locator('h1')).toBeVisible();
+});
+```
+
+### 使用页面对象
+
+```typescript
+import { HomePage } from '../pages/HomePage';
+
+test('首页测试', async ({ page }) => {
+  const homePage = new HomePage(page);
+  await homePage.navigate('zh');
+  await expect(homePage.mainContent).toBeVisible();
+});
+```
+
+## 配置
+
+配置文件：`playwright.config.ts`
+
+主要设置：
+
+- 基础 URL：`http://localhost:3200`
+- 浏览器：Chromium、Firefox、WebKit、移动端
+- 自动启动开发服务器
+- 失败时截图/录像
+- 重试时跟踪
+
+## CI/CD 集成
+
+GitHub Actions 工作流：`.github/workflows/playwright.yml`
+
+功能：
+
+- 在推送/PR 时运行
+- 跨多个浏览器测试
+- 上传测试报告作为工件
+- 并行执行
+
+## 最佳实践
+
+1. 使用语义化选择器（`getByRole`、`getByLabel`）
+2. 利用自动等待而非固定延迟
+3. 保持测试独立和隔离
+4. 使用页面对象模型提高可重用性
+5. 测试用户旅程，而非实现细节
+6. 在每个测试中包含可访问性检查
+7. 监控性能指标
+
+## 调试
+
+### UI 模式（推荐）
+
+```bash
+npm run test:e2e:ui
+```
+
+功能：
+
+- 时间旅行调试
+- DOM 快照
+- 网络日志
+- 跟踪查看器
+
+### 调试模式
+
+```bash
+npm run test:e2e:debug
+```
+
+使用 Playwright Inspector：
+
+- 单步执行测试
+- 检查选择器
+- 编辑定位器
+
+### 跟踪查看器
+
+```bash
+npx playwright show-trace test-results/path/to/trace.zip
+```
+
+## VS Code 集成
+
+安装 [Playwright Test for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright) 扩展以获得：
+
+- 从编辑器运行测试
+- 设置断点
+- 内联查看结果
+- 录制测试
+
+## 故障排除
+
+### 测试超时
+
+- 在配置中增加超时时间
+- 检查开发服务器是否运行
+- 验证网络连接
+
+### 找不到元素
+
+- 使用 Playwright Inspector 调试选择器
+- 检查元素是否在 frame/shadow DOM 中
+- 验证元素是否存在于 DOM 中
+
+### 测试不稳定
+
+- 使用自动等待而非固定延迟
+- 确保测试之间正确清理
+- 检查竞态条件
+
+## 资源
+
+### 项目文档
+
+- [Playwright 文档中心](./playwright/README.md) - 所有 Playwright 文档的入口
+- [快速入门指南](./playwright/quickstart.md) - 快速上手
+- [详细测试指南](./playwright/testing-guide.md) - 完整参考
+- [设置完成指南](./playwright/setup-complete.md) - 配置和故障排除
+- [安装摘要](./playwright/installation-summary.md) - 安装详情
+- [E2E 测试文档](./playwright/e2e-tests.md) - E2E 测试代码文档
+
+### 外部资源
+
+- [Playwright 官方文档](https://playwright.dev/)
+- [API 参考](https://playwright.dev/docs/api/class-playwright)
+
+## 下一步
+
+1. 查看 `e2e/example.spec.ts`
+2. 使用 `npm run test:e2e:ui` 运行测试
+3. 为你的功能编写自定义测试
+4. 集成到 CI/CD 管道
+5. 监控测试结果和覆盖率

package/dist/templates/react-app/docs/zh/playwright/quickstart.md

@@ -0,0 +1,325 @@
+# Playwright E2E Testing - Quick Start Guide
+
+## 🎯 快速开始
+
+### 1. 安装依赖
+
+首先，修复 npm 权限问题（如果存在）：
+
+```bash
+sudo chown -R $(id -u):$(id -g) "$HOME/.npm"
+```
+
+然后安装 Playwright：
+
+```bash
+npm install -D @playwright/test playwright
+```
+
+安装浏览器驱动：
+
+```bash
+npx playwright install
+```
+
+### 2. 运行第一个测试
+
+```bash
+# 运行示例测试
+npm run test:e2e -- e2e/example.spec.ts
+
+# 或者使用 UI 模式（推荐用于开发）
+npm run test:e2e:ui
+```
+
+### 3. 查看测试报告
+
+```bash
+npm run test:e2e:report
+```
+
+## 📋 可用的测试脚本
+
+| 命令                        | 说明                           |
+| --------------------------- | ------------------------------ |
+| `npm run test:e2e`          | 运行所有 E2E 测试              |
+| `npm run test:e2e:ui`       | 在 UI 模式下运行（交互式）     |
+| `npm run test:e2e:headed`   | 在有头模式下运行（可见浏览器） |
+| `npm run test:e2e:debug`    | 在调试模式下运行               |
+| `npm run test:e2e:chromium` | 仅在 Chrome 上运行             |
+| `npm run test:e2e:firefox`  | 仅在 Firefox 上运行            |
+| `npm run test:e2e:webkit`   | 仅在 Safari/WebKit 上运行      |
+| `npm run test:e2e:report`   | 查看测试报告                   |
+
+## 📚 测试文件说明
+
+### 已创建的测试套件
+
+1. **`example.spec.ts`** - 验证 Playwright 设置的示例测试
+2. **`home.spec.ts`** - 首页功能测试
+3. **`navigation.spec.ts`** - 导航和路由测试
+4. **`auth.spec.ts`** - 认证流程测试
+5. **`i18n.spec.ts`** - 国际化测试
+6. **`accessibility.spec.ts`** - 可访问性测试
+7. **`performance.spec.ts`** - 性能测试
+
+### Page Object Models
+
+已创建的页面对象模型（位于 `e2e/pages/`）：
+
+- `BasePage.ts` - 基础页面类
+- `HomePage.ts` - 首页
+- `LoginPage.ts` - 登录页面
+
+## 🔧 常用操作
+
+### 运行特定测试文件
+
+```bash
+npx playwright test e2e/tests/home.spec.ts
+```
+
+### 运行特定测试用例
+
+```bash
+npx playwright test -g "should load and display home page"
+```
+
+### 仅运行失败的测试
+
+```bash
+npx playwright test --last-failed
+```
+
+### 更新快照
+
+```bash
+npx playwright test --update-snapshots
+```
+
+### 生成代码
+
+```bash
+npx playwright codegen http://localhost:3200
+```
+
+这将打开浏览器并记录你的操作，自动生成测试代码！
+
+## 🐛 调试技巧
+
+### 1. 使用 UI 模式（推荐）
+
+```bash
+npm run test:e2e:ui
+```
+
+UI 模式提供：
+
+- 可视化测试执行
+- 时间旅行调试
+- DOM 快照
+- 网络日志
+
+### 2. 使用调试模式
+
+```bash
+npm run test:e2e:debug
+```
+
+这会打开 Playwright Inspector，允许你：
+
+- 单步执行测试
+- 查看选择器
+- 编辑定位器
+
+### 3. 在测试中添加断点
+
+```typescript
+test('debug example', async ({ page }) => {
+  await page.goto('/');
+  await page.pause(); // 添加这一行来暂停执行
+  // ... 其他测试代码
+});
+```
+
+### 4. 查看 Trace
+
+如果测试失败，会自动生成 trace 文件：
+
+```bash
+npx playwright show-trace test-results/.../trace.zip
+```
+
+## 💡 编写测试的最佳实践
+
+### 1. 使用 Page Object Model
+
+```typescript
+import { HomePage } from '../pages/HomePage';
+
+test('example', async ({ page }) => {
+  const homePage = new HomePage(page);
+  await homePage.navigate('zh');
+  await expect(homePage.mainContent).toBeVisible();
+});
+```
+
+### 2. 使用语义化选择器
+
+```typescript
+// ✅ 好的做法
+await page.getByRole('button', { name: '登录' });
+await page.getByLabel('用户名');
+await page.getByTestId('submit-button');
+
+// ❌ 避免
+await page.locator('.btn-primary');
+await page.locator('#username');
+```
+
+### 3. 等待元素而不是固定延迟
+
+```typescript
+// ✅ 好的做法
+await page.waitForSelector('[data-testid="content"]');
+await expect(page.locator('.result')).toBeVisible();
+
+// ❌ 避免
+await page.waitForTimeout(3000);
+```
+
+### 4. 保持测试独立
+
+```typescript
+test.describe('Feature Tests', () => {
+  test.beforeEach(async ({ page }) => {
+    // 每个测试前重置状态
+    await page.goto('/');
+  });
+
+  test('test 1', async ({ page }) => {
+    // 这个测试不依赖其他测试
+  });
+
+  test('test 2', async ({ page }) => {
+    // 这个测试也不依赖其他测试
+  });
+});
+```
+
+## 🎨 自定义配置
+
+### 修改基础 URL
+
+在 `playwright.config.ts` 中：
+
+```typescript
+use: {
+  baseURL: 'http://localhost:3000', // 修改为你的端口
+}
+```
+
+或使用环境变量：
+
+```bash
+PLAYWRIGHT_BASE_URL=http://localhost:3000 npm run test:e2e
+```
+
+### 添加新的浏览器配置
+
+在 `playwright.config.ts` 的 `projects` 数组中添加：
+
+```typescript
+{
+  name: 'Mobile Safari',
+  use: { ...devices['iPhone 12'] }
+}
+```
+
+### 配置超时时间
+
+```typescript
+// 全局超时
+test.setTimeout(60000); // 60 秒
+
+// 单个测试
+test('slow test', async ({ page }) => {
+  test.setTimeout(120000); // 120 秒
+  // ... 测试代码
+});
+```
+
+## 📊 CI/CD 集成
+
+项目已包含 GitHub Actions 配置文件（`.github/workflows/playwright.yml`）。
+
+推送代码到 GitHub 后，测试会自动运行。
+
+## 🆘 常见问题
+
+### Q: 测试超时
+
+**A:** 增加 `playwright.config.ts` 中的 `timeout` 设置，或检查开发服务器是否正常运行。
+
+### Q: 找不到元素
+
+**A:** 使用 Playwright Inspector 检查选择器：
+
+```bash
+npm run test:e2e:debug
+```
+
+### Q: 测试不稳定（flaky）
+
+**A:**
+
+- 使用自动等待而非固定延迟
+- 使用 `waitForLoadState('networkidle')`
+- 检查是否有竞态条件
+
+### Q: 浏览器安装失败
+
+**A:**
+
+```bash
+# 强制重新安装
+npx playwright install --force
+
+# Linux 上安装依赖
+npx playwright install-deps
+```
+
+## 📖 更多资源
+
+- [详细测试指南](./testing-guide.md)
+- [设置完成文档](./setup-complete.md)
+- [安装摘要](./installation-summary.md)
+- [Playwright 官方文档](https://playwright.dev/)
+- [Playwright 最佳实践](https://playwright.dev/docs/best-practices)
+- [Playwright API 参考](https://playwright.dev/docs/api/class-playwright)
+
+## ✅ 验证安装
+
+运行以下命令验证一切正常：
+
+```bash
+# 1. 运行示例测试
+npm run test:e2e -- e2e/example.spec.ts
+
+# 2. 如果成功，尝试运行所有测试
+npm run test:e2e
+
+# 3. 查看报告
+npm run test:e2e:report
+```
+
+如果所有测试都通过了，恭喜！你已经成功设置了 Playwright E2E 测试！🎉
+
+## 🚀 下一步
+
+1. 查看 `e2e/example.spec.ts` 了解基本测试结构
+2. 阅读 [详细测试指南](./testing-guide.md) 了解更多信息
+3. 使用 `npm run test:e2e:ui` 以交互方式探索测试
+4. 根据你的应用需求编写自定义测试
+
+祝测试愉快！