Jest 断言匹配器 #

test('example', () => {
  expect(实际值).匹配器(预期值);
});

test('toBe examples', () => {
  // 基本类型
  expect(1 + 1).toBe(2);
  expect('hello').toBe('hello');
  expect(true).toBe(true);

  // 对象引用（必须是同一个引用）
  const obj = { a: 1 };
  expect(obj).toBe(obj);
  expect({ a: 1 }).not.toBe({ a: 1 }); // 不同引用
});

test('toEqual examples', () => {
  // 对象比较
  expect({ a: 1 }).toEqual({ a: 1 });
  expect({ a: { b: 2 } }).toEqual({ a: { b: 2 } });

  // 数组比较
  expect([1, 2, 3]).toEqual([1, 2, 3]);
  expect([{ id: 1 }]).toEqual([{ id: 1 }]);

  // 嵌套对象
  const user = {
    name: 'John',
    address: {
      city: 'New York',
      country: 'USA'
    }
  };
  expect(user).toEqual({
    name: 'John',
    address: {
      city: 'New York',
      country: 'USA'
    }
  });
});

test('toStrictEqual examples', () => {
  // 区分 undefined 和缺失属性
  expect({ a: undefined }).not.toStrictEqual({});
  expect({ a: undefined }).toEqual({});

  // 区分稀疏数组
  expect([, , 1]).not.toStrictEqual([undefined, undefined, 1]);
});

test('boolean matchers', () => {
  // toBeTruthy - 检查是否为真值
  expect(true).toBeTruthy();
  expect(1).toBeTruthy();
  expect('hello').toBeTruthy();
  expect({}).toBeTruthy();
  expect([]).toBeTruthy();

  // toBeFalsy - 检查是否为假值
  expect(false).toBeFalsy();
  expect(0).toBeFalsy();
  expect('').toBeFalsy();
  expect(null).toBeFalsy();
  expect(undefined).toBeFalsy();
  expect(NaN).toBeFalsy();
});

test('null and undefined matchers', () => {
  // toBeNull
  expect(null).toBeNull();
  expect(undefined).not.toBeNull();

  // toBeUndefined
  expect(undefined).toBeUndefined();
  expect(null).not.toBeUndefined();

  // toBeDefined
  expect(null).toBeDefined();
  expect(undefined).not.toBeDefined();
});

test('number equality', () => {
  expect(1 + 1).toBe(2);
  expect(1 + 1).toEqual(2);
  expect(1 + 1).not.toBe(3);
});

test('number comparisons', () => {
  const value = 10;

  // 大于
  expect(value).toBeGreaterThan(5);
  expect(value).toBeGreaterThan(9);

  // 大于等于
  expect(value).toBeGreaterThanOrEqual(10);
  expect(value).toBeGreaterThanOrEqual(9);

  // 小于
  expect(value).toBeLessThan(20);
  expect(value).toBeLessThan(11);

  // 小于等于
  expect(value).toBeLessThanOrEqual(10);
  expect(value).toBeLessThanOrEqual(11);
});

test('floating point numbers', () => {
  // 使用 toBeCloseTo 避免浮点精度问题
  expect(0.1 + 0.2).toBeCloseTo(0.3);
  expect(0.1 + 0.2).not.toBe(0.3); // 浮点精度问题

  // 指定精度
  expect(0.1 + 0.2).toBeCloseTo(0.3, 5); // 5位小数精度
  expect(0.1 + 0.2).toBeCloseTo(0.3, 10); // 10位小数精度
});

test('string equality', () => {
  expect('hello').toBe('hello');
  expect('hello').toEqual('hello');
});

test('string contains', () => {
  // toContain - 检查是否包含子字符串
  expect('hello world').toContain('world');
  expect('hello world').not.toContain('foo');

  // toContainEqual - 检查数组中是否包含特定对象
  expect([{ a: 1 }, { b: 2 }]).toContainEqual({ a: 1 });
});

test('string regex', () => {
  // toMatch - 正则表达式匹配
  expect('hello world').toMatch(/world/);
  expect('hello world').toMatch(/hello/);
  expect('hello world').toMatch(/^hello/);
  expect('hello world').toMatch(/world$/);
  expect('hello world').toMatch(/\s/);
});

test('string length', () => {
  expect('hello').toHaveLength(5);
  expect('hello world').toHaveLength(11);
});

test('array contains', () => {
  const arr = [1, 2, 3, 'a', 'b'];

  // toContain - 检查是否包含元素
  expect(arr).toContain(1);
  expect(arr).toContain('a');
  expect(arr).not.toContain(4);

  // toContainEqual - 检查是否包含匹配的对象
  const users = [
    { id: 1, name: 'John' },
    { id: 2, name: 'Jane' }
  ];
  expect(users).toContainEqual({ id: 1, name: 'John' });
});

test('array length', () => {
  expect([1, 2, 3]).toHaveLength(3);
  expect([]).toHaveLength(0);
});

test('array elements', () => {
  // toHaveLength - 检查长度
  expect([1, 2, 3]).toHaveLength(3);

  // toEqual - 深度比较
  expect([1, 2, 3]).toEqual([1, 2, 3]);

  // arrayContaining - 检查是否包含子集
  expect([1, 2, 3, 4, 5]).toEqual(
    expect.arrayContaining([1, 2, 3])
  );
});

test('object properties', () => {
  const user = {
    name: 'John',
    age: 30,
    email: 'john@example.com'
  };

  // toHaveProperty - 检查属性是否存在
  expect(user).toHaveProperty('name');
  expect(user).toHaveProperty('age');
  expect(user).toHaveProperty('address.city'); // 嵌套属性

  // 检查属性值
  expect(user).toHaveProperty('name', 'John');
  expect(user).toHaveProperty('age', 30);
});

test('object matching', () => {
  const user = {
    name: 'John',
    age: 30,
    email: 'john@example.com'
  };

  // objectContaining - 检查是否包含部分属性
  expect(user).toEqual(
    expect.objectContaining({
      name: 'John',
      age: 30
    })
  );

  // 匹配任意值
  expect(user).toEqual(
    expect.objectContaining({
      name: expect.any(String),
      age: expect.any(Number)
    })
  );
});

test('object keys', () => {
  const obj = { a: 1, b: 2, c: 3 };

  // 检查是否有特定数量的键
  expect(Object.keys(obj)).toHaveLength(3);
});

function throwError() {
  throw new Error('Something went wrong');
}

function throwCustomError() {
  throw new TypeError('Invalid type');
}

test('throwing errors', () => {
  // 检查是否抛出错误
  expect(throwError).toThrow();
  expect(throwError).toThrow(Error);

  // 检查错误消息
  expect(throwError).toThrow('Something went wrong');
  expect(throwError).toThrow(/wrong/);

  // 检查错误类型
  expect(throwCustomError).toThrow(TypeError);
  expect(throwCustomError).toThrow('Invalid type');
});

async function asyncError() {
  throw new Error('Async error');
}

test('async errors', async () => {
  // 使用 rejects
  await expect(asyncError()).rejects.toThrow('Async error');
  await expect(asyncError()).rejects.toThrow(Error);

  // 使用 .rejects
  await expect(Promise.reject('error')).rejects.toBe('error');
});

test('function calls', () => {
  const mockFn = jest.fn();

  mockFn('hello');
  mockFn('world');

  // 检查是否被调用
  expect(mockFn).toHaveBeenCalled();
  expect(mockFn).toHaveBeenCalledTimes(2);

  // 检查调用参数
  expect(mockFn).toHaveBeenCalledWith('hello');
  expect(mockFn).toHaveBeenLastCalledWith('world');
  expect(mockFn).toHaveBeenNthCalledWith(1, 'hello');
  expect(mockFn).toHaveBeenNthCalledWith(2, 'world');
});

test('return values', () => {
  const mockFn = jest.fn();
  mockFn.mockReturnValue(42);
  mockFn.mockReturnValueOnce(1);

  expect(mockFn()).toBe(1);  // 第一次返回 1
  expect(mockFn()).toBe(42); // 之后返回 42
});

test('promise matchers', async () => {
  // resolves
  await expect(Promise.resolve('success')).resolves.toBe('success');
  await expect(Promise.resolve({ data: 'test' })).resolves.toEqual({ data: 'test' });

  // rejects
  await expect(Promise.reject('error')).rejects.toBe('error');
  await expect(Promise.reject(new Error('fail'))).rejects.toThrow('fail');
});

test('negation', () => {
  expect(1 + 1).not.toBe(3);
  expect('hello').not.toContain('world');
  expect([1, 2, 3]).not.toContain(4);
  expect({ a: 1 }).not.toEqual({ b: 2 });
  expect(null).not.toBeUndefined();
});

test('expect.any', () => {
  // 匹配任何该类型的值
  expect('hello').toEqual(expect.any(String));
  expect(42).toEqual(expect.any(Number));
  expect(true).toEqual(expect.any(Boolean));
  expect(() => {}).toEqual(expect.any(Function));
  expect({}).toEqual(expect.any(Object));
  expect([]).toEqual(expect.any(Array));
});

test('expect.anything', () => {
  // 匹配任何非 null 和 undefined 的值
  expect('hello').toEqual(expect.anything());
  expect(42).toEqual(expect.anything());
  expect(null).not.toEqual(expect.anything());
  expect(undefined).not.toEqual(expect.anything());
});

test('constructor matching', () => {
  class MyClass {}
  const instance = new MyClass();

  expect(instance).toBeInstanceOf(MyClass);
  expect([]).toBeInstanceOf(Array);
  expect({}).toBeInstanceOf(Object);
  expect(() => {}).toBeInstanceOf(Function);
});

test('snapshot matching', () => {
  const user = {
    name: 'John',
    age: 30,
    email: 'john@example.com'
  };

  expect(user).toMatchSnapshot();
});

test('inline snapshot', () => {
  const user = { name: 'John' };
  expect(user).toMatchInlineSnapshot(`
    {
      "name": "John"
    }
  `);
});

// jest.setup.js
expect.extend({
  toBeWithinRange(received, floor, ceiling) {
    const pass = received >= floor && received <= ceiling;
    if (pass) {
      return {
        message: () => `expected ${received} not to be within range ${floor} - ${ceiling}`,
        pass: true,
      };
    } else {
      return {
        message: () => `expected ${received} to be within range ${floor} - ${ceiling}`,
        pass: false,
      };
    }
  },
});

// 使用自定义匹配器
test('custom matcher', () => {
  expect(5).toBeWithinRange(1, 10);
  expect(15).not.toBeWithinRange(1, 10);
});

test('length assertions', () => {
  // 字符串长度
  expect('hello').toHaveLength(5);

  // 数组长度
  expect([1, 2, 3]).toHaveLength(3);

  // 对象键数量
  expect(Object.keys({ a: 1, b: 2 })).toHaveLength(2);
});

// ✅ 好的做法
expect(obj).toEqual({ a: 1 });  // 对象比较
expect(arr).toContain(1);       // 数组包含
expect(str).toMatch(/hello/);   // 字符串匹配

// ❌ 不好的做法
expect(JSON.stringify(obj)).toBe(JSON.stringify({ a: 1 }));
expect(arr.indexOf(1) > -1).toBe(true);
expect(str.includes('hello')).toBe(true);

// ✅ 好的做法
expect(user).toBeDefined();
expect(items).toHaveLength(3);
expect(error).toThrow();

// ❌ 不好的做法
expect(user !== undefined).toBe(true);
expect(items.length === 3).toBe(true);
expect(() => { throw error }).toThrow();