Interface IStage

Namespace

CSF.Screenplay

Assembly

CSF.Screenplay.Abstractions.dll

The stage facilitates a contextual Actor who is 'in the spotlight' - a currently-active actor

public interface IStage

Extension Methods

StageExtensions.Spotlight<TPersona>(IStage)

Examples

Consider a IPerformance which is based upon the following, which is described in Gherkin BDD syntax: https://cucumber.io/docs/gherkin/.

Given Jack can wash dishes
  And Jack has filled a basin with hot water
 When Jack washes a dinner plate
 Then Jack should have one clean dinner plate

This format of test is perfectly functional, but each performable item needed to be qualified with the actor's name: "Jack". This could be more human-readable but also more reusable from a code perspective if we had a context of a 'current' actor, who we could refer to with a pronoun. With such a concept, our gherkin could read "he has" or "he washes" and could accept any one of a variety of pronouns.

Remarks

The Stage is an optional but recommended component of Screenplay, useful when a IPerformance involves repeated use of an Actor. It facilitates the use of passive voice and the use of pronouns within the logic of performances without needing to frequently repeat the Name of the actor.

It is often more consise and easier to understand performances when some of the steps use the passive voice. In order to do this, there must be a concept which allows us to discern "which actor is acting at the moment". The stage provides this via the concept of a Spotlight. Either zero or one actor may be in the spotlight at any given time. If a new actor is placed in the spotlight then the previous actor is removed from it.

Spotlighting an actor facilitates performance steps which use 'the current actor' instead of a specific named actor.

The lifetime of a stage instance is equal to the lifetime of the current IPerformance. An actor in the spotlight will be consistent across the lifetime of the performance but will be independent of other performances.

In a Screenplay the stage is a dependency-injectable service which may be used within your performances. The stage implicitly consumes some functionality from the ICast. If Spotlight(IPersona) is used, then the Actor to put in the spotlight will implicitly be retrieved using the cast, via GetActor(IPersona).

Properties

Cast

Gets the cast to which the current stage is linked.

ICast Cast { get; }

Property Value

ICast

Methods

GetSpotlitActor()

Gets the actor which is currently in the spotlight.

Actor GetSpotlitActor()

Returns

Actor

The actor who has previously been placed in the spotlight, or a null reference if there is presently no actor in the spotlight.

Spotlight(Actor)

Places the specified actor into the spotlight, making them 'the current actor' on this stage.

void Spotlight(Actor actor)

Parameters

actor Actor

Remarks

A maximum of one actor may be in the spotlight at any time, so if a different actor is already in the spotlight as this method is used, then they will be implicitly removed and replaced by the specified actor. The actor who is in the spotlight may be retrieved by calling GetSpotlitActor().

If the specified actor is already in the spotlight then this method will have no effect, the actor will remain in the spotlight.

To remove an actor from the spotlight without replacing them, use TurnSpotlightOff().

Exceptions

ArgumentNullException

If the actor is null.

Spotlight(IPersona)

Places an actor matching the specified persona into the spotlight, making them 'the current actor' on this stage.

Actor Spotlight(IPersona persona)

Parameters

persona IPersona

Returns

Actor

The actor instance which was placed into the spotlight.

Remarks

A maximum of one actor may be in the spotlight at any time, so if a different actor is already in the spotlight as this method is used, then they will be implicitly removed and replaced by the actor derived from the persona. The actor who is in the spotlight may be retrieved by calling GetSpotlitActor().

If actor indicated by the persona is already in the spotlight then this method will have no effect, the actor will remain in the spotlight.

When spotlighting a persona, the actor instance is retrieved from an ICast based upon that same persona. See GetActor(IPersona) for more information.

To remove an actor from the spotlight without replacing them, use TurnSpotlightOff().

Consider using Spotlight<TPersona>(IStage) instead of this method; the generic version takes care of resolving the persona instance from dependency injection for you.

Exceptions

ArgumentNullException

If the actor is null.

TurnSpotlightOff()

Removes any existing actor from the spotlight, ensuring that no actor is in the spotlight.

Actor TurnSpotlightOff()

Returns

Actor

If an actor was previously in the spotlight, and has now been removed, then this method returns that actor; otherwise it will return a null reference.

Remarks

If there was already no actor in the spotlight when this method is executed then it will have no effect, the spotlight will remain empty and this method will return null.

See Also

ICast