externalabstractPageElement <Native_Element_Type>

Uses the actor's ability to BrowseTheWeb to identify a single Web element located by Selector.

Learn more

• Page Element Query Language
• Optional
• Switchable

Implements

• Optional
• Switchable

Index

Constructors

• constructor

Properties

• locator

Methods

• from
• of
• html
• of
• element
• elements
• closestTo
• nativeElement
• toString
• enterValue
• clearValue
• click
• doubleClick
• scrollIntoView
• hoverOver
• rightClick
• selectOptions
• selectedOptions
• dragTo
• attribute
• text
• value
• html
• switchTo
• isActive
• isClickable
• isEnabled
• isPresent
• isSelected
• isVisible

Models

• located
• createAdapter

Constructors

externalconstructor

• new PageElement<Native_Element_Type>(locator: Locator<Native_Element_Type, any>): PageElement<Native_Element_Type>

• Type parameters

  • Native_Element_Type = any

  Parameters

  • externallocator: Locator<Native_Element_Type, any>

  Returns PageElement<Native_Element_Type>

Properties

publicexternalreadonlylocator

locator: Locator<Native_Element_Type, any>

Methods

staticexternalfrom

• from<NET>(nativeElement: NET): MetaQuestionAdapter<PageElement<NET>, PageElement<NET>>

• Type parameters

  • NET

  Parameters

  • externalnativeElement: NET

  Returns MetaQuestionAdapter<PageElement<NET>, PageElement<NET>>

staticexternalof

• of<NET>(childElement: Answerable<PageElement<NET>>, parentElement: Answerable<PageElement<NET>>): MetaQuestionAdapter<PageElement<NET>, PageElement<NET>>

• Type parameters

  • NET

  Parameters

  • externalchildElement: Answerable<PageElement<NET>>

  • externalparentElement: Answerable<PageElement<NET>>

  Returns MetaQuestionAdapter<PageElement<NET>, PageElement<NET>>

staticexternalhtml

• html<NET>(): MetaQuestion<PageElement<NET>, QuestionAdapter<string>>

• A static method producing a MetaQuestion that can be used with PageElements.eachMappedTo method to extract the HTML of each element in a collection.

  Example

  import { actorCalled, Log } from '@serenity-js/core'
  import { Navigate, PageElement, By, Text } from '@serenity-js/web'
  import { includes } from '@serenity-js/assertions'
  
  await actorCalled('Debbie').attemptsTo(
    Navigate.to('https://serenity-js.org'),
  
    Log.the(
      PageElements.located(By.css('a'))
        .where(Text, includes('modular'))
        .eachMappedTo(PageElement.html())
    ),
  )

  ---

  Type parameters

  • NET

  Returns MetaQuestion<PageElement<NET>, QuestionAdapter<string>>

externalabstractof

• of(parentElement: PageElement<Native_Element_Type>): PageElement<Native_Element_Type>

• Locates a child element that:

  • matches the given selector
  • is located within the parentElement

  ---

  Parameters

  • externalparentElement: PageElement<Native_Element_Type>

  Returns PageElement<Native_Element_Type>

externalabstractelement

• element(selector: Selector): PageElement<Native_Element_Type>

• Locates a single descendant element matching the given selector, scoped within this element.

  ---

  Parameters

  • externalselector: Selector

    The selector to locate the child element

  Returns PageElement<Native_Element_Type>

externalabstractelements

• elements(selector: Selector): Promise<PageElement<Native_Element_Type>[]>

• Locates all descendant elements matching the given selector, scoped within this element.

  ---

  Parameters

  • externalselector: Selector

    The selector to locate the child elements

  Returns Promise<PageElement<Native_Element_Type>[]>

externalabstractclosestTo

• closestTo(childElement: PageElement<Native_Element_Type>): PageElement<Native_Element_Type>

• Traverses the element and its parents, heading toward the document root, until it finds a parent PageElement that matches its associated CSS selector.

  Example

  <div class="form-entry">
      <input id="username" />
      <ul class="warnings">
          <li>Username should be an email address</li>
      </ul>
  </div>

  class Username {
    static field = () =>
      PageElement.located(By.id('username'))
        .describedAs('username field')
  
    private static container = () =>
      PageElement.located(By.css('.form-entry'))
        .describedAs('form entry container')
  
    static warnings = () =>
      PageElements.located(By.css('ul.warnings li'))
        .describedAs('warnings')
        .of(
          Username.container().closestTo(Username.field())
        )
  }

  This method relies on Element: closest() API, and so is only compatible with locating parent elements specified using the following CSS selectors:

  • ByCss
  • ById
  • ByTagName

  ---

  Parameters

  • externalchildElement: PageElement<Native_Element_Type>

  Returns PageElement<Native_Element_Type>

  Learn more

  • Element: closest() method

externalnativeElement

• nativeElement(): Promise<Native_Element_Type>

• An "escape hatch" providing access to the integration tool-specific implementation of a Web element.

  ---

  Returns Promise<Native_Element_Type>

externaltoString

• toString(): string

• Returns string

externalabstractenterValue

• enterValue(value: string | number | (string | number)[]): Promise<void>

• Parameters

  • externalvalue: string | number | (string | number)[]

  Returns Promise<void>

externalabstractclearValue

• clearValue(): Promise<void>

• Returns Promise<void>

externalabstractclick

• click(): Promise<void>

• Returns Promise<void>

externalabstractdoubleClick

• doubleClick(): Promise<void>

• Returns Promise<void>

externalabstractscrollIntoView

• scrollIntoView(): Promise<void>

• Returns Promise<void>

externalabstracthoverOver

• hoverOver(): Promise<void>

• Returns Promise<void>

externalabstractrightClick

• rightClick(): Promise<void>

• Returns Promise<void>

externalabstractselectOptions

• selectOptions(...options: SelectOption[]): Promise<void>

• Parameters

  • externalrest...options: SelectOption[]

  Returns Promise<void>

externalabstractselectedOptions

• selectedOptions(): Promise<SelectOption[]>

• Returns Promise<SelectOption[]>

externalabstractdragTo

• dragTo(destination: PageElement<Native_Element_Type>): Promise<void>

• Drags this element and drops it on the destination element.

  ---

  Parameters

  • externaldestination: PageElement<Native_Element_Type>

    The element to drop this element on

  Returns Promise<void>

externalabstractattribute

• attribute(name: string): Promise<string>

• Parameters

  • externalname: string

  Returns Promise<string>

externalabstracttext

• text(): Promise<string>

• Returns Promise<string>

externalabstractvalue

• value(): Promise<string>

• Returns Promise<string>

externalabstracthtml

• html(): Promise<string>

• An instance method that resolves to the value of the outerHTML property of the underlying element.

  Example

  import { actorCalled, Log } from '@serenity-js/core'
  import { Navigate, PageElement, By } from '@serenity-js/web'
  
  await actorCalled('Debbie').attemptsTo(
    Navigate.to('https://serenity-js.org'),
  
    Log.the(
      PageElement.located(By.css('h1')).html()
    ),
  )

  ---

  Returns Promise<string>

externalabstractswitchTo

• switchTo(): Promise<SwitchableOrigin>

• Implementation of Switchable.switchTo

  When the element represents an iframe, calling this method switches the current browsing context to the given iframe context.

  When used with other types of Web Element, calling this method will have the same result as calling Element.focus().

  ---

  Returns Promise<SwitchableOrigin>

  Returns an object that allows the caller to switch back to the previous context if needed.

  Learn more

  • Switch
  • Switchable

externalabstractisActive

• isActive(): Promise<boolean>

• Resolves to true when the underlying element has focus. Otherwise, resolves to false.

  ---

  Returns Promise<boolean>

externalabstractisClickable

• isClickable(): Promise<boolean>

• Resolves to true when the underlying element can be clicked on. Otherwise, resolves to false.

  Please refer to test integration tool-specific documentation for details.

  ---

  Returns Promise<boolean>

externalabstractisEnabled

• isEnabled(): Promise<boolean>

• Resolves to true when the underlying element is not explicitly disabled

  Please refer to test integration tool-specific documentation for details.

  ---

  Returns Promise<boolean>

externalisPresent

• isPresent(): Promise<boolean>

• Implementation of Optional.isPresent

  Returns a Promise that resolves to true when the element is present in the Document Object Model (DOM), false otherwise.

  ---

  Returns Promise<boolean>

externalabstractisSelected

• isSelected(): Promise<boolean>

• Resolves to true when the underlying element:

  • has a selected attribute for <option /> elements
  • has a checked attribute for checkboxes

  Otherwise, resolves to false.

  ---

  Returns Promise<boolean>

externalabstractisVisible

• isVisible(): Promise<boolean>

• Resolves to true when the underlying element:

  • is not hidden, so doesn't have CSS style like display: none, visibility: hidden or opacity: 0
  • is within the browser viewport
  • doesn't have its centre covered by other elements

  Otherwise, resolves to false.

  ---

  Returns Promise<boolean>

Models

staticexternallocated

• located<NET>(selector: Answerable<Selector>): PageElementAdapter<NET>

• Locates a single Web element by Selector.

  The returned adapter supports fluent child element access:

  • .element(selector) — locates a single child element within this element
  • .elements(selector) — locates all matching children, returning a PageElementList with full PEQL support (.where(), .first(), .count(), .eachMappedTo(), etc.)
  • .of(parent) — rescopes this element within a different parent

  Example

  import { By, PageElement, Text } from '@serenity-js/web'
  import { Ensure, equals, includes } from '@serenity-js/assertions'
  
  const todoList = PageElement.located(By.css('.todo-list'))
    .describedAs('todo list')
  
  await actor.attemptsTo(
    Ensure.that(
      todoList.elements(By.css('.item'))
        .where(Text, includes('cheese'))
        .count(),
      equals(1),
    ),
  )

  ---

  Type parameters

  • NET

  Parameters

  • externalselector: Answerable<Selector>

  Returns PageElementAdapter<NET>

staticexternalcreateAdapter

• createAdapter<NET>(element: Answerable<PageElement<NET>>): PageElementAdapter<NET>

• Wraps any Answerable<PageElement> in a PageElementAdapter, providing .element() and .elements() for scoped child element lookups.

  Use this in Interaction Object constructors to ensure the root element supports fluent child element access regardless of whether it was constructed from a resolved PageElement (via the story fixture) or a deferred QuestionAdapter<PageElement> (via PageElement.located()):

  import type { Answerable } from '@serenity-js/core'
  import { By, PageElement } from '@serenity-js/web'
  
  class UserCard {
      private readonly rootElement;
  
      constructor(rootElement: Answerable<PageElement>) {
          this.rootElement = PageElement.createAdapter(rootElement);
      }
  
      name = () =>
          this.rootElement.element(By.css('.name')).text()
              .describedAs('user name');
  }

  ---

  Type parameters

  • NET

  Parameters

  • externalelement: Answerable<PageElement<NET>>

  Returns PageElementAdapter<NET>