Element Access

The els module provides low-level element manipulation functions for CodeceptJS tests, allowing for more granular control over element interactions and assertions. However, because element representation differs between frameworks, tests using element functions are not portable between helpers. So if you set to use Playwright you won't be able to witch to WebDriver with one config change in CodeceptJS.

Usage

Import the els functions in your test file:

const { element, eachElement, expectElement, expectAnyElement, expectAllElements } = require('codeceptjs/els');

element

The element function allows you to perform custom operations on the first matching element found by a locator. It provides a low-level way to interact with elements when the built-in helper methods aren't sufficient.

Syntax

element(purpose, locator, fn);
// or
element(locator, fn);

Parameters

• purpose (optional) - A string describing the operation being performed. If omitted, a default purpose will be generated from the function.
• locator - A locator string/object to find the element(s).
• fn - An async function that receives the element as its argument and performs the desired operation. el argument represents an element of an underlying engine used: Playwright, WebDriver, or Puppeteer.

Returns

Returns the result of the provided async function executed on the first matching element.

Example

Scenario('my test', async ({ I }) => {
  // combine element function with standard steps:
  I.amOnPage('/cart');

  // but use await every time you use element function
  await element(
    // with explicit purpose
    'check custom attribute',
    '.button',
    async el => await el.getAttribute('data-test'),
  );

  // or simply
  await element('.button', async el => {
    return await el.isEnabled();
  });
});

Notes

• Only works with helpers that implement the _locate method
• The function will only operate on the first element found, even if multiple elements match the locator
• The provided callback must be an async function
• Throws an error if no helper with _locate method is enabled

eachElement

The eachElement function allows you to perform operations on each element that matches a locator. It's useful for iterating through multiple elements and performing the same operation on each one.

Syntax

eachElement(purpose, locator, fn);
// or
eachElement(locator, fn);

Parameters

• purpose (optional) - A string describing the operation being performed. If omitted, a default purpose will be generated from the function.
• locator - A locator string/object to find the element(s).
• fn - An async function that receives two arguments:
  • el - The current element being processed
  • index - The index of the current element in the collection

Returns

Returns a promise that resolves when all elements have been processed. If any element operation fails, the function will throw the first encountered error.

Example

Scenario('my test', async ({ I }) => {
  // combine element function with standard steps:
  I.click('/hotels');

  // iterate over elements but don't forget to put await
  await eachElement(
    'validate list items', // explain your actions for future review
    '.list-item', // locator
    async (el, index) => {
      const text = await el.getText();
      console.log(`Item ${index}: ${text}`);
    },
  );

  // Or simply check if all checkboxes are checked
  await eachElement('input[type="checkbox"]', async el => {
    const isChecked = await el.isSelected();
    if (!isChecked) {
      throw new Error('Found unchecked checkbox');
    }
  });
});

Notes

• Only works with helpers that implement the _locate method
• The function will process all elements that match the locator
• The provided callback must be an async function
• If an operation fails on any element, the error is logged and the function continues processing remaining elements
• After all elements are processed, if any errors occurred, the first error is thrown
• Throws an error if no helper with _locate method is enabled

expectElement

The expectElement function allows you to perform assertions on the first element that matches a locator. It's designed for validating element properties or states and will throw an assertion error if the condition is not met.

Syntax

expectElement(locator, fn);

Parameters

• locator - A locator string/object to find the element(s).
• fn - An async function that receives the element as its argument and should return a boolean value:
  • true - The assertion passed
  • false - The assertion failed

Returns

Returns a promise that resolves when the assertion is complete. Throws an assertion error if the condition is not met.

Example

// Check if a button is enabled
await expectElement('.submit-button', async el => {
  return await el.isEnabled();
});

// Verify element has specific text content
await expectElement('.header', async el => {
  const text = await el.getText();
  return text === 'Welcome';
});

// Check for specific attribute value
await expectElement('#user-profile', async el => {
  const role = await el.getAttribute('role');
  return role === 'button';
});

Notes

• Only works with helpers that implement the _locate method
• The function will only check the first element found, even if multiple elements match the locator
• The provided callback must be an async function that returns a boolean
• The assertion message will include both the locator and the function used for validation
• Throws an error if no helper with _locate method is enabled

expectAnyElement

The expectAnyElement function allows you to perform assertions where at least one element from a collection should satisfy the condition. It's useful when you need to verify that at least one element among many matches your criteria.

Syntax

expectAnyElement(locator, fn);

Parameters

• locator - A locator string/object to find the element(s).
• fn - An async function that receives the element as its argument and should return a boolean value:
  • true - The assertion passed for this element
  • false - The assertion failed for this element

Returns

Returns a promise that resolves when the assertion is complete. Throws an assertion error if no elements satisfy the condition.

Example

Scenario('validate any element matches criteria', async ({ I }) => {
  // Navigate to the page
  I.amOnPage('/products');

  // Check if any product is marked as "in stock"
  await expectAnyElement('.product-item', async el => {
    const status = await el.getAttribute('data-status');
    return status === 'in-stock';
  });

  // Verify at least one price is below $100
  await expectAnyElement('.price-tag', async el => {
    const price = await el.getText();
    return parseFloat(price.replace('$', '')) < 100;
  });

  // Check if any button in the list is enabled
  await expectAnyElement('.action-button', async el => {
    return await el.isEnabled();
  });
});

Notes

• Only works with helpers that implement the _locate method
• The function will check all matching elements until it finds one that satisfies the condition
• Stops checking elements once the first matching condition is found
• The provided callback must be an async function that returns a boolean
• Throws an assertion error if no elements satisfy the condition
• Throws an error if no helper with _locate method is enabled

expectAllElements

The expectAllElements function verifies that every element matching the locator satisfies the given condition. It's useful when you need to ensure that all elements in a collection meet specific criteria.

Syntax

expectAllElements(locator, fn);

Parameters

• locator - A locator string/object to find the element(s).
• fn - An async function that receives the element as its argument and should return a boolean value:
  • true - The assertion passed for this element
  • false - The assertion failed for this element

Returns

Returns a promise that resolves when all assertions are complete. Throws an assertion error as soon as any element fails the condition.

Example

Scenario('validate all elements meet criteria', async ({ I }) => {
  // Navigate to the page
  I.amOnPage('/dashboard');

  // Verify all required fields have the required attribute
  await expectAllElements('.required-field', async el => {
    const required = await el.getAttribute('required');
    return required !== null;
  });

  // Check if all checkboxes in a form are checked
  await expectAllElements('input[type="checkbox"]', async el => {
    return await el.isSelected();
  });

  // Verify all items in a list have non-empty text
  await expectAllElements('.list-item', async el => {
    const text = await el.getText();
    return text.trim().length > 0;
  });

  // Ensure all buttons in a section are enabled
  await expectAllElements('#action-section button', async el => {
    return await el.isEnabled();
  });
});

Notes

• Only works with helpers that implement the _locate method
• The function checks every element that matches the locator
• Fails fast: stops checking elements as soon as one fails the condition
• The provided callback must be an async function that returns a boolean
• The assertion message will include which element number failed (e.g., "element #2 of...")
• Throws an error if no helper with _locate method is enabled