feat: checkable menu items and pressed-state toggle buttons

`checkOption` now reaches `role=menuitemcheckbox` and `role=menuitemradio`,
and pressed-state buttons get their own pair of actions.

Menu items are added to the ARIA role pass of all three helpers. Playwright's
`check()` clicks such an item but then waits for the state on a node the menu
may already have removed (Radix closes its menu on select, Base UI does not),
so those two roles take a click-plus-verify path instead: read `aria-checked`,
click only on a mismatch so a second `checkOption` cannot toggle the item back
off, then wait for the new state and treat a vanished element as applied.
Puppeteer and WebDriver already read `aria-checked` and already click only on
a mismatch, so only their role lists changed; WebDriver's
`seeCheckboxIsChecked` went through `findFields`, which no menu item can
satisfy, and now falls back to `findCheckable`.

`aria-pressed` is a different semantic from checked-ness, so Toggle and Toggle
Group (multiple) get `toggleButton`, `seeButtonIsPressed` and
`dontSeeButtonIsPressed` rather than an overloaded `checkOption`.
`seeCheckboxIsChecked` on such a button now names the right action instead of
surfacing Playwright's "Not a checkbox or radio button".

`grabCheckedElementStatus` reads `aria-checked` and `aria-pressed` instead of
requiring `type=checkbox|radio`, and names what it found when it still cannot
answer.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TcwzSXPnfaig8nBZD2Vxfi

Author: DavertMik

docs/webapi/dontSeeButtonIsPressed.mustache

@@ -0,0 +1,9 @@
+Verifies that a toggle button is not pressed, by reading its `aria-pressed` attribute.
+
+```js
+I.dontSeeButtonIsPressed('Bold');
+I.dontSeeButtonIsPressed('#bold');
+```
+
+@param {CodeceptJS.LocatorOrString} locator button located by text|CSS|XPath|strict locator.
+@returns {void} automatically synchronized promise through #recorder

docs/webapi/seeButtonIsPressed.mustache

@@ -0,0 +1,9 @@
+Verifies that a toggle button is pressed, by reading its `aria-pressed` attribute.
+
+```js
+I.seeButtonIsPressed('Bold');
+I.seeButtonIsPressed('#bold');
+```
+
+@param {CodeceptJS.LocatorOrString} locator button located by text|CSS|XPath|strict locator.
+@returns {void} automatically synchronized promise through #recorder

docs/webapi/toggleButton.mustache

@@ -0,0 +1,13 @@
+Toggles a button that reports its state with `aria-pressed`, like a Toggle or a Toggle Group item.
+
+Such a button is not a checkbox, so `checkOption` does not apply to it: this action flips it and
+waits until `aria-pressed` has changed.
+
+```js
+I.toggleButton('Bold');
+I.toggleButton('#bold');
+I.toggleButton({ css: '[aria-label=Bold]' });
+```
+
+@param {CodeceptJS.LocatorOrString} locator button located by text|CSS|XPath|strict locator.
+@returns {void} automatically synchronized promise through #recorder

lib/helper/Playwright.js

@@ -50,7 +50,8 @@ let defaultSelectorEnginesInitialized = false
 const popupStore = new Popup()
 const consoleLogStore = new Console()
 const availableBrowsers = ['chromium', 'webkit', 'firefox', 'electron']
-const checkableRoles = ['checkbox', 'radio', 'switch']
+const ariaCheckableRoles = ['menuitemcheckbox', 'menuitemradio']
+const checkableRoles = ['checkbox', 'radio', 'switch', ...ariaCheckableRoles]
 
 import { setRestartStrategy, restartsSession, restartsContext, restartsBrowser } from './extras/PlaywrightRestartOpts.js'
 import { createValueEngine, createDisabledEngine } from './extras/PlaywrightPropEngine.js'
@@ -1564,7 +1565,14 @@ class Playwright extends Helper {
     if (supportedTypes.includes(type)) {
       return el.isChecked(options)
     }
-    throw new Error(`Element is not a ${supportedTypes.join(' or ')} input`)
+
+    for (const attribute of ['aria-checked', 'aria-pressed']) {
+      const state = await el.getAttribute(attribute)
+      if (state !== null) return state === 'true'
+    }
+
+    const role = await el.getAttribute('role')
+    throw new Error(`Element is not a ${supportedTypes.join(' or ')} input and has no aria-checked or aria-pressed state (role: ${role || 'none'})`)
   }
   /**
    * Return the disabled status of given element.
@@ -2163,7 +2171,7 @@ class Playwright extends Helper {
    */
   async checkOption(field, context = null, options = { force: true }) {
     const elm = await this._locateCheckable(field, context)
-    await elm.check(options)
+    await setCheckableState.call(this, elm, true, field, options)
     return this._waitForAction()
   }
 
@@ -2183,7 +2191,7 @@ class Playwright extends Helper {
    */
   async uncheckOption(field, context = null, options = { force: true }) {
     const elm = await this._locateCheckable(field, context)
-    await elm.uncheck(options)
+    await setCheckableState.call(this, elm, false, field, options)
     return this._waitForAction()
   }
 
@@ -2201,6 +2209,39 @@ class Playwright extends Helper {
     return proceedIsChecked.call(this, 'negate', field)
   }
 
+  /**
+   * {{> toggleButton }}
+   */
+  async toggleButton(locator, options = {}) {
+    const els = await this._locateClickable(locator)
+    assertElementExists(els, locator, 'Toggle button')
+    const el = selectElement(els, locator, this)
+    const pressed = await el.getAttribute('aria-pressed')
+    if (pressed === null) {
+      throw new Error(`Element ${new Locator(locator)} is not a toggle button, it has no aria-pressed attribute`)
+    }
+
+    await highlightActiveElement.call(this, el)
+    await el.click(options)
+    await waitForAriaState(el, 'aria-pressed', pressed !== 'true', locator)
+
+    return this._waitForAction()
+  }
+
+  /**
+   * {{> seeButtonIsPressed }}
+   */
+  async seeButtonIsPressed(locator) {
+    return proceedIsPressed.call(this, 'assert', locator)
+  }
+
+  /**
+   * {{> dontSeeButtonIsPressed }}
+   */
+  async dontSeeButtonIsPressed(locator) {
+    return proceedIsPressed.call(this, 'negate', locator)
+  }
+
   /**
    * {{> pressKeyDown }}
    */
@@ -4412,11 +4453,72 @@ async function findCheckable(locator, context) {
 async function proceedIsChecked(assertType, option) {
   let els = await findCheckable.call(this, option)
   assertElementExists(els, option, 'Checkable')
-  els = await Promise.all(els.map(el => el.isChecked()))
+  els = await Promise.all(els.map(el => isElementChecked(el, option)))
   const selected = els.reduce((prev, cur) => prev || cur)
   return truth(`checkable ${option}`, 'to be checked')[assertType](selected)
 }
 
+async function isElementChecked(el, locator) {
+  try {
+    return await el.isChecked()
+  } catch (err) {
+    const checked = await el.getAttribute('aria-checked')
+    if (checked !== null) return checked === 'true'
+
+    const pressed = await el.getAttribute('aria-pressed')
+    if (pressed !== null) {
+      throw new Error(`Element ${new Locator(locator)} is a toggle button with aria-pressed="${pressed}", use seeButtonIsPressed to assert its state`)
+    }
+    throw err
+  }
+}
+
+async function setCheckableState(el, expected, locator, options = {}) {
+  const role = await el.getAttribute('role')
+  if (!ariaCheckableRoles.includes(role)) {
+    return expected ? el.check(options) : el.uncheck(options)
+  }
+
+  const current = await el.getAttribute('aria-checked')
+  if (current === null) {
+    throw new Error(`Element ${new Locator(locator)} with role "${role}" has no aria-checked state`)
+  }
+  if ((current === 'true') === expected) return
+
+  await el.click(options)
+  await waitForAriaState(el, 'aria-checked', expected, locator)
+}
+
+async function waitForAriaState(el, attribute, expected, locator) {
+  const deadline = Date.now() + 2000
+
+  while (Date.now() < deadline) {
+    if (!(await el.isVisible().catch(() => false))) return
+
+    const state = await el.getAttribute(attribute, { timeout: 1000 }).catch(() => null)
+    if (state === null) return
+    if ((state === 'true') === expected) return
+
+    await new Promise(resolve => setTimeout(resolve, 50))
+  }
+
+  throw new Error(`Element ${new Locator(locator)} was clicked but its ${attribute} did not become "${expected}"`)
+}
+
+async function proceedIsPressed(assertType, locator) {
+  const matcher = await this._getContext()
+  const els = await findClickable.call(this, matcher, locator)
+  assertElementExists(els, locator, 'Toggle button')
+
+  const states = await Promise.all(els.map(el => el.getAttribute('aria-pressed')))
+  if (states.every(state => state === null)) {
+    throw new Error(`Element ${new Locator(locator)} is not a toggle button, it has no aria-pressed attribute`)
+  }
+
+  const pressed = states.some(state => state === 'true')
+  return truth(`toggle button ${locator}`, 'to be pressed')[assertType](pressed)
+}
+
 async function findFields(locator, context = null) {
   let contextEl
   if (context) {

lib/helper/Puppeteer.js

@@ -64,7 +64,7 @@ function wrapError(e) {
 let perfTiming
 const popupStore = new Popup()
 const consoleLogStore = new Console()
-const checkableRoles = ['checkbox', 'radio', 'switch']
+const checkableRoles = ['checkbox', 'radio', 'switch', 'menuitemcheckbox', 'menuitemradio']
 
 /**
  * ## Configuration
@@ -1516,6 +1516,40 @@ class Puppeteer extends Helper {
     return proceedIsChecked.call(this, 'negate', field)
   }
 
+  /**
+   * {{> toggleButton }}
+   */
+  async toggleButton(locator) {
+    const els = await this._locateClickable(locator)
+    assertElementExists(els, locator, 'Toggle button')
+    const el = selectElement(els, locator, this)
+    const pressed = await grabAriaState(el, 'aria-pressed')
+    if (pressed === null) {
+      throw new Error(`Element ${new Locator(locator)} is not a toggle button, it has no aria-pressed attribute`)
+    }
+
+    highlightActiveElement.call(this, el, await this._getContext())
+
+    await el.click()
+    await waitForAriaState(el, 'aria-pressed', pressed !== 'true', locator)
+
+    return this._waitForAction()
+  }
+
+  /**
+   * {{> seeButtonIsPressed }}
+   */
+  async seeButtonIsPressed(locator) {
+    return proceedIsPressed.call(this, 'assert', locator)
+  }
+
+  /**
+   * {{> dontSeeButtonIsPressed }}
+   */
+  async dontSeeButtonIsPressed(locator) {
+    return proceedIsPressed.call(this, 'negate', locator)
+  }
+
   /**
    * {{> pressKeyDown }}
    */
@@ -3241,6 +3275,37 @@ async function proceedIsChecked(assertType, option) {
   return truth(`checkable ${option}`, 'to be checked')[assertType](selected)
 }
 
+async function grabAriaState(el, attribute) {
+  return el.evaluate((node, name) => node.getAttribute(name), attribute).catch(() => null)
+}
+
+async function waitForAriaState(el, attribute, expected, locator) {
+  const deadline = Date.now() + 2000
+
+  while (Date.now() < deadline) {
+    const state = await grabAriaState(el, attribute)
+    if (state === null) return
+    if ((state === 'true') === expected) return
+
+    await new Promise(resolve => setTimeout(resolve, 50))
+  }
+
+  throw new Error(`Element ${new Locator(locator)} was clicked but its ${attribute} did not become "${expected}"`)
+}
+
+async function proceedIsPressed(assertType, locator) {
+  const els = await this._locateClickable(locator)
+  assertElementExists(els, locator, 'Toggle button')
+
+  const states = await Promise.all(els.map(el => grabAriaState(el, 'aria-pressed')))
+  if (states.every(state => state === null)) {
+    throw new Error(`Element ${new Locator(locator)} is not a toggle button, it has no aria-pressed attribute`)
+  }
+
+  const pressed = states.some(state => state === 'true')
+  return truth(`toggle button ${locator}`, 'to be pressed')[assertType](pressed)
+}
+
 async function findVisibleFields(locator, context = null) {
   const els = await findFields.call(this, locator, context)
   const visible = await Promise.all(els.map(el => el.boundingBox()))

lib/helper/WebDriver.js

@@ -1635,6 +1635,41 @@ class WebDriver extends Helper {
     return proceedSeeCheckbox.call(this, 'negate', field)
   }
 
+  /**
+   * {{> toggleButton }}
+   */
+  async toggleButton(locator) {
+    const clickMethod = this.browser.isMobile && this.browser.capabilities.platformName !== 'android' ? 'touchClick' : 'elementClick'
+    const locateFn = prepareLocateFn.call(this)
+
+    const res = await findClickable.call(this, locator, locateFn)
+    assertElementExists(res, locator, 'Toggle button')
+    const elem = selectElement(res, locator, this)
+    const elementId = getElementId(elem)
+    const pressed = await this.browser.getElementAttribute(elementId, 'aria-pressed')
+    if (pressed === null) {
+      throw new Error(`Element ${new Locator(locator)} is not a toggle button, it has no aria-pressed attribute`)
+    }
+    highlightActiveElement.call(this, elem)
+
+    await this.browser[clickMethod](elementId)
+    return waitForAriaState.call(this, elementId, 'aria-pressed', pressed !== 'true', locator)
+  }
+
+  /**
+   * {{> seeButtonIsPressed }}
+   */
+  async seeButtonIsPressed(locator) {
+    return proceedIsPressed.call(this, 'assert', locator)
+  }
+
+  /**
+   * {{> dontSeeButtonIsPressed }}
+   */
+  async dontSeeButtonIsPressed(locator) {
+    return proceedIsPressed.call(this, 'negate', locator)
+  }
+
   /**
    * {{> seeElement }}
    *
@@ -3189,7 +3224,10 @@ function toArray(item) {
 }
 
 async function proceedSeeCheckbox(assertType, field) {
-  const res = await findFields.call(this, field)
+  let res = await findFields.call(this, field)
+  if (!res.length) {
+    res = await findCheckable.call(this, field, prepareLocateFn.call(this))
+  }
   assertElementExists(res, field, 'Field')
 
   const selected = await forEachAsync(res, async el => {
@@ -3224,6 +3262,36 @@ async function getElementTextAttributes(element) {
   return [ariaLabel, placeholder, innerText, labelText]
 }
 
+async function waitForAriaState(elementId, attribute, expected, locator) {
+  const deadline = Date.now() + 2000
+
+  while (Date.now() < deadline) {
+    const state = await this.browser.getElementAttribute(elementId, attribute).catch(() => null)
+    if (state === null) return
+    if ((state === 'true') === expected) return
+
+    await new Promise(resolve => setTimeout(resolve, 50))
+  }
+
+  throw new Error(`Element ${new Locator(locator)} was clicked but its ${attribute} did not become "${expected}"`)
+}
+
+async function proceedIsPressed(assertType, locator) {
+  const res = await findClickable.call(this, locator, prepareLocateFn.call(this))
+  assertElementExists(res, locator, 'Toggle button')
+
+  const states = []
+  for (const el of res) {
+    states.push(await this.browser.getElementAttribute(getElementId(el), 'aria-pressed'))
+  }
+  if (states.every(state => state === null)) {
+    throw new Error(`Element ${new Locator(locator)} is not a toggle button, it has no aria-pressed attribute`)
+  }
+
+  const pressed = states.some(state => state === 'true')
+  return truth(`toggle button ${locator}`, 'to be pressed')[assertType](pressed)
+}
+
 async function isElementChecked(browser, elementId) {
   let isChecked = await browser.isElementSelected(elementId)
   if (!isChecked) {
@@ -3270,7 +3338,7 @@ async function keepCheckable(els) {
     return Array.prototype.slice.call(arguments).map(function (el) {
       if (!el) return false
       const role = el.getAttribute('role')
-      if (role) return ['checkbox', 'radio', 'switch'].indexOf(role) > -1
+      if (role) return ['checkbox', 'radio', 'switch', 'menuitemcheckbox', 'menuitemradio'].indexOf(role) > -1
       return el.tagName === 'INPUT' && (el.type === 'checkbox' || el.type === 'radio')
     })
   }, ...els)