ueli-werner / xmlunit.net

XMLUnit.NET 2.x

XMLUnit.NET 2.x

Builds:

• AppVeyor using .NET 3.5 and .NET Core 2.0 and 7.0 on Windows, .NET Core 7.0 on Linux:

XMLUnit is a library that supports testing XML output in several ways.

Some goals for XMLUnit 2.x:

• create .NET and Java versions that are compatible in design while trying to be idiomatic for each platform
• remove all static configuration (the old XMLUnit class setter methods)
• focus on the parts that are useful for testing
  • XPath
  • (Schema) validation
  • comparisons
• be independent of any test framework

Documentation

• Developer Guide
• User's Guide

Help Wanted!

If you are looking for something to work on, we've compiled a list of known issues.

Please see the contributing guide for details on how to contribute.

Latest Release

The latest releases are available as GitHub releases or via nuget. Note: Due to a glitch in the nuspec files the package ids for the alpha-02 release are wrong, we began using XMLUnit.Core and XMLUnit.Constraints (with capital M and L) with the subsequent releases.

SNAPSHOT builds

NuGet packages are available from out CI builds at AppVeyor. Follow the link to the Debug or Release Configuration and then the link to Artifacts.

Examples

These are some really small examples, more is available as part of the user guide

Comparing Two Documents

ISource control = Input.FromFile("test-data/good.xml").Build();
ISource test = Input.FromByteArray(CreateTestDocument()).Build();
IDifferenceEngine diff = new DOMDifferenceEngine();
diff.DifferenceListener += (comparison, outcome) => {
            Assert.Fail("found a difference: {}", comparison);
        };
diff.Compare(control, test);

or using the fluent builder API

Diff d = DiffBuilder.Compare(Input.FromFile("test-data/good.xml"))
             .WithTest(CreateTestDocument()).Build();
Assert.IsFalse(d.HasDifferences());

or using the CompareConstraint

Assert.That(CreateTestDocument(), CompareConstraint.IsIdenticalTo(Input.FromFile("test-data/good.xml")));

Asserting an XPath Value

ISource source = Input.FromString("<foo>bar</foo>").Build();
IXPathEngine xpath = new XPathEngine();
IEnumerable<XmlNode> allMatches = xpath.SelectNodes("/foo", source);
string content = xpath.evaluate("/foo/text()", source);

or using HasXPathConstraint and EvaluateXPathConstraint

Assert.That("<foo>bar</foo>", HasXPathConstraint.HasXPath("/foo"));
Assert.That("<foo>bar</foo>", EvaluateXPathConstraint.HasXPath("/foo/text()",
                                                               Is.EqualTo("bar")));

Validating a Document Against an XML Schema

Validator v = Validator.ForLanguage(Languages.W3C_XML_SCHEMA_NS_URI);
v.SchemaSources = new ISource[] {
        Input.FromUri("http://example.com/some.xsd").Build(),
        Input.FromFile("local.xsd").Build()
    };
ValidationResult result = v.ValidateInstance(Input.FromDocument(CreateDocument()).Build());
bool valid = result.Valid;
IEnumerable<ValidationProblem> problems = result.Problems;

or using ValidationConstraint

Assert.That(CreateDocument(),
            new ValidationConstraint(Input.FromFile("local.xsd")));

Requirements

XMLUnit requires .NET 3.5 (it is known to work and actually is developed on Mono 4) or .NET Standard 2.0 (tested with .NET Core 2.1 and 2.2).

The core library provides all functionality needed to test XML output and hasn't got any dependencies. It uses NUnit 3.x for its own tests. The core library is complemented by two libaries of NUnit constraints targeting NUnit 2.x and 3.x respectively.

Checking out XMLUnit.NET

XMLUnit.NET uses a git submodule for test resources it shares with XMLUnit for Java. You can either clone this repository using git clone --recursive or run git submodule update --init inside your fresh working copy after cloning normally.

If you have checked out a working copy before we added the submodule, you'll need to run git submodule update --init once.

Building

Currently there are two different build setups for .NET Framework 3.5 and .NET Standard 2.0. Both build from the same sources and run the same tests but use separate solution and project files. The constraints for NUnit 2.x are ony built as part of the .NET Framework / Mono build.

.NET Framework / Mono 3.5

XMLUnit for .NET uses NuGet and msbuild/xbuild - or Visual Studio 2013. The correspondig solution and project files are suffixed with .NetFramework.

When using Visual Studio the build should automatically refresh the NuGet packages, build the core and constraints assemblies as well as the unit test projects and run all NUnit tests.

When not using Visual Studio you need to install nuget as well as msbuild or xbuild¹ and run

$ nuget restore XMLUnit.NET.NetFramework.sln

once to download the packages used by XMLUnit during the build (really only NUnit right now). After that you can run msbuild or xbuild like

> msbuild /p:Configuration=Debug XMLUnit.NET.NetFramework.sln

$ xbuild /p:Configuration=Debug XMLUnit.NET.NetFramework.sln

which compiles core and constraints, builds the assemblies and executes the NUnit tests.

1: In order to run nuget and xbuild on Linux (or any other platform supported by Mono) you may need to install Mono itself and the xbuild package (the deb packages are mono-complete and mono-xbuild). You'll need to download nuget and finally, if you encounter "System.Net.WebException: Error getting response stream" when running nuget.exe, you'll need to execute

$ mozroots --import --sync

to install the same certificates into your Mono truststore that are trusted by Firefox' default installation.

.NET Standard 2.0

XMLUnit for .NET uses the dotnet CLI - or Visual Studio 2017. In order to run the tests, .NET Core 2.0 is required.

When using Visual Studio the build should automatically refresh the NuGet packages, build the core and constraints assemblies as well as the unit test projects.

When not using Visual Studio you need to run

$ dotnet restore XMLUnit.NET.sln

once to download the packages used by XMLUnit during the build (really only NUnit right now). After that you can run dotnet like

> dotnet build XMLUnit.NET.sln -c Debug

which compiles core, constraints and placeholder and builds the assemblies. In order to run the tests use

> dotnet test src/tests/net-core/XMLUnit.Core.Tests.csproj
> dotnet test src/tests/net-constraints-nunit3/XMLUnit.NUnit3.Constraints.Test.csproj
> dotnet test src/tests/net-placeholders/XMLUnit.Placeholders.Tests.csproj

You may need to specify --roll-forward of DOTNET_ROLL_FORWARD to run the tests when using recent versions of .NET.