Writing new Report value formtters

To get the best results when Screenplay writes a report, the wording in the reports should be human-readable and avoid language that relates to .NET. Reports are built from report fragments, accumulated during each performance.

Baseline reporting functionality

It's strongly recommended that all performables and all abilities implement the ICanReport interface. This allows these types to generate report fragments when they are performed-by or granted-to to Actors. Performables and abilities which do not implement ICanReport will use a default/fallback report template which is likely to produce sub-optimal results.

Formatting values

As noted in the documentation for report fragments, they are written using template strings which include a placeholder syntax. Values must be inserted into these placeholders to get the final report; this is performed by IFormatsReportFragment. There are a few mechanisms by which IFormatsReportFragments converts values to human-readable strings; you are encouraged to pick the most suitable for each scenario.

You may extend Screenplay with new implementations of IHasName, IFormattableValue and/or IValueFormatter.

Objects with names

Actors and some other types implement the interface IHasName. This is suitable for objects which would always appear the same in any report. For example, the Actor "Joe" is always "Joe"; there's nothing more to their name than that.

Self-formattable values

Types which implement IFormattableValue have a FormatForReport() method which returns a human-readable formatted representation of that object, suitable for appearance in reports.

Use this if the object's state must be used to get the reporting representation, but does not require any external dependencies or services. Obviously, you must have control over the type - the ability to add IFormattableValue to its interfaces - in order to use this technique.

Value formatters

Value formatters are external objects which are able to format objects, without needing to make any changes to the object-to-be-formatted. Value formatters implement the interface IValueFormatter and must be added to dependency injection, as well as registered with the IFormatterRegistry. The easiest way to perform both of these is to add the Type of the value formatter implementation to ScreenplayOptions.ValueFormatters when creating the Screenplay. Any types added here will automatically be included in the formatter registry and added to DI when the Screenplay is built.

Use this technique when either you require external services from dependendency injection to format the object, or if you are unable/unwilling to have the type to be formatted implement IFormattableValue.

Use ToString()

The least optimal mechanism of formatting values in a report is to rely on the built-in (or an overridden) Object.ToString() method. Whilst this will work in reports, it is intended as fallback functionality for types which are not covered by any of the techniques above.

The results of the ToString() method are often a very poor choice for reports.