From 16232aeda8af679a2fbcfa344ecad40c26c97a75 Mon Sep 17 00:00:00 2001 From: Stefan Bodewig Date: Fri, 25 Apr 2025 10:39:00 +0200 Subject: [PATCH 1/5] initial nuget readme for core --- src/doc/readmes/net-core/README.md | 87 +++++++++++++++++++++++++++ src/main/net-core/XMLUnit.Core.nuspec | 2 + 2 files changed, 89 insertions(+) create mode 100644 src/doc/readmes/net-core/README.md diff --git a/src/doc/readmes/net-core/README.md b/src/doc/readmes/net-core/README.md new file mode 100644 index 0000000..e9f1b9c --- /dev/null +++ b/src/doc/readmes/net-core/README.md @@ -0,0 +1,87 @@ +# XMLUnit.NET + +XMLUnit provides you with the tools to verify the XML you emit is the +one you want to create. + +It provides helpers to validate against an XML Schema, assert the +values of XPath queries or compare XML documents against expected +outcomes. + +This package provides the core functionality and can be used +stand-alone. In addition there are libraries providing NUnit +constraints and a "placeholders" package that may simplify writing +comparison tests in certain cases. + +* [XMLUnit.NUnit2.Constraints - Constraints for NUnit 2.x ![nuget](https://img.shields.io/nuget/v/XMLUnit.NUnit2.Constraints.svg)](https://www.nuget.org/packages/XMLUnit.NUnit2.Constraints/) +* [XMLUnit.NUnit3.Constraints - Constraints for NUnit 3.x ![nuget](https://img.shields.io/nuget/v/XMLUnit.NUnit3.Constraints.svg)](https://www.nuget.org/packages/XMLUnit.NUnit3.Constraints/) +* [XMLUnit.NUnit4.Constraints - Constraints for NUnit 4.x ![nuget](https://img.shields.io/nuget/v/XMLUnit.NUnit4.Constraints.svg)](https://www.nuget.org/packages/XMLUnit.NUnit4.Constraints/) +* [XMLUnit.Placeholders - simplifies comparisons for special cases ![nuget](https://img.shields.io/nuget/v/XMLUnit.Placeholders.svg)](https://www.nuget.org/packages/XMLUnit.Placeholders/) + +[![Build status](https://ci.appveyor.com/api/projects/status/am34dfbr4vbcarr3?svg=true)] + +## Requirements + +XMLUnit requires .NET Standard 2.0 (tested with .NET 8 rigt now) and +should still support .NET Framework 3.5 and Mono. + +The core library hasn't got any dependencies itself. + +## Usage + +These are some really small examples, more is available as part of the +[user guide](https://github.com/xmlunit/user-guide/wiki) + +### Comparing Two Documents + +```csharp +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 + +```csharp +Diff d = DiffBuilder.Compare(Input.FromFile("test-data/good.xml")) + .WithTest(CreateTestDocument()).Build(); +Assert.IsFalse(d.HasDifferences()); +``` + +### Asserting an XPath Value + +```csharp +ISource source = Input.FromString("bar").Build(); +IXPathEngine xpath = new XPathEngine(); +IEnumerable allMatches = xpath.SelectNodes("/foo", source); +string content = xpath.evaluate("/foo/text()", source); +``` + +### Validating a Document Against an XML Schema + + +```csharp +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 problems = result.Problems; +``` + +## Additional Documentation + +XMLUnit.NET is developed at +[github](https://github.com/xmlunit/xmlunit.net). More documentation, +releases and an issue tracker can be found there. + +## Changelog + +See the [Release +Notes](https://github.com/xmlunit/xmlunit.net/blob/main/RELEASE_NOTES.md) +at github. diff --git a/src/main/net-core/XMLUnit.Core.nuspec b/src/main/net-core/XMLUnit.Core.nuspec index c6b847f..6455dd9 100644 --- a/src/main/net-core/XMLUnit.Core.nuspec +++ b/src/main/net-core/XMLUnit.Core.nuspec @@ -17,6 +17,7 @@ xmlunit xml unit-testing test xmldiff + docs\README.md @@ -25,5 +26,6 @@ + From b84d8caace935b3cd1721bdf449d38938cf78abd Mon Sep 17 00:00:00 2001 From: Stefan Bodewig Date: Fri, 25 Apr 2025 10:49:54 +0200 Subject: [PATCH 2/5] fix path --- src/main/net-core/XMLUnit.Core.nuspec | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/main/net-core/XMLUnit.Core.nuspec b/src/main/net-core/XMLUnit.Core.nuspec index 6455dd9..6e6ea92 100644 --- a/src/main/net-core/XMLUnit.Core.nuspec +++ b/src/main/net-core/XMLUnit.Core.nuspec @@ -26,6 +26,6 @@ - + From ec6720c993c662287c43bd22a64acdedab6814fb Mon Sep 17 00:00:00 2001 From: Stefan Bodewig Date: Fri, 25 Apr 2025 11:05:32 +0200 Subject: [PATCH 3/5] nuget package readmes for NUnit Constraints --- .../readmes/net-constraints-nunit2/README.md | 59 +++++++++++++++++++ .../readmes/net-constraints-nunit3/README.md | 59 +++++++++++++++++++ .../readmes/net-constraints-nunit4/README.md | 59 +++++++++++++++++++ .../XMLUnit.NUnit2.Constraints.nuspec | 2 + .../XMLUnit.NUnit3.Constraints.nuspec | 2 + .../XMLUnit.NUnit4.Constraints.nuspec | 2 + 6 files changed, 183 insertions(+) create mode 100644 src/doc/readmes/net-constraints-nunit2/README.md create mode 100644 src/doc/readmes/net-constraints-nunit3/README.md create mode 100644 src/doc/readmes/net-constraints-nunit4/README.md diff --git a/src/doc/readmes/net-constraints-nunit2/README.md b/src/doc/readmes/net-constraints-nunit2/README.md new file mode 100644 index 0000000..6add3a2 --- /dev/null +++ b/src/doc/readmes/net-constraints-nunit2/README.md @@ -0,0 +1,59 @@ +# XMLUnit.NET NUnit 2.x Constraints + +XMLUnit provides you with the tools to verify the XML you emit is the +one you want to create. + +This package provides Constraints on top of the XMLUnit.NET core +library to be used with NUnit 2.x. If you are using a different +version of NUUnit, please use the package for your version. + +* [XMLUnit.Core - Core Library ![nuget](https://img.shields.io/nuget/v/XMLUnit.Core.svg)](https://www.nuget.org/packages/XMLUnit.Core/) +* [XMLUnit.NUnit3.Constraints - Constraints for NUnit 3.x ![nuget](https://img.shields.io/nuget/v/XMLUnit.NUnit3.Constraints.svg)](https://www.nuget.org/packages/XMLUnit.NUnit3.Constraints/) +* [XMLUnit.NUnit4.Constraints - Constraints for NUnit 4.x ![nuget](https://img.shields.io/nuget/v/XMLUnit.NUnit4.Constraints.svg)](https://www.nuget.org/packages/XMLUnit.NUnit4.Constraints/) + +[![Build status](https://ci.appveyor.com/api/projects/status/am34dfbr4vbcarr3?svg=true)] + +## Requirements + +XMLUnit requires .NET Standard 2.0 (tested with .NET 8 rigt now) and +should still support .NET Framework 3.5 and Mono. + +This Constraints package requires NUnit 2.x and XMLUnit.Core. + +## Usage + +These are some really small examples, more is available as part of the +[user guide](https://github.com/xmlunit/user-guide/wiki) + +### Comparing Two Documents + +```csharp +Assert.That(CreateTestDocument(), CompareConstraint.IsIdenticalTo(Input.FromFile("test-data/good.xml"))); +``` + +### Asserting an XPath Value + +```csharp +Assert.That("bar", HasXPathConstraint.HasXPath("/foo")); +Assert.That("bar", EvaluateXPathConstraint.HasXPath("/foo/text()", +``` + +### Validating a Document Against an XML Schema + + +```csharp +Assert.That(CreateDocument(), + new ValidationConstraint(Input.FromFile("local.xsd"))); +``` + +## Additional Documentation + +XMLUnit.NET is developed at +[github](https://github.com/xmlunit/xmlunit.net). More documentation, +releases and an issue tracker can be found there. + +## Changelog + +See the [Release +Notes](https://github.com/xmlunit/xmlunit.net/blob/main/RELEASE_NOTES.md) +at github. diff --git a/src/doc/readmes/net-constraints-nunit3/README.md b/src/doc/readmes/net-constraints-nunit3/README.md new file mode 100644 index 0000000..9c460ef --- /dev/null +++ b/src/doc/readmes/net-constraints-nunit3/README.md @@ -0,0 +1,59 @@ +# XMLUnit.NET NUnit 3.x Constraints + +XMLUnit provides you with the tools to verify the XML you emit is the +one you want to create. + +This package provides Constraints on top of the XMLUnit.NET core +library to be used with NUnit 3.x. If you are using a different +version of NUUnit, please use the package for your version. + +* [XMLUnit.Core - Core Library ![nuget](https://img.shields.io/nuget/v/XMLUnit.Core.svg)](https://www.nuget.org/packages/XMLUnit.Core/) +* [XMLUnit.NUnit2.Constraints - Constraints for NUnit 2.x ![nuget](https://img.shields.io/nuget/v/XMLUnit.NUnit2.Constraints.svg)](https://www.nuget.org/packages/XMLUnit.NUnit2.Constraints/) +* [XMLUnit.NUnit4.Constraints - Constraints for NUnit 4.x ![nuget](https://img.shields.io/nuget/v/XMLUnit.NUnit4.Constraints.svg)](https://www.nuget.org/packages/XMLUnit.NUnit4.Constraints/) + +[![Build status](https://ci.appveyor.com/api/projects/status/am34dfbr4vbcarr3?svg=true)] + +## Requirements + +XMLUnit requires .NET Standard 2.0 (tested with .NET 8 rigt now) and +should still support .NET Framework 3.5 and Mono. + +This Constraints package requires NUnit 3.x and XMLUnit.Core. + +## Usage + +These are some really small examples, more is available as part of the +[user guide](https://github.com/xmlunit/user-guide/wiki) + +### Comparing Two Documents + +```csharp +Assert.That(CreateTestDocument(), CompareConstraint.IsIdenticalTo(Input.FromFile("test-data/good.xml"))); +``` + +### Asserting an XPath Value + +```csharp +Assert.That("bar", HasXPathConstraint.HasXPath("/foo")); +Assert.That("bar", EvaluateXPathConstraint.HasXPath("/foo/text()", +``` + +### Validating a Document Against an XML Schema + + +```csharp +Assert.That(CreateDocument(), + new ValidationConstraint(Input.FromFile("local.xsd"))); +``` + +## Additional Documentation + +XMLUnit.NET is developed at +[github](https://github.com/xmlunit/xmlunit.net). More documentation, +releases and an issue tracker can be found there. + +## Changelog + +See the [Release +Notes](https://github.com/xmlunit/xmlunit.net/blob/main/RELEASE_NOTES.md) +at github. diff --git a/src/doc/readmes/net-constraints-nunit4/README.md b/src/doc/readmes/net-constraints-nunit4/README.md new file mode 100644 index 0000000..a116f94 --- /dev/null +++ b/src/doc/readmes/net-constraints-nunit4/README.md @@ -0,0 +1,59 @@ +# XMLUnit.NET NUnit 4.x Constraints + +XMLUnit provides you with the tools to verify the XML you emit is the +one you want to create. + +This package provides Constraints on top of the XMLUnit.NET core +library to be used with NUnit 4.x. If you are using a different +version of NUUnit, please use the package for your version. + +* [XMLUnit.Core - Core Library ![nuget](https://img.shields.io/nuget/v/XMLUnit.Core.svg)](https://www.nuget.org/packages/XMLUnit.Core/) +* [XMLUnit.NUnit2.Constraints - Constraints for NUnit 2.x ![nuget](https://img.shields.io/nuget/v/XMLUnit.NUnit2.Constraints.svg)](https://www.nuget.org/packages/XMLUnit.NUnit2.Constraints/) +* [XMLUnit.NUnit3.Constraints - Constraints for NUnit 3.x ![nuget](https://img.shields.io/nuget/v/XMLUnit.NUnit3.Constraints.svg)](https://www.nuget.org/packages/XMLUnit.NUnit3.Constraints/) + +[![Build status](https://ci.appveyor.com/api/projects/status/am34dfbr4vbcarr3?svg=true)] + +## Requirements + +XMLUnit requires .NET Standard 2.0 (tested with .NET 8 rigt now) and +should still support .NET Framework 3.5 and Mono. + +This Constraints package requires NUnit 4.x and XMLUnit.Core. + +## Usage + +These are some really small examples, more is available as part of the +[user guide](https://github.com/xmlunit/user-guide/wiki) + +### Comparing Two Documents + +```csharp +Assert.That(CreateTestDocument(), CompareConstraint.IsIdenticalTo(Input.FromFile("test-data/good.xml"))); +``` + +### Asserting an XPath Value + +```csharp +Assert.That("bar", HasXPathConstraint.HasXPath("/foo")); +Assert.That("bar", EvaluateXPathConstraint.HasXPath("/foo/text()", +``` + +### Validating a Document Against an XML Schema + + +```csharp +Assert.That(CreateDocument(), + new ValidationConstraint(Input.FromFile("local.xsd"))); +``` + +## Additional Documentation + +XMLUnit.NET is developed at +[github](https://github.com/xmlunit/xmlunit.net). More documentation, +releases and an issue tracker can be found there. + +## Changelog + +See the [Release +Notes](https://github.com/xmlunit/xmlunit.net/blob/main/RELEASE_NOTES.md) +at github. diff --git a/src/main/net-constraints-nunit2/XMLUnit.NUnit2.Constraints.nuspec b/src/main/net-constraints-nunit2/XMLUnit.NUnit2.Constraints.nuspec index e4139bc..b39a6aa 100644 --- a/src/main/net-constraints-nunit2/XMLUnit.NUnit2.Constraints.nuspec +++ b/src/main/net-constraints-nunit2/XMLUnit.NUnit2.Constraints.nuspec @@ -22,10 +22,12 @@ xmlunit xml unit-testing test xmldiff nunit nunit2 + docs\README.md + diff --git a/src/main/net-constraints-nunit3/XMLUnit.NUnit3.Constraints.nuspec b/src/main/net-constraints-nunit3/XMLUnit.NUnit3.Constraints.nuspec index eaed99c..4700ee1 100644 --- a/src/main/net-constraints-nunit3/XMLUnit.NUnit3.Constraints.nuspec +++ b/src/main/net-constraints-nunit3/XMLUnit.NUnit3.Constraints.nuspec @@ -22,6 +22,7 @@ xmlunit xml unit-testing test xmldiff nunit nunit3 + docs\README.md @@ -30,5 +31,6 @@ + diff --git a/src/main/net-constraints-nunit4/XMLUnit.NUnit4.Constraints.nuspec b/src/main/net-constraints-nunit4/XMLUnit.NUnit4.Constraints.nuspec index b08006f..10d189a 100644 --- a/src/main/net-constraints-nunit4/XMLUnit.NUnit4.Constraints.nuspec +++ b/src/main/net-constraints-nunit4/XMLUnit.NUnit4.Constraints.nuspec @@ -22,6 +22,7 @@ xmlunit xml unit-testing test xmldiff nunit nunit4 + docs\README.md @@ -30,5 +31,6 @@ + From e234d9149781f7bb235562d11a116ffe2a32d725 Mon Sep 17 00:00:00 2001 From: Stefan Bodewig Date: Fri, 25 Apr 2025 11:20:23 +0200 Subject: [PATCH 4/5] readme for placeholders package --- src/doc/readmes/net-placeholders/README.md | 70 +++++++++++++++++++ .../XMLUnit.Placeholders.nuspec | 2 + 2 files changed, 72 insertions(+) create mode 100644 src/doc/readmes/net-placeholders/README.md diff --git a/src/doc/readmes/net-placeholders/README.md b/src/doc/readmes/net-placeholders/README.md new file mode 100644 index 0000000..9667f07 --- /dev/null +++ b/src/doc/readmes/net-placeholders/README.md @@ -0,0 +1,70 @@ +# XMLUnit.NET + +XMLUnit provides you with the tools to verify the XML you emit is the +one you want to create. + +This package provides a way to simplify comparisons by using a control +document with a simple expression language to compare against. + +## Requirements + +XMLUnit requires .NET Standard 2.0 (tested with .NET 8 rigt now) and +should still support .NET Framework 3.5 and Mono. + +The placeholders package only depends on XMLUnit.Core. + +## Usage + +More documentaion is available as part of +the [user guide](https://github.com/xmlunit/user-guide/wiki). + +If you are creating documents with a structure like + +```xml + + 12345 + Hello + +``` + +and can't predict the `id` inside your tests but still want to assert +it is a number, using just the core library will require some custom +code as a `IDifferenceEvaluator` + +Using the placeholders package you can write a control document like + +```xml + + ${xmlunit.isNumber} + Hello + +``` + +and run the test like + +```csharp +string control = ; +string test = ; +Diff diff = DiffBuilder.Compare(control).WithTest(test) + .WithDifferenceEvaluator(new PlaceholderDifferenceEvaluator()).build(); +Assert.IsFalse(d.HasDifferences()); +``` + +Currently the fillowing placeholders are defined: + +* `${xmlunit.ignore}` to completely ignore the element +* `${xmlunit.isNumber}` +* `${xmlunit.matchesRegex()}` with regex parameter +* `${xmlunit.isDateTime()}` with optional format parameter + +## Additional Documentation + +XMLUnit.NET is developed at +[github](https://github.com/xmlunit/xmlunit.net). More documentation, +releases and an issue tracker can be found there. + +## Changelog + +See the [Release +Notes](https://github.com/xmlunit/xmlunit.net/blob/main/RELEASE_NOTES.md) +at github. diff --git a/src/main/net-placeholders/XMLUnit.Placeholders.nuspec b/src/main/net-placeholders/XMLUnit.Placeholders.nuspec index 1f52af8..bc9643d 100644 --- a/src/main/net-placeholders/XMLUnit.Placeholders.nuspec +++ b/src/main/net-placeholders/XMLUnit.Placeholders.nuspec @@ -20,6 +20,7 @@ xmlunit xml unit-testing test xmldiff + docs\README.md @@ -28,5 +29,6 @@ + From 3daf73d24d609c3cbaba6a90bc3f359cdcfff5e3 Mon Sep 17 00:00:00 2001 From: Stefan Bodewig Date: Fri, 25 Apr 2025 11:21:46 +0200 Subject: [PATCH 5/5] record addition of readmes - closes #46 --- RELEASE_NOTES.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 19668ff..c5c4716 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -2,6 +2,9 @@ ## XMLUnit.NET 2.11.1 - /Not Released, yet/ +* added readme files for the nuget packages. + Issue [#46](https://github.com/xmlunit/xmlunit.net/issues/46). + * the NUnit 4.x constraints package tags nunit3 rather than nunit4. PR [#43](https://github.com/xmlunit/xmlunit.net/issues/43).