Class ScreenplayOptions
- Namespace
- CSF.Screenplay
- Assembly
- CSF.Screenplay.dll
Options model which permits the customization/configuration of Screenplay in DI.
public sealed class ScreenplayOptions- Inheritance
-
ScreenplayOptions
- Inherited Members
Remarks
Developer note: In an ideal world, this type would be registered into DI via the Options pattern: https://learn.microsoft.com/en-us/dotnet/core/extensions/options. Unfortunately, the BoDi DI container used by SpecFlow (which I wish to support with Screenplay) does not support the appropriate methods/logic to register the neccesary services for Options. This is why this object uses a somewhat homebrew version of options, without making use of the official libraries.
Properties
OnBeginScreenplayActions
Gets an ordered collection of actions which should be executed when the Screenplay begins, before the first IPerformance starts.
public List<Action<IServiceProvider>> OnBeginScreenplayActions { get; }Property Value
Remarks
Each of the actions in this configuration parameter are executed when the BeginScreenplay() method is invoked.
By default this collection contains one item. This will initialise an instance of IReporter and subscribe it to the event bus: IHasPerformanceEvents, which will activate Screenplay reporting.
You may add further callbacks if you wish, to extend Screenplay; they are executed in the order in which they appear in this collection.
OnEndScreenplayActions
Gets an ordered collection of actions which should be executed when the Screenplay finished, after the last IPerformance ends.
public List<Action<IServiceProvider>> OnEndScreenplayActions { get; }Property Value
Remarks
Each of the actions in this configuration parameter are executed when the CompleteScreenplay() method is invoked.
By default this collection contains one item, which disposes of the reporting infrastructure.
You may add further callbacks if you wish, to extend Screenplay; they are executed in the order in which they appear in this collection.
Be very wary of the use of this property. This is because it is usual for the end of a Screenplay to be triggered by the unloading of the the assemblies in the current process. If the logic triggered by this is nontrivial, it's very likely that it will be terminated early by the ending of the overall process.
PerformanceEventsConfig
An optional callback/action which exposes the various IHasPerformanceEvents which may be subscribed-to in order to be notified of the progress of a screenplay.
public Action<IHasPerformanceEvents> PerformanceEventsConfig { get; set; }Property Value
Remarks
The implementation of IHasPerformanceEvents is an event publisher which emits notifications when key evens occur during the lifetime of a Screenplay and its performances: IPerformance. If you wish, you may subscribe to these events from your own logic in order to develop new functionality or extend Screenplay.
There is no need to add an explicit subscription to any events for the reporting infrastructure. Screenplay will automatically subscribe to this object from the reporting mechanism, unless the value of ReportPath means that reporting is disabled.
ReportPath
Gets a file system path at which a Screenplay report file will be written.
public string ReportPath { get; set; }Property Value
Remarks
As a Screenplay executes each IPerformance, it accumulates data relating to those performances, via its reporting mechanism. This information is then written to a JSON-formatted report file, which is saved at the path specified by this property. Once the Screenplay has completed this file may be inspected, converted into a different format and otherwise used to learn-about and diagnose the Screenplay.
If this value is set to a relative file path, then it will be relative to the current working directory. If using Screenplay with a software testing integration, then this directory might not be easily determined.
The default value for this property is a relative file path in the current working directory, using the filename ScreenplayReport_[timestamp].json
where [timestamp] is replaced by the current UTC date & time in a format which is similar to ISO 8601, except that the : characters separating
the hours, minutes and second are omitted. This is because they are typically not legal filename characters. A sample of a Screenplay Report filename using
this default path is ScreenplayReport_2024-10-04T192345Z.json.
If this property is set to null, or an empty/whitespace-only string, or if the path is not writable, then the reporting functionality will be disabled and no report will be written.
ValueFormatters
Gets a collection of concrete Type which implement IValueFormatter, which will be used to format values which are to appear in Screenplay reports.
public IFormatterRegistry ValueFormatters { get; }Property Value
Remarks
As noted in the documentation for IFormatterRegistry, the types in this collection are considered for use in reverse-collection-order. In other words, they will be tested using CanFormat(object) from last-to-first in this collection. Thus, generalized formatters should be placed at the beginning of this collection, where more specialized formatters should be placed toward the end.
Make use of Add(T) to add new formatters to the end of this collection. It comes pre-loaded with three generalised formatters by default, in the following order.
- ToStringFormatter - a default/fallback implementation which may format any value at all
- HumanizerFormatter - a formatter for dates, times & time spans which uses the Humanizer library
- NameFormatter - which formats values that implement IHasName by emitting their name
- FormattableFormatter - which formats values that implement IFormattableValue
There is no need to register/add any types listed in this registry into dependency injection. The methods which accept a configuration action of ScreenplayOptions will iterate through this collection and add every one of the implementation types found as transient-lifetime services in dependency injection.