Author: veithen
Date: Sat Nov 7 21:10:16 2015
New Revision: 1713179
URL: http://svn.apache.org/viewvc?rev=1713179&view=rev
Log:
Prepare the xml-truth API for publication.
Added:
webservices/axiom/trunk/testing/xml-truth/src/main/java/org/apache/axiom/truth/xml/package-info.java
(with props)
Modified:
webservices/axiom/trunk/testing/xml-truth/src/main/java/org/apache/axiom/truth/xml/XMLSubject.java
webservices/axiom/trunk/testing/xml-truth/src/main/java/org/apache/axiom/truth/xml/XMLTruth.java
webservices/axiom/trunk/testing/xml-truth/src/site/markdown/index.md.vm
Modified:
webservices/axiom/trunk/testing/xml-truth/src/main/java/org/apache/axiom/truth/xml/XMLSubject.java
URL:
http://svn.apache.org/viewvc/webservices/axiom/trunk/testing/xml-truth/src/main/java/org/apache/axiom/truth/xml/XMLSubject.java?rev=1713179&r1=1713178&r2=1713179&view=diff
==============================================================================
---
webservices/axiom/trunk/testing/xml-truth/src/main/java/org/apache/axiom/truth/xml/XMLSubject.java
(original)
+++
webservices/axiom/trunk/testing/xml-truth/src/main/java/org/apache/axiom/truth/xml/XMLSubject.java
Sat Nov 7 21:10:16 2015
@@ -35,9 +35,13 @@ import org.apache.axiom.truth.xml.spi.XM
import com.google.common.truth.FailureStrategy;
import com.google.common.truth.Subject;
+/**
+ * Propositions for objects representing XML data.
+ */
public final class XMLSubject extends Subject<XMLSubject,Object> {
private final XML xml;
- private final Set<Event> ignoredEvents = new HashSet<Event>();
+ private boolean ignoreComments;
+ private boolean ignoreElementContentWhitespace;
private boolean ignoreWhitespace;
private boolean ignoreWhitespaceInPrologAndEpilog;
private boolean ignorePrologAndEpilog;
@@ -52,69 +56,228 @@ public final class XMLSubject extends Su
xml = XMLTruth.xml(subject);
}
+ /**
+ * Ignore comments; same as {@code ignoringComments(true)}.
+ *
+ * @return {@code this}
+ */
public XMLSubject ignoringComments() {
- ignoredEvents.add(Event.COMMENT);
- return this;
+ return ignoringComments(true);
}
+ /**
+ * Specifies if comments should be ignored.
+ *
+ * @param value
+ * {@code true} if comments should be ignored, {@code false}
otherwise
+ * @return {@code this}
+ */
+ public XMLSubject ignoringComments(boolean value) {
+ ignoreComments = value;
+ return this;
+ }
+
+ /**
+ * Ignore element content whitespace; same as {@code
ignoringElementContentWhitespace(true)}.
+ *
+ * @return {@code this}
+ */
public XMLSubject ignoringElementContentWhitespace() {
- ignoredEvents.add(Event.WHITESPACE);
+ return ignoringElementContentWhitespace(true);
+ }
+
+ /**
+ * Specifies if element content whitespace should be ignored. Note
+ * that this only has an effect for documents that have a DTD.
+ *
+ * @param value
+ * {@code true} if element content whitespace should be
ignored, {@code false}
+ * otherwise
+ * @return {@code this}
+ */
+ public XMLSubject ignoringElementContentWhitespace(boolean value) {
+ ignoreElementContentWhitespace = true;
return this;
}
+ /**
+ * Ignore all whitespace; same as {@code ignoringWhitespace(true)}.
+ *
+ * @return {@code this}
+ */
public XMLSubject ignoringWhitespace() {
- ignoredEvents.add(Event.WHITESPACE);
- ignoreWhitespace = true;
+ return ignoringWhitespace(true);
+ }
+
+ /**
+ * Specifies if whitespace should be ignored.
+ *
+ * @param value
+ * {@code true} if all text nodes that contain only whitespace
should be ignored,
+ * {@code false} otherwise
+ * @return {@code this}
+ */
+ public XMLSubject ignoringWhitespace(boolean value) {
+ ignoreWhitespace = value;
return this;
}
+ /**
+ * Ignore whitespace in the prolog and epilog; same as
+ * {@code ignoringWhitespaceInPrologAndEpilog(true)}.
+ *
+ * @return {@code this}
+ */
public XMLSubject ignoringWhitespaceInPrologAndEpilog() {
- ignoreWhitespaceInPrologAndEpilog = true;
+ return ignoringWhitespaceInPrologAndEpilog(true);
+ }
+
+ /**
+ * Specifies if whitespace in the prolog and epilog should be ignored.
This is especially useful
+ * when working with DOM documents because DOM strips whitespace from the
prolog and epilog.
+ *
+ * @param value
+ * {@code true} if whitespace in the prolog and epilog should
be ignored,
+ * {@code false} otherwise
+ * @return {@code this}
+ */
+ public XMLSubject ignoringWhitespaceInPrologAndEpilog(boolean value) {
+ ignoreWhitespaceInPrologAndEpilog = value;
return this;
}
+ /**
+ * Ignore the prolog and epilog entirely; same as {@code
ignoringPrologAndEpilog(true)}.
+ *
+ * @return {@code this}
+ */
public XMLSubject ignoringPrologAndEpilog() {
- ignorePrologAndEpilog = true;
+ return ignoringPrologAndEpilog(true);
+ }
+
+ /**
+ * Specifies if the prolog and epilog should be ignored entirely.
+ *
+ * @param value
+ * {@code true} if (text, comment and document type
declaration) nodes in the prolog
+ * and epilog should be ignored, {@code false} otherwise
+ * @return {@code this}
+ */
+ public XMLSubject ignoringPrologAndEpilog(boolean value) {
+ ignorePrologAndEpilog = value;
return this;
}
/**
- * Ignore all namespace declarations.
+ * Ignore all namespace declarations; same as {@code
ignoringNamespaceDeclarations(true)}.
*
* @return <code>this</code>
*/
public XMLSubject ignoringNamespaceDeclarations() {
- ignoreNamespaceDeclarations = true;
+ return ignoringNamespaceDeclarations(true);
+ }
+
+ /**
+ * Specifies if namespace declarations should be ignored.
+ *
+ * @param value
+ * {@code true} if namespace declarations should be ignored,
{@code false} otherwise
+ * @return {@code this}
+ */
+ public XMLSubject ignoringNamespaceDeclarations(boolean value) {
+ ignoreNamespaceDeclarations = value;
return this;
}
+ /**
+ * Ignore namespace prefixes; same as {@code
ignoringNamespacePrefixes(true)}.
+ *
+ * @return {@code this}
+ */
public XMLSubject ignoringNamespacePrefixes() {
- ignoreNamespacePrefixes = true;
+ return ignoringNamespacePrefixes(true);
+ }
+
+ /**
+ * Specifies if namespace prefixes should be ignored.
+ *
+ * @param value
+ * {@code true} if namespace prefixes are ignored when
comparing elements and
+ * attributes, {@code false} otherwise
+ * @return {@code this}
+ */
+ public XMLSubject ignoringNamespacePrefixes(boolean value) {
+ ignoreNamespacePrefixes = value;
return this;
}
/**
- * Ignore redundant namespace declarations. A namespace declaration is
considered redundant if
- * its presence doesn't modify the namespace context.
+ * Ignore redundant namespace declarations; same as
+ * {@code ignoringRedundantNamespaceDeclarations(true)}.
*
- * @return <code>this</code>
+ * @return {@code this}
*/
public XMLSubject ignoringRedundantNamespaceDeclarations() {
- ignoreRedundantNamespaceDeclarations = true;
+ return ignoringRedundantNamespaceDeclarations(true);
+ }
+
+ /**
+ * Specify if redundant namespace declarations should be ignored. A
namespace declaration is
+ * considered redundant if its presence doesn't modify the namespace
context.
+ *
+ * @param value
+ * {@code true} if redundant namespace declarations should be
ignored, {@code false}
+ * if all namespace declarations should be compared
+ * @return {@code this}
+ */
+ public XMLSubject ignoringRedundantNamespaceDeclarations(boolean value) {
+ ignoreRedundantNamespaceDeclarations = value;
return this;
}
+ /**
+ * Expand entity references; same as {@code
expandingEntityReferences(true)}.
+ *
+ * @return {@code this}
+ */
public XMLSubject expandingEntityReferences() {
return expandingEntityReferences(true);
}
+ /**
+ * Specifies if entity references should be expanded.
+ *
+ * @param value
+ * {@code true} if entity references should be expanded and
their replacement
+ * compared, {@code false} if the entity references themselves
should be compared
+ * @return {@code this}
+ */
public XMLSubject expandingEntityReferences(boolean value) {
expandEntityReferences = value;
return this;
}
+ /**
+ * Treat element content whitespace as simple text nodes; same as
+ * {@code treatingElementContentWhitespaceAsText(true)}.
+ *
+ * @return {@code this}
+ */
public XMLSubject treatingElementContentWhitespaceAsText() {
- treatWhitespaceAsText = true;
+ return treatingElementContentWhitespaceAsText(true);
+ }
+
+ /**
+ * Specifies how element content whitespace is to be treated. Use this
when comparing a document
+ * that has a DTD with a document that doesn't.
+ *
+ * @param value
+ * {@code true} if element whitespace should be considered as
text nodes,
+ * {@code false} if element whitespace should be considered as
a distinct node type
+ * @return {@code this}
+ */
+ public XMLSubject treatingElementContentWhitespaceAsText(boolean value) {
+ treatWhitespaceAsText = value;
return this;
}
@@ -152,6 +315,13 @@ public final class XMLSubject extends Su
}
};
}
+ final Set<Event> ignoredEvents = new HashSet<Event>();
+ if (ignoreComments) {
+ ignoredEvents.add(Event.COMMENT);
+ }
+ if (ignoreWhitespace || ignoreElementContentWhitespace) {
+ ignoredEvents.add(Event.WHITESPACE);
+ }
if (!ignoredEvents.isEmpty()) {
traverser = new Filter(traverser) {
@Override
@@ -207,6 +377,12 @@ public final class XMLSubject extends Su
return result;
}
+ /**
+ * Fails unless the subject represents the same XML as the given object.
+ *
+ * @param other
+ * the object to compare with
+ */
public void hasSameContentAs(Object other) {
try {
Traverser actual = createTraverser(xml);
Modified:
webservices/axiom/trunk/testing/xml-truth/src/main/java/org/apache/axiom/truth/xml/XMLTruth.java
URL:
http://svn.apache.org/viewvc/webservices/axiom/trunk/testing/xml-truth/src/main/java/org/apache/axiom/truth/xml/XMLTruth.java?rev=1713179&r1=1713178&r2=1713179&view=diff
==============================================================================
---
webservices/axiom/trunk/testing/xml-truth/src/main/java/org/apache/axiom/truth/xml/XMLTruth.java
(original)
+++
webservices/axiom/trunk/testing/xml-truth/src/main/java/org/apache/axiom/truth/xml/XMLTruth.java
Sat Nov 7 21:10:16 2015
@@ -38,9 +38,14 @@ import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.xml.sax.InputSource;
+import com.google.common.truth.AbstractVerb.DelegatedVerb;
import com.google.common.truth.FailureStrategy;
import com.google.common.truth.SubjectFactory;
+import com.google.common.truth.Truth;
+/**
+ * Google Truth extension for XML.
+ */
public final class XMLTruth {
private static final SubjectFactory<XMLSubject,Object> SUBJECT_FACTORY =
new SubjectFactory<XMLSubject,Object>() {
@Override
@@ -192,10 +197,27 @@ public final class XMLTruth {
private XMLTruth() {}
+ /**
+ * Get the {@link SubjectFactory} to be used with {@link
Truth#assertAbout(SubjectFactory)}.
+ *
+ * @return a {@link SubjectFactory} for {@link XMLSubject} instances
+ */
public static SubjectFactory<XMLSubject,Object> xml() {
return SUBJECT_FACTORY;
}
+ /**
+ * Prepare XML data so that it will be accessed through a particular API.
Use this method for
+ * objects that represent XML data, but that implement more than one API
supported by the
+ * factory returned by {@link #xml()} (e.g. DOM and the Axiom API).
+ *
+ * @param type
+ * the API to use (e.g. {@link Document}
+ * @param object
+ * an object implementing that API
+ * @return an object that can be passed to {@link
DelegatedVerb#that(Object)} or
+ * {@link XMLSubject#hasSameContentAs(Object)}
+ */
public static <T> Object xml(Class<T> type, T object) {
return createXML(type, object);
}
Added:
webservices/axiom/trunk/testing/xml-truth/src/main/java/org/apache/axiom/truth/xml/package-info.java
URL:
http://svn.apache.org/viewvc/webservices/axiom/trunk/testing/xml-truth/src/main/java/org/apache/axiom/truth/xml/package-info.java?rev=1713179&view=auto
==============================================================================
---
webservices/axiom/trunk/testing/xml-truth/src/main/java/org/apache/axiom/truth/xml/package-info.java
(added)
+++
webservices/axiom/trunk/testing/xml-truth/src/main/java/org/apache/axiom/truth/xml/package-info.java
Sat Nov 7 21:10:16 2015
@@ -0,0 +1,4 @@
+/**
+ * Google Truth extension for XML.
+ */
+package org.apache.axiom.truth.xml;
\ No newline at end of file
Propchange:
webservices/axiom/trunk/testing/xml-truth/src/main/java/org/apache/axiom/truth/xml/package-info.java
------------------------------------------------------------------------------
svn:eol-style = native
Modified:
webservices/axiom/trunk/testing/xml-truth/src/site/markdown/index.md.vm
URL:
http://svn.apache.org/viewvc/webservices/axiom/trunk/testing/xml-truth/src/site/markdown/index.md.vm?rev=1713179&r1=1713178&r2=1713179&view=diff
==============================================================================
--- webservices/axiom/trunk/testing/xml-truth/src/site/markdown/index.md.vm
(original)
+++ webservices/axiom/trunk/testing/xml-truth/src/site/markdown/index.md.vm Sat
Nov 7 21:10:16 2015
@@ -20,3 +20,37 @@
Introduction
------------
+This `xml-truth` module provides a [Google
Truth](https://github.com/google/truth) extension to
+compare XML data. It can be used as an alternative to
[XMLUnit](http://www.xmlunit.org/). The basic
+usage is as follows:
+
+ assertAbout(xml()).that(actual).hasSameContentAs(expected);
+
+This relies on the following static imports being present:
+
+ import static com.google.common.truth.Truth.assertAbout;
+ import static org.apache.axiom.truth.xml.XMLTruth.xml;
+
+`actual` and `expected` are objects that represent XML data. The following
types are currently
+supported:
+
+* `InputStream`, `Reader`, `String` and `byte[]` with XML data to be parsed
+
+* `javax.xml.transform.stream.StreamSource` and `org.xml.sax.InputSource`
+
+* DOM `Document` or `Element` nodes
+
+* `java.net.URL`
+
+By default, comparison is strict. E.g. the following assertion would fail:
+
+ assertAbout(xml()).that("<p:a xmlns:p='urn:ns'/>").hasSameContentAs("<a
xmlns='urn:ns'/>");
+
+To control how the comparison is performed, use the relevant methods on the
+[`XMLSubject`](apidocs/org/apache/axiom/truth/xml/XMLSubject.html) object
returned by `that()`:
+
+ assertAbout(xml())
+ .that("<p:a xmlns:p='urn:ns'/>")
+ .ignoringNamespacePrefixes()
+ .ignoringNamespaceDeclarations()
+ .hasSameContentAs("<a xmlns='urn:ns'/>");
