PlaywrightPHP

Check a checkbox or radio

Toggle checkboxes and radios by their label, then assert the checked state instead of the click.

Checkboxes and radios are label-first in Playwright PHP. You find the control the way a user reads it, by its label or role, then call check() or uncheck() on the returned locator. Both actions target the real input, not its label.

Check and uncheck by label

check() waits until the control is actionable, then checks it. It is idempotent: a control that is already checked stays checked, so you never toggle by accident. Use uncheck() to clear one.

php
$page->goto('https://app.example.test/settings');

$page->getByLabel('Subscribe to the newsletter')->check();
$page->getByLabel('Send me weekly digests')->uncheck();

Both methods verify the element is a checkbox or radio and that the state changed. A control that stays unchecked after check() fails the action instead of passing silently.

Choose a radio by role and name

Radios share a group, so pick the one you want by its accessible name. Checking a radio clears the others in its group.

php
$page->getByRole('radio', ['name' => 'Annual billing'])->check();

Role options go in an array. There are no named arguments here.

Assert the checked state

Assert the state the control ended in, not that the click happened. toBeChecked() polls until the box reports checked, so you do not need a fixed wait.

php
expect($page->getByLabel('Subscribe to the newsletter'))->toBeChecked();
expect($page->getByLabel('Send me weekly digests'))->not()->toBeChecked();

Pitfalls

  • Do not click the <label> to toggle the box. A label click depends on the label wrapping or pointing at the input; when it does not, nothing changes and the test still passes the click. check() acts on the input and verifies the result.
  • A label that matches two controls makes getByLabel() fail on purpose. Locators are strict: narrow the text or scope with a container locator.
  • check() is not the same as click(). click() toggles blindly; check() asserts the final state is checked.

Expected result

The checkbox or radio ends in the state you requested, and the assertion proves that final state. If the form saves later, also assert the visible confirmation or persisted setting.

Go next

← All recipes