feat: Add .toAppearBefore/.toAppearAfter matcher

[nossbigg]

What:

• Add .toAppearBefore()/.toAppearAfter() matchers

Why:

• As per Add .toAppearBefore(...) assertion #459

How:

• Uses compareDocumentPosition()

Checklist:

• Documentation
• Tests
• Updated Type Definitions
• Ready to be merged
  

[gnapse]

Looking good. Thanks!

There's one main comment below in this review that I'd like to see addressed before we merge it. The one about what happens if the elements are parent/ancestor to each other.

[gnapse]

What is the expected behavior if the two elements are parent/ancestor? That is:

    <div>
      <div data-testid='div-a'>
        <span data-testid='text-a'>
            Text A
            <span data-testid='text-b'>Text B</span>
        </span>
      </div>
    </div>

Whatever is it (I hope it is a logical behavior), can we document that behavior? And also add it to the tests?

[nossbigg]

@gnapse given:

• A is parent span
• B is nested span

Then

• expect(a).toAppearBefore(b), it will return Received: Unknown document position (20)
• expect(b).toAppearBefore(a), it will return Received: Unknown document position (10)

Note: Unknown document position is a default fill when we can't find a corresponding string representation (ref) for the returned compareDocumentPosition() value.

I've covered the parent/child scenarios here ✅

jest-dom/src/__tests__/to-appear-before.js

Lines 31 to 41 in efba541

	it('errors out when first element is parent of second element', () => {
	expect(() => expect(divA).toAppearBefore(textA)).toThrowError(
	/Received: Unknown document position \(20\)/i,
	)
	})
	it('errors out when first element is child of second element', () => {
	expect(() => expect(textA).toAppearBefore(divA)).toThrowError(
	/Received: Unknown document position \(10\)/i,
	)
	})

I think there's three ways that we can go with this:

• Treat parent as "before": this will avail the .toAppearBefore() matcher to use cases where devs are trying to test against parent/child relationships, but otherwise makes the matcher more lax.
• Do not treat parent as "before": This constrains the .toAppearBefore() matcher to strictly only sibling use cases, which is more exacting, but leaves devs out in the cold when it comes to testing parent/child relationships (ie. they'll have to write their own test helper for it)
• Add additional param to allow user to set if parent should be treated as "before": This gives users the flexibility to opt-in (or opt-out, depending on what makes for best defaults) the aforementioned behavior in Point 1.

Thoughts?

[gnapse]

I'm leaning towards thinking that the behavior I'd expect is that neither element is before or after the other. So both assertions would fail.

[nossbigg]

Ah ok - the current implementation does error out on parent/child relationships. Shall I outline this behavior in the docs?

[gnapse]

If it errors out in both cases, that's ok.

[gnapse]

@all-contributors please add @nossbigg for code, test

[allcontributors]

@gnapse

I've put up a pull request to add @nossbigg! 🎉

[gnapse]

CI is failing all around now and I have no time to look into it. Will look into it later this week.