Skip to main content

externalabstractPage <Native_Element_Type>

Serenity/JS Screenplay Pattern-style model that enables interactions with a Web page rendered in a Web browser tab.

Referring to the current page

import { Ensure, endsWith } from '@serenity-js/assertions'
import { actorCalled } from '@serenity-js/core'
import { Navigate, Page } from '@serenity-js/web'

await actorCalled('Serena').attemptsTo(
  Navigate.to('https://serenity-js.org'),
  Ensure.that(Page.current().title(), endsWith('Serenity/JS')),
)

Switching to another open page

import { Ensure, equals, includes, startsWith } from '@serenity-js/assertions'
import { actorCalled } from '@serenity-js/core'
import { Navigate, Page, Switch, Text } from '@serenity-js/web'

const Navigation = {
  linkTo = (name: Answerable<string>) =>
    PageElements.located(By.css('nav a'))
      .where(Text, includes(name))
      .first()
}

await actorCalled('Serena').attemptsTo(
  Navigate.to('https://serenity-js.org'),
  Click.on(Navigation.linkTo('GitHub')),

  Switch.to(Page.whichUrl(startsWith('https://github.com')))

  Ensure.that(
    Page.current().url().href,
    equals('https://github.com/serenity-js/serenity-js')
  ),
)

Retrieving information about another open page

You can retrieve information about another open page without having to explicitly switch to it:

import { Ensure, equals, includes, startsWith } from '@serenity-js/assertions'
import { actorCalled } from '@serenity-js/core'
import { Navigate, Page, Text } from '@serenity-js/web'

const Navigation = {
  linkTo = (name: Answerable<string>) =>
    PageElements.located(By.css('nav a'))
      .where(Text, includes(name))
      .first()
}

await actorCalled('Serena').attemptsTo(
  Navigate.to('https://serenity-js.org'),
  Click.on(Navigation.linkTo('GitHub')),
  Ensure.that(
    Page.whichUrl(startsWith('https://github.com')).url().href,
    equals('https://github.com/serenity-js/serenity-js')
  ),
)

Performing activities in the context of another page

import { Ensure, equals, includes, startsWith } from '@serenity-js/assertions'
import { actorCalled } from '@serenity-js/core'
import { Navigate, Page, Text } from '@serenity-js/web'

const Navigation = {
  linkTo = (name: Answerable<string>) =>
    PageElements.located(By.css('nav a'))
      .where(Text, includes(name))
      .first()
}

await actorCalled('Serena').attemptsTo(

  // Serenity/JS GitHub repository opens in a new browser tab
  Navigate.to('https://serenity-js.org'),
  Click.on(Navigation.linkTo('GitHub')),

  // Switch to the newly opened page and perform an assertion
  Switch.to(Page.whichUrl(startsWith('https://github.com')))
    .and(
      Ensure.that(
        Page.current().url().href,
        equals('https://github.com/serenity-js/serenity-js')
      )
    ),
  // Automatically switch back to the original page

  Ensure.that(Page.current().url().href, equals('https://serenity-js.org'),
)

Learn more

Implements

Index

Constructors

Properties

Methods

Constructors

externalconstructor

  • Type parameters

    • Native_Element_Type = any

    Parameters

    Returns Page<Native_Element_Type>

Properties

publicexternalreadonlyid

id: CorrelationId

Methods

staticexternalcurrent

staticexternalwhichName

  • Creates a QuestionAdapter that resolves to a Page which Page.name meets the expectation.

    Switching to a page with the desired name

    import { includes } from '@serenity-js/assertions'
    import { actorCalled } from '@serenity-js/core'
    import { Switch } from '@serenity-js/web'

    actorCalled('Bernie').attemptsTo(
      Switch.to(Page.whichName(includes(`photo-gallery`))),
    )

    Parameters

    Returns QuestionAdapter<Page<any>>

staticexternalwhichTitle

  • Creates a QuestionAdapter that resolves to a Page which Page.title meets the expectation.

    Switching to a page with the desired title

    import { includes } from '@serenity-js/assertions'
    import { actorCalled } from '@serenity-js/core'
    import { Switch } from '@serenity-js/web'

    actorCalled('Bernie').attemptsTo(
      Switch.to(Page.whichTitle(includes(`Summer collection`))),
    )

    Parameters

    Returns QuestionAdapter<Page<any>>

staticexternalwhichUrl

  • Creates a QuestionAdapter that resolves to a Page which Page.url meets the expectation.

    Switching to a page with the desired URL

    import { endsWith } from '@serenity-js/assertions'
    import { actorCalled } from '@serenity-js/core'
    import { Switch } from '@serenity-js/web'

    actorCalled('Bernie').attemptsTo(
      Switch.to(Page.whichUrl(endsWith(`/gallery.html`))),
    )

    Parameters

    Returns QuestionAdapter<Page<any>>

externalabstractcreatePageElement

  • createPageElement(nativeElement: Native_Element_Type): PageElement<Native_Element_Type>

  • Creates a PageElement wrapping a native element.

    Parameters

    • externalnativeElement: Native_Element_Type

    Returns PageElement<Native_Element_Type>

externalabstractlocate

externalabstractlocateAll

externalabstractnavigateTo

  • navigateTo(destination: string): Promise<void>

externalabstractnavigateBack

  • navigateBack(): Promise<void>

  • Causes the browser to traverse one step backward in the joint session history of the current Page (the current top-level browsing context).

    This is equivalent to pressing the back button in the browser UI, or calling window.history.back.

    Returns Promise<void>

externalabstractnavigateForward

  • navigateForward(): Promise<void>

  • Causes the browser to traverse one step forward in the joint session history of the current Page (the current top-level browsing context).

    This is equivalent to pressing the back button in the browser UI, or calling window.history.forward.

    Returns Promise<void>

externalabstractreload

  • reload(): Promise<void>

  • Causes the browser to reload the Page in the current top-level browsing context.

    Returns Promise<void>

externalabstractsendKeys

  • sendKeys(keys: (string | Key)[]): Promise<void>

  • Send a sequence of Key strokes to the active element.

    Parameters

    • externalkeys: (string | Key)[]

      Keys to enter

    Returns Promise<void>

externalabstractexecuteScript

  • executeScript<Result, InnerArguments>(script: string | (...parameters: InnerArguments) => Result, ...args: InnerArguments): Promise<Result>

  • Schedules a command to execute JavaScript in the context of the currently selected frame or window.

    The script fragment will be executed as the body of an anonymous function. If the script is provided as a function object, that function will be converted to a string for injection into the target window.

    Any arguments provided in addition to the script will be included as script arguments and may be referenced using the arguments object. Arguments may be a boolean, number, string or WebElement. Arrays and objects may also be used as script arguments as long as each item adheres to the types previously mentioned.

    The script may refer to any variables accessible from the current window. Furthermore, the script will execute in the window's context, thus document may be used to refer to the current document. Any local variables will not be available once the script has finished executing, though global variables will persist.

    If the script has a return value (i.e. if the script contains a return statement), then the following steps will be taken for resolving this functions return value:

    • For a PageElement, the value will resolve to a HTMLElement
    • null and undefined return values will resolve to null
    • boolean, number, and string values will resolve as is
    • Functions will resolve to their string representation
    • For arrays and objects, each member item will be converted according to the rules above

    Use injected JavaScript to retrieve information about a HTMLElement

    BrowseTheWeb.as(actor).executeAsyncScript(`
      return arguments[0].tagName;
    `, PageElement.located(By.css('h1')).describedAs('header'))

    // returns a Promise that resolves to 'h1'

    Learn more

    Type parameters

    • Result
    • InnerArguments: any[]

    Parameters

    • externalscript: string | (...parameters: InnerArguments) => Result
      • externalrest...args: InnerArguments

      Returns Promise<Result>

    externalabstractexecuteAsyncScript

    • executeAsyncScript<Result, Parameters>(script: string | (...args: [...parameters: Parameters[], callback: (result: Result) => void]) => void, ...args: Parameters): Promise<Result>

    • Schedules a command to execute asynchronous JavaScript in the context of the currently selected frame or window.

      The script fragment will be executed as the body of an anonymous function. If the script is provided as a function object, that function will be converted to a string for injection into the target window.

      Any arguments provided in addition to the script will be included as script arguments and may be referenced using the arguments object. Arguments may be a boolean, number, string or WebElement Arrays and objects may also be used as script arguments as long as each item adheres to the types previously mentioned.

      Unlike executing synchronous JavaScript with Page.executeScript, scripts executed with this function must explicitly signal they are finished by invoking the provided callback.

      This callback will always be injected into the executed function as the last argument, and thus may be referenced with arguments[arguments.length - 1].

      The following steps will be taken for resolving this functions return value against the first argument to the script's callback function:

      • For a PageElement, the value will resolve to a HTMLElement
      • null and undefined return values will resolve to null
      • boolean, number, and string values will resolve as is
      • Functions will resolve to their string representation
      • For arrays and objects, each member item will be converted according to the rules above

      Perform a sleep in the browser under test>

      BrowseTheWeb.as(actor).executeAsyncScript(`
        var delay    = arguments[0];
        var callback = arguments[arguments.length - 1];

        window.setTimeout(callback, delay);
      `, 500)

      Return a value asynchronously

      BrowseTheWeb.as(actor).executeAsyncScript(`
        var callback = arguments[arguments.length - 1];

        callback('some return value')
      `).then(value => doSomethingWithThe(value))

      Learn more

      Type parameters

      • Result
      • Parameters: any[]

      Parameters

      • externalscript: string | (...args: [...parameters: Parameters[], callback: (result: Result) => void]) => void
        • externalrest...args: Parameters

        Returns Promise<Result>

      externalabstractlastScriptExecutionResult

      • lastScriptExecutionResult<R>(): R

      externalabstracttakeScreenshot

      • takeScreenshot(): Promise<string>

      • Take a screenshot of the top-level browsing context's viewport.

        @throws

        BrowserWindowClosedError When the page you're trying to take the screenshot of has already been closed

        Returns Promise<string>

        A promise that will resolve to a base64-encoded screenshot PNG

      externalabstractcookie

      • cookie(name: string): Promise<Cookie>

      • Retrieves a cookie identified by name and visible to this Page.

        Parameters

        • externalname: string

        Returns Promise<Cookie>

      externalabstractsetCookie

      • Adds a single cookie with CookieData to the cookie store associated with the active Page's address.

        Parameters

        Returns Promise<void>

      externalabstractdeleteAllCookies

      • deleteAllCookies(): Promise<void>

      • Removes all the cookies.

        Returns Promise<void>

      externalabstracttitle

      • title(): Promise<string>

      externalabstracturl

      • url(): Promise<URL>

      • Retrieves the URL of the current top-level browsing context.

        Returns Promise<URL>

      externalabstractname

      • name(): Promise<string>

      • Retrieves the name of the current top-level browsing context.

        Returns Promise<string>

      externalabstractisPresent

      • isPresent(): Promise<boolean>

      • Checks if a given window / tab / page is open and can be switched to, e.g. it's not closed.

        Returns Promise<boolean>

      externalabstractviewportSize

      • viewportSize(): Promise<{ width: number; height: number }>

      • Returns the actual viewport size available for the given page, excluding any scrollbars.

        Returns Promise<{ width: number; height: number }>

      externalabstractsetViewportSize

      • setViewportSize(size: { width: number; height: number }): Promise<void>

      • Sets ths size of the visible viewport to desired dimensions.

        Parameters

        • externalsize: { width: number; height: number }
          • externalwidth: number
          • externalheight: number

        Returns Promise<void>

      externalswitchTo

      • Switches the current browsing context to the given page and returns an object that allows the caller to switch back to the previous context when needed.

        Learn more

        Returns Promise<SwitchableOrigin>

      externalabstractclose

      • close(): Promise<void>

      • Closes this page.

        Returns Promise<void>

      externalabstractcloseOthers

      • closeOthers(): Promise<void>

      • Closes any open pages, except for this one.

        Returns Promise<void>

      externalmodalDialog

      externaltoString

      • toString(): string

      • Returns a description of this Page and its ID.

        Returns string

      Page Options