@qlover/create-app 0.7.15 → 0.9.0

package/dist/templates/react-app/docs/en/playwright/e2e-tests.md

@@ -0,0 +1,321 @@
+# E2E Testing with Playwright
+
+This directory contains end-to-end (E2E) tests for the React application using [Playwright](https://playwright.dev/).
+
+## 📁 Directory Structure
+
+```
+e2e/
+├── fixtures/           # Custom test fixtures
+│   └── base.fixture.ts
+├── pages/             # Page Object Models
+│   ├── BasePage.ts
+│   ├── HomePage.ts
+│   └── LoginPage.ts
+├── tests/             # Test files
+│   ├── home.spec.ts
+│   ├── navigation.spec.ts
+│   ├── auth.spec.ts
+│   ├── i18n.spec.ts
+│   ├── accessibility.spec.ts
+│   └── performance.spec.ts
+└── utils/             # Test utilities
+    └── test-helpers.ts
+```
+
+## 🚀 Getting Started
+
+### Installation
+
+First, install Playwright and its dependencies:
+
+```bash
+# Install Playwright
+npm install -D @playwright/test playwright
+
+# Install browsers (this may take a few minutes)
+npx playwright install
+```
+
+### Running Tests
+
+```bash
+# Run all E2E tests
+npm run test:e2e
+
+# Run tests in UI mode (interactive)
+npm run test:e2e:ui
+
+# Run tests in headed mode (see browser)
+npm run test:e2e:headed
+
+# Run tests in debug mode
+npm run test:e2e:debug
+
+# Run tests for specific browser
+npm run test:e2e:chromium
+npm run test:e2e:firefox
+npm run test:e2e:webkit
+
+# View test report
+npm run test:e2e:report
+```
+
+### Running Specific Tests
+
+```bash
+# Run a specific test file
+npx playwright test e2e/tests/home.spec.ts
+
+# Run tests matching a pattern
+npx playwright test e2e/tests/auth
+
+# Run a specific test by name
+npx playwright test -g "should load and display home page"
+```
+
+## 📝 Test Categories
+
+### 1. Home Page Tests (`home.spec.ts`)
+
+- Page loading and rendering
+- Navigation menu functionality
+- Responsive design testing
+- Locale handling
+
+### 2. Navigation Tests (`navigation.spec.ts`)
+
+- Inter-page navigation
+- 404 page handling
+- Browser back/forward navigation
+- State persistence during navigation
+
+### 3. Authentication Tests (`auth.spec.ts`)
+
+- Login form validation
+- Form submission
+- Navigation to register page
+- Keyboard navigation support
+
+### 4. Internationalization Tests (`i18n.spec.ts`)
+
+- Locale switching
+- Translation coverage
+- Locale persistence
+- Invalid locale handling
+
+### 5. Accessibility Tests (`accessibility.spec.ts`)
+
+- Document structure
+- Heading hierarchy
+- Alt text for images
+- Form labels
+- Keyboard navigation
+- ARIA roles
+
+### 6. Performance Tests (`performance.spec.ts`)
+
+- Page load time
+- First Contentful Paint
+- Bundle size
+- Lazy loading
+- Memory leak detection
+
+## 🏗️ Writing Tests
+
+### Using Page Object Model
+
+```typescript
+import { test, expect } from '../fixtures/base.fixture';
+import { HomePage } from '../pages/HomePage';
+
+test('example test', async ({ page }) => {
+  const homePage = new HomePage(page);
+  await homePage.navigate('zh');
+  await expect(homePage.mainContent).toBeVisible();
+});
+```
+
+### Using Test Helpers
+
+```typescript
+import { waitForAppReady, navigateToLocalePath } from '../utils/test-helpers';
+
+test('example with helpers', async ({ page }) => {
+  await navigateToLocalePath(page, '/about', 'en');
+  await waitForAppReady(page);
+  // ... rest of test
+});
+```
+
+### Custom Fixtures
+
+```typescript
+// In fixtures/base.fixture.ts
+export const test = base.extend({
+  authenticatedPage: async ({ page }, use) => {
+    // Setup authenticated state
+    await page.goto('/login');
+    // ... perform login
+    await use(page);
+  }
+});
+```
+
+## 🔧 Configuration
+
+Test configuration is located in `playwright.config.ts` at the project root.
+
+Key settings:
+
+- **Base URL**: `http://localhost:3200` (automatically starts dev server)
+- **Browsers**: Chromium, Firefox, WebKit, Mobile Chrome, Mobile Safari
+- **Reporters**: HTML, JSON, List
+- **Retry**: 2 times on CI, 0 times locally
+- **Screenshots**: On failure
+- **Videos**: Retained on failure
+- **Traces**: On first retry
+
+## 📊 Test Reports
+
+After running tests, view the HTML report:
+
+```bash
+npm run test:e2e:report
+```
+
+Or open the report file directly:
+
+```bash
+open playwright-report/index.html
+```
+
+## 🐛 Debugging Tests
+
+### Debug Mode
+
+```bash
+npm run test:e2e:debug
+```
+
+This opens the Playwright Inspector where you can:
+
+- Step through tests
+- See browser actions
+- Inspect selectors
+- View console logs
+
+### VS Code Extension
+
+Install the [Playwright Test for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright) extension for:
+
+- Running tests from the editor
+- Setting breakpoints
+- Viewing test results inline
+
+### Trace Viewer
+
+If a test fails, traces are automatically recorded. View them with:
+
+```bash
+npx playwright show-trace test-results/path-to-trace.zip
+```
+
+## 📸 Screenshots
+
+Screenshots are automatically captured on test failure. Manual screenshots can be taken using:
+
+```typescript
+await page.screenshot({ path: 'e2e/screenshots/my-screenshot.png' });
+```
+
+Or using the helper:
+
+```typescript
+import { takeScreenshot } from '../utils/test-helpers';
+
+await takeScreenshot(page, 'my-screenshot');
+```
+
+## 🌍 Environment Variables
+
+- `PLAYWRIGHT_BASE_URL`: Override the base URL (default: `http://localhost:3200`)
+- `CI`: Set to enable CI-specific settings (retries, parallel execution)
+
+Example:
+
+```bash
+PLAYWRIGHT_BASE_URL=http://localhost:3000 npm run test:e2e
+```
+
+## 🔄 Continuous Integration
+
+### GitHub Actions
+
+A sample GitHub Actions workflow is provided in `.github/workflows/playwright.yml`.
+
+The workflow:
+
+1. Installs dependencies
+2. Installs Playwright browsers
+3. Runs tests
+4. Uploads test reports as artifacts
+
+## 📚 Best Practices
+
+1. **Use Page Object Models** for reusable page interactions
+2. **Use meaningful test names** that describe what is being tested
+3. **Avoid hard-coded waits** - use Playwright's auto-waiting
+4. **Test user journeys** not implementation details
+5. **Keep tests isolated** - each test should be independent
+6. **Use data-testid** attributes for stable selectors
+7. **Test accessibility** alongside functionality
+8. **Monitor performance** with performance tests
+
+## 🔗 Useful Links
+
+- [Playwright Documentation](https://playwright.dev/)
+- [Playwright Best Practices](https://playwright.dev/docs/best-practices)
+- [Playwright API Reference](https://playwright.dev/docs/api/class-playwright)
+- [Playwright Selectors](https://playwright.dev/docs/selectors)
+- [Playwright Assertions](https://playwright.dev/docs/test-assertions)
+
+## 🆘 Troubleshooting
+
+### Tests timing out
+
+- Increase timeout in `playwright.config.ts`
+- Check if the dev server is running
+- Ensure no network issues
+
+### Selector not found
+
+- Use Playwright Inspector to debug selectors
+- Check if element is in a frame or shadow DOM
+- Verify the element exists in the DOM
+
+### Flaky tests
+
+- Avoid hardcoded waits - use `waitFor*` methods
+- Ensure proper cleanup between tests
+- Check for race conditions
+- Use `test.describe.serial` for dependent tests
+
+### Browser installation issues
+
+```bash
+# Reinstall browsers
+npx playwright install --force
+
+# Install browser dependencies (Linux)
+npx playwright install-deps
+```
+
+## 💡 Tips
+
+1. Use `--ui` mode for developing tests interactively
+2. Use `--debug` mode to step through failing tests
+3. Use `--headed` mode to see what the browser is doing
+4. Use `--trace on` to record traces for all tests
+5. Use `--project` to run tests on specific browsers
+6. Use grep patterns to run specific tests: `-g "pattern"`

package/dist/templates/react-app/docs/en/playwright/index.md

@@ -0,0 +1,19 @@
+# Playwright E2E Testing Documentation (English)
+
+> This directory contains all Playwright E2E testing related documentation in English
+
+## 📚 Documentation List
+
+- **[Overview](./overview.md)** - Feature highlights and quick introduction
+- **[Quick Start Guide](./quickstart.md)** ⭐ Recommended for beginners
+- **[Detailed Testing Guide](./testing-guide.md)** - Complete testing reference manual
+- **[Setup Complete Guide](./setup-complete.md)** - Configuration and troubleshooting
+- **[Installation Summary](./installation-summary.md)** - Installation details and project statistics
+- **[E2E Tests Documentation](./e2e-tests.md)** - E2E directory structure guide
+- **[Reorganization Notes](./reorganization-notes.md)** - Documentation reorganization details
+
+## 🔗 Related Links
+
+- [中文文档](../../zh/playwright/) - Chinese Documentation
+- [Back to Documentation Home](../../README.md)
+- [English Documentation Index](../index.md) - Back to English docs

package/dist/templates/react-app/docs/en/playwright/installation-summary.md

@@ -0,0 +1,332 @@
+# 🎯 Playwright E2E 测试安装总结
+
+## ✅ 已完成的工作
+
+### 1. 核心配置文件 (5 个)
+
+| 文件                    | 说明                                           | 状态 |
+| ----------------------- | ---------------------------------------------- | ---- |
+| `playwright.config.ts`  | Playwright 主配置（多浏览器、自动启动服务器）  | ✅   |
+| `tsconfig.e2e.json`     | E2E 测试的 TypeScript 配置                     | ✅   |
+| `.eslintignore`         | ESLint 忽略规则（包含 e2e 和 playwright 文件） | ✅   |
+| `.vscode/settings.json` | VS Code Playwright 配置                        | ✅   |
+| `.gitignore`            | 更新了测试报告和截图目录                       | ✅   |
+
+### 2. E2E 测试文件 (12 个)
+
+#### Fixtures (1 个)
+
+- ✅ `e2e/fixtures/base.fixture.ts` - 自定义测试固件基类
+
+#### Page Objects (3 个)
+
+- ✅ `e2e/pages/BasePage.ts` - 基础页面对象模型
+- ✅ `e2e/pages/HomePage.ts` - 首页 POM
+- ✅ `e2e/pages/LoginPage.ts` - 登录页 POM
+
+#### 测试规范 (7 个)
+
+- ✅ `e2e/example.spec.ts` - 验证 Playwright 设置的示例测试
+- ✅ `e2e/tests/home.spec.ts` - 首页功能测试（6 个测试用例）
+- ✅ `e2e/tests/navigation.spec.ts` - 导航和路由测试（5 个测试用例）
+- ✅ `e2e/tests/auth.spec.ts` - 认证流程测试（8 个测试用例）
+- ✅ `e2e/tests/i18n.spec.ts` - 国际化测试（6 个测试用例）
+- ✅ `e2e/tests/accessibility.spec.ts` - 可访问性测试（10 个测试用例）
+- ✅ `e2e/tests/performance.spec.ts` - 性能测试（8 个测试用例）
+
+#### 工具函数 (1 个)
+
+- ✅ `e2e/utils/test-helpers.ts` - 测试辅助函数库
+
+**总计**: 43+ 个测试用例，覆盖功能、质量、性能和可访问性
+
+### 3. 文档文件 (7 个)
+
+| 文件                                      | 说明                        | 语言    |
+| ----------------------------------------- | --------------------------- | ------- |
+| `docs/playwright/quickstart.md`           | 快速入门指南                | 中文    |
+| `docs/playwright/setup-complete.md`       | 设置完成指南                | 中文    |
+| `docs/playwright/installation-summary.md` | 安装总结（本文档）          | 中文    |
+| `docs/playwright/testing-guide.md`        | 详细测试指南                | 中文    |
+| `docs/zh/playwright-testing.md`           | Playwright 测试概述         | 中文    |
+| `docs/en/playwright-testing.md`           | Playwright Testing Overview | English |
+| `e2e/README.md`                           | E2E 目录文档                | English |
+
+### 4. CI/CD 配置 (1 个)
+
+- ✅ `.github/workflows/playwright.yml` - GitHub Actions 工作流
+  - 多浏览器矩阵测试
+  - 自动上传测试报告
+  - 失败时上传截图和视频
+  - 合并测试报告
+
+### 5. 更新的项目文件 (2 个)
+
+#### `package.json`
+
+添加了 8 个新的 npm 脚本：
+
+```json
+"test:e2e": "playwright test",
+"test:e2e:ui": "playwright test --ui",
+"test:e2e:headed": "playwright test --headed",
+"test:e2e:debug": "playwright test --debug",
+"test:e2e:chromium": "playwright test --project=chromium",
+"test:e2e:firefox": "playwright test --project=firefox",
+"test:e2e:webkit": "playwright test --project=webkit",
+"test:e2e:report": "playwright show-report playwright-report"
+```
+
+#### `eslint.config.mjs`
+
+- 添加了 `tsconfig.e2e.json` 到 parser options
+- 添加了 `playwright-report/` 和 `.playwright/` 到 ignores
+- 添加了 `playwright.config.*` 到 ignores
+- 添加了 `e2e/**` 到 ignores
+
+## 📊 项目统计
+
+- **配置文件**: 5 个
+- **测试文件**: 12 个
+- **文档文件**: 7 个
+- **测试用例**: 43+ 个
+- **Page Objects**: 3 个
+- **测试工具函数**: 8+ 个
+- **npm 脚本**: 8 个
+- **支持的浏览器**: 5 个（Chromium, Firefox, WebKit, Mobile Chrome, Mobile Safari）
+
+## 🎯 测试覆盖范围
+
+### 功能测试
+
+- ✅ 页面加载和渲染
+- ✅ 导航和路由
+- ✅ 表单验证和提交
+- ✅ 用户交互
+- ✅ 404 错误处理
+
+### 质量测试
+
+- ✅ 国际化 (i18n)
+- ✅ 语言切换
+- ✅ 响应式设计
+- ✅ 移动端兼容性
+
+### 可访问性测试
+
+- ✅ ARIA 角色和属性
+- ✅ 键盘导航
+- ✅ 屏幕阅读器支持
+- ✅ 语义化 HTML
+- ✅ 表单标签
+- ✅ 图片替代文本
+
+### 性能测试
+
+- ✅ 页面加载时间
+- ✅ First Contentful Paint (FCP)
+- ✅ Time to Interactive (TTI)
+- ✅ 包大小监控
+- ✅ 懒加载验证
+- ✅ 内存泄漏检测
+- ✅ 图片优化检查
+
+## 🚀 下一步行动清单
+
+### 必需步骤
+
+- [ ] **修复 npm 权限**
+
+  ```bash
+  sudo chown -R $(id -u):$(id -g) "$HOME/.npm"
+  ```
+
+- [ ] **安装 Playwright**
+
+  ```bash
+  npm install -D @playwright/test playwright
+  ```
+
+- [ ] **安装浏览器**
+
+  ```bash
+  npx playwright install
+  ```
+
+- [ ] **运行示例测试**
+  ```bash
+  npm run test:e2e -- e2e/example.spec.ts
+  ```
+
+### 推荐步骤
+
+- [ ] **安装 VS Code 扩展**
+  - [Playwright Test for VS Code](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright)
+
+- [ ] **清除 ESLint 缓存**（如果有 linting 错误）
+
+  ```bash
+  rm -rf .eslintcache
+  ```
+
+- [ ] **熟悉 UI 模式**
+
+  ```bash
+  npm run test:e2e:ui
+  ```
+
+- [ ] **查看测试报告**
+  ```bash
+  npm run test:e2e:report
+  ```
+
+### 可选步骤
+
+- [ ] **配置 CI/CD**
+  - GitHub Actions 配置已准备好
+  - 只需推送到 GitHub 即可自动运行
+
+- [ ] **编写自定义测试**
+  - 基于你的应用特定功能
+  - 使用提供的 Page Objects 作为模板
+
+- [ ] **配置测试覆盖率**
+  - 添加代码覆盖率工具
+  - 监控测试覆盖率
+
+## 📁 完整的项目结构
+
+```
+react-app/
+├── .github/
+│   └── workflows/
+│       └── playwright.yml              # CI/CD 配置
+├── .vscode/
+│   └── settings.json                   # VS Code 配置
+├── docs/
+│   ├── playwright/                     # Playwright 文档目录
+│   │   ├── quickstart.md              # 快速入门
+│   │   ├── setup-complete.md          # 设置完成指南
+│   │   ├── installation-summary.md    # 安装摘要
+│   │   └── testing-guide.md           # 详细测试指南
+│   ├── en/
+│   │   └── playwright-testing.md       # 英文概述
+│   └── zh/
+│       └── playwright-testing.md       # 中文概述
+├── e2e/                                # E2E 测试根目录
+│   ├── fixtures/
+│   │   └── base.fixture.ts            # 测试固件
+│   ├── pages/                          # Page Object Models
+│   │   ├── BasePage.ts
+│   │   ├── HomePage.ts
+│   │   └── LoginPage.ts
+│   ├── tests/                          # 测试规范
+│   │   ├── accessibility.spec.ts
+│   │   ├── auth.spec.ts
+│   │   ├── home.spec.ts
+│   │   ├── i18n.spec.ts
+│   │   ├── navigation.spec.ts
+│   │   └── performance.spec.ts
+│   ├── utils/
+│   │   └── test-helpers.ts            # 工具函数
+│   ├── example.spec.ts                 # 示例测试
+│   └── README.md                       # E2E 文档
+├── .eslintignore                       # ESLint 忽略规则
+├── .gitignore                          # Git 忽略规则
+├── playwright.config.ts                # Playwright 配置
+├── tsconfig.e2e.json                   # E2E TypeScript 配置
+└── package.json                        # 更新的依赖和脚本
+```
+
+## 🎨 特性亮点
+
+### 1. 完整的测试架构
+
+- Page Object Model 设计模式
+- 自定义 fixtures
+- 可重用的测试工具函数
+- 结构化的测试组织
+
+### 2. 多浏览器支持
+
+- Desktop: Chromium, Firefox, WebKit
+- Mobile: Chrome (Pixel 5), Safari (iPhone 12)
+- 并行执行测试
+
+### 3. 开发者友好
+
+- 交互式 UI 模式
+- 调试模式
+- 自动截图和视频
+- 详细的测试报告
+
+### 4. CI/CD 就绪
+
+- GitHub Actions 配置
+- 自动化测试执行
+- 测试报告上传
+- 失败时的调试信息
+
+### 5. 全面的文档
+
+- 集中式文档管理
+- 快速入门指南
+- 详细的 API 文档
+- 最佳实践指南
+
+## 🔍 快速验证
+
+运行以下命令验证安装：
+
+```bash
+# 1. 检查 Playwright 配置
+cat playwright.config.ts
+
+# 2. 列出所有测试文件
+find e2e -name "*.spec.ts"
+
+# 3. 检查 npm 脚本
+npm run | grep test:e2e
+
+# 4. 查看文档结构
+ls -R docs/playwright/
+```
+
+## 📞 获取帮助
+
+如果遇到问题，请查看：
+
+1. **快速入门**: [docs/playwright/quickstart.md](./quickstart.md)
+2. **设置指南**: [docs/playwright/setup-complete.md](./setup-complete.md)
+3. **测试指南**: [docs/playwright/testing-guide.md](./testing-guide.md)
+4. **E2E 文档**: [e2e/README.md](../../e2e/README.md)
+5. **官方文档**: https://playwright.dev/
+
+## 🎉 总结
+
+你现在拥有一个完整的、生产就绪的 Playwright E2E 测试套件！
+
+**包含**:
+
+- ✅ 43+ 个预定义测试用例
+- ✅ 5 个浏览器支持
+- ✅ Page Object Models
+- ✅ 测试工具函数
+- ✅ CI/CD 集成
+- ✅ 集中式文档管理
+
+**文档位置**:
+
+- 所有 Playwright 文档位于 `docs/playwright/` 目录
+- 中英文概述位于 `docs/zh/` 和 `docs/en/`
+- E2E 目录文档位于 `e2e/README.md`
+
+**下一步**: 安装依赖并运行你的第一个测试！
+
+```bash
+npm install -D @playwright/test playwright
+npx playwright install
+npm run test:e2e:ui
+```
+
+祝测试愉快！🚀