Chai 全局配置选项 - config includeStack showDiff truncateThreshold

配置在哪里

Chai 的配置通过 chai.config 对象访问，所有设置都是顶级属性。应该在测试套件开始前统一配置（比如 .mocharc.js 的 require 入口文件中）。

const chai = require('chai');

chai.config.includeStack = true;
chai.config.showDiff = false;
chai.config.truncateThreshold = 0;

三个核心配置项

includeStack（默认 false）

控制断言错误是否包含完整堆栈跟踪。默认关闭——错误消息只显示一行，干净利落：

AssertionError: expected 2 to equal 3

开启后会在错误消息下方追加堆栈：

AssertionError: expected 2 to equal 3
    at Context.<anonymous> (/path/to/test.js:5:12)
    at callFn (/path/to/mocha/lib/runnable.js:348:21)
    ...

什么时候开启：

断言被封装在自己写的 helper 函数里，堆栈能帮你快速定位到最终调用位置。
CI 环境下断言失败难以复现，堆栈信息有帮助。
开启后错误消息会变得很长，日常开发中默认关闭更利于快速阅读。

showDiff（默认 true）

控制断言错误消息中是否包含 diff 标记。默认开启——复杂对象比较失败时，会在消息中高亮显示差异：

AssertionError: expected [ Array(2) ] to deeply equal [ Array(2) ]
+ expected - actual

 [
   1,
-  3
+  2
 ]

关闭后只显示"expected X to deeply equal Y"，不显示差异细节。

什么时候关闭：

自定义测试报告器自己做 diff 渲染，重复显示没必要。
某些 diff 格式被 CI 日志吞掉或显示错乱。

truncateThreshold（默认 40）

控制断言错误消息中实际值和期望值的字符长度阈值。超过阈值时自动截断并省略：

chai.config.truncateThreshold = 40;

const longStr = 'a'.repeat(100);
expect(longStr).to.equal('b'.repeat(100));

// 错误消息中 longStr 会被截断显示
// "expected 'aaaa...' (100 chars) to equal 'bbbb...' (100 chars)"

设为 0 禁用截断，完整显示所有值：

chai.config.truncateThreshold = 0;

什么时候调整：

断言的值很长（比如大 JSON、长字符串），截断后看不到有用信息 → 设为 0 或更大的值。
CI 日志太长 → 保持默认或减小阈值。

完整配置示例

在 .mocharc.js 中统一配置：

// test/setup-chai.js
const chai = require('chai');

chai.config.includeStack = true;   // 开启堆栈
chai.config.showDiff = true;        // 保持 diff
chai.config.truncateThreshold = 0;  // 不截断

// 选一种风格全局注册
chai.should();  // 或者: require('chai/register-should')

module.exports = chai;

然后 .mocharc.js 里引用：

module.exports = {
  require: ['./test/setup-chai.js'],
  timeout: 5000,
  reporter: 'spec'
};

浏览器端配置

在浏览器中同样通过 chai.config 配置：

<script src="chai.js"></script>
<script>
  chai.config.truncateThreshold = 0;
  chai.config.includeStack = true;
</script>

插件可能增加的配置

某些插件会向 chai.config 添加自己的配置项。比如 chai-subset 可能支持调整子集匹配的严格程度。装了插件如果发现有 config 项，以插件文档为准。

不要做的事

不要修改 chai.config 下不存在的属性——不会报错，但也不会生效。
不要在单个测试用例里修改 config——其他测试会读到修改后的值，产生不可预测的行为。
不要指望重置 config——Chai 没有提供 chai.config.reset() 之类的方法，测试间共享同一配置。

如果某个测试需要特殊配置，自己保存原值再恢复：

const original = chai.config.truncateThreshold;
chai.config.truncateThreshold = 0;
// ... 特殊测试 ...
chai.config.truncateThreshold = original;

但这种场景很罕见，一般在全局层面配置一次就够了。

下一步

配置好风格和全局参数，接下来进入核心 API 的学习：

语言链与修饰器 → 语言链总览
按数据类型的断言 → 后续分组章节