docs: a few docs comments

docs/.vitepress/config.ts

@@ -263,6 +263,11 @@ export default ({ mode }: { mode: string }) => {
                     link: '/guide/browser/context',
                     docFooterText: 'Context | Browser Mode',
                   },
+                  {
+                    text: 'Locators',
+                    link: '/guide/browser/locators',
+                    docFooterText: 'Locators | Browser Mode',
+                  },
                   {
                     text: 'Interactivity API',
                     link: '/guide/browser/interactivity-api',

docs/guide/browser/locators.md

@@ -1,5 +1,6 @@
 ---
 title: Locators | Browser Mode
+outline: deep
 ---
 
 # Locators <Version>2.x</Version> <!-- TODO when we decide on the release -->
@@ -24,6 +25,53 @@ title: Locators | Browser Mode
 ### dropTo
 ### selectOptions
 ### screenshot
+
 ### element
+
+- **Type:** `() => Element`
+
+This method returns a single element matching the locator's selector.
+
+If _no element_ matches the selector, an error is thrown. Consider using [`.query()`](#query) when you just need to check if the element exists.
+
+If _multiple elements_ match the selector, an error is thrown. Use [`.elements()`](#elements) when you need all matching DOM Elements or [`.all()`](#all) if you need an array of locators matching the selector.
+
+::: tip
+This method can be useful if you need to pass it down to an external library. It is called automatically when locator is used with `expect.element` every time the assertion is [retried](/guide/browser/retry-ability):
+
+```ts
+await expect.element(page.getByRole('button')).toBeDisabled()
+```
+:::
+
+Consider the following DOM structure:
+
+```html
+<div>Hello <span>World</span></div>
+<div>Hello Germany</div>
+<div>Hello</div>
+```
+
+These locators will not throw an error:
+
+```ts
+page.getByText('Hello World').element() // ✅
+page.getByText('Hello Germany').element() // ✅
+page.getByText('World').element() // ✅
+page.getByText('Hello', { exact: true }).element() // ✅
+```
+
+These locators will throw an error:
+
+```ts
+// returns multiple elements
+page.getByText('Hello').element() // ❌
+page.getByText(/^Hello/).element() // ❌
+
+// returns no elements
+page.getByText('Hello USA').element() // ❌
+```
+
+### query
 ### elements
 ### all

packages/browser/context.d.ts

@@ -112,6 +112,7 @@ export interface UserEvent {
   /**
    * Types text into an element. Uses provider's API under the hood.
    * **Supports** [user-event `keyboard` syntax](https://testing-library.com/docs/user-event/keyboard) (e.g., `{Shift}`) even with `playwright` and `webdriverio` providers.
+   * This method can be significantly slower than `userEvent.fill`, so it should be used only when necessary.
    * @example
    * await userEvent.type(input, 'foo') // translates to: f, o, o
    * await userEvent.type(input, '{{a[[') // translates to: {, a, [
@@ -181,16 +182,23 @@ export interface UserEventTripleClickOptions {}
 export interface UserEventDragAndDropOptions {}
 
 export interface LocatorOptions {
+  /**
+   * Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
+   * regular expression. Note that exact match still trims whitespace.
+   */
   exact?: boolean
 }
 
-export interface LocatorByRoleOptions {
+export interface LocatorByRoleOptions extends LocatorOptions {
   checked?: boolean
   disabled?: boolean
-  exact?: boolean
   expanded?: boolean
   includeHidden?: boolean
   level?: number
+  /**
+   * Option to match the [accessible name](https://w3c.github.io/accname/#dfn-accessible-name). By default, matching is
+   * case-insensitive and searches for a substring, use `exact` to control this behavior.
+   */
   name?: string | RegExp
   pressed?: boolean
   selected?: boolean
@@ -199,39 +207,116 @@ export interface LocatorByRoleOptions {
 interface LocatorScreenshotOptions extends Omit<ScreenshotOptions, 'element'> {}
 
 export interface Locator {
-  selector: string
-
+  /**
+   * @see {@link https://vitest.dev/guide/browser/locators#getByRole}
+   */
   getByRole(role: ARIARole | ({} & string), options?: LocatorByRoleOptions): Locator
+  /**
+   * @see {@link https://vitest.dev/guide/browser/locators#getByLabelText}
+   */
   getByLabelText(text: string | RegExp, options?: LocatorOptions): Locator
-  getByTestId(text: string | RegExp): Locator
+  /**
+   * @see {@link https://vitest.dev/guide/browser/locators#getByAltText}
+   */
   getByAltText(text: string | RegExp, options?: LocatorOptions): Locator
+  /**
+   * @see {@link https://vitest.dev/guide/browser/locators#getByPlaceholder}
+   */
   getByPlaceholder(text: string | RegExp, options?: LocatorOptions): Locator
+  /**
+   * @see {@link https://vitest.dev/guide/browser/locators#getByText}
+   */
   getByText(text: string | RegExp, options?: LocatorOptions): Locator
+  /**
+   * @see {@link https://vitest.dev/guide/browser/locators#getByTitle}
+   */
   getByTitle(text: string | RegExp, options?: LocatorOptions): Locator
+  /**
+   * @see {@link https://vitest.dev/guide/browser/locators#getByTestId}
+   */
+  getByTestId(text: string | RegExp): Locator
 
-  dropTo(target: Locator, options?: UserEventDragAndDropOptions): Promise<void>
+  /**
+   * @see {@link https://vitest.dev/guide/browser/locators#click}
+   */
   click(options?: UserEventClickOptions): Promise<void>
+  /**
+   * @see {@link https://vitest.dev/guide/browser/locators#dblClick}
+   */
   dblClick(options?: UserEventDoubleClickOptions): Promise<void>
+  /**
+   * @see {@link https://vitest.dev/guide/browser/locators#tripleClick}
+   */
   tripleClick(options?: UserEventTripleClickOptions): Promise<void>
+  /**
+   * @see {@link https://vitest.dev/guide/browser/locators#clear}
+   */
   clear(): Promise<void>
+  /**
+   * @see {@link https://vitest.dev/guide/browser/locators#hover}
+   */
   hover(): Promise<void>
+  /**
+   * @see {@link https://vitest.dev/guide/browser/locators#unhover}
+   */
   unhover(): Promise<void>
+  /**
+   * @see {@link https://vitest.dev/guide/browser/locators#fill}
+   */
   fill(text: string, options?: UserEventFillOptions): Promise<void>
+  /**
+   * @see {@link https://vitest.dev/guide/browser/locators#dropTo}
+   */
+  dropTo(target: Locator, options?: UserEventDragAndDropOptions): Promise<void>
+  /**
+   * @see {@link https://vitest.dev/guide/browser/locators#selectOptions}
+   */
   selectOptions(
     values: HTMLElement | HTMLElement[] | string | string[],
     options?: UserEventSelectOptions,
   ): Promise<void>
 
-  element(): Element
-  elements(): Element[]
-  query(): Element | null
-  all(): Locator[]
-
+  /**
+   * @see {@link https://vitest.dev/guide/browser/locators#screenshot}
+   */
   screenshot(options: Omit<LocatorScreenshotOptions, 'base64'> & { base64: true }): Promise<{
     path: string
     base64: string
   }>
   screenshot(options?: LocatorScreenshotOptions): Promise<string>
+
+  /**
+   * Returns an element matching the selector.
+   *
+   * - If multiple elements match the selector, an error is thrown.
+   * - If no elements match the selector, an error is thrown.
+   *
+   * @see {@link https://vitest.dev/guide/browser/locators#element}
+   */
+  element(): Element
+  /**
+   * Returns an array of elements matching the selector.
+   *
+   * If no elements match the selector, an empty array is returned.
+   *
+   * @see {@link https://vitest.dev/guide/browser/locators#elements}
+   */
+  elements(): Element[]
+  /**
+   * Returns an element matching the selector.
+   *
+   * - If multiple elements match the selector, an error is thrown.
+   * - If no elements match the selector, returns `null`.
+   *
+   * @see {@link https://vitest.dev/guide/browser/locators#query}
+   */
+  query(): Element | null
+  /**
+   * Wraps an array of `.elements()` matching the selector in a new `Locator`.
+   *
+   * @see {@link https://vitest.dev/guide/browser/locators#all}
+   */
+  all(): Locator[]
 }
 
 export interface UserEventTabOptions {

packages/browser/src/client/tester/locators/playwright-selector/selector.ts

@@ -114,7 +114,7 @@ export class PlaywrightSelector {
     }
     const element = node as Element
 
-    const attrs = []
+    const attrs: string[] = []
     for (let i = 0; i < element.attributes.length; i++) {
       const { name, value } = element.attributes[i]
       if (name === 'style') {