Skip to main content

externalabstractBrowseTheWeb <Native_Element_Type>

The ability to BrowseTheWeb enables an actor to interact with and retrieve information from Web-based user interfaces.

BrowseTheWeb wraps test integration tools such as Playwright, Protractor, or WebdriverIO, and together with Serenity/JS Web models, such as Page or PageElement - offers a standardised way to write Web-based tests following the Screenplay Pattern.

The consistent and portable design of abstractions provided by the @serenity-js/web module also helps to make your tests portable across the various test integration tools and helps to make your test code easier to reuse across projects and teams.

Giving the actors an ability to BrowseTheWeb

To give an actor an ability to BrowseTheWeb, provide the integration tool-specific implementation via Actor.whoCan in Cast.prepare, or via Cast.where.

import { beforeEach } from 'mocha'
import { engage, Actor, Cast } from '@serenity-js/core'
import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
import { Browser, chromium } from 'playwright'

beforeEach(async () => {
  const browser = await chromium.launch({ headless: true })

  engage(
    BrowseTheWebWithPlaywright.using(browser),
  )
})

Learn more

To learn more about using Serenity/JS with your chosen test integration tool, follow their respective documentation:

Using the ability to BrowseTheWeb

To use the ability to BrowseTheWeb in a custom Interaction or Question, use the generic method BrowseTheWeb.as to retrieve it.

This generic method retrieves the integration tool-specific implementation of BrowseTheWeb present on the Actor, such as BrowseTheWebWithPlaywright or BrowseTheWebWithWebdriverIO, using Actor.abilityTo.

This decoupling mechanism helps to make your test code portable across test integration tools, since the only part of your test suite that needs to know about the test integration tool used are the actors. The rest of your test code, so tasks, interactions, and questions, remain fully agnostic of the underlying tool.

import { BrowseTheWeb, Question } from '@serenity-js/web'

const BrowserDetails = () =>
 Question.about('browser details', async actor => {
   const capabilities = await BrowseTheWeb.as(actor).browserCapabilities();
   return ${ capabilities.browserName } ${ capabilities.browserVersion }`;
 })

Pro tip: Use the specific BrowseTheWebWith<test integration tool name> to give the actor the ability, and generic BrowseTheWeb.as(actor) to retrieve it.

Learn more

Hierarchy

Index

Constructors

Methods

Constructors

externalconstructor

  • Type parameters

    • Native_Element_Type = any

    Parameters

    Returns BrowseTheWeb<Native_Element_Type>

Methods

externaltoJSON

  • Returns a JSON representation of the ability and its current state, if available. The purpose of this method is to enable reporting the state of the ability in a human-readable format, rather than to serialise and deserialise the ability itself.

    Returns SerialisedAbility

externalabilityType

  • Returns the most abstract type of this Ability instance, specifically the first class in the inheritance hierarchy that directly extends the Ability class.

    import { Ability } from '@serenity-js/core';

    class MyAbility extends Ability {}
    class MySpecialisedAbility extends MyAbility {}

    new MyAbility().abilityType();            // returns MyAbility
    new MySpecialisedAbility().abilityType(); // returns MyAbility

    Returns AbilityType<Ability>

externalcurrentPage

  • currentPage(): Promise<Page<Native_Element_Type>>

  • Returns a Page representing the currently active browser tab.

    Returns Promise<Page<Native_Element_Type>>

externalallPages

  • allPages(): Promise<Page<Native_Element_Type>[]>

  • Returns an array of pages representing all the browser tabs available in the current BrowsingSession.

    Returns Promise<Page<Native_Element_Type>[]>

externalbrowserCapabilities

Page Options