Package org.xmlunit.placeholder

This package contains experimental support for configuring parts of the test engine by using ${xmlunit.KEYWORD} sequences inside the control document.

This package and the whole module are considered experimental and any API may change between releases of XMLUnit.

The placeholder feature allows a placeholder sequence of ${xmlunit.KEYWORD(args...)} to be used as nested text in elements or as attribute values of the control document and trigger special handling based on the keyword.

The "special handling" is controlled by an instance of PlaceholderHandler per keyword. The class PlaceholderDifferenceEvaluator loads all implementations via java.util.ServiceLoader so it is possible to extend the set of handlers via your own modules.

The placeholder sequence can take any number of string values as arguments in the form ${xmlunit.KEYWORD(args1,arg2)} - 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 ${, }, (, ), and ,) can be configured explicitly.

Keywords currently supported by built-in handlers are:

  • ${xmlunit.ignore} which makes XMLUnit ignore the nested text or attribute completely. This is handled by IgnorePlaceholderHandler.
  • ${xmlunit.isNumber} makes the comparison pass if the textual content of the element or attributes looks like a number. This is handled by IsNumberPlaceholderHandler.
  • ${xmlunit.matchesRegex} 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 MatchesRegexPlaceholderHandler.
  • ${xmlunit.isDateTime} 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 SimpleDateFormat pattern to use when trying to parse the test. This is handled by IsDateTimePlaceholderHandler.

The default delimiters of ${ and } can be overwritten using custom regular expressions.

The easiest way to activate the placeholder feature is to use one of the methods in PlaceholderSupport to add it to a DiffBuilder or org.xmlunit.matchers.CompareMatcher instance. The alternative approach is to create an instance of PlaceholderDifferenceEvaluator as a DifferenceEvaluator and add it to the builder yourself.

Placeholder sequences must appear as values inside of attribute values or nested textual content of elements - inside the control document. As a special case they may also appear as local part of a tye name of xsi:type attributes of control documents - i.e. xsi:type="prefix:${xmlunit:ignore}". The namepace URIs of the compared types must match with the test document. Support for xsi:types has been added with XMLUnit 2.10.1.

Since:
2.6.0