[Feature] Add support for custom equality testers #13654

andrewiggins · 2022-12-01T21:27:25Z

packages/expect/src/types.ts

packages/expect/src/__tests__/customEqualityTesters.test.ts

michkot · 2022-12-02T17:51:26Z

packages/expect/src/types.ts

packages/expect-utils/src/types.ts

michkot · 2022-12-02T18:01:37Z

packages/expect-utils/src/utils.ts

+    iterableEquality(a, b, [...customTesters], [...aStack], [...bStack]);
+
+  customTesters = [
+    ...customTesters.filter(t => t !== iterableEquality),


why the check? deserver's a code comment i think

is it to prevent infinite recursion in case somebody would manage to add the build-in iterableEquality (somehow imported it directly) into the customTesters array in configuration?

Yup - except here all testers are passed in the full array of custom testers, including themselves. So currently it is guaranteed you'll be called with yourself in the custom testers array.

I could also do the filtering in the custom testers loop in equals so a tester is never called for itself, but I wasn't sure that was worth since not every tester would need this since not every tester is recursive, but maybe it would make the API easier to work with.

Ye, not sure about the additional filtering...

packages/expect-utils/src/utils.ts

michkot · 2022-12-02T18:09:06Z

packages/expect/src/__tests__/customEqualityTesters.test.ts

+    const result = this.equals(
+      expected,
+      actual,
+      jestExpect.customEqualityTesters,


not sure whether ... having to / having the option to... specify override of the customEqualityTesters here is a good thing

The idea here is to enable custom matchers to have the same capabilities as the built in matchers. Built-in matchers need to pass in custom equality testers to equals and so I would like custom matchers to have ability to do the same.

We could look overriding the equals implementation on MatcherContext to automatically pass in custom testers, but then a matcher couldn't customize the testers, which it might want to do. So my thinking was to just require custom matchers to do what the built-in matchers and pass in custom equality testers.

If we change the expect API to something like expect.addEqualityTesters, it would be nice to provide some API for custom matchers to access the added testers. Perhaps as a property on MatcherContext?

So my thinking was to just require custom matchers to do what the built-in matchers and pass in custom equality testers.

Okey, I understand the approach = custom matchers must opt-in to global custom eq. testers being used. I also think its the "safes one", however...

The gotcha is that anyone having custom matchers (especially imported ones) that are not aware of "this PR" might not be passing the testers, while their user (which set-up some custom eq. testers using this PR) would like these extra matchers to respect the custom testers... That leads me to an idea, that maybe the global custom eq testers should be used with custom matchers by default, and they would have to opt-out / override to use different set of them (e.g. empty set).

michkot · 2022-12-02T18:18:03Z

andrewiggins · 2022-12-02T23:28:02Z

michkot · 2022-12-15T13:43:21Z

andrewiggins · 2022-12-16T06:12:51Z

cpojer · 2023-01-02T01:02:04Z

andrewiggins

packages/expect-utils/src/types.ts

packages/expect/__typetests__/expect.test.ts

SimenB · 2023-01-02T14:23:32Z

docs/ExpectAPI.md

+For example, let's say you have a `Book` class that contains an array of `Author` classes and both of these classes have custom testers. The `Book` custom tester would want to do a deep equality check on the array of `Author`s and pass in the custom testers so the `Author`s custom equality tester is applied:
+
+```js title="customEqualityTesters.js"
+import {equals} from '@jest/expect-utils';


can we ask people to use this.equals instead of importing it?

I'd be happy to, but currently customTesters are called without any this context (source from this PR). Custom testers are invoked by equals in the expect-utils package and so don't have access to the matcher context.

One idea to avoid importing encouraging importing equals would be to create an EqualityTesterContext with equals and invoke equality testers with that, similar to what we do for matchers and MatchContext. Should I do that?

right, that makes sense! Yeah, I think we should have a context with at least equals (maybe only that for now?). That way, if people publish custom equality testers, they don't need to care what version of Jest people are using (beyond 29.4+) when we release 30, 31 etc..

Oh nice! Yea, that makes sense. I believe the latest changes I've pushed do this. Let me know if you see anything else missing!

I've also re-exported the Tester and TesterContext types from the expect package. My thinking was that since those types are implicitly exposed through expect.addEqualityTester, explicitly exporting them would make using TypeScript a little easier and better mirror what people can do with expect.extend with the MatcherFunction and MatcherContext types. However, if you'd prefer people import Tester and TesterContext directly from @jest/expect-utils, we can simply revert that commit.

sounds good 👍

SimenB

andrewiggins

andrewiggins · 2023-01-03T06:57:17Z

docs/ExpectAPI.md

+For example, let's say you have a `Book` class that contains an array of `Author` classes and both of these classes have custom testers. The `Book` custom tester would want to do a deep equality check on the array of `Author`s and pass in the custom testers so the `Author`s custom equality tester is applied:
+
+```js title="customEqualityTesters.js"
+import {equals} from '@jest/expect-utils';


I'd be happy to, but currently customTesters are called without any this context (source from this PR). Custom testers are invoked by equals in the expect-utils package and so don't have access to the matcher context.

One idea to avoid importing encouraging importing equals would be to create an EqualityTesterContext with equals and invoke equality testers with that, similar to what we do for matchers and MatchContext. Should I do that?

mrazauskas · 2023-01-03T09:03:19Z

packages/expect/__typetests__/expect.test.ts

+  Tester,
+  TesterContext,
  expect,
 } from 'expect';


This re-export looks right. Thanks!

SimenB · 2023-01-03T09:25:32Z

SimenB · 2023-01-24T10:57:48Z

github-actions · 2023-02-24T00:09:03Z

andrewiggins added 13 commits December 1, 2022 12:52

Add customEqualityTesters support to toEqual

63d7186

Add support for custom testers in iterableEquality

8f1daca

Add customTester support to toContainEqual and toHaveProperty

45243cd

Add customTester support toStrictEqual

cb73a20

Add customTester support to toMatchObject

ce6aca4

8000 Add customTesters to asymmetric matchers

b5684ce

Add customTesters to spy matchers

2fa1336

Add test for custom matcher

e414bcc

Clean up new tests a bit

944934f

Add support for customTesters to matcher recommendations in errors

8a8bc17

Give custom testers higher priority over built-in testers

1ee862f

Add custom testers to getObjectSubset

3961c37

Add CHANGELOG entry

7bdcded

facebook-github-bot added the cla signed label Dec 1, 2022

andrewiggins mentioned this pull request Dec 1, 2022

[Feature]: Allow extending functionality of toEqual #12880

Closed

Fix customEqualityTesters TS errors

144f351

mrazauskas reviewed Dec 2, 2022

View reviewed changes

packages/expect/src/types.ts Outdated Show resolved Hide resolved

packages/expect/src/__tests__/customEqualityTesters.test.ts Outdated Show resolved Hide resolved

mrazauskas reviewed Dec 2, 2022

View reviewed changes

packages/expect/src/__tests__/customEqualityTesters.test.ts Outdated Show resolved Hide resolved

Update packages/expect/src/__tests__/customEqualityTesters.test.ts

1c9b629

Co-authored-by: Tom Mrazauskas <tom@mrazauskas.de>

andrewiggins force-pushed the custom-tester-extensions branch from 466265c to 1c9b629 Compare December 2, 2022 12:02

michkot reviewed Dec 2, 2022

View reviewed changes

andrewiggins added 4 commits December 15, 2022 21:26

Change API to addEqualityTesters

9998279

Get customTesters from matcherContext

9fcf9b5

Rename customTesters to filteredCustomTesters

a791dcb

Add type tests for new API

32d0e38

andrewiggins added 4 commits January 1, 2023 17:18

Add docs, pt. 1

c9dc27c

Reorganize code to obsolete eslint ignore

d22295b

Convert custom equal testers tests to use Volume object matching docs

8591181

Finish out ExpectAPI docs and add recursive equality tester test

e88fff2

andrewiggins commented Jan 2, 2023

View reviewed changes

packages/expect-utils/src/types.ts Show resolved Hide resolved

mrazauskas reviewed Jan 2, 2023

View reviewed changes

packages/expect/__typetests__/expect.test.ts Outdated Show resolved Hide resolved

packages/expect/__typetests__/expect.test.ts Outdated Show resolved Hide resolved

SimenB added 2 commits January 2, 2023 15:17

reorganize

bed9a1e

link in changelog

15e509c

SimenB reviewed Jan 2, 2023

View reviewed changes

link section

96de10d

SimenB approved these changes Jan 2, 2023

View reviewed changes

andrewiggins commented Jan 3, 2023

View reviewed changes

andrewiggins added 2 commits January 3, 2023 00:45

Expose equals function on tester context

dea4949

Re-export Tester and TesterContext in expect package

90afadb

mrazauskas reviewed Jan 3, 2023

View reviewed changes

SimenB linked an issue Jan 3, 2023 that may be closed by this pull request

[Feature]: Allow extending functionality of toEqual #12880

Closed

SimenB merged commit 4fd1cb3 into jestjs:main Jan 3, 2023

andrewiggins deleted the custom-tester-extensions branch January 3, 2023 14:17

stephenh mentioned this pull request Jan 3, 2023

Investigate Jest's new custom equality matchers joist-orm/joist-orm#491

Open

ms-bot mentioned this pull request Feb 6, 2023

chore(deps): bump 🧳 jest to ^29.7.0 mobsuccess-devops/github-actions-asana#47

Closed

DannyNemer mentioned this pull request Feb 9, 2023

docs: Fix typos in documentation for custom equality testers #13878

Merged

justin-tay mentioned this pull request Feb 13, 2023

TypeError: this.customTesters is not iterable in expect.jsonContaining in jest 29.4.0 debugmaster/jest-json-matchers#9

Closed

ms-bot mentioned this pull request Feb 20, 2023

chore(deps): bump 🧳 jest to ^29.7.0 mobsuccess-devops/github-actions-review#40

Closed

github-actions bot locked as resolved and limited conversation to collaborators Feb 24, 2023

Uh oh!

[Feature] Add support for custom equality testers #13654

[Feature] Add support for custom equality testers #13654

Uh oh!

Conversation

Uh oh!

Summary

Test plan

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!