/voyager

Modern Selector Strategy & Accessibility-First Testing

Purpose: Use this file when Voyager must choose stable selectors, apply ARIA snapshots, or justify accessibility-first locator decisions.

Contents:

• Selector priority ladder and fallback flow
• getByRole() patterns and known limits
• ARIA snapshots versus DOM snapshots
• Accessibility-first form and interaction testing
• Integration with automated axe-core checks

Selector Priority Ladder

Fallback Flow

Does the element expose an accessible role?
  -> Yes: use getByRole()
  -> No
Does the form control have a label?
  -> Yes: use getByLabel()
  -> No
Does it have a stable placeholder?
  -> Yes: use getByPlaceholder()
  -> No
Does it have unique visible text?
  -> Yes: use getByText()
  -> No
Can you add a test-specific attribute?
  -> Yes: use getByTestId()
  -> No: CSS/XPath only as a documented last resort

getByRole() Patterns

Basic Usage

await page.getByRole('button', { name: 'Save changes' }).click();
await page.getByRole('link', { name: 'Sign up' }).click();
await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
await page.getByRole('checkbox', { name: 'Agree to terms' }).check();
await expect(page.getByRole('heading', { level: 1 })).toHaveText('Dashboard');
await page.getByRole('navigation').getByRole('link', { name: 'Home' }).click();

Filtering and Scoping

await page.getByRole('checkbox', { name: 'Newsletter', checked: true });
await page.getByRole('tab', { name: 'Settings', selected: true });
await page.getByRole('treeitem', { expanded: true });

const dialog = page.getByRole('dialog');
await dialog.getByRole('button', { name: 'Confirm' }).click();

// Hidden elements should be rare and intentional
await page.getByRole('button', { name: 'Menu', includeHidden: true });

Known Limits

ARIA Snapshots

ARIA snapshots test semantics instead of raw DOM shape.

await expect(page.getByRole('navigation')).toMatchAriaSnapshot(`
  - navigation:
    - link "Home"
    - link "Products"
    - link "About"
    - link "Contact"
`);

await expect(page.getByRole('form')).toMatchAriaSnapshot(`
  - form:
    - textbox
    - textbox
    - button "Submit"
`);

ARIA vs DOM Snapshots

Accessibility-First Testing

Principle:

Write tests the way a screen-reader or keyboard user experiences the UI.
If the test breaks because accessible semantics disappeared, the test found a real problem.

Prefer Semantic Interactions

// Implementation-coupled
await page.locator('#submit-btn').click();
await page.locator('.error-msg').isVisible();

// Accessibility-first
await page.getByRole('button', { name: 'Submit order' }).click();
await expect(page.getByRole('alert')).toContainText('Invalid email');

Accessibility-First Form Example

test('submits the registration form', async ({ page }) => {
  await page.getByLabel('Full name').fill('John Doe');
  await page.getByLabel('Email address').fill('john@example.com');
  await page.getByLabel('Password').fill('SecurePass123');
  await page.getByRole('checkbox', { name: 'I agree to terms' }).check();
  await page.getByRole('button', { name: 'Create account' }).click();
  await expect(page.getByRole('status')).toContainText('Account created');
});

Common Roles

axe-core Integration

import AxeBuilder from '@axe-core/playwright';

test('checkout page is accessible', async ({ page }) => {
  await page.goto('/checkout');

  await page.getByLabel('Card number').fill('4111111111111111');
  await page.getByRole('button', { name: 'Pay now' }).click();

  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa'])
    .analyze();

  expect(results.violations).toEqual([]);
});

Problems This Strategy Exposes Early

Sources: Playwright: Locators · Playwright: Accessibility Testing · Playwright: ARIA Snapshots · Components.Guide: Accessibility-First Playwright · Cam McHenry: Accessible Playwright Tests · Momentic: Limits of getByRole