Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Use Playwright’s role locator with the control’s exposed ARIA role and accessible name. For a labeled text field, the usual pattern is page.getByRole('textbox', { name: 'Email address' }). Do not use getByRole('input'): input is an HTML tag name, not the ARIA role that Playwright queries.

The direct answer

Locate a text-entry control by its semantic role, then add its accessible name to identify the intended field:

const email = page.getByRole('textbox', { name: 'Email address' });
await email.fill('[email protected]');

This locator asks Playwright for the control that assistive technology exposes as a textbox named “Email address.” The name normally comes from a visible label, aria-label, or aria-labelledby. Passing a name is the recommended way to make a role locator precise when more than one control has the same role.

Why the role is not “input”

getByRole() follows W3C ARIA roles and accessible-name behavior, not literal HTML element names. An <input> element can expose several different roles depending on its type and accessibility semantics. A normal text or email input commonly exposes textbox; a search field exposes searchbox; a number spinner exposes spinbutton; and a range control exposes slider. A checkbox is queried as checkbox, not as input.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
#1 Best Overall
Sale
Philips 24 Inch Computer Monitor FHD 100Hz VA VESA Flicker-Free, 241V8LB
  • CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
  • INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
  • THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
  • WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
  • A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents

Because input is an element name rather than an ARIA role, this fails or finds nothing useful:

// Wrong: “input” is not the role of a generic text field
page.getByRole('input');

Choose the role that users and accessibility tools perceive. If the page’s markup does not expose the expected semantics, inspect and correct the markup or use a locator that matches the application’s stable contract.

Choose the role that matches the control

Control or widget Typical Playwright role Example
Free-form text, email, or multiline text entry textbox page.getByRole('textbox', { name: 'Email address' })
Search field searchbox page.getByRole('searchbox', { name: 'Search' })
Numeric spinner spinbutton page.getByRole('spinbutton', { name: 'Quantity' })
Range slider slider page.getByRole('slider', { name: 'Volume' })
Checkbox checkbox page.getByRole('checkbox', { name: 'Subscribe' })
Combo box or select-like widget combobox page.getByRole('combobox', { name: 'Country' })

The exact role depends on the accessibility tree, especially for custom widgets. A custom component styled to look like a text field is not automatically a textbox; it must expose the appropriate semantics.

Give every field a usable accessible name

The accessible name is the user-facing identifier that follows the control. Prefer a meaningful label that remains stable for users and localization. A native label is usually the clearest contract:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
<label for="email">Email address</label>
<input id="email" type="email">
const email = page.getByRole('textbox', { name: 'Email address' });

An explicit ARIA label also supplies a name:

<input type="text" aria-label="Project name">
const projectName = page.getByRole('textbox', { name: 'Project name' });

When a longer visible element labels the field, reference it with aria-labelledby:

<span id="billing-label">Billing address</span>
<input aria-labelledby="billing-label">

A placeholder is not a substitute for a durable label. If the placeholder is the application’s intentional identifier, getByPlaceholder() is a documented alternative, but a real label generally survives copy and design changes better.

Rank #2
Philips 22 Inch Computer Monitor FHD 100Hz VA VESA Flicker-Free, 221V8LB
  • CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
  • 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
  • SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
  • INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
  • THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors

Complete TypeScript example

The following Playwright Test example opens a page, fills a named text field, checks a checkbox, and verifies the resulting value. Save it as a test file in a project that has @playwright/test installed.

import { test, expect } from '@playwright/test';

test('fills the sign-up form by role', async ({ page }) => {
  await page.goto('https://example.com/signup');

  const email = page.getByRole('textbox', { name: 'Email address' });
  await email.fill('[email protected]');
  await expect(email).toHaveValue('[email protected]');

  const subscribe = page.getByRole('checkbox', { name: 'Subscribe to updates' });
  await subscribe.check();
  await expect(subscribe).toBeChecked();
});

If the page has two forms with an “Email address” field, scope the role locator to the relevant container first:

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
const billingForm = page.getByRole('form', { name: 'Billing details' });
const billingEmail = billingForm.getByRole('textbox', { name: 'Email address' });
await billingEmail.fill('[email protected]');

Scoping prevents a locator from accidentally selecting a similarly named control elsewhere on the page. The containing element must itself have the expected accessible semantics and name.

Common input patterns

Text input and textarea

Use textbox for ordinary text entry, including a multiline <textarea>, when the accessible tree exposes that role:

const message = page.getByRole('textbox', { name: 'Message' });
await message.fill('A multiline response');
await expect(message).toHaveValue('A multiline response');

The locator API’s input-oriented operations, including fill(), clear(), and inputValue(), are intended for input, textarea, or contenteditable targets (or an associated control inside a label).

Checkbox

const updates = page.getByRole('checkbox', { name: 'Subscribe' });
await updates.check();
await expect(updates).toBeChecked();

Use the checkbox’s complete accessible name rather than a nearby visual phrase that is not associated with the control.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #3
Sale
Dell 24 Monitor - SE2426H - 23.8-inch FHD (1920x1080) 144Hz 1ms Display, in-Plane Switching (IPS) Technology, AMD FreeSync™, TÜV 3-Star 2X HDMI, Tilt
  • Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
  • Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
  • Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
  • In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
  • Ultra-thin bezels: Maximize your viewing experience with thin bezels.

Search, numeric, and range controls

const search = page.getByRole('searchbox', { name: 'Search products' });
await search.fill('keyboard');

const quantity = page.getByRole('spinbutton', { name: 'Quantity' });
await quantity.fill('2');

const volume = page.getByRole('slider', { name: 'Volume' });
await volume.fill('75');

If a custom widget is announced differently, use the role it actually exposes rather than forcing one based on its visual appearance.

Comboboxes

const country = page.getByRole('combobox', { name: 'Country' });
await country.click();
await page.getByRole('option', { name: 'Canada' }).click();

This pattern assumes the widget exposes a combobox and its choices expose option semantics. A native select and a custom component can expose different trees, so verify the actual roles before writing the locator.

When a role locator is ambiguous

Ambiguity usually means multiple controls share a role and name, or the accessible name is not what the page visually suggests. Resolve it in this order:

  1. Improve the name. Use the complete visible label, including the field’s distinguishing text.
  2. Scope to a region. Start with a form, dialog, table row, or other containing locator, then call getByRole() inside it.
  3. Fix the markup. Associate labels with controls and give custom widgets the correct role and name.
  4. Use a documented fallback. Choose getByLabel(), getByPlaceholder(), or getByTestId() when that is the clearer, stable contract.

Do not make a locator unique by adding unrelated CSS classes or DOM positions unless those details are the application’s explicit test contract. Positional selectors tend to break when the form is reordered.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Role locators versus other built-in locators

Locator Use it when Example
getByRole() The control’s semantic role and accessible name are the clearest user-facing contract. getByRole('textbox', { name: 'Email address' })
getByLabel() The associated label is the most direct way to identify the form control. getByLabel('Email address')
getByPlaceholder() The placeholder is intentionally used as the field identifier and is stable. getByPlaceholder('[email protected]')
getByTestId() The application owns a stable test-id contract that is more reliable than visible copy. getByTestId('email-input')

These are alternatives, not invitations to stack every selector at once. Pick the locator that best represents the contract you want the test to protect.

Debugging failures

“No elements found”

  • Confirm that the page has reached the expected route and state.
  • Check the control’s exposed role. A search field may be searchbox, not textbox.
  • Check spelling, capitalization, and punctuation in the accessible name.
  • Verify that the label is actually associated with the input through for/id, aria-label, or aria-labelledby.
  • If the control is inside an iframe, work through the appropriate frame locator before querying its role.

“Strict mode” or multiple matches

The role and name identify more than one element. Scope to the correct form or dialog, or make the accessible names distinct. Avoid selecting the first match merely to silence the error; that can hide a real accessibility and test-quality problem.

Rank #4
Samsung 27" Essential S3 (S36GD) Series FHD 1800R Curved Computer Monitor
  • CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
  • SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
  • MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
  • KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
  • INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient

The visible label does not match the name

Accessible names can include text contributed by multiple labeling nodes, so the computed name may differ from a single visual fragment. Inspect the page’s accessibility tree with your browser’s accessibility tools, then use the name that assistive technology receives. If the computed name is unintentionally verbose or missing, correct the markup instead of encoding the defect in a brittle selector.

A custom field is not exposed as a textbox

Visual styling does not create ARIA semantics. A custom widget must expose the appropriate role and an accessible name. If you cannot change the component immediately, use the application’s documented stable locator, such as a test id, while treating the missing semantics as a separate accessibility issue.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Keeping role locators maintainable

  • Prefer user-facing names. “Email address” communicates intent better than a generated class name.
  • Keep names stable across translations. If tests run in multiple locales, use localized accessible names or a stable test-id strategy deliberately; do not assume English text exists everywhere.
  • Use the narrowest meaningful scope. A form or dialog scope documents which part of the page the test exercises.
  • Assert the result. After filling or checking a control, verify its value or state so a passing action cannot conceal a wrong target.
  • Review custom widgets. A role locator is only as reliable as the accessibility semantics the application exposes.

Role-based tests therefore do double duty: they exercise the control a user perceives and make missing or incorrect accessibility semantics visible during test development.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Or skip the browser setup

If your goal is to capture the resulting page rather than interact with its controls, ScreenshotNeo provides a one-request website screenshot API. It can accept a cookie or consent banner like a visitor, remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture, and return PNG, JPEG, WebP, or PDF output. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed as clean shots; the response identifies the page verdict and billing status in X-Page-Verdict and X-Billed headers.

See the ScreenshotNeo API documentation for request options. A basic cURL capture is:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp

The same request in Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

And in Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const data = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', data);

For automated capture, ScreenshotNeo also supports full-page shots with lazy images loaded, CSS-selector element capture, dark mode, device presets and custom viewports, retina scale, PDF paper and page-range settings, custom CSS and JavaScript, pre-capture clicks, selector or network-idle waits, request and resource blocking, headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, an OpenAPI specification, and an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

There is a free allowance of 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; yearly billing gives two months free. Create a free ScreenshotNeo account to try it.

Best Value
Sale
Sceptre New 22-Inch Gaming Monitor, FHD 1080p, Up to 144Hz, HDMI, DisplayPort, Built-in Speakers, Machine Black (E225W-FW144 Series, 2026)
  • 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
  • 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
  • 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.

FAQ

Can I use getByRole() with an HTML tag name?

No. Pass an ARIA role such as textbox, checkbox, or combobox. The HTML tag and the exposed accessibility role are different concepts.

What should I do when a control has no accessible name?

First add or fix its label, aria-label, or aria-labelledby. If changing the page is not possible, use a documented fallback such as a stable test id rather than guessing a role name.

Is a placeholder a reliable replacement for a label?

Only when the application intentionally treats that placeholder as its stable identifier. A persistent label is usually a better accessibility and testing contract.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Frequently Asked Questions

Can I use getByRole() with an HTML tag name?

No. Use the exposed ARIA role, such as textbox, checkbox, or combobox; input is an HTML element name.

What should I do when a control has no accessible name?

Fix its label, aria-label, or aria-labelledby when possible. Otherwise use a documented stable fallback such as a test id.

Is a placeholder a reliable replacement for a label?

Only if the application deliberately treats it as a stable identifier. A persistent label is generally more durable.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.