Resolve #265 - Take a screenshot

This includes reworking some of the options to support
a collection of event handler callbacks.

Author: craigfowler

CSF.Screenplay.Selenium/Reporting/ITakesScreenshotWhenPerformableFails.cs

@@ -0,0 +1,23 @@
+using CSF.Screenplay.Actors;
+
+namespace CSF.Screenplay.Selenium.Reporting
+{
+    /// <summary>
+    /// A service which subscribes to the <see cref="IHasPerformableEvents.PerformableFailed"/> event and takes a screenshot
+    /// when a performable fails.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This is useful when diagnosing and debugging failed performances.
+    /// </para>
+    /// </remarks>
+    public interface ITakesScreenshotWhenPerformableFails
+    {
+        /// <summary>
+        /// Handles the <see cref="IHasPerformableEvents.PerformableFailed"/> event.
+        /// </summary>
+        /// <param name="sender">The event sender</param>
+        /// <param name="ev">The event args</param>
+        void OnPerformableFailed(object sender, PerformableFailureEventArgs ev);
+    }
+}

CSF.Screenplay.Selenium/Reporting/PerformableFailureScreenshotTaker.cs

@@ -0,0 +1,38 @@
+using CSF.Screenplay.Actors;
+using CSF.Screenplay.Performables;
+
+namespace CSF.Screenplay.Selenium.Reporting
+{
+    /// <summary>
+    /// Implementation of <see cref="ITakesScreenshotWhenPerformableFails"/> which takes a screenshot in PNG format, with the name
+    /// <c>Auto-screenshot on performable failure</c>.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// A screenshot is only taken if the <see cref="PerformableFailureEventArgs.Exception"/> is not an instance of
+    /// <see cref="PerformableException"/> and if the <see cref="ActorEventArgs.Actor"/> has the ability <see cref="BrowseTheWeb"/>.
+    /// If the exception is a performable exception then this indicates that an 'inner' performable is the true source of the exception
+    /// and that this failure simply represents an exception bubbling upward through the performable stack.
+    /// Additionally, if the actor cannot browse the web, then they of course cannot possibly take a screenshot.
+    /// </para>
+    /// <para>
+    /// This handler internally uses the task <see cref="Tasks.TakeAndSaveScreenshot"/> and configures it to fail silently if taking
+    /// a screenshot is not supported by the current browser.  Thus, this is not certain to always result in a screenshot.
+    /// When a screenshot is taken in this way, it is saved alongside the report as an asset file.
+    /// </para>
+    /// </remarks>
+    public class PerformableFailureScreenshotTaker : ITakesScreenshotWhenPerformableFails
+    {
+        /// <inheritdoc/>
+        public void OnPerformableFailed(object sender, PerformableFailureEventArgs ev)
+        {
+            if (ev.Exception is PerformableException) return;
+            if (!((ICanPerform)ev.Actor).HasAbility<BrowseTheWeb>()) return;
+
+            var task = ev.Actor.PerformAsync(PerformableBuilder.TakeAndSaveAScreenshotIfSupported()
+                .WithTheFormat(OpenQA.Selenium.ScreenshotImageFormat.Png)
+                .WithTheName("Auto-screenshot on performable failure"));
+            task.AsTask().Wait();
+        }
+    }
+}

CSF.Screenplay.Selenium/ServiceCollectionExtensions.cs

@@ -18,12 +18,22 @@ public static IServiceCollection AddSelenium(this IServiceCollection services)
             services.AddWebDriverFactory();
             services.AddWebDriverQuirks(BrowserQuirks.GetQuirksData());
 
+            services.AddSingleton<Reporting.ITakesScreenshotWhenPerformableFails, Reporting.PerformableFailureScreenshotTaker>();
+
             services.AddTransient<Reporting.OptionsFormatter>();
             services.AddTransient<Reporting.ScreenshotFormatter>();
             services.Configure<ScreenplayOptions>(o =>
             {
                 o.ValueFormatters.Add(typeof(Reporting.OptionsFormatter));
                 o.ValueFormatters.Add(typeof(Reporting.ScreenshotFormatter));
+                
+                o.PerformanceEventHandlers.Add((eventBus, s) =>
+                {
+                    var screenshotTaker = s.GetRequiredService<Reporting.ITakesScreenshotWhenPerformableFails>();
+
+                    eventBus.PerformableFailed -= screenshotTaker.OnPerformableFailed;
+                    eventBus.PerformableFailed += screenshotTaker.OnPerformableFailed;
+                });
             });
 
             return services;

CSF.Screenplay/ScreenplayOptions.cs

@@ -38,7 +38,7 @@ public sealed class ScreenplayOptions
         /// </para>
         /// <para>
         /// Make use of <see cref="ICollection{T}.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.
+        /// It comes pre-loaded with some general-use formatters by default, in the following order.
         /// </para>
         /// <list type="number">
         /// <item><description><see cref="ToStringFormatter"/> - a default/fallback implementation which may format any value at all</description></item>
@@ -94,7 +94,7 @@ public sealed class ScreenplayOptions
         public string ReportPath { get; set; } = $"ScreenplayReport_{DateTime.UtcNow.ToString("yyyy-MM-ddTHHmmssZ", CultureInfo.InvariantCulture)}";
 
         /// <summary>
-        /// An optional callback/action which exposes the various <see cref="IHasPerformanceEvents"/> which may be subscribed-to in order to be notified
+        /// A collection of optional callbacks/actions which expose the various <see cref="IHasPerformanceEvents"/> which may be subscribed-to in order to be notified
         /// of the progress of a screenplay.
         /// </summary>
         /// <remarks>
@@ -104,12 +104,18 @@ public sealed class ScreenplayOptions
         /// If you wish, you may subscribe to these events from your own logic in order to develop new functionality or extend Screenplay.
         /// </para>
         /// <para>
-        /// 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 <see cref="ReportPath"/> means that
-        /// reporting is disabled.
+        /// There is no need to use this mechanism in order to use the Screenplay Reporting infrastructure.
+        /// Built-in logic will automatically subscribe to the event published from the reporting infrastructure.
+        /// Note that if <see cref="ReportPath"/> is a null or whitepsace-only string, the reporting infrastructure will be disabled.
+        /// </para>
+        /// <para>
+        /// This collection of configuration callbacks may be used to subscribe to the event publisher from custom Screenplay extensions, in order
+        /// be notified at particular points in the Screenplay's lifecycle.
+        /// Each extension should add a single item to this list of callbacks. In this manner, multiple extensions may coexist without worrying about
+        /// overwriting one another's event subscriptions.
         /// </para>
         /// </remarks>
-        public Action<IHasPerformanceEvents> PerformanceEventsConfig { get; set; }
+        public List<Action<IHasPerformanceEvents, IServiceProvider>> PerformanceEventHandlers { get; } = new List<Action<IHasPerformanceEvents, IServiceProvider>>();
 
         /// <summary>
         /// Gets an ordered collection of actions which should be executed when the <see cref="Screenplay"/> begins, before the first

CSF.Screenplay/ScreenplayServiceCollectionExtensions.cs

@@ -36,7 +36,10 @@ public static IServiceCollection AddScreenplay(this IServiceCollection services)
 
             services
                 .AddOptions<ScreenplayOptions>()
-                .Configure((ScreenplayOptions o, PerformanceEventBus eventBus) => o.PerformanceEventsConfig?.Invoke(eventBus));
+                .PostConfigure((ScreenplayOptions o, PerformanceEventBus eventBus, IServiceProvider s) => {
+                    foreach(var callback in o.PerformanceEventHandlers)
+                        callback.Invoke(eventBus, s);
+                });
 
             services
                 .AddSingleton<Screenplay>()