单元测试失败时如何扩展辅助函数外的调用栈至测试用例

问题背景 #

封装TestUtils类的静态辅助函数expectedResponseForGET/expectedResponseForPOST复用HTTP请求和断言逻辑后，一旦断言失败，报错调用栈仅指向辅助函数内的代码行，无法直接定位到测试用例中调用该函数的具体位置，增加了问题排查成本。

报错调用栈示例 #

src/tests/sites/add.test.ts
  Add site route
    ✓  User4 - Add site, not company manager (238 ms)
    ✕  User1 - Add site, company manager (269 ms)

  ● Add site route ›  User1 - Add site, company manager

    expect(received).toEqual(expected) // deep equality

    - Expected  -  1
    + Received  +  1

    @@ -1,63 +1,10 @@
    -       "location": "Location2",
    +       "location": "Location",

      92 |       .set('Authorization', user.token);
      93 |     expect(res.status).toBe(200);
    > 94 |     expect(res.body).toEqual(response);
         |                      ^
      95 |     return res;
      96 |   };
      97 |

      at src/tests/utils.ts:94:22
      at fulfilled (src/tests/utils.ts:5:58)

测试用例代码 #

test(' User1 - Add site, company manager', async () => {
    await TestUtils.expectedResponseForPOST(
      server,
      C1.users.U1,
      route,
      C1.sites.S5.requests.addSite,
      C1.sites.S5.responses.fullSite,
    );

    await TestUtils.expectedResponseForGET(
      server,
      C1.users.U1,
      routeSites,
      C1.sites.responses.allAfterS5,
    );

   await TestUtils.expectedResponseForGET(
      server,
      C1.users.U1,
      routeWork,
      C1.work.responses.allAfterS5,
    );
  });

辅助函数代码 #

import request from 'supertest';

class TestUtils{
  static expectedResponseForGET = async (
    server: Express,
    user: UserTest,
    route: string,
    response: GenericResponse,
  ) => {
    const res = await request(server)
      .get(route)
      .set('Authorization', user.token);
    expect(res.status).toBe(200);
    expect(res.body).toEqual(response);
    return res;
  };

  static expectedResponseForPOST = async (
    server: Express,
    user: UserTest,
    route: string,
    // eslint-disable-next-line @typescript-eslint/ban-types
    req: Object,
    response: GenericResponse,
  ) => {
    const res = await request(server)
      .post(route)
      .send(req)
      .set('Authorization', user.token);
    expect(res.status).toBe(200);
    expect(res.body).toEqual(response);
    return res;
  };
}

解决方案 #

方案1：拆分逻辑，辅助函数仅负责发起请求 #

将断言逻辑从辅助函数中剥离，让辅助函数只处理HTTP请求并返回响应，断言逻辑移到测试用例中实现。这样断言失败时，调用栈会直接指向测试用例中的断言行。

修改后的辅助函数：

class TestUtils{
  static makeGETRequest = async (
    server: Express,
    user: UserTest,
    route: string,
  ) => {
    return request(server)
      .get(route)
      .set('Authorization', user.token);
  };

  static makePOSTRequest = async (
    server: Express,
    user: UserTest,
    route: string,
    req: Object,
  ) => {
    return request(server)
      .post(route)
      .send(req)
      .set('Authorization', user.token);
  };
}

测试用例中调用：

test(' User1 - Add site, company manager', async () => {
    const postRes = await TestUtils.makePOSTRequest(
      server,
      C1.users.U1,
      route,
      C1.sites.S5.requests.addSite,
    );
    expect(postRes.status).toBe(200);
    expect(postRes.body).toEqual(C1.sites.S5.responses.fullSite);

    const getSitesRes = await TestUtils.makeGETRequest(
      server,
      C1.users.U1,
      routeSites,
    );
    expect(getSitesRes.status).toBe(200);
    expect(getSitesRes.body).toEqual(C1.sites.responses.allAfterS5);

    const getWorkRes = await TestUtils.makeGETRequest(
      server,
      C1.users.U1,
      routeWork,
    );
    expect(getWorkRes.status).toBe(200);
    expect(getWorkRes.body).toEqual(C1.work.responses.allAfterS5);
  });

优点：逻辑清晰，调用栈直接指向测试用例，排查直观；缺点：测试用例会增加少量重复代码。

方案2：捕获断言错误并修正调用栈 #

在辅助函数中捕获断言失败的错误，手动创建新错误并调整调用栈，让错误指向测试用例中调用辅助函数的位置。

修改后的辅助函数：

class TestUtils{
  static expectedResponseForGET = async (
    server: Express,
    user: UserTest,
    route: string,
    response: GenericResponse,
  ) => {
    const res = await request(server)
      .get(route)
      .set('Authorization', user.token);
    
    try {
      expect(res.status).toBe(200);
      expect(res.body).toEqual(response);
    } catch (err) {
      const originalError = err as Error;
      // 创建新错误，携带请求路径和原始错误信息
      const newError = new Error(`GET ${route} 断言失败: ${originalError.message}`);
      // 跳过当前函数的栈帧，让调用栈指向测试用例的调用处
      Error.captureStackTrace(newError, TestUtils.expectedResponseForGET);
      // 保留原始错误的对比信息（Jest的diff）
      (newError as any).diff = (originalError as any).diff;
      throw newError;
    }

    return res;
  };

  static expectedResponseForPOST = async (
    server: Express,
    user: UserTest,
    route: string,
    req: Object,
    response: GenericResponse,
  ) => {
    const res = await request(server)
      .post(route)
      .send(req)
      .set('Authorization', user.token);
    
    try {
      expect(res.status).toBe(200);
      expect(res.body).toEqual(response);
    } catch (err) {
      const originalError = err as Error;
      const newError = new Error(`POST ${route} 断言失败: ${originalError.message}`);
      Error.captureStackTrace(newError, TestUtils.expectedResponseForPOST);
      (newError as any).diff = (originalError as any).diff;
      throw newError;
    }

    return res;
  };
}

优点：保留了辅助函数的复用性，错误信息更明确，调用栈指向测试用例；缺点：需要额外处理错误捕获和栈帧调整。

方案3：传递自定义错误上下文 #

在调用辅助函数时，传入自定义的标识信息（比如测试步骤描述），当断言失败时将该信息包含在错误消息中，帮助定位测试用例中的具体调用位置。

调用示例：

await TestUtils.expectedResponseForGET(
  server,
  C1.users.U1,
  routeSites,
  C1.sites.responses.allAfterS5,
  "校验添加站点后的站点列表" // 新增的上下文参数
);

修改辅助函数接收并使用该参数：

static expectedResponseForGET = async (
  server: Express,
  user: UserTest,
  route: string,
  response: GenericResponse,
  context?: string,
) => {
  const res = await request(server)
    .get(route)
    .set('Authorization', user.token);
  
  const contextMsg = context ? `[${context}] ` : '';
  expect(res.status).toBe(200);
  expect(res.body).toEqual(response, `${contextMsg}GET ${route} 响应不匹配`);
  return res;
};

优点：实现简单，通过自定义消息快速定位测试步骤；缺点：需要手动维护上下文信息，调用栈仍指向辅助函数，但错误消息足够明确。

内容的提问来源于stack exchange，提问作者chreniuc