Comparing an xml tree with a pattern file

Instead of having to check the XML contents directly within your test case file via multiple calls to "TTB_EXP" you can perform a comparison with a predefined external pattern file with expected contents.

How to compare

Simply call method CompareXmlSubTreeWithPatternFile.

• Pass the xml data to compare as pugi::xml_document, pugi::xml_node or simply a string containing the XML tree.
• Specify the file path to the pattern file
• optional: specify that only a sub node of your XML tree shall be checked, adress the sub tree by using XPath expressions (see Selecting interesting parts with XPath)

Examples:

    // Get the example XML tree
    pugi::xml_document doc;
    TTB::TheXmlCheck()->ReadFromString(doc, DEMO_XML_STRING);
    
    // All of the following compare methods write a filtered part of the XML tree
    // to the file "<YourTargetDir>/<YourTestAppName>_<NamePatternFile>.xml.out"
    // and compare it with given pattern file "<NamePatternFile>.xml"

    // Simply check complete XML tree using XML document
    TTB_CHECK_COND(CompareXmlSubTreeWithPatternFile(doc, MY_TEST_DIR + "/FullContentsFiltered.xml"));

    // Check subtree using XPath expression relative to XML document root
    TTB_CHECK_COND(CompareXmlSubTreeWithPatternFile(doc, MY_TEST_DIR + "/Vector_1.xml", "MyContainer/Group_A/Vector[1]"));

    // Check subtree using XPath expression relative to arbitrary XML tree node
    auto subNode = TTB::TheXmlCheck()->NodeFromXPath(doc, "MyContainer/Group_A");
    TTB_CHECK_COND(CompareXmlSubTreeWithPatternFile(subNode, MY_TEST_DIR + "/Vector_2.xml", "Vector[2]"));

    // Check subtree using XPath expression for given XML string
    TTB_CHECK_COND(CompareXmlSubTreeWithPatternFile(DEMO_XML_STRING, MY_TEST_DIR + "/Vector_3.xml", "MyContainer/Group_A/Vector[@id='3']"));

Principles

• as the result of the comparison a boolean value is returned. "True" means that the XML data are identical to the pattern file. Verification of the result is possible via test macros TTB_CHECK_COND or BOOST_CHECK.
• all filter settings from XML check are considered (e.g. attributes or nodes can be omitted, precision of double values can be configured, see Available options for checking data)

Error detection

If there are differences between the observed xml tree and the pattern file

• method CompareXmlSubTreeWithPatternFile will return "false"
• the first found difference will be reported as a test event

Example:

    // Deliberately compare with differing pattern file.
    // The first detected error will be reported as a test event
    TTB_CHECK_EQUAL(CompareXmlSubTreeWithPatternFile(DEMO_XML_STRING, MY_TEST_DIR + "/Vector_3_with_2_errors.xml", "MyContainer/Group_A/Vector[@id='3']"), false);

    TTB_EXP("Difference detected");
    TTB_EXP("lhs: tolerance: 1.36(path: /Vector/tolerance, pos: 1)");
    TTB_EXP("rhs: tolerance: 1.39(path: /Vector/tolerance, pos: 24)");

For a deaper analysis of differences consider the following:

• the XML (sub) tree which has to be compared with the pattern file is written as a separate XML file to the target directory of your test application. If the pattern file is named "SomeDir/SomePatternFile.xml" the recorded xml file will be named "<YourTargetDir>/<YourTestAppName>_SomePatternFile.xml.out".
• The recorded file contains only the subtree to check with only those attributes and nodes which are not filtered out.
• In case of a failed comparison you can use any diff tool to compare the generated XML file and the pattern file in detail.

Tip: automatic generation of a patternfile

To get a valid pattern file you can simply start without an existing pattern file.

• run your test and inspect the generated xml file
• if the contents are ok use it as your pattern file by appropriate renaming and moving to your desired directory