feat: Implement Locator.nth()

docs/guide/browser/locators.md

@@ -709,6 +709,18 @@ Internally, this method calls `.elements` and wraps every element using [`page.e
 
 - [See `locator.elements()`](#elements)
 
+### nth, first, last
+
+```ts
+function nth(index: number): Locator
+function first(): Locator
+function last(): Locator
+```
+
+These methods return a new locator that matches only a specific element within a multi-element query.
+
+It is similar to calling `.elements()[n]` but more readable, with better failure messages, and can be retried more easily with `expect.element`.
+
 ## Properties
 
 ### selector

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

@@ -185,6 +185,18 @@ export abstract class Locator {
     return this.elements().map(element => this.elementLocator(element))
   }
 
+  public nth(index: number): Locator {
+    return this.locator(`nth=${index}`)
+  }
+
+  public first(): Locator {
+    return this.nth(0)
+  }
+
+  public last(): Locator {
+    return this.nth(-1)
+  }
+
   public toString(): string {
     return this.selector
   }

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

@@ -22,5 +22,10 @@ test('renders blog posts', async () => {
 
   expect(screen.getByRole('listitem').all()).toHaveLength(3)
 
+  expect(screen.getByRole('listitem').nth(0).element()).toHaveTextContent(/molestiae ut ut quas/)
+  await expect.element(screen.getByRole('listitem').nth(666)).not.toBeInTheDocument()
+  expect(screen.getByRole('listitem').first().element()).toHaveTextContent(/molestiae ut ut quas/)
+  expect(screen.getByRole('listitem').last().element()).toHaveTextContent(/eum et est/)
+
   expect(screen.getByPlaceholder('non-existing').query()).not.toBeInTheDocument()
 })