allow a custom pattern to be specified for isDateTime

Author: bodewig

src/doc/monodoc/placeholders/ns-Org.XmlUnit.Placeholder.xml

@@ -1,8 +1,78 @@
 <Namespace Name="Org.XmlUnit.Placeholder">
   <Docs>
     <summary>Keyword based Configuration Experiment.</summary>
-    <remarks>Experimental support for configuring parts of the test
-    engine by using ${xmlunit.KEYWORD} sequences inside the control
-    document.</remarks>
+    <remarks>
+      <para>Experimental support for configuring parts of the test
+      engine by using <c>${xmlunit.KEYWORD}</c> sequences inside the
+      control document.</para>
+
+      <para>This namepace and the whole package are considered
+      experimental and any API may change between releases of
+      XMLUnit.</para>
+
+      <para>The placeholder feature allows a placeholder sequence of
+      <c>${xmlunit.KEYWORD(args...)}</c> to be used as nested text in
+      elements or as attribute values of the control document and
+      trigger special handling based on the keyword.</para>
+
+      <para>The "special handling" is controlled by an instance of
+      <see cref="IPlaceholderHandler"/> per keyword. The class <see
+      cref="PlaceholderDifferenceEvaluator"/> loads all
+      implementations from the current assembly via reflection.</para>
+
+      <para>The placeholder sequence can take any number of string
+      values as arguments in the form
+      <c>${xmlunit.KEYWORD(args1,arg2)}</c> - if no arguments are used
+      the parentheses can be omitted completely. Arguments are not
+      quoted, whitespace inside of the argument list is
+      significant. All separators (by default <c>${</c>, <c>}</c>,
+      <c>(</c>, <c>)</c>, and <c>,</c>) can be configured
+      explicitly.</para>
+
+      <para>Keywords currently supported by built-in handlers
+      are:</para>
+      <list type="bullet">
+
+        <item><c>${xmlunit.ignore}</c> which makes XMLUnit ignore the
+        nested text or attribute completely. This is handled by <see
+        cref="IgnorePlaceholderHandler"/>.</item>
+
+        <item><c>${xmlunit.isNumber}</c> makes the comparison pass if
+        the textual content of the element or attributes looks like a
+        number. This is handled by <see
+        cref="IsNumberPlaceholderHandler"/>.</item>
+
+        <item><c>${xmlunit.matchesRegex}</c> makes the comparison pass
+        if the textual content of the element or attribute matches the
+        regular expression specified as the first (and only) argument.
+        If there is no argument at all, the comparison will fail. This
+        is handled by <see
+        cref="MatchesRegexPlaceholderHandler"/>.</item>
+
+        <item><c>${xmlunit.isDateTime}</c> makes the comparison pass
+        if the textual content of the element or attributes looks like
+        a date or datetime in the current locale or parsed by ISO
+        rules. An optional argument can be used to specify a pattern
+        unserstood by <see cref="DateTime.ParseExact"/> to use when
+        trying to parse the test. This is handled by <see
+        cref="IsDateTimePlaceholderHandler"/>.</item>
+
+      </list
+
+      <para>The default delimiters of <c>${</c> and <c>}</c> can be
+      overwritten using custom regular expressions.</para>
+
+      <para>The easiest way to activate the placeholder feature is to
+      use one of the methods in <see cref="PlaceholderSupport"/> to
+      add it to a <see cref="org.xmlunit.builder.DiffBuilder"/> or
+      <c>org.xmlunit.matchers.CompareMatcher</c> instance. The
+      alternative approach is to create an instance of <see
+      cref="PlaceholderDifferenceEvaluator"/> as a <see
+      cref="org.xmlunit.diff.DifferenceEvaluator"/> and add it to the
+      builder yourself.</para>
+
+    </remarks>
+
+
   </Docs>
 </Namespace>

src/main/net-placeholders/IsDateTimePlaceholderHandler.cs

@@ -39,11 +39,25 @@ public class IsDateTimePlaceholderHandler : IPlaceholderHandler
         /// <inheritdoc/>
         public ComparisonResult Evaluate(string testText, params string[] args)
         {
+            if (args != null && args.Length == 1) {
+                return CanParse(args[0], testText)
+                    ? ComparisonResult.EQUAL
+                    : ComparisonResult.DIFFERENT;
+            }
             DateTime _;
             var result = DateTime.TryParse(testText, out _);
             return result
                 ? ComparisonResult.EQUAL
                 : ComparisonResult.DIFFERENT;
         }
+
+        private bool CanParse(string pattern, string testText) {
+            try {
+                var _ = DateTime.ParseExact(testText, pattern, CultureInfo.InvariantCulture);
+                return true;
+            } catch (FormatException) {
+                return false;
+            }
+        }
     }
 }

src/tests/net-placeholders/IsDateTimePlaceholderHandlerTests.cs

@@ -62,5 +62,14 @@ public void ShouldGetKeyword()
 
             Assert.AreEqual(expected, keyword);
         }
+
+        [Test]
+        public void ShouldParseExplicitPattern() {
+            Assert.AreEqual(ComparisonResult.EQUAL,
+                            placeholderHandler.Evaluate("31 01 2020 12:34", "dd MM yyyy HH:mm"));
+            Assert.AreEqual(ComparisonResult.DIFFERENT,
+                            placeholderHandler.Evaluate("abc", "dd MM yyyy HH:mm"));
+        }
+
     }
 }

src/tests/net-placeholders/PlaceholderDifferenceEvaluatorTest.cs

@@ -407,6 +407,16 @@ public void HasIsDateTimePlaceholder_Attribute_IsDateTime() {
             Assert.IsFalse(diff.HasDifferences());
         }
 
+        [Test]
+        public void IsDateTimePlaceholder_Attribute_IsDateTime_CustomFormat() {
+            string control = "<elem1 attr='${xmlunit.isDateTime(dd.MM.yyyy)}'/>";
+            string test = "<elem1 attr='05.09.2020'/>";
+            var diff = DiffBuilder.Compare(control).WithTest(test)
+                .WithDifferenceEvaluator(new PlaceholderDifferenceEvaluator().Evaluate).Build();
+
+            Assert.IsFalse(diff.HasDifferences());
+        }
+
         [Test]
         public void HasIsDateTimePlaceholder_Element_NotDateTime() {
             string control = "<elem1>${xmlunit.isDateTime}</elem1>";
@@ -426,5 +436,15 @@ public void HasIsDateTimePlaceholder_Element_IsDateTime() {
 
             Assert.IsFalse(diff.HasDifferences());
         }
+
+        [Test]
+        public void IsDateTimePlaceholder_Element_IsDateTime_CustomFormat() {
+            string control = "<elem1>${xmlunit.isDateTime(dd.MM.yyyy)}</elem1>";
+            string test = "<elem1>09.05.2020</elem1>";
+            var diff = DiffBuilder.Compare(control).WithTest(test)
+                .WithDifferenceEvaluator(new PlaceholderDifferenceEvaluator().Evaluate).Build();
+
+            Assert.IsFalse(diff.HasDifferences());
+        }
     }
 }