Deprecate assertEqualXMLStructure()

[sebastianbergmann]

I have never understood the use case for this assertion and have never seen it used in the wild.

[povetina]

That actually doesn't mean people don't use it.
For example, I maintain a project which among other things exports XML data to remote server.
To check that my code generates correct XML file I use precisely assertEqualXMLStructure() function.
Also, it doesn't strike me as the best practice to remove the function completely without providing a new one.

[tim-bezhashvyly]

Also using it. Now have to work it around. 😔

[tshafer]

I am using it as well.

[theseer]

I'm not sure whether or not this very method or its implementation are the best way to solve the use case it at least for me did cover.

But the general use case is actually rather simple, given that the definition of "equal" with XML documents isn't exactly clear:

<?xml version="1.0" ?>
<root>
    <node />
</root>

./.

<?xml version="1.0" ?>
<root><node /></root>

Are these equal?

If you parse an XML document into a DOM and compare the resulting object graph, they won't be because of additional DOMText-Elements representing the whitespaces for the indentation and the line breaks in the first XML.

In many (most?) contexts though, the whitespace is actually pretty irrelevant. So how would one assert that two structures are "otherwise" equal?

Maybe the method name doesn't (didn't) really transport that intention, but that's what at least I have been using it for.

[theseer]

Another example:

<?xml version="1.0" ?>
<root a="true" b="true" />

./.

<?xml version="1.0" ?>
<root b="true" a="true" />

Logically (semantically?), the two XML structures are equal. On a string and DOM-Basis, they are not.

[theseer]

Talked with @sebastianbergmann, and we decided that I'll re-implement this functionality.

A PR will be provided for it hopefully soon, not sure yet as to when exactly I'll have time to do though.