Is it possible to write custom locator assertions?

[jnizet]

Is there any way (or plan) to write custom assertions for locators in browser mode.
The documentation shows how to write custom locators, and I would find it super-useful to have somthing similar for assertions.

[sheremet-va]

Is there any way (or plan) to write custom assertions for locators in browser mode. The documentation shows how to write custom locators, and I would find it super-useful to have somthing similar for assertions.

You can write regular assertions with expect.extend. If you use expect.element with the locator, then the received value will be the element and it will be automatically retried:

expect.extend({
  toBeFoo(received, expected) {
    console.log(received) // value of expect.element(here)
    console.log(expected) // value of .toBeFoo(here)
    return {
      pass: true,
      message: () => ``
    }
  }
})

[jnizet]

Thanks a lot @sheremet-va! And sorry for missing that part of the documentation.

From this, and from your PR, I understand that there is actually no way to receive the locator when using expect.element. We always receive the element of the locator, which makes it hard to write custom automatically retried assertion for a locator targeting multiple elements, am I right?

Maybe there should be an expect.elements that would automatically retry like expect.element, but which would pass the elements of the locator to the assertion. WDYT?

[sheremet-va]

We always receive the element of the locator, which makes it hard to write custom automatically retried assertion for a locator targeting multiple elements, am I right?

You can keep using expect.poll:

await expect.poll(() => locator).toHaveCustomAssertion()

Maybe there should be an expect.elements that would automatically retry like expect.element, but which would pass the elements of the locator to the assertion. WDYT?

I don't see the use case for this in Vitest, so I doubt we will add this. expect.element exists because locator.element() can throw, not because the assertion can. locator.elements() always returns something

[sheremet-va]

One thing I was planning to do is pass down a locator instead of an element. The expect.element existed initially just so we can automatically support jest-dom, but since we now provide it ourselves, we don't need to wrap it anymore.

[jnizet]

That would be great, because it would make it possible to write an assertion on a locator even if it matches several elements.

I was thinking about (potentially custom) matchers such as

• expect.elements(locator).toHaveLengthAtLeastEqualTo(3)
• expect.elements(locator).toHaveLengthAtMostEqualTo(3)
• expect.elements(locator).toAllMatch(el => expect(el).toXxx())
• expect.elements(locator).toSomeMatch(el => expect(el).toXxx())

And it would also avoid this workaround which is not quite elegant, IMHO:

    if (name === 'toHaveLength') {
      // we know that `toHaveLength` requires multiple elements,
      // but types generally expect a single one
      return elementOrLocator.elements() as unknown as HTMLElement
    }