Package org.xmlunit.diff

Class ElementSelectors

java.lang.Object
org.xmlunit.diff.ElementSelectors
public final class ElementSelectors extends Object
Common ElementSelector implementations.

  • Field Details

    • Default

      public static final ElementSelector Default
      Always returns true, i.e. each element can be compared to each other element.

      Generally this means elements will be compared in document order.

    • byName

      public static final ElementSelector byName
      Elements with the same local name (and namespace URI - if any) can be compared.

    • byNameAndText

      public static final ElementSelector byNameAndText
      Elements with the same local name (and namespace URI - if any) and nested text (if any) can be compared.

    • byNameAndAllAttributes

      public static final ElementSelector byNameAndAllAttributes
      Elements with the same local name (and namespace URI - if any) and attribute values for all attributes can be compared.

  • Method Details

    • byNameAndAttributes

      public static ElementSelector byNameAndAttributes(String... attribs)
      Elements with the same local name (and namespace URI - if any) and attribute values for the given attribute names can be compared.

      Attributes are only searched for in the null namespace.

      Parameters:
      attribs - the names of all attributes who's values must be the same
      Returns:
      the ElementSelector

    • byNameAndAttributesControlNS

      public static ElementSelector byNameAndAttributesControlNS(String... attribs)
      Elements with the same local name (and namespace URI - if any) and attribute values for the given attribute names can be compared.

      Namespace URIs of attributes are those of the attributes on the control element or the null namespace if they don't exist.

      Parameters:
      attribs - the names of all attributes who's values must be the same
      Returns:
      the ElementSelector

    • byNameAndAttributes

      public static ElementSelector byNameAndAttributes(QName... attribs)
      Elements with the same local name (and namespace URI - if any) and attribute values for the given attribute names can be compared.
      Parameters:
      attribs - the qualified names of all attributes who's values must be the same
      Returns:
      the ElementSelector

    • not

      public static ElementSelector not(ElementSelector es)
      Negates another ElementSelector.
      Parameters:
      es - the ElementSelector to negate
      Returns:
      the ElementSelector

    • or

      public static ElementSelector or(ElementSelector... selectors)
      Accepts two elements if at least one of the given ElementSelectors does.

      There is an important difference between using or(org.xmlunit.diff.ElementSelector...) to combine multiple ElementSelectors and using DefaultNodeMatcher's constructor with multiple ElementSelectors:

      Consider ElementSelectors e1 and e2 and two control and test nodes each. Assume e1 would match the first control node to the second test node and vice versa if used alone, while e2 would match the nodes in order (the first control node to the first test and so on).

      or(org.xmlunit.diff.ElementSelector...) creates a combined ElementSelector that is willing to match the first control node to both of the test nodes - and the same for the second control node. Since nodes are compared in order when possible the result will be the same as running e2 alone.

      DefaultNodeMatcher with two ElementSelectors will consult the ElementSelectors separately and only invoke e2 if there are any nodes not matched by e1 at all. In this case the result will be the same as running e1 alone.

      Parameters:
      selectors - the ElementSelectors to combine
      Returns:
      the ElementSelector

    • and

      public static ElementSelector and(ElementSelector... selectors)
      Accepts two elements if all of the given ElementSelectors do.
      Parameters:
      selectors - the ElementSelectors to combine
      Returns:
      the ElementSelector

    • xor

      public static ElementSelector xor(ElementSelector es1, ElementSelector es2)
      Accepts two elements if exactly on of the given ElementSelectors does.
      Parameters:
      es1 - the first ElementSelector to combine
      es2 - the second ElementSelector to combine
      Returns:
      the ElementSelector

    • conditionalSelector

      public static ElementSelector conditionalSelector(Predicate<? super Element> predicate, ElementSelector es)
      Applies the wrapped ElementSelector's logic if and only if the control element matches the given predicate.
      Parameters:
      predicate - the predicate applied to the control element
      es - the ElementSelector to consult
      Returns:
      the ElementSelector

    • selectorForElementNamed

      public static ElementSelector selectorForElementNamed(String expectedName, ElementSelector es)
      Applies the wrapped ElementSelector's logic if and only if the control element has the given (local) name.
      Parameters:
      expectedName - expected name of the control element
      es - the ElementSelector to consult
      Returns:
      the ElementSelector

    • selectorForElementNamed

      public static ElementSelector selectorForElementNamed(QName expectedName, ElementSelector es)
      Applies the wrapped ElementSelector's logic if and only if the control element has the given name.
      Parameters:
      expectedName - expected name of the control element
      es - the ElementSelector to consult
      Returns:
      the ElementSelector

    • byXPath

      public static ElementSelector byXPath(String xpath, ElementSelector childSelector)
      Selects two elements as matching if the child elements selected via XPath match using the given childSelector.

      The xpath expression should yield elements. Two elements match if a DefaultNodeMatcher applied to the selected children finds matching pairs for all children.

      Parameters:
      xpath - XPath expression applied in the context of the elements to chose from that selects the children to compare.
      childSelector - ElementSelector to apply to the selected children.
      Returns:
      the ElementSelector

    • byXPath

      public static ElementSelector byXPath(String xpath, XPathEngine engine, ElementSelector childSelector)
      Selects two elements as matching if the child elements selected via XPath match using the given childSelector.

      The xpath expression should yield elements. Two elements match if a DefaultNodeMatcher applied to the selected children finds matching pairs for all children.

      Parameters:
      xpath - XPath expression applied in the context of the elements to chose from that selects the children to compare.
      engine - XPathEngine to use. If null a JAXPXPathEngine with default configuration will be used.
      childSelector - ElementSelector to apply to the selected children.
      Returns:
      the ElementSelector
      Since:
      XMLUnit 2.9.1

    • byXPath

      public static ElementSelector byXPath(String xpath, Map<String,String> prefix2Uri, ElementSelector childSelector)
      Selects two elements as matching if the child elements selected via XPath match using the given childSelector.

      The xpath expression should yield elements. Two elements match if a DefaultNodeMatcher applied to the selected children finds matching pairs for all children.

      Parameters:
      xpath - XPath expression applied in the context of the elements to chose from that selects the children to compare.
      prefix2Uri - maps from prefix to namespace URI.
      childSelector - ElementSelector to apply to the selected children.
      Returns:
      the ElementSelector

    • byXPath

      public static ElementSelector byXPath(String xpath, XPathEngine xpathEngine, Map<String,String> prefix2Uri, ElementSelector childSelector)
      Selects two elements as matching if the child elements selected via XPath match using the given childSelector.

      The xpath expression should yield elements. Two elements match if a DefaultNodeMatcher applied to the selected children finds matching pairs for all children.

      Parameters:
      xpath - XPath expression applied in the context of the elements to chose from that selects the children to compare.
      xpathEngine - XPathEngine to use. If null a JAXPXPathEngine with default configuration will be used.
      prefix2Uri - maps from prefix to namespace URI.
      childSelector - ElementSelector to apply to the selected children.
      Returns:
      the ElementSelector
      Since:
      XMLUnit 2.9.1

    • conditionalBuilder

      public static ElementSelectors.ConditionalSelectorBuilder conditionalBuilder()
      Allows to build complex ElementSelectors by combining simpler blocks.

      All pairs created by the when*/thenUse pairs are evaluated in order until one returns true, finally the default, if any, is consulted.

      Returns:
      a builder for conditional ElementSelectors