fix(browser): explain TypeScript support in docs and add asymmetric matchers to types

[sheremet-va]

Description

This PR adds more examples on how to make TS see expect.* types and also adds missing asymmetrict matchers type definitions:

expect(elements).toEqual([
  expect.toHaveTextContent('First'),
  expect.toHaveTextContent('Second'),
])

(Asymmetric definitions only support Elements, they don't support locators yet)

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

• It's really useful if your PR references an issue where it is discussed ahead of time. If the feature is substantial or introduces breaking changes without a discussion, PR might be closed.
• Ideally, include a test that fails without this PR but passes with it.
• Please, don't make changes to pnpm-lock.yaml unless you introduce a new test example.

Tests

• Run the tests with pnpm test:ci.

Documentation

• If you introduce new functionality, document it. You can run documentation with pnpm run docs command.

Changesets

• Changes in changelog are generated from PR name. Please, make sure that it explains your changes in an understandable manner. Please, prefix changeset messages with feat:, fix:, perf:, docs:, or chore:.

[sheremet-va]

@kettanaito let me know if this is clear enough - any recommendations are also welcome 😄

I removed mentions about tsconfig because adding .types removes auto include of @types/*. This also follows how Vite recommends enabling IntelliSense, but I can add it as an alternative

[netlify]

✅ Deploy Preview for vitest-dev ready!

Name	Link
🔨 Latest commit	26ae94b
🔍 Latest deploy log	https://app.netlify.com/sites/vitest-dev/deploys/673dd46edbb9a70008bc7325
😎 Deploy Preview	https://deploy-preview-6934--vitest-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[kettanaito]

Thank you for improving the docs!

I left a few comments, please let me know what you think.

[hi-ogawa]

Asymmetric definitions only support Elements, they don't support locators yet

What's working and not working currently (and expected to work in the future)? Would this already work with expect.element like this?

await expect.element(page.getByRole('button')).toEqual(expect.toHaveTextContent('First'))

[sheremet-va]

Asymmetric definitions only support Elements, they don't support locators yet

What's working and not working currently (and expected to work in the future)? Would this already work with expect.element like this?

await expect.element(page.getByRole('button')).toEqual(expect.toHaveTextContent('First'))

Yes, expect.element passes down the locator.element() value, not the locator. We could maybe do something like expect.element.toHaveTextContent('First')

expected to work in the future

Example in the PR shouldn't work (I didn't run it) because there is no .element and we also don't unwrap locator arrays, so asymmetric matcher will receive a locator instead of an element.

[kettanaito]

@sheremet-va, despite expect returning a locator and not an element. expect.toHaveTextContent() works. I have a branch that confirms that. Is that considered a bug?

[hi-ogawa]

@kettanaito Can you show your code? It's not expected to work for locator directly and that's how I see locally too with the following code:

import { page } from '@vitest/browser/context';
import { expect, test } from 'vitest';

test('asymmetric', async () => {
  document.body.innerHTML = '<div><input value="hi" placeholder="message" /></div>'

  // OK
  await expect.element(page.getByPlaceholder('message')).toEqual(expect.toHaveValue('hi'))

  // OK
  expect(page.getByPlaceholder('message').element()).toEqual(expect.toHaveValue('hi'))

  // ERROR: received value must be an HTMLElement or an SVGElement.
  expect(page.getByPlaceholder('message')).toEqual(expect.toHaveValue('hi'))
})