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

• BrowseTheWeb
• PageElement
• Optional
• Switchable

Implements

• Optional
• Switchable

Index

Constructors

• constructor

Properties

• id

Methods

• current
• whichName
• whichTitle
• whichUrl
• createPageElement
• locate
• locateAll
• navigateTo
• navigateBack
• navigateForward
• reload
• sendKeys
• executeScript
• executeAsyncScript
• lastScriptExecutionResult
• takeScreenshot
• cookie
• setCookie
• deleteAllCookies
• title
• url
• name
• isPresent
• viewportSize
• setViewportSize
• switchTo
• close
• closeOthers
• modalDialog
• toString

Constructors

externalconstructor

• new Page<Native_Element_Type>(session: BrowsingSession<Page<Native_Element_Type>>, rootLocator: RootLocator<Native_Element_Type>, modalDialogHandler: ModalDialogHandler, id: CorrelationId): Page<Native_Element_Type>

• Type parameters

  • Native_Element_Type = any

  Parameters

  • externalsession: BrowsingSession<Page<Native_Element_Type>>

  • externalrootLocator: RootLocator<Native_Element_Type>

  • externalmodalDialogHandler: ModalDialogHandler

  • externalid: CorrelationId

  Returns Page<Native_Element_Type>

Properties

publicexternalreadonlyid

id: CorrelationId

Methods

staticexternalcurrent

• current(): QuestionAdapter<Page<any>>

• Creates a QuestionAdapter representing the currently active Page.

  ---

  Returns QuestionAdapter<Page<any>>

staticexternalwhichName

• whichName(expectation: Expectation<string>): QuestionAdapter<Page<any>>

• 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

  • externalexpectation: Expectation<string>

  Returns QuestionAdapter<Page<any>>

staticexternalwhichTitle

• whichTitle(expectation: Expectation<string>): QuestionAdapter<Page<any>>

• 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

  • externalexpectation: Expectation<string>

  Returns QuestionAdapter<Page<any>>

staticexternalwhichUrl

• whichUrl(expectation: Expectation<string>): QuestionAdapter<Page<any>>

• 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

  • externalexpectation: Expectation<string>

  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

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

• Creates a PageElement, retrieving an element located by Selector.

  ---

  Parameters

  • externalselector: Selector

  Returns PageElement<Native_Element_Type>

externalabstractlocateAll

• locateAll(selector: Selector): PageElements<Native_Element_Type>

• Creates PageElement, retrieving a collection of elements located by Selector.

  ---

  Parameters

  • externalselector: Selector

  Returns PageElements<Native_Element_Type>

externalabstractnavigateTo

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

• Navigate to a given destination, specified as an absolute URL or a path relative to any base URL configured in your web test integration tool.

  Learn more

  • WebdriverIO: Configuration Options
  • Playwright: Browser
  • Playwright: Test Options
  • Protractor: Configuration

  ---

  Parameters

  • externaldestination: string

  Returns 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

  • Selenium WebDriver: JavaScript Executor
  • Page.lastScriptExecutionResult

  ---

  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

  • Selenium WebDriver: JavaScript Executor
  • Page.lastScriptExecutionResult

  ---

  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

• Returns the last result of calling Page.executeAsyncScript or Page.executeScript

  ---

  Type parameters

  • R = any

  Returns 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

• setCookie(cookieData: CookieData): Promise<void>

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

  ---

  Parameters

  • externalcookieData: CookieData

  Returns Promise<void>

externalabstractdeleteAllCookies

• deleteAllCookies(): Promise<void>

• Removes all the cookies.

  ---

  Returns Promise<void>

externalabstracttitle

• title(): Promise<string>

• Retrieves the document title of the current top-level browsing context, equivalent to calling document.title.

  Learn more

  • Mozilla Developer Network: Document title

  ---

  Returns 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>

• Implementation of Optional.isPresent

  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

• switchTo(): Promise<SwitchableOrigin>

• Implementation of Switchable.switchTo

  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

  • Switch
  • Switchable

  ---

  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

• modalDialog(): ModalDialogHandler

• Returns the ModalDialogHandler for the current Page.

  ---

  Returns ModalDialogHandler

externaltoString

• toString(): string

• Returns a description of this Page and its ID.

  ---

  Returns string