ARIA Role Selectors

What are ARIA Role Selectors?

Role selectors target elements based on their ARIA role or implicit HTML role. This approach aligns with how users interact with your application through assistive technologies, making your tests more resilient and aligned with accessibility practices.

Using getByRole is often considered the most robust selector strategy because it:

Registration Form with ARIA Roles

This form demonstrates elements that can be targeted by their ARIA roles and properties.

Create Your Account

Gender
Select your gender for demographic purposes

ARIA Role Selectors JSON Configuration

Copy this JSON configuration to test the form with TesterUtilities extension. It uses getByRole selectors to target elements by their ARIA roles and accessible properties. 

{
  "email": {
    "selector": "textbox",
    "queryType": "role",
    "queryOptions": {
      "name": "Email Address"
    },
    "type": "input",
    "dataType": "function",
    "dataGenerator": "fakerEmail"
  },
  "password": {
    "selector": "textbox",
    "queryType": "role",
    "queryOptions": {
      "name": "Password"
    },
    "type": "input",
    "data": "SecurePassword123!",
    "dataType": "static"
  },
  "confirmPassword": {
    "selector": "textbox",
    "queryType": "role",
    "queryOptions": {
      "name": "Confirm Password"
    },
    "type": "input",
    "data": "SecurePassword123!",
    "dataType": "static"
  },
  "firstName": {
    "selector": "textbox",
    "queryType": "role",
    "queryOptions": {
      "name": "First Name"
    },
    "type": "input",
    "dataType": "function",
    "dataGenerator": "fakerFirstName"
  },
  "lastName": {
    "selector": "textbox",
    "queryType": "role",
    "queryOptions": {
      "name": "Last Name"
    },
    "type": "input",
    "dataType": "function",
    "dataGenerator": "fakerLastName"
  },
  "phoneNumber": {
    "selector": "textbox",
    "queryType": "role",
    "queryOptions": {
      "name": "Phone Number"
    },
    "type": "input",
    "dataType": "function",
    "dataGenerator": "generatePolishMobile"
  },
  "country": {
    "selector": "combobox",
    "queryType": "role",
    "queryOptions": {
      "name": "Country selection"
    },
    "type": "input",
    "data": "pl",
    "dataType": "static"
  },
  "birthdate": {
    "selector": "textbox",
    "queryType": "role",
    "queryOptions": {
      "name": "Date of Birth"
    },
    "type": "input",
    "dataType": "function",
    "dataGenerator": "generateRandomDate:18:65"
  },
  "newsletter": {
    "selector": "checkbox",
    "queryType": "role",
    "queryOptions": {
      "name": "Subscribe to newsletter"
    },
    "type": "checkCheckbox"
  },
  "genderMale": {
    "selector": "radio",
    "queryType": "role",
    "queryOptions": {
      "name": "Male"
    },
    "type": "checkCheckbox"
  },
  "comments": {
    "selector": "textbox",
    "queryType": "role",
    "queryOptions": {
      "name": "Additional comments"
    },
    "type": "input",
    "dataType": "function",
    "dataGenerator": "fakerRaw:lorem.paragraph:pl"
  },
  "submitButton": {
    "selector": "button",
    "queryType": "role",
    "queryOptions": {
      "name": "Submit registration"
    },
    "type": "simpleClick"
  }
}

How Role Selectors Work

In the TesterUtilities extension, role selectors use the getByRole function, which finds elements with the specified accessible role and name. 

// Example of how getByRole works:
function getByRole(document, role, options = {}) {
  const { name, exact = false, index = 0 } = options;
  
  // Find all elements with the given role
  const elements = Array.from(document.querySelectorAll(`[role="${role}"]`));
  
  // Also include elements with implicit roles
  if (role === 'textbox') {
    elements.push(...document.querySelectorAll('input[type="text"], input[type="email"], input[type="password"], input[type="tel"], textarea'));
  } else if (role === 'button') {
    elements.push(...document.querySelectorAll('button, input[type="button"], input[type="submit"]'));
  } else if (role === 'checkbox') {
    elements.push(...document.querySelectorAll('input[type="checkbox"]'));
  } else if (role === 'radio') {
    elements.push(...document.querySelectorAll('input[type="radio"]'));
  } else if (role === 'combobox') {
    elements.push(...document.querySelectorAll('select'));
  }
  
  // If name is provided, filter by accessible name
  if (name) {
    const filteredElements = elements.filter(el => {
      const accessibleName = getAccessibleName(el);
      return exact 
        ? accessibleName === name 
        : accessibleName.includes(name);
    });
    
    // Return the element at the specified index or null
    return filteredElements[index] || null;
  }
  
  return elements[index] || null;
}

Common ARIA Roles