expect.extend creation of asymmetric matchers not mentioned in documentation

[tonyhallett]

🐛 Bug Report

To Reproduce

There is no mention in the documentation of the behaviour described.

Expected behavior

I expect it to be described so the functionality created can be used.
#6649

I am happy to update the documentation if required.

[kbirger]

I was going to log an issue for this, but I think this one is related... There doesn't seem to be documentation around how to create asymmetric matchers that is relevant or up to date (maybe?).

[SimenB]

Docs PRs are always most welcome 😀 Seems we've forgotten to document this one

[tonyhallett]

Ok, I will make a pull request

[tonyhallett]

@kbirger

Every custom matcher that is supplied to expect.extend is available as an asymmetric matcher, although one that returns the result asynchronously should not be used.

If you are using typescript you can do the following ( instead of using Matchers<R,T> )

const extendedMatchers = {
  asymmetricMatcherToHaveProp:(received:any,prop:string)=>{
    const pass = received[prop]!==undefined;
    return {
      pass,
      message:()=>'todo'
    }
  },
  toBoth:(first:any,second:any,asymmetricMatcher:jest.AsymmetricMatcher)=>{
    const pass = asymmetricMatcher.asymmetricMatch(first)&&asymmetricMatcher.asymmetricMatch(second);
    return {
      pass,
      message:()=>'todo'
    }
  },
  //this is not available in intellisense as an asymmetric matcher - as asymmetricMatch does not work with asynchronous result
  asyncEquals:function(this:jest.MatcherContext, received:any,actual:any){
    return new Promise<jest.CustomMatcherResult>(resolve => {
      const pass = this.equals(received,actual);
      resolve({
        pass,
        message:()=>'todo'
      })
    })
  }
}

expect.extend(extendedMatchers);

const extendedExpect:jest.ExtendedExpect<typeof extendedMatchers> = expect as any;

describe('demo', () => {
  it('should pass', () => {
    extendedExpect({compare:'this'}).toBoth({compare:'that'},extendedExpect.asymmetricMatcherToHaveProp('compare'));
  })
  it('should fail', () => {
    extendedExpect({compare:'this'}).not.toBoth({x:'that'},extendedExpect.asymmetricMatcherToHaveProp('compare'));
  })
  it('should pass with not', () => {
    extendedExpect({x:'this'}).toBoth({y:'that'},extendedExpect.not.asymmetricMatcherToHaveProp('compare'));
  })
  it('should fail with not', () => {
    extendedExpect({compare:'this'}).not.toBoth({y:'that'},extendedExpect.not.asymmetricMatcherToHaveProp('compare'));
  })


  it('should have async on expect - but do not use it !', () => {
    expect((expect as any).asyncEquals).toBeDefined();
  })
})

[github-actions]

This issue is stale because it has been open for 1 year with no activity. Remove stale label or comment or this will be closed in 14 days.

[github-actions]

This issue was closed because it has been stalled for 7 days with no activity. Please open a new issue if the issue is still relevant, linking to this one.

[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.