[Feature]: Expose equals from expect package.

[chyzwar]

🚀 Feature Proposal

Slightly popular package jest-when(https://www.npmjs.com/package/jest-when) that depend on "expect" use portion of private api require('expect/build/jasmineUtils') I just raised PR to use jest as peer timkindberg/jest-when#84

We would like to ask jest to expose "equals" from jasmineUtils or provide suitable API to get current equals matcher.

Motivation

1. I am worried that can break with ESM enforcing exports fields
2. jest-when use private api it is withing jest project rights to break it on minor releases.
3. Hopefully jest project consider adding jest-when functionality to core as it is useful and good API

Example

No response

Pitch

See above motivation. Either expose equals or provide jest-when compatible functionality in core.

[SimenB]

this.equals is injected into every custom matcher: https://jestjs.io/docs/expect#thisequalsa-b

So there's no need to import it or have a dependency

[SimenB]

Hmm, I guess this isn't a custom matcher, but used within the mock function itself? That's a bit more tricky. Essentially same as #11816

[timkindberg]

I know it's a hack but could I make a custom matcher and manually trigger it in order to get access to the this.equals reference and then save the reference for my own use? Total hack I know but it would give me the correct equals reference for now until this is figured out. Maybe somehting like this:

let equals = () => {}
expect.extend({
  __capture_equals__ () {
    equals = this.equals
    return { pass: true }
  }
})
expect().__capture_equals__()

// Now I can use equals
equals(a, b)

Update: It seems to kind of work. All jest-when tests except 2 are passing.

[SimenB]

That should work, yeah.

I'll try to get a proper fix for this in Jest 28

[timkindberg]

https://github.com/timkindberg/jest-when/releases/tag/v3.4.1

[ErisDS]

I would like to second the request to expose equals from expect, but for an entirely different reason, that might lead to a slightly different solution.

I'm using jest-snapshot outside of jest, as per https://medium.com/blogfoster-engineering/how-to-use-the-power-of-jests-snapshot-testing-without-using-jest-eff3239154e5.

The modularity of jest is allowing me to migrate a large mocha-based test suite to using snapshots, with a view to migrating to full jest sometime later. Incremental rewrites = super cool 😎 .

However, the method outlined in the blog post (and all of the existing tools I can find around like expect-mocha-snapshot or chai-jest-snapshot) all don't support property matching, so you can't use things like expect.any(String) to map out parts of a snapshot that change intentionally.

I was looking into how to add this functionality, and it seems fairly straight forward. I need to add utils and equals to the .bind() object, and then it works, except there's no "proper" way to get access to equals.

const {SnapshotState, toMatchSnapshot} = require('jest-snapshot');
const utils = require('expect/build/utils');
const equals = ???!;

function myToMatchSnapshot(received, properties) {
  // I do some stuff to generate filenames etc...
  const {fileName, snapshotName, willUpdate} = myGetConfigFn();

  const snapshotState = new SnapshotState(fileName, {
    updateSnapshot: willUpdate
  });
  
  const matcher = toMatchSnapshot.bind({
      snapshotState,
      currentTestName: snapshotName,
      utils,
      equals
  });

  const result = matcher(received, properties);
}

Right now, I'm using the hack suggested in this thread and it works... it really works!!! But it's so ugly it makes me feel a bit dirty.

Can we please have equals exposed? Pretty please?

I'm happy to raise a PR but not sure what's preferable - adding jasmineUtils to the exports in package.json, or exporting equals from expect?

Thanks for listening, and for making jest so modular ❤️

[SimenB]

Hi @ErisDS, and thanks for the detailed use case! I'll be adding a separate @jest/expect-utils in Jest 28 🙂 It'll suddenly be available. jest-snapshot itself also uses "private" stuff from expect

[SimenB]

https://github.com/facebook/jest/releases/tag/v28.0.0-alpha.0

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.