Allow extending toEqual

[shun-shobon]

Clear and concise description of the problem

I would like to make toEqual extensible so that I can easily compare objects that contain custom classes. This is a feature that is also included in Jest and would be very useful if added.

class Volume {
  constructor(public amount: number, public unit: "L" | "mL") {}

  equals(other: Volume): boolean {
    if (this.unit === other.unit) {
      return this.amount === other.amount;
    } else if (this.unit === "L" && other.unit === "mL") {
      return this.amount * 1000 === other.amount;
    } else {
      return this.amount === other.amount * 1000;
    }
  }
}

it("Object Assertion", () => {
  const obj1 = { volume: new Volume(1, "L") };
  const obj2 = { volume: new Volume(1000, "mL") };

  // Expect to succeed, but we actually fail
  expect(obj1).toEqual(obj2);
  // This is a bit redundant
  assert(obj1.volume.equals(obj2));
});

Suggested solution

Like Jest, it provides an API that allows toEqual to be extended. It is not necessary to make everything the same as Jest, but a similar API format would be easier to use.

function areVolumesEqual(a: unknown, b: unknown): boolean | undefined {
  const isAVolume = a instanceof Volume;
  const isBVolume = b instanceof Volume;

  if (isAVolume && isBVolume) {
    return a.equals(b);
  } else if (isAVolume !== isBVolume) {
    return false;
  } else {
    return undefined;
  }
}

expect.addEqualityTesters([areVolumesEqual]);

Alternative

It is still possible to compare classes using assert, but the test becomes redundant if the class is contained in an object or if there are a large number of classes in the object.

Additional context

No response

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[samkevin1]

Hey! Can I work on this one?

[sheremet-va]

Hey! Can I work on this one?

Sure