From 157b80b1d54e85ad707210fb78aa1e9fed0684a2 Mon Sep 17 00:00:00 2001 From: Chris C Date: Wed, 19 Jul 2023 15:03:37 -0600 Subject: [PATCH] Updated the ReadMe with v1.1.0+ compatibility. Also updated the quickstart and examples. --- README.md | 78 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 58 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 8006d8c..c62fd47 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,39 @@ +![CI/CD](https://github.com/saturdaymp/NConstraints/actions/workflows/ci.yml/badge.svg) +![Release Notes](https://github.com/saturdaymp/NConstraints/actions/workflows/release-notes.yml/badge.svg) + # NConstraints -Adds additional [constraints](https://github.com/nunit/docs/wiki/Constraints) to [NUnit](https://github.com/nunit/nunit) such as comparing all the property values on two objects. +Adds additional [constraints](https://github.com/nunit/docs/wiki/Constraints) to [NUnit](https://github.com/nunit/nunit) such as comparing the properties of two objects. + +## Installing +Install by adding the [SaturdayMP.NContraints](https://www.nuget.org/packages/SaturdayMP.NConstraints) NuGet package: + +``` +dotnet add package SaturdayMP.NConstraints +``` + +You can find alternative install methods on the NuGet [page](https://www.nuget.org/packages/SaturdayMP.NConstraints). + +NConstraints is compatible with [.NET Standard 2.0](https://dotnet.microsoft.com/en-us/platform/dotnet-standard#versions) and [NUnit 3](https://github.com/nunit/nunit). If you would like to use NConstraints on a older project please try [v1.0.0](https://www.nuget.org/packages/SaturdayMP.NConstraints/1.0.0) which is compatiable with [.NET Standard 1.6](https://dotnet.microsoft.com/en-us/platform/dotnet-standard#versions). -# Installing -You can find the latest stable NuGet package at [here](https://www.nuget.org/packages/SaturdayMP.NConstraints). If you want the live on the wild side you can find the developer NuGet packages on [MyGet](https://www.myget.org/feed/saturdaymp/package/nuget/SaturdayMP.NConstraints). +If you want the live on the wild side you can find the alpha/beta NuGet packages on [MyGet](https://www.myget.org/feed/saturdaymp/package/nuget/SaturdayMP.NConstraints). -If you have any issues with the installation please let me know by opening an [issue](https://github.com/saturdaymp/NConstraints/issues) or [pull request](https://github.com/saturdaymp/NConstraints/pulls). +Please report issues with the installation by opening an [issue](https://github.com/saturdaymp/NConstraints/issues) or [pull request](https://github.com/saturdaymp/NConstraints/pulls). Feel free to ping me if you want to use NConstraints with an older versions of NUnit and/or .NET and I'll see what I can do. -# Quickstart -The additional constraints can be used when using [Assert.That](https://github.com/nunit/docs/wiki/Assertions) and extend the [Is helper class](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Is.cs). For example: +## Quickstart +```C# +using NUnit.Framework; // Assume you already added this +using SaturdayMP.NConstraints; // Add this statement. +using Is = SaturdayMP.NConstraints.Is; // Add this statement. +``` + +Now you can write: + +```C# +Assert.That(expected, Is.EquivalentPropertyWiseTo(actual); +``` + +## Details +NConstratins extends the [Is helper class](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Is.cs) which is used when writting [Assert.That](https://github.com/nunit/docs/wiki/Assertions) statements. For example: ```C# Assert.That(expected, SaturdayMP.NConstraints.Is.EquivalentPropertyWiseTo(actual); @@ -62,48 +88,60 @@ You will get compile errors because there are two Is classes, one in the NUnit.F Finally some code analyizers, like [ReSharper](https://www.jetbrains.com/resharper/), will raise warnings like "Access to a static member or a type via a dirvied type". You can safely ignore these warnings, I don't know a good way to remove these warnings. If you do please open an [issue](https://github.com/saturdaymp/NConstraints/issues) or [pull request](https://github.com/saturdaymp/NConstraints/pulls). -# Constraints +## Constraints This project adds the following constraints to NUnit: | Constraint Name | Description | |:--- |:--- | | [EquivalentPropertyWiseTo](#equivalentpropertywiseto) | Asserts that the property values of expected object are the same on the actual object. | -## EquivalentPropertyWiseTo +### EquivalentPropertyWiseTo Asserts that the property values of expected object are the same on the actual object. The objects don't have to be the same class but if a property exists on the expected object but not on the actual object then the assert fails. ```C# /// -/// Properties don't match up. +/// Objects are equivalent if they have the same properties and they are all the same. /// [Test] -public void PropertiesNotTheSame() +public void PropertiesTheSame() { - var expected = new TestClass() {IntegerProperty = 1}; - var actual = new TestClass(); + var expected = new TestClass() {IntegerPropery = 1, StringPropery = "Test"}; + var actual = new TestClass() {IntegerPropery = expected.IntegerPropery, StringPropery = expected.StringPropery}; - Assert.That(expected, NUnit.Framework.Is.Not.EquivalentPropertyWiseTo(actual)); + Assert.That(expected, Is.EquivalentPropertyWiseTo(actual)); } /// -/// Properties match. +/// Objects are alos equivalent if all the property values match but actual has properties not on actual. /// [Test] public void PropertiesTheSame() { - var expected = new TestClass() { IntegerProperty = 1 }; - var actual = new TestClass() {IntegerProperty = expected.IntegerProperty}; + var expected = new TestClass() {IntegerPropery = 1, StringPropery = "Test"}; + var actual = new TestClass2() {IntegerPropery = expected.IntegerPropery, SecondIntegerProperty = 2, StringPropery = expected.StringPropery}; + + Assert.That(expected, Is.EquivalentPropertyWiseTo(actual)); +} + +/// +/// Objects are NOT equivalent if expected has a property not on actual. +/// +[Test] +public void PropertyDoesNotExistOnActual() +{ + var expected = new TestClass2() { IntegerPropery = 1, SecondIntegerProperty = 2, StringPropery = "Test"}; + var actual = new TestClass() { IntegerPropery = expected.IntegerPropery, StringPropery = expected.StringPropery}; - Assert.That(expected, Is.EquivalentPropertyWiseTo(actual)); + Assert.That(expected, Is.Not.EquivalentPropertyWiseTo(actual)) } ``` -# Contributing +## Contributing If you have any questions, notice a bug, or have a suggestion/enhancment please let me know by: - opening a [issue](https://github.com/saturdaymp/NConstraints/issues) or [pull request](https://github.com/saturdaymp/NConstraints/pulls). - asking a question on [StackOverflow](https://stackoverflow.com/) with the tag *nconstraints*. - send an e-mail to support@saturdaymp.com. -# Acknowledgements -Thanks to the [NUnit team](https://github.com/orgs/nunit/people) for creating NUnit and continuing to support it. I’ve used NUnit for most of my career to properly test and improve my code. +## Acknowledgements +Thanks to the [NUnit team](https://github.com/orgs/nunit/people) for creating NUnit and continuing to support it. NUnit was one of the first frameworks as a young developer.