Add text-trimming functionality

Fixes #276

This now means that by default, when reading text from the browser,
leading and trailing whitespace will be trimmed.
This will help us out in Safari, where unwanted whitespace gets
returned by the browser.

Author: craigfowler

CSF.Screenplay.Selenium/Builders/QueryPredicatePrototypeBuilder.cs

@@ -230,6 +230,20 @@ public QueryPredicatePrototype<Size> Size(Size value)
         /// <summary>
         /// Creates a query predicate based on the element's text content.
         /// </summary>
+        /// <remarks>
+        /// <para>
+        /// When reading text from the web browser, this predicate will trim leading/trailing whitespace from that text before comparing it.
+        /// This is because some browsers (Safari)
+        /// include whitespace at the beginning/end of text read from the browser, which isn't visible to the end user.  This is typically the 
+        /// space which is inherent in the markup, but which browsers ignore when actually displaying content.
+        /// </para>
+        /// <para>
+        /// Trimming it by default ensures that Screenplay reproduces functionality reliably cross-browser.
+        /// If this causes an issue and you would like the leading/trailing whitespace included the use
+        /// <see cref="TextWithoutTrimmingWhitespace(string)"/> instead.
+        /// Note that you may see different results in browsers which include leading/trailing whitespace anyway.
+        /// </para>
+        /// </remarks>
         /// <param name="predicate">The predicate to apply to the element's text.</param>
         /// <returns>A <see cref="QueryPredicatePrototype{String}"/>, which may be converted to a full predicate.</returns>
         public QueryPredicatePrototype<string> Text(Func<string,bool> predicate)
@@ -238,11 +252,55 @@ public QueryPredicatePrototype<string> Text(Func<string,bool> predicate)
         /// <summary>
         /// Creates a query predicate based on the element's text content.
         /// </summary>
+        /// <remarks>
+        /// <para>
+        /// When reading text from the web browser, this predicate will trim leading/trailing whitespace from that text before comparing it.
+        /// This is because some browsers (Safari)
+        /// include whitespace at the beginning/end of text read from the browser, which isn't visible to the end user.  This is typically the 
+        /// space which is inherent in the markup, but which browsers ignore when actually displaying content.
+        /// </para>
+        /// <para>
+        /// Trimming it by default ensures that Screenplay reproduces functionality reliably cross-browser.
+        /// If this causes an issue and you would like the leading/trailing whitespace included the use
+        /// <see cref="TextWithoutTrimmingWhitespace(string)"/> instead.
+        /// Note that you may see different results in browsers which include leading/trailing whitespace anyway.
+        /// </para>
+        /// </remarks>
         /// <param name="value">The value to compare against the element's text.</param>
         /// <returns>A <see cref="QueryPredicatePrototype{String}"/>, which may be converted to a full predicate.</returns>
         public QueryPredicatePrototype<string> Text(string value)
             => CreatePrototype(new TextQuery(), Spec.Func<string>(x => x == value), t => $"{t.Name} has text equal to '{value}'");
 
+        /// <summary>
+        /// Creates a query predicate based on the element's text content.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// When reading text from the web browser, this predicate will leave any leading/trailing whitespace in the text
+        /// without trimming it.
+        /// Note that you may see different results in browsers which include leading/trailing whitespace anyway.
+        /// </para>
+        /// </remarks>
+        /// <param name="predicate">The predicate to apply to the element's text.</param>
+        /// <returns>A <see cref="QueryPredicatePrototype{String}"/>, which may be converted to a full predicate.</returns>
+        public QueryPredicatePrototype<string> TextWithoutTrimmingWhitespace(Func<string,bool> predicate)
+            => CreatePrototype(new TextQuery(false), Spec.Func(predicate), t => $"{t.Name} has text matching a predicate");
+
+        /// <summary>
+        /// Creates a query predicate based on the element's text content, without trimming leading/trailing whitespace.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// When reading text from the web browser, this predicate will leave any leading/trailing whitespace in the text
+        /// without trimming it.
+        /// Note that you may see different results in browsers which include leading/trailing whitespace anyway.
+        /// </para>
+        /// </remarks>
+        /// <param name="value">The value to compare against the element's text.</param>
+        /// <returns>A <see cref="QueryPredicatePrototype{String}"/>, which may be converted to a full predicate.</returns>
+        public QueryPredicatePrototype<string> TextWithoutTrimmingWhitespace(string value)
+            => CreatePrototype(new TextQuery(false), Spec.Func<string>(x => x == value), t => $"{t.Name} has text equal to '{value}'");
+
         /// <summary>
         /// Creates a query predicate based on the element's DOM <c>value</c>.
         /// </summary>

CSF.Screenplay.Selenium/Builders/TextMultiQueryBuilder.cs

@@ -0,0 +1,104 @@
+using System.Collections.Generic;
+using CSF.Screenplay.Performables;
+using CSF.Screenplay.Selenium.Elements;
+using CSF.Screenplay.Selenium.Queries;
+using CSF.Screenplay.Selenium.Questions;
+
+namespace CSF.Screenplay.Selenium.Builders
+{
+    /// <summary>
+    /// Builder type for a performable that gets a collection of text values.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// The purpose of this builder is to enable or disable the trimming of whitespace characters at the beginning or end of the returned text.
+    /// </para>
+    /// </remarks>
+    public class TextMultiQueryBuilder : IGetsPerformableWithResult<IReadOnlyList<string>>
+    {
+        readonly ITarget elements;
+        bool trimWhitespace = true;
+
+        /// <summary>
+        /// Configures the performable to disable the trimming of whitespace characters at the beginning or end of the returned text.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Trimming of whitespace at the beginning/end of text is enabled by default.  This is because some browsers (Safari)
+        /// include whitespace at the beginning/end of text read from the browser, which isn't visible to the end user.  This is typically the 
+        /// space which is inherent in the markup, but which browsers ignore when actually displaying content.
+        /// </para>
+        /// <para>
+        /// Trimming it by default ensures that Screenplay reproduces functionality reliably cross-browser.
+        /// If this causes an issue and you would like the leading/trailing whitespace included in the result then use this method.
+        /// Note that you may see different results in browsers which include leading/trailing whitespace anyway.
+        /// </para>
+        /// </remarks>
+        /// <returns>The current instance of the builder, so calls may be chained.</returns>
+        public TextMultiQueryBuilder WithoutTrimmingWhitespace()
+        {
+            trimWhitespace = false;
+            return this;
+        }
+
+        IPerformableWithResult<IReadOnlyList<string>> IGetsPerformableWithResult<IReadOnlyList<string>>.GetPerformable()
+            => ElementCollectionPerformableWithResultAdapter.From(ElementCollectionQuery.From(new TextQuery(trimWhitespace)), elements);
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="TextMultiQueryBuilder"/> class.
+        /// </summary>
+        /// <param name="elements">The target elements to query.</param>
+        public TextMultiQueryBuilder(ITarget elements)
+        {
+            this.elements = elements ?? throw new System.ArgumentNullException(nameof(elements));
+        }
+    }
+
+    /// <summary>
+    /// Builder type for a performable that gets a single text value.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// The purpose of this builder is to enable or disable the trimming of whitespace characters at the beginning or end of the returned text.
+    /// </para>
+    /// </remarks>
+    public class TextQueryBuilder : IGetsPerformableWithResult<string>
+    {
+        readonly ITarget element;
+        bool trimWhitespace = true;
+
+        /// <summary>
+        /// Configures the performable to disable the trimming of whitespace characters at the beginning or end of the returned text.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Trimming of whitespace at the beginning/end of text is enabled by default.  This is because some browsers (Safari)
+        /// include whitespace at the beginning/end of text read from the browser, which isn't visible to the end user.  This is typically the 
+        /// space which is inherent in the markup, but which browsers ignore when actually displaying content.
+        /// </para>
+        /// <para>
+        /// Trimming it by default ensures that Screenplay reproduces functionality reliably cross-browser.
+        /// If this causes an issue and you would like the leading/trailing whitespace included in the result then use this method.
+        /// Note that you may see different results in browsers which include leading/trailing whitespace anyway.
+        /// </para>
+        /// </remarks>
+        /// <returns>The current instance of the builder, so calls may be chained.</returns>
+        public TextQueryBuilder WithoutTrimmingWhitespace()
+        {
+            trimWhitespace = false;
+            return this;
+        }
+
+        IPerformableWithResult<string> IGetsPerformableWithResult<string>.GetPerformable()
+            => SingleElementPerformableWithResultAdapter.From(SingleElementQuery.From(new TextQuery(trimWhitespace)), element);
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="TextQueryBuilder"/> class.
+        /// </summary>
+        /// <param name="element">The target element to query.</param>
+        public TextQueryBuilder(ITarget element)
+        {
+            this.element = element ?? throw new System.ArgumentNullException(nameof(element));
+        }
+    }
+}

CSF.Screenplay.Selenium/Queries/TextQuery.cs

@@ -7,10 +7,26 @@ namespace CSF.Screenplay.Selenium.Queries
     /// </summary>
     public class TextQuery : IQuery<string>
     {
+        readonly bool trimWhitespace;
+
         /// <inheritdoc/>
         public string Name => $"the contained text";
 
         /// <inheritdoc/>
-        public string GetValue(SeleniumElement element) => element.WebElement.Text;
+        public string GetValue(SeleniumElement element)
+        {
+            var text = element.WebElement.Text;
+            return trimWhitespace ? text?.Trim() : text;
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="TextQuery"/> class.
+        /// </summary>
+        /// <param name="trimWhitespace">If <see langword="true"/>, leading &amp; trailing whitespace will be trimmed from
+        /// the returned text content; if <see langword="true"/> it will not.</param>
+        public TextQuery(bool trimWhitespace = true)
+        {
+            this.trimWhitespace = trimWhitespace;
+        }
     }
 }