Resolve #250 - Add tests for entering dates

Author: craigfowler

CSF.Screenplay.Selenium/Builders/EnterTheDateBuilder.cs

@@ -0,0 +1,80 @@
+using System;
+using System.Globalization;
+using CSF.Screenplay.Performables;
+using CSF.Screenplay.Selenium.Actions;
+using CSF.Screenplay.Selenium.Elements;
+
+namespace CSF.Screenplay.Selenium.Builders
+{
+    /// <summary>
+    /// A builder type which creates an instance of <see cref="EnterTheDate"/>.
+    /// </summary>
+    public class EnterTheDateBuilder : IGetsPerformable
+    {
+        readonly DateTime? date;
+        ITarget target;
+        CultureInfo culture;
+
+        /// <summary>
+        /// Specifies the target element into which to enter the date.  This must be an <c>&lt;input type="date"&gt;</c> element.
+        /// </summary>
+        /// <param name="target">The target element</param>
+        /// <returns>This same builder, so calls may be chained</returns>
+        /// <exception cref="ArgumentNullException">If <paramref name="target"/> is null</exception>
+        /// <exception cref="InvalidOperationException">If this method is used more than once</exception>
+        public EnterTheDateBuilder Into(ITarget target)
+        {
+            if (target is null)
+                throw new ArgumentNullException(nameof(target));
+            if(this.target != null)
+                throw new InvalidOperationException("The target has already been set; it may not be set again.");
+            
+            this.target = target;
+            return this;
+        }
+
+        /// <summary>
+        /// Specifies the culture for which to enter the date.  This must be the culture in which the web browser is operating.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Web browser are culture-aware applications and they will render the input/display value of a date field using the culture
+        /// in which their operating system is configured.  This impacts the manner in which users input dates.
+        /// If this method is not used, the task returned by this builder will use the culture of the operating system/environment
+        /// that is executing the Screenplay Performance. This is usually OK when running the web browser locally, but it might not match
+        /// the browser's culture when using remote web browsers.
+        /// </para>
+        /// </remarks>
+        /// <example>
+        /// <para>
+        /// For example, a British English browser <c>en-GB</c> expects dates to be entered in the format ddMMyyyy.
+        /// However, a US English browser <c>en-US</c> expects dates to be entered in the format MMddyyyy.
+        /// </para>
+        /// <para>
+        /// The <paramref name="cultureIdentifier"/> parameter of this method must be the culture identifier of the culture which the
+        /// browser is operating under, such as <c>en-GB</c>.
+        /// </para>
+        /// </example>
+        /// <param name="cultureIdentifier">A culture identifier string</param>
+        /// <returns>This same builder, so calls may be chained</returns>
+        /// <exception cref="ArgumentNullException">If <paramref name="cultureIdentifier"/> is null</exception>
+        /// <exception cref="CultureNotFoundException">If <paramref name="cultureIdentifier"/> indicates a culture which is not found</exception>
+        public EnterTheDateBuilder ForTheCultureNamed(string cultureIdentifier)
+        {
+            culture = CultureInfo.GetCultureInfo(cultureIdentifier);
+            return this;
+        }
+
+        /// <inheritdoc/>
+        public IPerformable GetPerformable() => new EnterTheDate(date, target, culture);
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="EnterTheDateBuilder"/> class with the specified date.
+        /// </summary>
+        /// <param name="date">The date to enter, or null</param>
+        public EnterTheDateBuilder(DateTime? date)
+        {
+            this.date = date;
+        }
+    }
+}

CSF.Screenplay.Selenium/PerformableBuilder.elementPerformables.cs

@@ -1,3 +1,4 @@
+using System;
 using CSF.Screenplay.Selenium.Actions;
 using CSF.Screenplay.Selenium.Builders;
 using CSF.Screenplay.Selenium.Elements;
@@ -32,6 +33,18 @@ public static partial class PerformableBuilder
         /// <returns>A builder with which the user may select a target element.</returns>
         public static SendKeysBuilder EnterTheText(params string[] text) => new SendKeysBuilder(string.Join(string.Empty, text));
 
+        /// <summary>
+        /// Gets a builder for creating a performable action which represents an actor entering a date into an <c>&lt;input type="date"&gt;</c> element.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// If the specified <paramref name="date"/> is <see langword="null"/> then the input element will be cleared.
+        /// </para>
+        /// </remarks>
+        /// <param name="date">The date to enter into the input control.</param>
+        /// <returns>A builder with which the user may select a target element and optionally a culture.</returns>
+        public static EnterTheDateBuilder EnterTheDate(DateTime? date) => new EnterTheDateBuilder(date);
+
         /// <summary>
         /// Gets a performable which represents an actor deselecting everything from a <c>&lt;select&gt;</c> element.
         /// </summary>

CSF.Screenplay.Selenium/Tasks/EnterTheDate.cs

@@ -0,0 +1,76 @@
+using System;
+using System.Globalization;
+using System.Text.RegularExpressions;
+using System.Threading;
+using System.Threading.Tasks;
+using CSF.Screenplay.Selenium.Elements;
+using static CSF.Screenplay.Selenium.PerformableBuilder;
+
+namespace CSF.Screenplay.Selenium.Actions
+{
+    /// <summary>
+    /// A <see cref="IPerformable"/> which represents an actor entering a date value into an <c>&lt;input type="date"&gt;</c> element.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Note that this task is culture-sensitive.  Ensure that the date value is entered into the browser using the culture in which the browser is
+    /// running.
+    /// If no culture information is specified then this task defaults to the current culture: <see cref="CultureInfo.CurrentCulture"/>.
+    /// However, this is not certain to be correct, particularly in remote/cloud configurations where the web browser is operating on different
+    /// infrastructure to the computer which is executing the Screenplay performance.  These two computers might be operating in different cultures.
+    /// </para>
+    /// <para>
+    /// If the date specified to this task is <see langword="null"/> then this task will clear the date from the target.
+    /// </para>
+    /// </remarks>
+    /// <example>
+    /// <para>
+    /// For example, a British English browser <c>en-GB</c> expects dates to be entered in the format ddMMyyyy.
+    /// However, a US English browser <c>en-US</c> expects dates to be entered in the format MMddyyyy.
+    /// </para>
+    /// </example>
+    public class EnterTheDate : IPerformable, ICanReport
+    {
+        const string nonNumericPattern = @"\D";
+        static readonly Regex nonNumeric = new Regex(nonNumericPattern, RegexOptions.Compiled | RegexOptions.IgnoreCase | RegexOptions.CultureInvariant);
+
+        readonly DateTime? date;
+        readonly ITarget target;
+        readonly CultureInfo culture;
+
+        string GetShortDatePattern() => culture.DateTimeFormat.ShortDatePattern;
+
+        string FormatDate() => date.HasValue ? date.Value.ToString(GetShortDatePattern()) : null;
+
+        /// <inheritdoc/>
+        public ValueTask PerformAsAsync(ICanPerform actor, CancellationToken cancellationToken = default)
+        {
+            if(!date.HasValue)
+                return actor.PerformAsync(ClearTheContentsOf(target), cancellationToken);
+
+            var dateText = nonNumeric.Replace(FormatDate(), string.Empty);
+            return actor.PerformAsync(EnterTheText(dateText).Into(target), cancellationToken);
+        }
+
+        /// <inheritdoc/>
+        public ReportFragment GetReportFragment(Actor actor, IFormatsReportFragment formatter)
+        {
+            return date.HasValue
+                ? formatter.Format("{Actor} enters the date {Date} into {Target}", actor.Name, FormatDate(), target)
+                : formatter.Format("{Actor} clears the date from {Target}", actor.Name, date, target);
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="EnterTheDate"/> class with the specified date.
+        /// </summary>
+        /// <param name="date">The date to enter into the element.</param>
+        /// <param name="target">The element into which to enter the data</param>
+        /// <param name="culture">The culture for which to enter the date</param>
+        public EnterTheDate(DateTime? date, ITarget target, CultureInfo culture = null)
+        {
+            this.date = date;
+            this.target = target ?? throw new ArgumentNullException(nameof(target));
+            this.culture = culture ?? CultureInfo.CurrentCulture;
+        }
+    }
+}

Tests/CSF.Screenplay.Selenium.TestWebapp/wwwroot/InputDateTests.html

@@ -0,0 +1,21 @@
+<html>
+    <head>
+    </head>
+    <body>
+        <h1>Date input Tests</h1>
+        <p>
+            Typing into the input box will immediately update the value of the display area, below.
+        </p>
+        <input type="date" id="inputArea" value="2001-01-01">
+        <code><pre id="display" style="background: yellow"></pre></code>
+        <script>
+            window.onload = function() {
+                const inputArea = document.getElementById("inputArea");
+                inputArea.addEventListener("input", function() {
+                    const displayElement = document.getElementById("display");
+                    displayElement.innerText = inputArea.value;
+                });
+            }
+        </script>
+    </body>
+</html>

Tests/CSF.Screenplay.Selenium.Tests/Tasks/EnterTheDateTests.cs

@@ -0,0 +1,60 @@
+using System;
+using System.Globalization;
+using CSF.Screenplay.Selenium.Elements;
+using static CSF.Screenplay.PerformanceStarter;
+using static CSF.Screenplay.Selenium.PerformableBuilder;
+
+namespace CSF.Screenplay.Selenium.Tasks;
+
+[TestFixture, Parallelizable]
+public class EnterTheDateTests
+{
+    static readonly ITarget
+        inputArea = new ElementId("inputArea", "the input area"),
+        displayText = new ElementId("display", "the displayable text");
+
+    static readonly NamedUri testPage = new NamedUri("InputDateTests.html", "the test page");
+
+    [Test, Screenplay]
+    public async Task EnteringADateShouldYieldTheCorrectValue(IStage stage)
+    {
+        var webster = stage.Spotlight<Webster>();
+
+        await Given(webster).WasAbleTo(OpenTheUrl(testPage));
+        await When(webster).AttemptsTo(EnterTheDate(new DateTime(2025, 11, 12)).Into(inputArea));
+        var result = await Then(webster).Should(ReadFromTheElement(displayText).TheText());
+
+        Assert.That(result, Is.EqualTo("2025-11-12"));
+    }
+    
+    [Test, Screenplay]
+    public async Task EnteringANullDateShouldClearTheValue(IStage stage)
+    {
+        var webster = stage.Spotlight<Webster>();
+
+        await Given(webster).WasAbleTo(OpenTheUrl(testPage));
+        await When(webster).AttemptsTo(EnterTheDate(null).Into(inputArea));
+        var result = await Then(webster).Should(ReadFromTheElement(displayText).TheText());
+
+        Assert.That(result, Is.EqualTo(string.Empty));
+    }
+    
+    [Test, Screenplay]
+    public async Task EnteringADateInAnUnusualCultureShouldYieldIncorrectResults(IStage stage)
+    {
+        var webster = stage.Spotlight<Webster>();
+
+        if(CultureInfo.CurrentCulture.DateTimeFormat.ShortDatePattern.StartsWith("y", StringComparison.InvariantCultureIgnoreCase))
+            Assert.Inconclusive("This test can't be meaningfully run when the current culture uses Y/M/D date formatting");
+
+        await Given(webster).WasAbleTo(OpenTheUrl(testPage));
+        await When(webster).AttemptsTo(EnterTheDate(new DateTime(2025, 11, 12)).Into(inputArea).ForTheCultureNamed("ja-JP"));
+        var result = await Then(webster).Should(ReadFromTheElement(displayText).TheText());
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(result, Is.Not.EqualTo(string.Empty), "The date shouldn't be empty");
+            Assert.That(result, Is.Not.EqualTo("2025-11-12"), "The date shouldn't be the value which was entered either, because of the culture/format difference"); 
+        });
+    }
+}