novalon/everything-is-suitable
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(admin): 添加用户管理相关文件

Browse Source 
添加用户管理视图、API和状态管理文件
This commit is contained in:
张翔
2026-03-28 14:37:29 +08:00
commit 08ea5fbe98
1643 changed files with 255646 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/troubleshooting-guide.md
+618
View File
@@ -0,0 +1,618 @@
# 自动化测试框架故障排查指南
本文档提供详细的故障排查步骤，帮助您快速定位和解决常见问题。
---
## 📋 目录
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
**维护人员**: 张翔