Skip to main content

externalActorLifecycleManager

Manages the lifecycle of actors on the stage, including their creation, retrieval, and tracking of which actors are in the foreground (scene-scoped) versus background (test run-scoped).

The ActorLifecycleManager is responsible for:

  • Instantiating and caching actors via the configured cast
  • Tracking which actor is currently in the spotlight (active)
  • Managing the focus area (foreground vs background) where new actors are created
  • Providing access to actors for dismissal when scenes or test runs finish

Default behaviour

By default, actors created before the actual test scenario starts, e.g. in beforeAll hooks, are placed in the 'background' focus area. When a SceneStarts event is announced, the focus switches to 'foreground'. When a SceneFinishes event is announced, foreground actors are dismissed, their abilities discarded and focus returns to 'background'.

Custom lifecycle management

Test runner adapters like @serenity-js/playwright-test, where test execution and reporting happen in separate processes, can inject a custom ActorLifecycleManager instance to control actor lifecycle programmatically.

const actorLifecycleManager = new ActorLifecycleManager(cast, clock, interactionTimeout);
const serenity = new Serenity(clock, cueTimeout, actorLifecycleManager);

// At the start of each test:
actorLifecycleManager.switchFocus('foreground');

Learn more

Index

Constructors

Methods

Constructors

externalconstructor

Methods

externalconfigure

  • configure(options: { interactionTimeout: Duration }): void

  • Configures the manager with new settings.

    Parameters

    • externaloptions: { interactionTimeout: Duration }

      Configuration options

      • externalinteractionTimeout: Duration

        The maximum time to wait for an interaction to complete

    Returns void

externalassignTo

  • assignTo(stage: Stage): void

  • Associates this manager with a Stage instance.

    This method is called automatically by the Stage during construction. It establishes the bidirectional relationship between the manager and the stage, allowing the manager to emit domain events when actors enter the stage or are spotlighted.

    Parameters

    • externalstage: Stage

      The Stage instance to associate with this manager

    Returns void

externalengage

  • engage(actors: Cast): void

  • Configures the manager to use the provided cast for preparing actors.

    @throws

    ConfigurationError If the provided cast is not defined or doesn't have a prepare method

    Parameters

    • externalactors: Cast

      The cast to use for preparing new actors

    Returns void

externalcurrentCast

  • Returns the current cast used for preparing actors.

    Returns Cast

    The currently configured cast

publicexternalactor

  • actor(name: string): Actor

  • Instantiates a new Actor or fetches an existing one identified by their name if they've already been instantiated.

    When a new actor is instantiated, an ActorEntersStage event is announced. When the spotlight shifts to a different actor (or the same actor in a different scene), an ActorSpotlighted event is announced.

    Actors are first looked up in the 'background' focus area, then in 'foreground'. New actors are always created in the current focus area.

    Parameters

    • externalname: string

      Case-sensitive name of the Actor, e.g. Alice

    Returns Actor

    The actor with the given name

publicexternalhasActorInTheSpotlight

  • hasActorInTheSpotlight(): boolean

  • Returns true if there is an Actor in the spotlight, false otherwise.

    Returns boolean

    true if an actor is currently spotlighted

publicexternalactorInTheSpotlight

  • actorInTheSpotlight(): Actor

externalswitchFocus

  • Switches the focus to the specified stage area.

    Actors created after this call will be added to the specified area. This method is typically called automatically by the Stage in response to SceneStarts and SceneFinishes events.

    Test runner adapters can also call this method directly to control actor lifecycle when scene events are not available (e.g., in Playwright Test where the reporter runs in a separate process).

    Parameters

    • externalfocus: StageFocus

      The focus area to switch to: 'foreground' for scene-scoped actors, 'background' for test run-scoped actors

    Returns void

externalcurrentFocus

  • Returns the current focus area.

    Returns StageFocus

    The current focus: 'foreground' or 'background'

externalactorsIn

  • Returns all actors in the specified focus area.

    This method is used by the Stage to retrieve actors for dismissal when scenes or test runs finish.

    Parameters

    • externalfocus: StageFocus

      The focus area to retrieve actors from

    Returns Actor[]

    An array of actors in the specified focus area

externalclearSpotlightIfIn

  • Clears the spotlight if the current actor is in the specified focus area.

    This ensures that after actors in a focus area are dismissed, the spotlight doesn't reference a dismissed actor.

    Parameters

    Returns void

externalclearActorsIn

  • Clears all actors from the specified focus area.

    This method is called by the Stage after actors have been dismissed to remove them from the internal tracking maps.

    Parameters

    Returns void

Page Options