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 测试

npm run test:e2e:debug

Debug 所有测试

npm run test:debug

使用步骤：

  1. 运行上述命令
  2. 打开 Chrome 浏览器，访问 chrome://inspect
  3. 点击 “inspect” 链接
  4. 在 Chrome DevTools 中设置断点和调试

环境变量配置

E2E 测试需要连接到 IoTDB 实例。可以通过环境变量配置连接信息：

export IOTDB_HOST=localhost
export IOTDB_PORT=6667
export IOTDB_USER=root
export IOTDB_PASSWORD=root
export LOG_LEVEL=DEBUG  # 开启详细日志

使用 .env 文件（可选）

创建 .env 文件：

IOTDB_HOST=localhost
IOTDB_PORT=6667
IOTDB_USER=root
IOTDB_PASSWORD=root
LOG_LEVEL=DEBUG

然后在终端中执行：

source .env
npm run test:e2e:debug

设置断点

VS Code 中设置断点

  1. 在代码行号左侧点击，会出现红色圆点
  2. 或者将光标放在要断点的行，按 F9

常见断点位置

  • 测试文件中的 test() 函数内部
  • Session 或 SessionPool 方法调用前后
  • 数据处理逻辑
  • 错误处理 catch 块

Debug 技巧

1. 使用 --runInBand

所有 debug 配置都使用了 --runInBand 参数，这会：

  • 串行运行测试（而非并行）
  • 使调试更稳定
  • 避免多个测试同时运行的干扰

2. 调试单个测试

在测试文件中，可以临时使用 test.only() 来只运行特定测试：

test.only("Should execute query statement", async () => {
  // 只运行这个测试
});

3. 查看详细日志

设置 LOG_LEVEL=DEBUG 环境变量可以看到更详细的日志输出：

  • Thrift 连接详情
  • SQL 语句执行
  • 数据序列化/反序列化过程

4. 使用 debugger 语句

在代码中直接添加 debugger; 语句：

test("Should insert data", async () => {
  const tablet = {
    /* ... */
  };
  debugger; // 执行到这里会自动暂停
  await session.insertTablet(tablet);
});

使用 Docker 启动 IoTDB 实例

如果没有运行的 IoTDB 实例，可以使用 Docker 快速启动：

单节点（推荐用于调试）

docker-compose -f docker-compose-1c1d.yml up -d

3节点集群

docker-compose -f docker-compose-3c3d.yml up -d

停止 IoTDB

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 中右键点击断点，选择“编辑断点” → “表达式”，可以设置条件：

row.length > 10; // 只在满足条件时暂停

Logpoint（日志点）

不想停止执行，只想输出日志？右键断点选择“Logpoint”：

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 中执行表达式查看状态

参考资源