Skip to main content

Switch

Instructs an actor who has the ability to BrowseTheWeb to switch the context for future activities to a Switchable, such as a Page or a PageElement.

Please note that when the PageElement implementing Switchable represents an iframe, using Switch will result in switching the top-level browsing context to that iframe.

When the PageElement represents any other HTMLElement, using Switch sets HTMLElement#focus on the specified element. Assuming it can be focused.

Note: The focused element is the element which will receive keyboard Press events by default.

Perform activities in the context of an iframe

import { actorCalled } from '@serenity-js/core'
import { By, Click, Enter, PageElement, Switch } from '@serenity-js/web'

// Lean Page Object describing a login form, embedded in an iframe
class LoginForm {
  static iframe = () =>
    PageElement.located(By.css('iframe'))
      .describedAs('login form')

  static usernameField = () =>
    PageElement.located(By.css('[data-testid="username"]'))
      .describedAs('username field')

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

  static submitButton = () =>
    PageElement.located(By.css('button[type="submit"]'))
      .describedAs('submit button')
 }

 await actorCalled('Francesca')
   .attemptsTo(
     Switch.to(LoginForm.iframe).and(
       Enter.theValue('francesca@example.org').into(LoginForm.usernameField()),
       Enter.theValue('correct-horse-battery-staple').into(LoginForm.passwordField()),
       Click.on(LoginForm.submitButton()),
     )
   )

Perform activities in the context of another page

import { actorCalled } from '@serenity-js/core'
import { Click, Enter, Switch } from '@serenity-js/web'
import { browser } from '@wdio/globals'

await actorCalled('Francesca')
  .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
  .attemptsTo(
    Switch.to(Page.whichName(startsWith('popup'))).and(
      // perform some activities in the context of the new window

      // optionally, close the browser tab
      Page.current().close(),
    ),

    // Note that switching back to the original page happens automatically
    // after the last activity from the list finishes
  )

Perform activities in the context of a focused page element

import { Ensure, equals } from '@serenity-js/assertions'
import { actorCalled } from '@serenity-js/core'
import { Key, PageElement, Press, Switch, Value } from '@serenity-js/web'
import { browser } from '@wdio/globals'

const inputField = () =>
  PageElement.located(By.css('input'));

await actorCalled('Francesca')
  .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
  .attemptsTo(
    Switch.to(inputField()).and(
      Press.the('h', 'e', 'l', 'l', 'o'),
      Press.the(Key.Tab),
    ),
    Ensure.that(Value.of(inputField()), equals('hello'))
  )

Learn more

Hierarchy

  • Interaction
    • Switch

Index

Methods

Methods

staticto

instantiationLocation

  • instantiationLocation(): FileSystemLocation

  • Returns the location where this Activity was instantiated.

    Returns FileSystemLocation

toString

  • toString(): string

  • Generates a human-friendly description to be used when reporting this Activity.

    Note: When this activity is reported, token #actor in the description will be replaced with the name of the actor performing this Activity.

    For example, #actor clicks on a button becomes Wendy clicks on a button.

    Returns string

and

  • and(...activities: Activity[]): Task

  • Instructs the Actor to switch the context for future activities to a Switchable, such as a Page or a PageElement, perform a sequence of activities, and then switch the context back.

    Parameters

    • rest...activities: Activity[]

      A sequence of activities to perform

    Returns Task

performAs

  • performAs(actor: UsesAbilities & AnswersQuestions): Promise<void>
  • @inheritDoc

    Parameters

    • actor: UsesAbilities & AnswersQuestions

    Returns Promise<void>