张翔
11 KiB
11 KiB
自动化测试框架故障排查指南
本文档提供详细的故障排查步骤，帮助您快速定位和解决常见问题。
📋 目录
环境问题
问题1：环境变量未设置
症状：
❌ 错误: 缺少必需的环境变量
缺失的变量: WECOM_WEBHOOK_URL WECOM_TABLE_ID
原因：.env.test文件中缺少必需的环境变量或使用了占位符。
解决方案：
# 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
原因：测试端口已被其他进程占用。
解决方案：
# 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配置错误或资源不足。
解决方案：
# 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容器未运行或端口配置错误。
解决方案：
# 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
原因：测试数据库未创建。
解决方案：
# 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未创建。
解决方案：
# 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
原因：测试用例执行时间过长。
解决方案：
# 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']"
原因：页面元素未加载或选择器错误。
解决方案：
# 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
原因：测试数据未清理，导致数据冲突。
解决方案：
# 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'
原因：变更文件列表不存在。
解决方案：
# 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
原因：新文件未添加到测试映射配置中。
解决方案：
# 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：选择的测试过多或过少
症状：
- 选择了不相关的测试
- 漏选了相关的测试
原因：映射配置不准确或关联分析配置不当。
解决方案：
# 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配置错误或环境问题。
解决方案：
# 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测试失败
原因：环境差异或时序问题。
解决方案：
# 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
原因：测试执行时间过长。
解决方案：
# 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：测试执行缓慢
症状：
- 测试执行时间过长
- 资源占用高
原因：测试用例未优化或资源不足。
解决方案：
# 1. 并行执行测试
npx playwright test --workers=4
# 2. 使用分片执行
npx playwright test --shard=1/4
# 3. 优化测试用例
# - 减少不必要的等待
# - 使用更快的操作
# - 避免重复操作
# 4. 增加资源
# - 增加CPU核心
# - 增加内存
问题2：内存泄漏
症状：
- 测试过程中内存持续增长
- 最终导致OOM错误
原因：测试代码存在内存泄漏。
解决方案：
# 1. 监控内存使用
node --expose-gc --inspect dist/scripts/run-all-tests.js
# 2. 在测试中手动触发垃圾回收
if (global.gc) {
global.gc();
}
# 3. 检查测试代码
# - 清理事件监听器
# - 关闭数据库连接
# - 清理定时器
# 4. 使用afterEach清理资源
afterEach(async () => {
await cleanup();
});
日志分析
查看测试日志
# 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
分析日志
# 1. 查找错误信息
grep -i "error" test.log
# 2. 查找警告信息
grep -i "warning" test.log
# 3. 查找特定测试的日志
grep "test-name" test.log
# 4. 统计错误数量
grep -c "error" test.log
🆘 获取帮助
如果以上方法都无法解决问题，请：
-
查看官方文档
-
搜索已知问题
- GitHub Issues
- Stack Overflow
-
联系支持团队
- 提供详细的错误信息
- 提供复现步骤
- 提供环境信息
📝 故障排查清单
在报告问题前，请确认：
- 已运行环境变量验证脚本
- 已检查Docker容器状态
- 已检查数据库连接
- 已查看详细日志
- 已尝试本地复现
- 已搜索已知问题
文档版本: v1.0
最后更新: 2026-03-28
维护人员: 张翔