Locators

Locators tell CodeceptJS which element on the page a step acts on. Every action that touches the DOM — click, fillField, see, waitForVisible — accepts one.

CodeceptJS accepts locators in two forms:

• Strict locator — an object whose single key names the strategy: { css: 'button' }, { role: 'button', name: 'Submit' }, { xpath: '//td[1]' }, { id: 'email' }. The strategy is explicit, so the helper runs exactly one query.
• Semantic locator — a plain string like 'Sign In' or 'Email'. CodeceptJS matches it against labels, button text, placeholders, and aria-* attributes the way a user would read the page.

Both are idiomatic. The strongest pattern in CodeceptJS — readable, resilient, and unambiguous — is a semantic locator scoped to a context:

I.click('Save', '.header')
I.fillField('Search', 'Item 1', '.topbar')
I.click({ role: 'button', name: 'Submit' }, '#login-form')

The context narrows the search to one region of the page, and the semantic string says what the user actually clicks. This is more precise than ARIA or CSS alone because it combines structural scope with human-readable intent.

Supported strategies: css, xpath, id, name, role, frame, shadow, pw. Shadow DOM has its own page — see Shadow DOM. Playwright-specific locators use the pw strategy: { pw: '[data-testid="save"]' }. To test components by their accessible role, use ARIA locators.

Locator types at a glance

ARIA locators

ARIA role locators are the modern default. They identify elements the way assistive technology does — by role and accessible name — and they survive layout and class refactors that break CSS.

I.click({ role: 'button', name: 'Login' })
I.fillField({ role: 'textbox', name: 'Email Address' }, '[email protected]')
I.seeElement({ role: 'heading', name: 'Dashboard' })
I.selectOption({ role: 'combobox', name: 'Country' }, 'Ukraine')

The name matches the element's accessible name — its visible text, aria-label, or the text referenced by aria-labelledby.

Common roles: button, link, textbox, checkbox, radio, combobox, listbox, menuitem, tab, dialog, alert, heading, navigation, banner, main.

Prefer ARIA when:

• The element has a visible label or accessible text.
• You want the test to double as an accessibility smoke check.
• The UI is rewritten often and class names drift.

Reach for something else when:

• The element has no accessible name (purely decorative icons, unlabeled inputs).
• The page predates ARIA annotation and you cannot change it.
• A hot loop runs thousands of locator calls and needs the speed of a direct CSS query.

ARIA locators rely on the accessibility tree of the underlying helper. Playwright and modern WebDriver support them natively.

CSS selectors

CSS is the fastest locator type and most frontend developers read it fluently.

I.seeElement('.user-profile .avatar')
I.click('#checkout-btn')
I.fillField('input[name="email"]', '[email protected]')

Pair CSS with stable test attributes — data-testid, data-qa — rather than style classes. Style classes drift with every design update; test attributes exist to be locators.

I.click('[data-testid="submit-order"]')

Tie locators to structure, not to presentation: .btn-primary survives a redesign; .bg-green-500 does not.

Force CSS when a bare string would trigger fuzzy matching:

I.fillField({ css: 'input[type=password]' }, '123456')

XPath

XPath reaches where CSS cannot. Use it for:

• Text matching: //button[contains(., 'Save changes')]
• Axis navigation: ancestor, following-sibling, preceding-sibling
• Positional selection deep in a table or list

I.click({ xpath: "//tr[td[text()='Acme Corp']]//button[contains(., 'Edit')]" })

Long XPath expressions become unreadable fast. The locate() builder produces the same XPath with a fluent syntax — prefer it for anything beyond two conditions.

Semantic locators

A plain string is a semantic locator. CodeceptJS reads it the way a user would: as a button label, a link, a field name, a placeholder, or an aria-label.

I.click('Sign In')                       // matches <a>, <button>, or <input type="submit">
I.fillField('Email', '[email protected]')          // matches label, placeholder, name, or aria-label
I.checkOption('I accept the terms')

Pair semantic locators with a context

The same label often appears in more than one place — a "Save" button in the toolbar, the modal, and the inline editor. Pass a context as the last argument and the lookup is unambiguous, fast, and still readable:

I.click('Save', '.toolbar')
I.fillField('Search', 'Item 1', '.topbar')
I.click('Edit', { css: 'tr.acme' })
I.see('Welcome', '.header')

The context can be any locator (CSS, XPath, ARIA, locate() chain). The action runs only inside it, so duplicate labels elsewhere on the page no longer cause flaky matches. This is the recommended default for stable scenarios — production-grade, not a prototyping shortcut.

How matching works

For fillField and similar actions, CodeceptJS resolves the locator in this order:

1. ARIA role locator ({ role: 'textbox', name: 'Email' }) — resolved through the accessibility tree.
2. Strict locator ({ css: ... }, { xpath: ... }, { id: ... }, …) — run directly.
3. Plain string treated as semantic, tried in order:
   1. Field whose name, id+label[for], or placeholder equals the string — or a <label> with that exact text wrapping an input.
   2. The same match with contains, extended to aria-label, aria-labelledby, and title.
   3. An input with that name attribute.
   4. The string as a CSS selector.
4. Nothing matched? Throw ElementNotFound.

A semantic lookup runs several queries, but each query is cheap and the second argument (context) prunes the search space dramatically.

ID locators

Three short forms cover id-based matching:

• #user or { id: 'user' } — element with id="user"
• { name: 'email' } — form field with name="email"
• ~login-button — accessibility id (mobile) or aria-label (web)

I.fillField('#email', '[email protected]')
I.seeElement({ id: 'confirmation' })
I.tap('~submit')   // mobile

Picking a specific element

When a locator matches several elements on the page, CodeceptJS acts on the first one by default. To target a different match, pass elementIndex via step.opts():

import step from 'codeceptjs/steps'

I.click('a', step.opts({ elementIndex: 2 }))       // the 2nd link
I.click('a', step.opts({ elementIndex: 'last' }))  // the last link
I.fillField('.email-input', '[email protected]', step.opts({ elementIndex: -1 }))

elementIndex accepts positive numbers (1-based), negative numbers (-1 is last), or the aliases 'first' and 'last'. It works with click, fillField, selectOption, checkOption, and other single-element actions.

To catch ambiguous locators during development rather than silently using the first match, enable strict: true in the helper config, or pass step.opts({ exact: true }) on a single step:

I.click('a', step.opts({ exact: true }))
// throws MultipleElementsFound if more than one link matches

See Element Selection for full details on elementIndex, strict mode, and iterating over matches with eachElement.

Combining locators

Two mechanisms narrow a locator to a region of the page:

• Context — the last argument of most actions. Works with every locator type. In I.click('Save', '.toolbar') it is the second argument; in I.fillField('Email', '[email protected]', '#login-form') it is the third.
• locate() builder — a fluent API that composes CSS and XPath into a single XPath expression. Does not accept ARIA role locators.

Context: scope any locator to a region

Every action that targets an element accepts a context locator as its last argument. The action searches only inside the context. Use it by default — even a one-line scenario reads better and survives more refactors when the lookup is scoped:

I.click('Login', '#login-form')
I.fillField('Email', '[email protected]', '.modal')
I.seeElement({ role: 'button', name: 'Delete' }, '.toolbar')

Why scope every action:

• Duplicate labels stop being a problem ("Save" in the toolbar vs. the modal).
• The semantic locator stays semantic — no need to rewrite as [data-testid="save-toolbar"] to disambiguate.
• The lookup is faster: each strategy queries only inside the context, not the whole DOM.
• Tests read like a sentence about the page: "click Save in the header".

The two sides can be any combination — semantic+CSS, ARIA+CSS, semantic+locate(). Mix freely.

Example: a dropdown inside a top bar

A complex app often has several menus on screen at once: the top navigation bar, a left sidebar, a right-click context menu. Each may contain a "Settings" item. Without scoping, I.click('Settings') is a coin toss.

// Open the user dropdown in the top bar, then pick Settings
I.click({ role: 'button', name: 'User menu' }, '.top-bar')
I.click({ role: 'menuitem', name: 'Settings' }, '.top-bar')

// The same label in the sidebar goes to a different screen
I.click({ role: 'link', name: 'Settings' }, '.sidebar')

The context itself accepts any locator type: a bare string, a strict object, or a locate() chain.

I.click({ role: 'menuitem', name: 'Log out' }, locate('.dropdown-menu').inside('header'))

locate() builder: compose CSS and XPath

locate() chains CSS and XPath conditions into a single XPath expression. Each method returns the builder so you keep composing.

locate('a')
  .withAttr({ href: '#' })
  .inside(locate('label').withText('Hello'))
// .//a[@href = '#'][ancestor::label[contains(., 'Hello')]]

Give long chains a name for readable logs:

locate('//table').find('a').withText('Edit').as('row edit button')

locate() does not wrap ARIA role locators. The builder produces XPath; ARIA role matching relies on the accessibility tree provided by the helper. To scope an ARIA locator to a region, pass the region as a context argument rather than wrapping it in locate().

Example: the dropdown from the top bar, expressed with locate()

When menu items expose no useful ARIA role (custom components built from <div> elements and click handlers), fall back to CSS and XPath inside a locate() chain:

const userMenu = locate('.dropdown-menu').inside('.top-bar').as('user menu')

I.click('.user-avatar', '.top-bar')
I.click(locate('a').withText('Settings').inside(userMenu))

Example: the Edit button in a specific table row

const editAcme = locate('tr')
  .withDescendant(locate('td').withText('Acme Corp'))
  .find('button')
  .withText('Edit')
  .as('Edit button for Acme')

I.click(editAcme)

Builder methods

The with* family filters elements positively; without* excludes; and / andNot / or compose raw predicates or union locators.

Translating complex XPath

Long XPath expressions become readable with the DSL. For example:

//*[self::button
    and contains(@class,"red-btn")
    and contains(@class,"btn-text-and-icon")
    and contains(@class,"btn-lg")
    and contains(@class,"btn-selected")
    and normalize-space(.)="Button selected"
    and not(.//svg)]

becomes:

locate('button')
  .withClass('red-btn', 'btn-text-and-icon', 'btn-lg', 'btn-selected')
  .withText('Button selected')
  .withoutDescendant('svg')

withClass uses word-exact matching (same as CSS .foo), so .withClass('btn') will not accidentally match class="btn-lg". Use withAttrContains('class', …) if you need the old substring behavior.

Custom locators

Teams that tag elements with data-qa, data-test, or similar attributes can register a short-form syntax instead of typing { css: '[data-qa-id=register_button]' } every time.

The customLocator plugin maps a prefix to an attribute:

// with plugin enabled: $name → [data-qa=name]
I.click('$register_button')
I.fillField('$email', '[email protected]')

For more control, register a filter from a bootstrap script or plugin:

codeceptjs.locator.addFilter((providedLocator, locatorObj) => {
  if (providedLocator.data) {
    locatorObj.type = 'css'
    locatorObj.value = `[data-element=${providedLocator.data}]`
  }
})

After registration, { data: 'user-login' } is a valid strict locator:

I.click({ data: 'user-login' })

Further reading: Mozilla's Writing reliable locators for Selenium and WebDriver tests and the Locator Advicer.