Merge pull request #329 from csf-dev/242-adapter-type-names

Resolve #242 - more useful type names

Author: craigfowler

CSF.Screenplay.Abstractions/IHasCustomTypeName.cs

@@ -0,0 +1,30 @@
+namespace CSF.Screenplay
+{
+    /// <summary>
+    /// An object which can provide a custom human-readable .NET type name.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This is particularly important when reporting, particularly when writing the name of the performable type
+    /// into a report.  Some performables may be written using the adapter or decorator patterns, in which a general-use
+    /// class wraps a specific class which implements a subset of a performable. Using <see cref="System.Type.GetType()"/>
+    /// will yield the type name of the general-use 'outer' class, which is usually not very useful on its own.
+    /// </para>
+    /// <para>
+    /// If general-use performables, such as adapters, implement this interface, then they can return more useful human-readable
+    /// type names to the consuming logic, making use of their inner/wrapped implementation type.
+    /// </para>
+    /// </remarks>
+    public interface IHasCustomTypeName
+    {
+        /// <summary>
+        /// Gets a human-readable name of the type of the current instance.
+        /// </summary>
+        /// <remarks>
+        /// <para>See the remarks on <see cref="IHasCustomTypeName"/>; this does not need to be the same as <see cref="System.Type.GetType()"/>.</para>
+        /// </remarks>
+        /// <returns>A human-readable name of the .NET type of the current instance, which could (for example) be
+        /// qualified with additional context, such as a wrapped implementation.</returns>
+        string GetHumanReadableTypeName();
+    }
+}

CSF.Screenplay.Selenium/Actions/SingleElementPerformableAdapter.cs

@@ -18,7 +18,7 @@ namespace CSF.Screenplay.Selenium.Actions
     /// to fetch it using the WebDriver more than once.  As such, instances of this adapter (like all performables) should not be re-used.
     /// </para>
     /// </remarks>
-    public class SingleElementPerformableAdapter : IPerformable, ICanReport
+    public class SingleElementPerformableAdapter : IPerformable, ICanReport, IHasCustomTypeName
     {
         readonly ISingleElementPerformable performable;
         readonly ITarget target;
@@ -38,6 +38,10 @@ public ValueTask PerformAsAsync(ICanPerform actor, CancellationToken cancellatio
             return performable.PerformAsAsync(actor, actor.GetAbility<BrowseTheWeb>().WebDriver, lazyElement, cancellationToken);
         }
 
+        /// <inheritdoc/>
+        public string GetHumanReadableTypeName()
+            => $"{performable.GetType().FullName}, via {nameof(SingleElementPerformableAdapter)}";
+
         /// <summary>
         /// Initializes a new instance of the <see cref="SingleElementPerformableAdapter"/> class with the specified performable and target.
         /// </summary>

CSF.Screenplay.Selenium/Questions/ElementCollectionPerformableWithResultAdapter.cs

@@ -19,7 +19,7 @@ namespace CSF.Screenplay.Selenium.Questions
     /// to fetch it using the WebDriver more than once.  As such, instances of this adapter (like all performables) should not be re-used.
     /// </para>
     /// </remarks>
-    public class ElementCollectionPerformableWithResultAdapter<TResult> : IPerformableWithResult<IReadOnlyList<TResult>>, ICanReport
+    public class ElementCollectionPerformableWithResultAdapter<TResult> : IPerformableWithResult<IReadOnlyList<TResult>>, ICanReport, IHasCustomTypeName
     {
         readonly IElementCollectionPerformableWithResult<TResult> performable;
         readonly ITarget target;
@@ -39,6 +39,10 @@ public ValueTask<IReadOnlyList<TResult>> PerformAsAsync(ICanPerform actor, Cance
             return performable.PerformAsAsync(actor, actor.GetAbility<BrowseTheWeb>().WebDriver, lazyElements, cancellationToken);
         }
 
+        /// <inheritdoc/>
+        public string GetHumanReadableTypeName()
+            => $"{performable.GetHumanReadableTypeName()}, via {nameof(ElementCollectionPerformableWithResultAdapter)}";
+
         /// <summary>
         /// Initializes a new instance of the <see cref="ElementCollectionPerformableWithResultAdapter{TResult}"/> class with the specified performable and target.
         /// </summary>

CSF.Screenplay.Selenium/Questions/ElementCollectionQuery.cs

@@ -57,6 +57,10 @@ public ReportFragment GetReportFragment(Actor actor, Lazy<SeleniumElementCollect
         public ValueTask<IReadOnlyList<TResult>> PerformAsAsync(ICanPerform actor, IWebDriver webDriver, Lazy<SeleniumElementCollection> elements, CancellationToken cancellationToken = default)
             => new ValueTask<IReadOnlyList<TResult>>(elements.Value.Select(query.GetValue).ToList());
 
+        /// <inheritdoc/>
+        public string GetHumanReadableTypeName()
+            => $"{query.GetType().FullName}, via {nameof(ElementCollectionQuery)}";
+
         /// <summary>
         /// Initializes a new instance of the <see cref="ElementCollectionQuery{TResult}"/> class with the specified query.
         /// </summary>

CSF.Screenplay.Selenium/Questions/FindElement.cs

@@ -85,6 +85,9 @@ Lazy<IHasSearchContext> GetLazyElement(ICanPerform actor)
             return new Lazy<IHasSearchContext>(() => searchContext);
         }
 
+        /// <inheritdoc/>
+        public string GetHumanReadableTypeName() => GetType().FullName;
+
         /// <summary>
         /// Initializes a new instance of the <see cref="FindElement"/> class.
         /// </summary>

CSF.Screenplay.Selenium/Questions/FindElements.cs

@@ -84,6 +84,9 @@ Lazy<IHasSearchContext> GetLazyElement(ICanPerform actor)
             return new Lazy<IHasSearchContext>(() => searchContext);
         }
 
+        /// <inheritdoc/>
+        public string GetHumanReadableTypeName() => GetType().FullName;
+
         /// <summary>
         /// Initializes a new instance of the <see cref="FindElements"/> class.
         /// </summary>

CSF.Screenplay.Selenium/Questions/GetShadowRootNatively.cs

@@ -34,6 +34,9 @@ public class GetShadowRootNatively : ISingleElementPerformableWithResult<Element
         public ReportFragment GetReportFragment(Actor actor, Lazy<SeleniumElement> element, IFormatsReportFragment formatter)
             => formatter.Format("{Actor} gets the Shadow Root node from {Element} using the native Selenium technique", actor, element.Value);
 
+        /// <inheritdoc/>
+        public string GetHumanReadableTypeName() => GetType().FullName;
+
         /// <inheritdoc/>
         public ValueTask<Elements.ShadowRoot> PerformAsAsync(ICanPerform actor, IWebDriver webDriver, Lazy<SeleniumElement> element, CancellationToken cancellationToken = default)
         {

CSF.Screenplay.Selenium/Questions/GetShadowRootWithJavaScript.cs

@@ -35,6 +35,9 @@ public class GetShadowRootWithJavaScript : ISingleElementPerformableWithResult<E
         public ReportFragment GetReportFragment(Actor actor, Lazy<SeleniumElement> element, IFormatsReportFragment formatter)
             => formatter.Format("{Actor} gets the Shadow Root node from {Element} using JavaScript", actor, element.Value);
 
+        /// <inheritdoc/>
+        public string GetHumanReadableTypeName() => GetType().FullName;
+
         /// <inheritdoc/>
         public async ValueTask<Elements.ShadowRoot> PerformAsAsync(ICanPerform actor, IWebDriver webDriver, Lazy<SeleniumElement> element, CancellationToken cancellationToken = default)
         {

CSF.Screenplay.Selenium/Questions/IElementCollectionPerformableWithResult.cs

@@ -21,7 +21,7 @@ namespace CSF.Screenplay.Selenium.Questions
     /// <see cref="SingleElementPerformableWithResultAdapter{TResult}"/>.
     /// </para>
     /// </remarks>
-    public interface IElementCollectionPerformableWithResult<TResult> : ICanReportForElements
+    public interface IElementCollectionPerformableWithResult<TResult> : ICanReportForElements, IHasCustomTypeName
     {
         /// <summary>
         /// Counterpart to <see cref="IPerformableWithResult{TResult}.PerformAsAsync(ICanPerform, CancellationToken)"/> except that this method also offers

CSF.Screenplay.Selenium/Questions/ISingleElementPerformableWithResult.cs

@@ -20,7 +20,7 @@ namespace CSF.Screenplay.Selenium.Questions
     /// <see cref="SingleElementPerformableWithResultAdapter{TResult}"/>.
     /// </para>
     /// </remarks>
-    public interface ISingleElementPerformableWithResult<TResult> : ICanReportForElement
+    public interface ISingleElementPerformableWithResult<TResult> : ICanReportForElement, IHasCustomTypeName
     {
         /// <summary>
         /// Counterpart to <see cref="IPerformableWithResult{TResult}.PerformAsAsync(ICanPerform, CancellationToken)"/> except that this method also offers