Introduce IOSAriaRole and AndroidAriaRole typings for getByRole()

[Dhakshath11]

Problem or motivation

Mobilewright currently supports role-based locators through methods like getByRole(), but there is no exported strongly-typed role contract similar to Playwright’s AriaRole.

As a result, framework consumers must use plain string values for roles, which removes compile-time validation and autocomplete support.

Example:

screen.getByRole('button', { name: 'Login' });

Currently, invalid values such as:

screen.getByRole('random-role');

are accepted at compile time and only fail during runtime.

For automation framework developers building reusable abstractions on top of Mobilewright, having exported role typings would improve:

• type safety
• autocomplete experience
• framework API consistency
• developer ergonomics
• platform-aware locator validation

This becomes especially useful for larger automation frameworks integrating Web + iOS + Android under unified locator APIs.

Proposed solution

Introduce exported role typings similar to Playwright’s AriaRole, but platform-specific for mobile automation.

Example:

export type IOSAriaRole =
  | 'button'
  | 'textfield'
  | 'image'
  | 'switch'
  | 'tab'
  | 'searchbox'
  | ...;

export type AndroidAriaRole =
  | 'button'
  | 'edittext'
  | 'image'
  | 'checkbox'
  | 'tab'
  | ...;

Then allow usage like:

import type { IOSAriaRole } from '@mobilewright/core';

async getLocator(role: IOSAriaRole) {
    return screen.getByRole(role);
}

This would provide:

• compile-time validation
• IDE autocomplete
• clearer platform semantics
• safer framework abstractions
• improved developer experience

An alternative approach could also be:

• exporting a shared MobileAriaRole
• while internally mapping platform-specific accessibility roles.

Target platform

Both

Alternatives considered

Currently, framework developers must use plain string types for mobile roles:

getByRole(role: string)

While this keeps the API flexible, it removes:

• compile-time validation
• autocomplete support
• platform-aware typing

Another alternative is for consumers to create their own custom role unions manually inside their frameworks. However, this leads to duplicated role definitions across projects and inconsistent platform mappings.

Example:

type IOSRole = 'button' | 'textfield' | 'switch';

This approach works, but responsibility shifts to framework consumers rather than being standardized within Mobilewright itself.

A shared exported typing from Mobilewright would provide a more consistent and maintainable developer experience.

Additional context

This feature would especially benefit teams building reusable automation frameworks on top of Mobilewright for:

• enterprise mobile automation
• cross-platform abstraction layers
• unified Web + Mobile test frameworks
• reusable page object architectures

The request is inspired by Playwright’s AriaRole typing support, which significantly improves IDE assistance and API safety for locator strategies.

The goal is not strict enforcement of accessibility semantics, but rather improving developer ergonomics and reducing invalid role usage during framework development.

[gmegidish]

That is a great suggestion. Stopping things at compile time is what we want. Let me get back to you on this.

[Dhakshath-Lambdatest]

@gmegidish Would like to contribute the fix.