如何组合使用Jest匹配器，实现模拟函数入参的灵活多规则断言

针对现有测试用例硬编码断言脆弱、缺少多规则组合校验能力的问题，可通过自定义非对称匹配器实现完全符合预期的灵活校验逻辑，无需侵入原有测试流程，也不影响原有内置断言的使用体验。

核心实现逻辑 #

Jest 内置的非对称匹配器（比如expect.stringMatching、expect.objectContaining）本身就提供了统一的校验接口，完全可以基于这套接口扩展两类核心组合能力：

• 逻辑与（对应预期的expect.all）：待校验值必须满足所有传入的匹配规则，任意一条规则不通过即判定校验失败
• 逻辑或（对应预期的多规则任意匹配）：待校验值只要满足任意一条传入的匹配规则，即判定校验通过

全局匹配器注册代码 #

只需要在项目的Jest setup文件中写一次注册逻辑，所有测试用例即可直接复用：

// 在 jest.setup.js 中全局注册自定义匹配器
expect.extend({
  // 实现全量匹配逻辑：所有规则都通过才返回校验成功
  allRules(received, ...matchers) {
    const failedReasons = matchers
      .map(matcher => matcher.asymmetricMatch(received))
      .filter(Boolean);
    return {
      pass: failedReasons.length === 0,
      message: () => `待校验值 ${JSON.stringify(received)} 未通过全部规则校验：\n${failedReasons.join('\n')}`
    };
  },

  // 实现任意匹配逻辑：任意一条规则通过即返回校验成功
  anyRule(received, ...matchers) {
    const pass = matchers.some(matcher => !matcher.asymmetricMatch(received));
    return {
      pass,
      message: () => `待校验值 ${JSON.stringify(received)} 未命中任何一条匹配规则`
    };
  }
});

// 为内置匹配器扩展链式调用能力，实现预期的 .and/.or 链式写法
const originalStringMatching = expect.stringMatching;
expect.stringMatching = (rule) => {
  const baseMatcher = originalStringMatching(rule);
  // 绑定and方法：拼接与逻辑规则
  baseMatcher.and = (nextMatcher) => expect.allRules(baseMatcher, nextMatcher);
  // 绑定or方法：拼接或逻辑规则
  baseMatcher.or = (nextMatcher) => expect.anyRule(baseMatcher, nextMatcher);
  return baseMatcher;
};

实际测试用例写法 #

自定义匹配器完全兼容toHaveBeenCalledWith这类针对模拟函数入参的断言，因为它完全遵循Jest非对称匹配器的接口规范，不需要额外获取实际入参值，校验逻辑全部在匹配器内部完成：

expect(mockedModule.mockFunction).toHaveBeenCalledTimes(1);
expect(mockedModule.mockFunction).toHaveLastBeenCalledWith(
  "argument1",
  {
    field1: expect.allRules(
      expect.stringMatching(/^argument1/),
      expect.anyRule(
        expect.stringMatching("42"),
        expect.stringMatching("8675309")
      )
    )
  }
);

完全等价的链式写法也可以直接使用：

field1: expect.stringMatching(/^argument1/).and(
  expect.stringMatching("42").or(
    expect.stringMatching("8675309")
  )
)

日常使用注意事项 #

• 这种自定义匹配器不会破坏原有测试的校验逻辑：校验失败时会明确输出所有未满足的规则明细，不会像多次调用toHaveLastBeenCalledWith那样，某条规则失败就中断后续校验，排查问题的效率更高。
• 不需要为了灵活校验反复拆分断言调用：所有的多规则校验逻辑会在单次匹配中完成，也避免了硬编码字面量带来的测试脆弱问题。
• 如果不想自行编写匹配器，也可以使用社区维护的Jest匹配器扩展库，这类库已经内置了同类多规则组合能力，可以直接在项目中引入使用。

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