everything-is-suitable/docs/troubleshooting-guide.md

# 自动化测试框架故障排查指南

本文档提供详细的故障排查步骤，帮助您快速定位和解决常见问题。

---

## 📋 目录

1. [环境问题](#环境问题)
2. [数据库问题](#数据库问题)
3. [测试执行问题](#测试执行问题)
4. [智能测试选择器问题](#智能测试选择器问题)
5. [CI/CD问题](#cicd问题)
6. [性能问题](#性能问题)
7. [日志分析](#日志分析)

---

## 环境问题

### 问题1：环境变量未设置

**症状**：
```
❌ 错误: 缺少必需的环境变量
缺失的变量: WECOM_WEBHOOK_URL WECOM_TABLE_ID
```

**原因**：.env.test文件中缺少必需的环境变量或使用了占位符。

**解决方案**：
```bash
# 1. 检查.env.test文件
cat .env.test

# 2. 编辑.env.test文件，设置实际值
vim .env.test

# 3. 验证环境变量
./scripts/verify-env.sh
```

**预防措施**：
- 使用环境变量验证脚本定期检查配置
- 在CI/CD中添加环境变量验证步骤

---

### 问题2：端口被占用

**症状**：
```
Error: Port 5174 is already in use
```

**原因**：测试端口已被其他进程占用。

**解决方案**：
```bash
# 1. 查找占用端口的进程
lsof -i :5174

# 2. 终止占用端口的进程
kill -9 <PID>

# 或者批量终止
lsof -ti :5174 | xargs kill -9

# 3. 验证端口已释放
lsof -i :5174
```

**预防措施**：
- 在启动测试环境前检查端口可用性
- 使用不同的端口配置避免冲突

---

### 问题3：Docker容器无法启动

**症状**：
```
Error: Cannot start service admin-frontend-test
```

**原因**：Docker配置错误或资源不足。

**解决方案**：
```bash
# 1. 检查Docker状态
docker info

# 2. 查看容器日志
docker-compose -f docker-compose.test.yml logs admin-frontend-test

# 3. 检查容器配置
docker-compose -f docker-compose.test.yml config

# 4. 清理并重新启动
docker-compose -f docker-compose.test.yml down -v
docker-compose -f docker-compose.test.yml up -d

# 5. 检查Docker资源
docker system df
docker system prune  # 清理未使用的资源
```

**预防措施**：
- 定期清理Docker资源
- 监控Docker资源使用情况

---

## 数据库问题

### 问题1：数据库连接失败

**症状**：
```
Error: Connection refused (host.docker.internal:55432)
```

**原因**：PostgreSQL容器未运行或端口配置错误。

**解决方案**：
```bash
# 1. 检查PostgreSQL容器状态
docker ps | grep postgresql_dev

# 2. 启动PostgreSQL容器
docker start postgresql_dev

# 3. 验证数据库连接
docker exec postgresql_dev psql -U postgres -c "SELECT 1"

# 4. 检查端口映射
docker port postgresql_dev

# 5. 测试数据库连接
psql -h localhost -p 55432 -U postgres -d everything_suitable_test
```

**预防措施**：
- 设置PostgreSQL容器自动启动
- 使用健康检查监控数据库状态

---

### 问题2：测试数据库不存在

**症状**：
```
Error: database "everything_suitable_test" does not exist
```

**原因**：测试数据库未创建。

**解决方案**：
```bash
# 1. 运行数据库初始化脚本
./scripts/init-test-database.sh

# 2. 验证数据库创建
docker exec postgresql_dev psql -U postgres -c "\l" | grep everything_suitable_test

# 3. 初始化测试数据（可选）
npm run ts-node scripts/init-test-data.ts
```

**预防措施**：
- 在CI/CD中添加数据库初始化步骤
- 定期备份测试数据

---

### 问题3：Schema不存在

**症状**：
```
Error: schema "test_data" does not exist
```

**原因**：test_data schema未创建。

**解决方案**：
```bash
# 1. 创建schema
docker exec postgresql_dev psql -U postgres -d everything_suitable_test -c "CREATE SCHEMA IF NOT EXISTS test_data;"

# 2. 验证schema创建
docker exec postgresql_dev psql -U postgres -d everything_suitable_test -c "\dn" | grep test_data

# 3. 授予权限
docker exec postgresql_dev psql -U postgres -d everything_suitable_test -c "GRANT ALL ON SCHEMA test_data TO postgres;"
```

---

## 测试执行问题

### 问题1：测试超时

**症状**：
```
Error: Test timeout of 30000ms exceeded
```

**原因**：测试用例执行时间过长。

**解决方案**：
```bash
# 1. 增加超时时间
export TEST_TIMEOUT=60000

# 2. 在测试文件中设置超时
test('my test', async ({ page }) => {
  test.setTimeout(60000);
  // ...
});

# 3. 在playwright.config.ts中设置全局超时
export default defineConfig({
  timeout: 60000,
});
```

**预防措施**：
- 优化测试用例，减少不必要的等待
- 使用合适的超时设置

---

### 问题2：元素定位失败

**症状**：
```
Error: Timed out waiting for selector "button[data-testid='submit']"
```

**原因**：页面元素未加载或选择器错误。

**解决方案**：
```bash
# 1. 使用调试模式查看页面状态
npx playwright test --debug

# 2. 使用UI模式检查元素
npx playwright test --ui

# 3. 添加等待策略
await page.waitForSelector('button[data-testid="submit"]', { state: 'visible' });

# 4. 使用更可靠的选择器
await page.getByRole('button', { name: '提交' }).click();

# 5. 添加截图调试
await page.screenshot({ path: 'debug.png' });
```

**预防措施**：
- 使用data-testid属性
- 使用Playwright推荐的选择器策略
- 添加适当的等待机制

---

### 问题3：测试数据污染

**症状**：
```
Error: Duplicate key value violates unique constraint
```

**原因**：测试数据未清理，导致数据冲突。

**解决方案**：
```bash
# 1. 清理测试数据
docker exec postgresql_dev psql -U postgres -d everything_suitable_test -c "TRUNCATE TABLE test_data.users CASCADE;"

# 2. 重新初始化测试数据
npm run ts-node scripts/init-test-data.ts

# 3. 在测试中使用beforeEach清理数据
beforeEach(async () => {
  await cleanTestData();
});
```

**预防措施**：
- 每个测试用例独立管理数据
- 使用事务回滚机制
- 定期清理测试数据

---

## 智能测试选择器问题

### 问题1：找不到变更文件

**症状**：
```
Error: Cannot find module 'changed-files.txt'
```

**原因**：变更文件列表不存在。

**解决方案**：
```bash
# 1. 创建变更文件列表
git diff --name-only origin/main...HEAD > changed-files.txt

# 2. 如果没有变更，创建空文件
echo "[]" > changed-files.txt

# 3. 验证文件内容
cat changed-files.txt
```

---

### 问题2：测试映射配置错误

**症状**：
```
Warning: No mapping found for file: src/views/NewFeature.vue
```

**原因**：新文件未添加到测试映射配置中。

**解决方案**：
```bash
# 1. 编辑测试映射配置
vim config/test-mapping.config.ts

# 2. 添加新的映射
export const testMapping: TestMapping = {
  // ... 现有映射 ...
  
  'everything-is-suitable-admin/src/views/NewFeature.vue': {
    tests: [
      'e2e/new-feature/*.spec.ts',
    ],
    priority: 'high',
    modules: ['new-feature'],
  },
};

# 3. 重新编译
npx tsc

# 4. 验证配置
node dist/scripts/scripts/cli/smart-test-selector-cli.js \
  --input changed-files.txt \
  --output selected-tests.json
```

**预防措施**：
- 在添加新功能时同步更新映射配置
- 定期审查映射配置的完整性

---

### 问题3：选择的测试过多或过少

**症状**：
- 选择了不相关的测试
- 漏选了相关的测试

**原因**：映射配置不准确或关联分析配置不当。

**解决方案**：
```bash
# 1. 调整关联分析设置
node dist/scripts/scripts/cli/smart-test-selector-cli.js \
  --input changed-files.txt \
  --no-include-related \
  --output selected-tests.json

# 2. 调整优先级过滤
node dist/scripts/scripts/cli/smart-test-selector-cli.js \
  --input changed-files.txt \
  --priority high \
  --output selected-tests.json

# 3. 手动调整映射配置
vim config/test-mapping.config.ts
```

---

## CI/CD问题

### 问题1：CI构建失败

**症状**：
```
Error: Build failed in Woodpecker CI
```

**原因**：CI配置错误或环境问题。

**解决方案**：
```bash
# 1. 查看CI日志
# 在Woodpecker CI界面查看详细日志

# 2. 本地复现CI环境
docker run --rm -it node:20-alpine sh
npm ci
npm run test:all

# 3. 检查CI配置
cat .woodpecker.yml

# 4. 验证环境变量
# 确保CI中的环境变量已正确设置
```

---

### 问题2：测试在CI中失败但本地通过

**症状**：
- 本地测试通过
- CI测试失败

**原因**：环境差异或时序问题。

**解决方案**：
```bash
# 1. 检查环境差异
# - Node.js版本
# - 依赖版本
# - 环境变量

# 2. 增加等待时间
await page.waitForTimeout(1000);

# 3. 使用重试机制
export default defineConfig({
  retries: 2,
});

# 4. 添加调试日志
console.log('Debug info:', debugInfo);
```

**预防措施**：
- 保持本地和CI环境一致
- 使用容器化环境
- 添加适当的等待和重试机制

---

### 问题3：CI超时

**症状**：
```
Error: Build timed out after 60 minutes
```

**原因**：测试执行时间过长。

**解决方案**：
```bash
# 1. 优化测试执行
# - 并行执行测试
# - 减少测试数量
# - 优化测试用例

# 2. 调整CI超时设置
# .woodpecker.yml
pipeline:
  smart-test-execution:
    image: node:20-alpine
    commands:
      - npm run test:smart selected-tests.json
    timeout: 120  # 分钟

# 3. 使用智能测试选择
# 只执行相关的测试
```

---

## 性能问题

### 问题1：测试执行缓慢

**症状**：
- 测试执行时间过长
- 资源占用高

**原因**：测试用例未优化或资源不足。

**解决方案**：
```bash
# 1. 并行执行测试
npx playwright test --workers=4

# 2. 使用分片执行
npx playwright test --shard=1/4

# 3. 优化测试用例
# - 减少不必要的等待
# - 使用更快的操作
# - 避免重复操作

# 4. 增加资源
# - 增加CPU核心
# - 增加内存
```

---

### 问题2：内存泄漏

**症状**：
- 测试过程中内存持续增长
- 最终导致OOM错误

**原因**：测试代码存在内存泄漏。

**解决方案**：
```bash
# 1. 监控内存使用
node --expose-gc --inspect dist/scripts/run-all-tests.js

# 2. 在测试中手动触发垃圾回收
if (global.gc) {
  global.gc();
}

# 3. 检查测试代码
# - 清理事件监听器
# - 关闭数据库连接
# - 清理定时器

# 4. 使用afterEach清理资源
afterEach(async () => {
  await cleanup();
});
```

---

## 日志分析

### 查看测试日志

```bash
# 1. 查看Playwright日志
DEBUG=pw:api npx playwright test

# 2. 查看浏览器日志
npx playwright test --trace on

# 3. 查看详细日志
npx playwright test --reporter=list

# 4. 保存日志到文件
npx playwright test > test.log 2>&1
```

### 分析日志

```bash
# 1. 查找错误信息
grep -i "error" test.log

# 2. 查找警告信息
grep -i "warning" test.log

# 3. 查找特定测试的日志
grep "test-name" test.log

# 4. 统计错误数量
grep -c "error" test.log
```

---

## 🆘 获取帮助

如果以上方法都无法解决问题，请：

1. **查看官方文档**
   - [Playwright文档](https://playwright.dev/)
   - [Woodpecker CI文档](https://woodpecker-ci.org/)

2. **搜索已知问题**
   - GitHub Issues
   - Stack Overflow

3. **联系支持团队**
   - 提供详细的错误信息
   - 提供复现步骤
   - 提供环境信息

---

## 📝 故障排查清单

在报告问题前，请确认：

- [ ] 已运行环境变量验证脚本
- [ ] 已检查Docker容器状态
- [ ] 已检查数据库连接
- [ ] 已查看详细日志
- [ ] 已尝试本地复现
- [ ] 已搜索已知问题

---

**文档版本**: v1.0  
**最后更新**: 2026-03-28  
**维护人员**: 张翔