feat: Implement Locator.nth()

docs/guide/browser/locators.md

@@ -709,6 +709,17 @@ Internally, this method calls `.elements` and wraps every element using [`page.e
 
 - [See `locator.elements()`](#elements)
 
+### nth
+
+```ts
+function nth(index: number): Locator
+```
+
+This method returns a new locator that matches only a specific element within a multi-element locator.
+
+Internally, this method calls `.elements`, verifies that the element exists, and wraps it using [`page.elementLocator`](/guide/browser/context#page). It's useful because it will throw a descriptive error
+instead of returning `undefined` and allowing chained methods or matchers to fail mysteriously.
+
 ## Properties
 
 ### selector

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

@@ -185,6 +185,15 @@ export abstract class Locator {
     return this.elements().map(element => this.elementLocator(element))
   }
 
+  public nth(index: number): Locator {
+    const element = this.elements()[index]
+    if (!element) {
+      // TODO: better error message (misleading -- we _did_ find elements, just not enough of them)
+      throw getElementError(this._pwSelector || this.selector, this._container || document.body)
+    }
+    return this.elementLocator(element)
+  }
+
   public toString(): string {
     return this.selector
   }

test/browser/fixtures/locators/blog.test.tsx

@@ -16,6 +16,16 @@ test('renders blog posts', async () => {
   expect(firstPost.element()).toHaveTextContent(/molestiae ut ut quas/)
   expect(firstPost.getByRole('heading').element()).toHaveTextContent(/occaecati excepturi/)
 
+  expect(screen.getByRole('listitem').nth(0).element()).toHaveTextContent(/molestiae ut ut quas/)
+  var thrown
+  try {
+    screen.getByRole('listitem').nth(666)
+  } catch(err) {
+    thrown = err
+  }
+  expect(thrown).toBeInstanceOf(Error);
+  expect(thrown.message).toMatch(/^Cannot find element/)
+
   await expect.element(secondPost.getByRole('heading')).toHaveTextContent('qui est esse')
 
   await userEvent.click(secondPost.getByRole('button', { name: 'Delete' }))