What does getByPlaceholder do in Playwright?

page.getByPlaceholder('text') finds an input by the hint text in its placeholder attribute. Playwright suggests it for form fields that have no label but do have a placeholder.

This answer is one piece of Chapter 9: Locators I: What the User Sees.

getByRole and the Accessible Name
getByText, getByLabel, getByPlaceholder, getByTestId
Strict Mode — One Locator, One Element

A placeholder is the grey hint inside an empty field, such as 10 digits. It disappears from the screen once the user types, but it stays in the placeholder attribute, so the locator keeps working after you fill the field.

It is a fallback rather than a first choice. A label is the stable name of a field. A placeholder is an example, and teams change examples freely. When a field has a working label, use getByLabel().

The phone field on the fulfilment form is the case placeholders are for. Its <label for> points at an id that does not exist, on purpose, so the label is not associated with the input. getByLabel('Phone number') matches zero elements, which the test proves with toHaveCount(0).

The field still has placeholder="10 digits", so getByPlaceholder('10 digits') finds it. The test fills a number and checks it with toHaveValue().

The match is a case-insensitive substring unless you pass { exact: true }, and you can pass a regular expression instead of a string.

qa-044.spec.js(https://practice.learnplayforge.com)

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

test('getByPlaceholder finds the phone field its broken label cannot', async ({ page }) => {
  await page.goto('/fulfilment.html?mock=static&seed=42&autologin=1');

  // The label's for= points at an id that does not exist
  await expect(page.getByLabel('Phone number')).toHaveCount(0);

  const phone = page.getByPlaceholder('10 digits');
  await phone.fill('9876543210');
  await expect(phone).toHaveValue('9876543210');
});

Output

1 passed (1.6s)

Test yourself

When does the locator guide suggest reaching for getByPlaceholder()?

Practised in the full course: the drill The label that points nowhere.

See the chapter

AI can write the test now. The job is knowing whether it checks anything. That's what the course teaches, one chapter at a time.

163 lessons · 226 drills · start free

What does getByPlaceholder do in Playwright?

Related questions