Class Screenplay

Namespace

CSF.Screenplay

Assembly

CSF.Screenplay.dll

An object which represents a complete execution of Screenplay logic, which should include one or more Performance instances.

public sealed class Screenplay : IHasServiceProvider

Inheritance

object

Screenplay

Implements

IHasServiceProvider

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ScreenplayExtensions.CreateScopedPerformance(Screenplay, IList<IdentifierAndName>)

ScreenplayExtensions.ExecuteAsPerformance(Screenplay, Func<IServiceProvider, bool?>, IList<IdentifierAndName>, int)

ScreenplayExtensions.ExecuteAsPerformance(Screenplay, Func<IServiceProvider, bool?>, IList<IdentifierAndName>, CancellationToken)

ScreenplayExtensions.ExecuteAsPerformanceAsync<T>(Screenplay, IList<IdentifierAndName>, CancellationToken)

Remarks

A Screenplay, when used as a noun (an instance of this class), refers to a complete execution of the Screenplay software. A Screenplay is composed of at least one Performance and typically contains many performances.

When the Screenplay architecture is applied to automated testing, an instance of this class corresponds to a complete test run, where each test corresponds to a performance. End-user logic, such as test logic, rarely interacts directly with this class. That is because the Screenplay object is generally consumed only by integration logic.

It is recommended to create instances of this type by adding Screenplay to a dependency injection IServiceCollection via the extension method AddScreenplay(IServiceCollection, Action<ScreenplayOptions>) and then resolving an instance of this class from the service provider. Alternatively, if you do not wish to configure a service collection manually and just want an instance of this type then use the static Create(Action<IServiceCollection>, Action<ScreenplayOptions>) method.

The Screenplay object is used to create instances of Performance via the PerformanceFactory. You may wish to read a diagram showing how screenplays, performances, actors and performables relate to one another.

Constructors

Screenplay(IServiceProvider)

Initialises a new instance of Screenplay.

public Screenplay(IServiceProvider serviceProvider)

Parameters

serviceProvider IServiceProvider

A service provider

Remarks

It is unlikely that developers should be executing this constructor directly. Consider using the static factory method Create(Action<IServiceCollection>, Action<ScreenplayOptions>). Alternatively, add Screenplay to an IServiceCollection using AddScreenplay(IServiceCollection, Action<ScreenplayOptions>) and then resolve an instance of this class from the service provider built from that service collection.

Exceptions

ArgumentNullException

If serviceProvider is null.

Properties

ServiceProvider

Gets a service provider/resolver instance associated with this object.

public IServiceProvider ServiceProvider { get; }

Property Value

IServiceProvider

Methods

BeginScreenplay()

Execute this method from the consuming logic in order to inform the Screenplay architecture that the Screenplay has begun.

public void BeginScreenplay()

CompleteScreenplay()

Execute this method from the consuming logic in order to inform the Screenplay architecture that the Screenplay is now complete.

public void CompleteScreenplay()

Create(Action<IServiceCollection>, Action<ScreenplayOptions>)

Creates and returns a Screenplay, optionally including some dependency injection service customisations.

public static Screenplay Create(Action<IServiceCollection> serviceCollectionCustomisations = null, Action<ScreenplayOptions> options = null)

Parameters

serviceCollectionCustomisations Action<IServiceCollection>

An optional action which permits further customization of the service collection that is implicitly created by this method.

options Action<ScreenplayOptions>

An optional action to configure the Screenplay which is created by this method.

Returns

Screenplay

A Screenplay instance created from a new service collection.

Remarks

Use this method to create an instance of Screenplay when you are not already using an IServiceCollection. This method creates a new service collection instance, adds Screenplay to it and then creates & returns the Screenplay object instance.

If you already have an IServiceCollection and you wish to integrate Screenplay into it, then use the extension method AddScreenplay(IServiceCollection, Action<ScreenplayOptions>) instead.

ExecuteAsPerformanceAsync(Func<IServiceProvider, CancellationToken, Task<bool?>>, IList<IdentifierAndName>, CancellationToken)

Executes the specified logic as a Performance

public Task ExecuteAsPerformanceAsync(Func<IServiceProvider, CancellationToken, Task<bool?>> performanceLogic, IList<IdentifierAndName> namingHierarchy = null, CancellationToken cancellationToken = default)

Parameters

performanceLogic Func<IServiceProvider, CancellationToken, Task<bool?>>

The logic to be executed by the performance.

namingHierarchy IList<IdentifierAndName>

An optional naming hierarchy used to identify the performance.

cancellationToken CancellationToken

An optional cancellation token to abort the performance logic.

Returns

Task

A task which completes when the performance's logic has completed.

Remarks

This method is the primary entry point for beginning a Screenplay Performance. This method begins a new Dependency Injection Scope, and within that scope starts the performance, which executes the specified performance logic: performanceLogic. The return value from the performance logic should conform to the semantics of the parameter value passed to FinishPerformance(bool?).

The namingHierarchy may be used to give the performance a name, so that its results (and subsequent report) may be identified. This parameter has the same semantics as NamingHierarchy.

Note that if the performanceLogic raises a PerformableException then this method will catch that exception and not rethrow. In that case:

• An event will be raised with the event bus: IHasPerformanceEvents, specifically PerformableFailed. This will contain details of the exception which occurred; subscribers to be informed that the performance has failed.
• The performance will be immediately terminated and placed into the Failed state.

Any other exception, which does not derive from PerformableException, will not be caught by this method and will propagate outward. These exceptions will be interpreted as an error within the Screenplay architecture, since the Actor class will always catch and rethrow any exception encountered from any overload of PerformAsync, wrapped as the inner exception of a PerformableException.

Exceptions

ArgumentNullException

If the performanceLogic is null.

See Also

Performance

ScreenplayServiceCollectionExtensions