feat(browser): add length property to locators, toHaveLength now accepts locators (#8512)

Author: sheremet-va

docs/guide/browser/locators.md

@@ -956,6 +956,25 @@ test('works correctly', async () => {
 ```
 :::
 
+### length
+
+This getter returns a number of elements that this locator is matching. It is equivalent to calling `locator.elements().length`.
+
+Consider the following DOM structure:
+
+```html
+<button>Click Me!</button>
+<button>Don't click me!</button>
+```
+
+This property will always succeed:
+
+```ts
+page.getByRole('button').length // ✅ 2
+page.getByRole('button', { title: 'Click Me!' }).length // ✅ 1
+page.getByRole('alert').length // ✅ 0
+```
+
 ## Custom Locators <Version>3.2.0</Version> <Badge type="danger">advanced</Badge> {#custom-locators}
 
 You can extend built-in locators API by defining an object of locator factories. These methods will exist as methods on the `page` object and any created locator.

packages/browser/context.d.ts

@@ -475,6 +475,12 @@ export interface Locator extends LocatorSelectors {
    */
   readonly selector: string
 
+  /**
+   * The number of elements that this locator is matching.
+   * @see {@link https://vitest.dev/guide/browser/locators#length}
+   */
+  readonly length: number
+
   /**
    * Click on an element. You can use the options to set the cursor position.
    * @see {@link https://vitest.dev/guide/browser/interactivity-api#userevent-click}

packages/browser/src/client/tester/expect-element.ts

@@ -1,30 +1,39 @@
 import type { Locator } from '@vitest/browser/context'
 import type { ExpectPollOptions } from 'vitest'
 import { chai, expect } from 'vitest'
+import { getType } from 'vitest/internal/browser'
 import { matchers } from './expect'
 import { processTimeoutOptions } from './utils'
 
-function element<T extends Element | null | Locator>(elementOrLocator: T, options?: ExpectPollOptions): unknown {
-  if (elementOrLocator != null && !(elementOrLocator instanceof Element) && !('element' in elementOrLocator)) {
-    throw new Error(`Invalid element or locator: ${elementOrLocator}. Expected an instance of Element or Locator, received ${typeof elementOrLocator}`)
+const kLocator = Symbol.for('$$vitest:locator')
+
+function element<T extends HTMLElement | SVGElement | null | Locator>(elementOrLocator: T, options?: ExpectPollOptions): unknown {
+  if (elementOrLocator != null && !(elementOrLocator instanceof HTMLElement) && !(elementOrLocator instanceof SVGElement) && !(kLocator in elementOrLocator)) {
+    throw new Error(`Invalid element or locator: ${elementOrLocator}. Expected an instance of HTMLElement, SVGElement or Locator, received ${getType(elementOrLocator)}`)
   }
 
-  return expect.poll<Element | null>(function element(this: object) {
+  return expect.poll<HTMLElement | SVGElement | null>(function element(this: object) {
     if (elementOrLocator instanceof Element || elementOrLocator == null) {
       return elementOrLocator
     }
     chai.util.flag(this, '_poll.element', true)
 
     const isNot = chai.util.flag(this, 'negate') as boolean
     const name = chai.util.flag(this, '_name') as string
-    // element selector uses prettyDOM under the hood, which is an expensive call
-    // that should not be called on each failed locator attempt to avoid memory leak:
-    // https://github.com/vitest-dev/vitest/issues/7139
-    const isLastPollAttempt = chai.util.flag(this, '_isLastPollAttempt')
     // special case for `toBeInTheDocument` matcher
     if (isNot && name === 'toBeInTheDocument') {
       return elementOrLocator.query()
     }
+    if (name === 'toHaveLength') {
+      // we know that `toHaveLength` requires multiple elements,
+      // but types generally expect a single one
+      return elementOrLocator.elements() as unknown as HTMLElement
+    }
+
+    // element selector uses prettyDOM under the hood, which is an expensive call
+    // that should not be called on each failed locator attempt to avoid memory leak:
+    // https://github.com/vitest-dev/vitest/issues/7139
+    const isLastPollAttempt = chai.util.flag(this, '_isLastPollAttempt')
 
     if (isLastPollAttempt) {
       return elementOrLocator.element()

packages/browser/src/client/tester/locators/index.ts

@@ -43,13 +43,24 @@ export const selectorEngine: Ivya = Ivya.create({
   testIdAttribute: server.config.browser.locators.testIdAttribute,
 })
 
+const kLocator = Symbol.for('$$vitest:locator')
+
 export abstract class Locator {
   public abstract selector: string
 
   private _parsedSelector: ParsedSelector | undefined
   protected _container?: Element | undefined
   protected _pwSelector?: string | undefined
 
+  constructor() {
+    Object.defineProperty(this, kLocator, {
+      enumerable: false,
+      writable: false,
+      configurable: false,
+      value: kLocator,
+    })
+  }
+
   public click(options: UserEventClickOptions = {}): Promise<void> {
     return this.triggerCommand<void>('__vitest_click', this.selector, options)
   }
@@ -222,6 +233,10 @@ export abstract class Locator {
     return selectorEngine.querySelectorAll(parsedSelector, document.documentElement) as (HTMLElement | SVGElement)[]
   }
 
+  public get length(): number {
+    return this.elements().length
+  }
+
   public all(): Locator[] {
     return this.elements().map(element => this.elementLocator(element))
   }

packages/vitest/src/public/browser.ts

@@ -14,6 +14,7 @@ export * as SpyModule from '@vitest/spy'
 export {
   format,
   getSafeTimers,
+  getType,
   inspect,
   stringify,
 } from '@vitest/utils'

test/browser/fixtures/expect-dom/toHaveLength.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, test } from 'vitest';
+import { render } from './utils';
+import { page } from '@vitest/browser/context';
+
+describe('.toHaveLength', () => {
+  test('accepts locator', async () => {
+    render(`
+      <button></button>
+      <button></button>
+      <button></button>
+    `)
+
+    await expect.element(page.getByRole('button')).toHaveLength(3)
+    await expect.element(page.getByRole('button')).not.toHaveLength(0)
+
+    expect(page.getByRole('button')).toHaveLength(3)
+    expect(page.getByRole('button')).not.toHaveLength(0)
+  })
+})

test/core/test/exports.test.ts

@@ -62,6 +62,7 @@ it('exports snapshot', async ({ skip, task }) => {
           "collectTests": "function",
           "format": "function",
           "getSafeTimers": "function",
+          "getType": "function",
           "inspect": "function",
           "loadDiffConfig": "function",
           "loadSnapshotSerializers": "function",
@@ -221,6 +222,7 @@ it('exports snapshot', async ({ skip, task }) => {
             "collectTests": "function",
             "format": "function",
             "getSafeTimers": "function",
+            "getType": "function",
             "inspect": "function",
             "loadDiffConfig": "function",
             "loadSnapshotSerializers": "function",