noPlaywrightElementHandle (JavaScript)

Language JavaScript (and super languages)

Summary

Rule available since: v2.4.2
Diagnostic Category: lint/nursery/noPlaywrightElementHandle
This rule has an unsafe fix.
The default severity of this rule is information.
This rule belongs to the following domains:
- playwright
Sources:
- Same as playwright/no-element-handle

How to configure

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "noPlaywrightElementHandle": "error"
6
      }
7
    }
8
  }
9
}

Description

Disallow usage of element handles (page.$() and page.$$()).

Element handles are discouraged in Playwright. Use locators instead, which auto-wait and are more reliable. Locators represent a way to find elements at any moment, while element handles are references to specific elements that may become stale.

Examples

Invalid

1
const button = await page.$('button');

code-block.js:1:22 lint/nursery/noPlaywrightElementHandle  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ Unexpected use of element handles.
  
  > 1 │ const button = await page.$('button');
      │                      ^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ Locators auto-wait and are more reliable than element handles, which can become stale.
  
  ℹ Use page.locator() or getByRole() instead.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  
  ℹ Unsafe fix: Replace $() with locator().
  
    1   │ - const·button·=·await·page.$('button');
      1 │ + const·button·=·await·page.locator('button');
    2 2 │

1
const buttons = await page.$$('.btn');

code-block.js:1:23 lint/nursery/noPlaywrightElementHandle  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ Unexpected use of element handles.
  
  > 1 │ const buttons = await page.$$('.btn');
      │                       ^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ Locators auto-wait and are more reliable than element handles, which can become stale.
  
  ℹ Use page.locator() or getByRole() instead.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  
  ℹ Unsafe fix: Replace $$() with locator().
  
    1   │ - const·buttons·=·await·page.$$('.btn');
      1 │ + const·buttons·=·await·page.locator('.btn');
    2 2 │

1
const element = await frame.$('#element');

code-block.js:1:23 lint/nursery/noPlaywrightElementHandle  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ Unexpected use of element handles.
  
  > 1 │ const element = await frame.$('#element');
      │                       ^^^^^^^^^^^^^^^^^^^
    2 │ 
  
  ℹ Locators auto-wait and are more reliable than element handles, which can become stale.
  
  ℹ Use frame.locator() or getByRole() instead.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.
  
  ℹ Unsafe fix: Replace $() with locator().
  
    1   │ - const·element·=·await·frame.$('#element');
      1 │ + const·element·=·await·frame.locator('#element');
    2 2 │

Valid

1
const button = page.locator('button');
2
await button.click();

1
const buttons = page.locator('.btn');
2
await expect(buttons).toHaveCount(3);

1
await page.getByRole('button', { name: 'Submit' }).click();