Skip to main content

externalBy

By produces a Selector used to locate a PageElement or PageElement on a web page. Selectors can be defined using a static value or a Question to be resolved at runtime.

Defining a selector using a string

Every selector method on this class accepts a static string value to define a selector.

import { PageElement, By } from '@serenity-js/web'

class LoginForm {
  static usernameField = () =>
    PageElement.located(By.role('textbox', { name: 'Username' }))
      .describedAs('username field'),

  static passwordField = () =>
    PageElement.located(By.css('[data-test-id="password"]'))
      .describedAs('password field')
}

Defining a selector using a Question

Each method on this class also accepts an Answerable to allow for dynamic resolution of the selector. This can be useful when the selector is not known at the time of writing the test, or when the selector needs to be calculated based on the state of the system under test.

The example below demonstrates how to use q to define a selector that includes a dynamic value.

import { q } from '@serenity-js/core'
import { PageElement, By } from '@serenity-js/web'

class FormField {
  static withTestId = (id: Answerable<string>) =>
    PageElement.located(By.css(q`input[data-test-id="${ id }"]`))
      .describedAs('form field')
}

Learn more

Index

Constructors

Methods

Constructors

externalconstructor

  • new By(): By

  • Returns By

Methods

staticexternalcss

staticexternalcssContainingText

staticexternaldeepCss

staticexternalid

staticexternalrole

  • Locates a PageElement by its ARIA role, ARIA attributes and accessible name.

    Example usage

    Given the following HTML structure:

    <h3>Sign up</h3>
    <label>
      <input type="checkbox" /> Subscribe
    </label>
    <br/>
    <button>Submit</button>

    Each element can be located by its implicit accessibility role:

    const heading  = PageElement.located(By.role('heading', { name: 'Sign up' })).describedAs('Sign up heading');
    const checkbox = PageElement.located(By.role('checkbox', { name: 'Subscribe' })).describedAs('Subscribe checkbox');
    const button   = PageElement.located(By.role('button', { name: 'Submit' })).describedAs('Submit button');

    Playwright Test

    import { Ensure } from '@serenity-js/assertions'
    import { Click, PageElement, By, isVisible } from '@serenity-js/web'

    // ... page element definitions as above

    describe('ARIA role selector', () => {
      it('locates an element by its accessible name', async ({ actor }) => {
        await actor.attemptsTo(
          Ensure.that(heading, isVisible()),
          Click.on(checkbox),
          Click.on(button),
        )
      })
    })

    WebdriverIO

    import { actorCalled } from '@serenity-js/core'
    import { Ensure } from '@serenity-js/assertions'
    import { Click, PageElement, By, isVisible } from '@serenity-js/web'

    // ... page element definitions as above

    describe('ARIA role selector', () => {
      it('locates an element by its accessible name', async () => {
        await actorCalled('Nick').attemptsTo(
          Ensure.that(heading, isVisible()),
          Click.on(checkbox),
          Click.on(button),
        )
      })
    })

    Parameters

    Returns Question<Promise<ByRole>>

staticexternaltagName

staticexternalxpath

Page Options