Skip to main content


Interactions are low-level activities that encapsulate a handful of instructions for an actor on how to use their abilities to perform an individual interaction with the given interface of the system under test.

Tasks or interactions?

Because of their low-level nature, interactions are named using the vocabulary of the solution domain, and represent an individual interaction with the given interface, e.g. Click, Enter, or Send.

Interactions follow the Single Responsibility Principle which means that they do one thing and one thing only. If you’re considering implementing an “interaction” that performs more than one logical activity, e.g. checks if the button is visible and then clicks on it if is, consider using separate interactions for separate responsibilities and then composing them using a task.

Interactions are the core building block of the Screenplay Pattern, along with Actors, Abilities, Questions, and Tasks.

Learn more about:

Writing a custom interaction

Serenity/JS modules ship with dozens of interactions to help you compose your test scenarios. However, if you need to interact with a non-standard interface, or want to create a flavour of a given interaction that behaves slightly differently than the built-in version, you can easily create your own implementations using the Interaction.where factory method.

import { Actor, Interaction } from '@serenity-js/core'
import { BrowseTheWeb, Page } from '@serenity-js/web'

export const ClearLocalStorage = () =>
Interaction.where(`#actor clears local storage`, async (actor: Actor) => {
// Interaction to ClearLocalStorage directly uses Actor's ability to BrowseTheWeb
const page: Page = await
await page.executeScript(() => window.localStorage.clear())

Using a custom interaction

import { actorCalled } from '@serenity-js/core';
import { BrowseTheWebWithPlaywright } from '@serenity-js/playwright'
import { By, Navigate, PageElement } from '@serenity-js/web'
import { Ensure, equals } from '@serenity-js/assertions'
import { Browser, chromium } from 'playwright'

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

await actorCalled('Inês')
ClearLocalStorage(), // reported as "Inês clears local storage"





  • new Interaction(description: string, location?: FileSystemLocation): Interaction
  • Parameters

    • description: string
    • location: FileSystemLocation = ...

    Returns Interaction



  • Parameters

    • description: string

      Description to be used when reporting this interaction, for example #actor clears local storage. Note that #actor will be replaced with the name of the actor performing this interaction.

    • interaction: (actor: UsesAbilities & AnswersQuestions & CollectsArtifacts) => void | Promise<void>

    Returns Interaction


  • instantiationLocation(): FileSystemLocation
  • Returns the location where this Activity was instantiated.

    Returns FileSystemLocation


  • 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