| # E2E 测试 Debug 指南 |
| |
| 本文档说明如何调试 E2E 测试。 |
| |
| ## 方法一：使用 VS Code Debug 配置（推荐） |
| |
| 项目已配置好多个 debug 启动配置，位于 `.vscode/launch.json`： |
| |
| ### 1. Debug E2E Tests |
| |
| 调试所有 E2E 测试 |
| |
| **使用步骤：** |
| |
| 1. 按 `F5` 或点击 VS Code 左侧的"运行和调试"图标 |
| 2. 选择 "Debug E2E Tests" |
| 3. 点击绿色播放按钮或按 `F5` |
| |
| ### 2. Debug Current E2E Test File |
| |
| 调试当前打开的测试文件 |
| |
| **使用步骤：** |
| |
| 1. 在 VS Code 中打开要调试的测试文件（如 `Session.test.ts`） |
| 2. 按 `F5` 或选择 "Debug Current E2E Test File" |
| 3. 在代码中设置断点（点击行号左侧） |
| |
| ### 3. Debug Unit Tests |
| |
| 调试所有单元测试 |
| |
| ### 4. Debug All Tests |
| |
| 调试所有测试（单元测试 + E2E 测试） |
| |
| ## 方法二：使用命令行脚本 |
| |
| ### Debug E2E 测试 |
| |
| ```bash |
| npm run test:e2e:debug |
| ``` |
| |
| ### Debug 所有测试 |
| |
| ```bash |
| npm run test:debug |
| ``` |
| |
| **使用步骤：** |
| |
| 1. 运行上述命令 |
| 2. 打开 Chrome 浏览器，访问 `chrome://inspect` |
| 3. 点击 "inspect" 链接 |
| 4. 在 Chrome DevTools 中设置断点和调试 |
| |
| ## 环境变量配置 |
| |
| E2E 测试需要连接到 IoTDB 实例。可以通过环境变量配置连接信息： |
| |
| ```bash |
| export IOTDB_HOST=localhost |
| export IOTDB_PORT=6667 |
| export IOTDB_USER=root |
| export IOTDB_PASSWORD=root |
| export LOG_LEVEL=DEBUG # 开启详细日志 |
| ``` |
| |
| ### 使用 .env 文件（可选） |
| |
| 创建 `.env` 文件： |
| |
| ```bash |
| IOTDB_HOST=localhost |
| IOTDB_PORT=6667 |
| IOTDB_USER=root |
| IOTDB_PASSWORD=root |
| LOG_LEVEL=DEBUG |
| ``` |
| |
| 然后在终端中执行： |
| |
| ```bash |
| source .env |
| npm run test:e2e:debug |
| ``` |
| |
| ## 设置断点 |
| |
| ### VS Code 中设置断点 |
| |
| 1. 在代码行号左侧点击，会出现红色圆点 |
| 2. 或者将光标放在要断点的行，按 `F9` |
| |
| ### 常见断点位置 |
| |
| - 测试文件中的 `test()` 函数内部 |
| - Session 或 SessionPool 方法调用前后 |
| - 数据处理逻辑 |
| - 错误处理 `catch` 块 |
| |
| ## Debug 技巧 |
| |
| ### 1. 使用 `--runInBand` |
| |
| 所有 debug 配置都使用了 `--runInBand` 参数，这会： |
| |
| - 串行运行测试（而非并行） |
| - 使调试更稳定 |
| - 避免多个测试同时运行的干扰 |
| |
| ### 2. 调试单个测试 |
| |
| 在测试文件中，可以临时使用 `test.only()` 来只运行特定测试： |
| |
| ```typescript |
| test.only("Should execute query statement", async () => { |
| // 只运行这个测试 |
| }); |
| ``` |
| |
| ### 3. 查看详细日志 |
| |
| 设置 `LOG_LEVEL=DEBUG` 环境变量可以看到更详细的日志输出： |
| |
| - Thrift 连接详情 |
| - SQL 语句执行 |
| - 数据序列化/反序列化过程 |
| |
| ### 4. 使用 debugger 语句 |
| |
| 在代码中直接添加 `debugger;` 语句： |
| |
| ```typescript |
| test("Should insert data", async () => { |
| const tablet = { |
| /* ... */ |
| }; |
| debugger; // 执行到这里会自动暂停 |
| await session.insertTablet(tablet); |
| }); |
| ``` |
| |
| ## 使用 Docker 启动 IoTDB 实例 |
| |
| 如果没有运行的 IoTDB 实例，可以使用 Docker 快速启动： |
| |
| ### 单节点（推荐用于调试） |
| |
| ```bash |
| docker-compose -f docker-compose-1c1d.yml up -d |
| ``` |
| |
| ### 3节点集群 |
| |
| ```bash |
| docker-compose -f docker-compose-3c3d.yml up -d |
| ``` |
| |
| ### 停止 IoTDB |
| |
| ```bash |
| docker-compose -f docker-compose-1c1d.yml down |
| ``` |
| |
| ## 故障排查 |
| |
| ### 问题：无法连接到 IoTDB |
| |
| **解决方案：** |
| |
| 1. 检查 IoTDB 是否正在运行 |
| 2. 确认环境变量 `IOTDB_HOST` 和 `IOTDB_PORT` 是否正确 |
| 3. 查看 IoTDB 日志：`docker logs iotdb-datanode` |
| |
| ### 问题：断点不生效 |
| |
| **解决方案：** |
| |
| 1. 确保使用了 `--inspect-brk` 参数（已在配置中） |
| 2. 检查是否使用了 `--runInBand` 参数（已在配置中） |
| 3. 尝试重启 VS Code |
| |
| ### 问题：测试超时 |
| |
| **解决方案：** |
| |
| 1. 在 `jest.config.js` 中增加超时时间 |
| 2. 或在具体测试中设置：`test('...', async () => {...}, 120000)` |
| |
| ## 高级用法 |
| |
| ### 条件断点 |
| |
| 在 VS Code 中右键点击断点，选择"编辑断点" → "表达式"，可以设置条件： |
| |
| ```javascript |
| row.length > 10; // 只在满足条件时暂停 |
| ``` |
| |
| ### Logpoint（日志点） |
| |
| 不想停止执行，只想输出日志？右键断点选择"Logpoint"： |
| |
| ```javascript |
| result.rows.length: {result.rows.length} |
| ``` |
| |
| ### Watch 表达式 |
| |
| 在 Debug 面板的 "WATCH" 区域添加表达式，实时监控变量值。 |
| |
| ## 示例：调试一个失败的测试 |
| |
| 1. 打开 `tests/e2e/Session.test.ts` |
| 2. 在失败的测试中设置断点 |
| 3. 选择 "Debug Current E2E Test File" 配置 |
| 4. 按 `F5` 开始调试 |
| 5. 使用 Debug 工具栏： |
| - Continue (F5): 继续执行 |
| - Step Over (F10): 单步跳过 |
| - Step Into (F11): 单步进入 |
| - Step Out (Shift+F11): 跳出当前函数 |
| 6. 查看变量面板中的值 |
| 7. 在 Debug Console 中执行表达式查看状态 |
| |
| ## 参考资源 |
| |
| - [VS Code Debugging Guide](https://code.visualstudio.com/docs/editor/debugging) |
| - [Jest Debugging Guide](https://jestjs.io/docs/troubleshooting) |
| - [Node.js Debugging Guide](https://nodejs.org/en/docs/guides/debugging-getting-started/) |
