Label Selectors

What are Label Selectors?

Label selectors target form controls through their associated text labels. This approach matches how users typically interact with forms, as they first read the label to understand what information is required.

Using getByLabel is an excellent choice for form testing because:

It closely resembles how users find form fields
Labels rarely change even when the underlying implementation does
It encourages proper form accessibility with labeled controls
It works with both explicit (for attribute) and implicit label associations

Registration Form with Labels

This form demonstrates elements that can be targeted by their associated label text.

Email Address

Password

Confirm Password

Name

Phone Number

Country

Date of Birth

Subscribe to newsletter

Gender

Male Female Other

Additional Comments

Label Selectors JSON Configuration

Copy this JSON configuration to test the form with TesterUtilities extension. It uses getByLabel selectors to target elements by their associated label text.

{
  "email": {
    "selector": "Email Address",
    "queryType": "label",
    "type": "input",
    "data": "test.user@example.com",
    "dataType": "static"
  },
  "password": {
    "selector": "Password",
    "queryType": "label",
    "type": "input",
    "data": "SecurePassword123!",
    "dataType": "static"
  },
  "confirmPassword": {
    "selector": "Confirm Password",
    "queryType": "label",
    "type": "input",
    "data": "SecurePassword123!",
    "dataType": "static"
  },
  "firstName": {
    "selector": "Name",
    "queryType": "label",
    "queryOptions": {
      "index": 0
    },
    "type": "input",
    "data": "John",
    "dataType": "static"
  },
  "lastName": {
    "selector": "Name",
    "queryType": "label",
    "queryOptions": {
      "index": 1
    },
    "type": "input",
    "data": "Doe",
    "dataType": "static"
  },
  "phoneNumber": {
    "selector": "Phone Number",
    "queryType": "label",
    "type": "input",
    "data": "+1 (555) 123-4567",
    "dataType": "static"
  },
  "country": {
    "selector": "Country",
    "queryType": "label",
    "type": "input",
    "data": "us",
    "dataType": "static"
  },
  "birthdate": {
    "selector": "Date of Birth",
    "queryType": "label",
    "type": "input",
    "data": "1990-01-15",
    "dataType": "static"
  },
  "newsletter": {
    "selector": "Subscribe to newsletter",
    "queryType": "label",
    "type": "checkCheckbox"
  },
  "gender": {
    "selector": "Male",
    "queryType": "label",
    "type": "checkCheckbox"
  },
  "comments": {
    "selector": "Additional Comments",
    "queryType": "label",
    "type": "input",
    "data": "This is a test comment using label selectors.",
    "dataType": "static"
  },
  "register": {
    "selector": "Register",
    "queryType": "text",
    "type": "simpleClick"
  }
}

How Label Selectors Work

In the TesterUtilities extension, label selectors use the getByLabel function, which finds elements by their associated label text. This works with explicit labels (using the for attribute) and implicit labels (where the input is a child of the label).

// Example of how getByLabel works:
function getByLabel(document, labelText, options = {}) {
  const { exact = false, index = 0 } = options;
  
  // Find all label elements
  const labels = Array.from(document.querySelectorAll('label'));
  
  // Filter labels by text content
  const matchingLabels = labels.filter(label => {
    const labelContent = label.textContent.trim();
    return exact 
      ? labelContent === labelText 
      : labelContent.includes(labelText);
  });
  
  // Get the target label based on index
  const targetLabel = matchingLabels[index];
  if (!targetLabel) return null;
  
  // Case 1: Label has 'for' attribute - find element by ID
  const forAttribute = targetLabel.getAttribute('for');
  if (forAttribute) {
    return document.getElementById(forAttribute);
  }
  
  // Case 2: Input is child of label (implicit label)
  const inputElements = targetLabel.querySelectorAll('input, select, textarea');
  if (inputElements.length > 0) {
    return inputElements[0];
  }
  
  return null;
}

Important Notes About Label Selectors

Handling Duplicate Labels: When multiple elements share the same label text, use the index parameter to specify which one to target (0-based).
Exact Matching: By default, label matching is partial (contains). Set exact: true to require an exact match.
Label Associations: This approach works with both explicit labels (using the for attribute) and implicit labels (input within label).