Bump to version 3.0.0-preview.1

xaviersolau · xaviersolau · commit c54cc3dcc8de · 2026-03-13T02:42:42.000+01:00
diff --git a/CodeQuality.sln b/CodeQuality.sln
@@ -9,6 +9,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "SoloX.CodeQuality.Test", "s
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Documents", "Documents", "{57F5BB2E-CD03-470B-BF16-31FE02A386B1}"
 	ProjectSection(SolutionItems) = preProject
+		documents\BreakingChanges.md = documents\BreakingChanges.md
 		LICENSE = LICENSE
 		README.md = README.md
 		src\SharedProperties.props = src\SharedProperties.props
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # CodeQuality
 
-This project provides an easy way to set up .Net Core [static code analysis](#coding-style-and-analysis) with pre-configured quality and coding style
+This project provides an easy way to set up .NET [static code analysis](#coding-style-and-analysis) with pre-configured quality and coding style
 rules for your Test and your Prod C# projects.
 
 It also provides:
@@ -14,15 +14,20 @@ It also provides:
 [![Build - CI](https://github.com/xaviersolau/CodeQuality/actions/workflows/build-ci.yml/badge.svg)](https://github.com/xaviersolau/CodeQuality/actions/workflows/build-ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-| Package                                 | Nuget.org | Pre-release |
-|-----------------------------------------|-----------|-------------|
-|**SoloX.CodeQuality.Prod**               |[![NuGet Beta](https://img.shields.io/nuget/v/SoloX.CodeQuality.Prod.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Prod)                             |[![NuGet Beta](https://img.shields.io/nuget/vpre/SoloX.CodeQuality.Prod.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Prod)
-|**SoloX.CodeQuality.Test**               |[![NuGet Beta](https://img.shields.io/nuget/v/SoloX.CodeQuality.Test.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Test)                             |[![NuGet Beta](https://img.shields.io/nuget/vpre/SoloX.CodeQuality.Test.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Test)
-|**SoloX.CodeQuality.Playwright**         |[![NuGet Beta](https://img.shields.io/nuget/v/SoloX.CodeQuality.Playwright.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Playwright)                 |[![NuGet Beta](https://img.shields.io/nuget/vpre/SoloX.CodeQuality.Playwright.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Playwright)
-|**SoloX.CodeQuality.Test.Helpers**       |[![NuGet Beta](https://img.shields.io/nuget/v/SoloX.CodeQuality.Test.Helpers.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Test.Helpers)             |[![NuGet Beta](https://img.shields.io/nuget/vpre/SoloX.CodeQuality.Test.Helpers.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Test.Helpers)
-|**SoloX.CodeQuality.Test.Helpers.XUnit** |[![NuGet Beta](https://img.shields.io/nuget/v/SoloX.CodeQuality.Test.Helpers.XUnit.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Test.Helpers.XUnit) |[![NuGet Beta](https://img.shields.io/nuget/vpre/SoloX.CodeQuality.Test.Helpers.XUnit.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Test.Helpers.XUnit)
-|**SoloX.CodeQuality.Test.Helpers.NUnit** |[![NuGet Beta](https://img.shields.io/nuget/v/SoloX.CodeQuality.Test.Helpers.NUnit.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Test.Helpers.NUnit) |[![NuGet Beta](https://img.shields.io/nuget/vpre/SoloX.CodeQuality.Test.Helpers.NUnit.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Test.Helpers.NUnit)
-|**SoloX.CodeQuality.WebHost**            |[![NuGet Beta](https://img.shields.io/nuget/v/SoloX.CodeQuality.WebHost.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.WebHost)                       |[![NuGet Beta](https://img.shields.io/nuget/vpre/SoloX.CodeQuality.WebHost.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.WebHost)
+| Package                                     | Nuget.org | Pre-release |
+|---------------------------------------------|-----------|-------------|
+|**SoloX.CodeQuality.Prod**                   |[![NuGet Beta](https://img.shields.io/nuget/v/SoloX.CodeQuality.Prod.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Prod)                                   |[![NuGet Beta](https://img.shields.io/nuget/vpre/SoloX.CodeQuality.Prod.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Prod)
+|**SoloX.CodeQuality.Test**                   |[![NuGet Beta](https://img.shields.io/nuget/v/SoloX.CodeQuality.Test.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Test)                                   |[![NuGet Beta](https://img.shields.io/nuget/vpre/SoloX.CodeQuality.Test.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Test)
+|**SoloX.CodeQuality.Playwright**             |[![NuGet Beta](https://img.shields.io/nuget/v/SoloX.CodeQuality.Playwright.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Playwright)                       |[![NuGet Beta](https://img.shields.io/nuget/vpre/SoloX.CodeQuality.Playwright.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Playwright)
+|**SoloX.CodeQuality.Test.Helpers**           |[![NuGet Beta](https://img.shields.io/nuget/v/SoloX.CodeQuality.Test.Helpers.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Test.Helpers)                   |[![NuGet Beta](https://img.shields.io/nuget/vpre/SoloX.CodeQuality.Test.Helpers.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Test.Helpers)
+|~~**SoloX.CodeQuality.Test.Helpers.XUnit**~~ |[![NuGet Beta](https://img.shields.io/nuget/v/SoloX.CodeQuality.Test.Helpers.XUnit.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Test.Helpers.XUnit)       |[![NuGet Beta](https://img.shields.io/nuget/vpre/SoloX.CodeQuality.Test.Helpers.XUnit.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Test.Helpers.XUnit)
+|**SoloX.CodeQuality.Test.Helpers.XUnit.V3**  |[![NuGet Beta](https://img.shields.io/nuget/v/SoloX.CodeQuality.Test.Helpers.XUnit.V3.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Test.Helpers.XUnit.V3) |[![NuGet Beta](https://img.shields.io/nuget/vpre/SoloX.CodeQuality.Test.Helpers.XUnit.V3.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Test.Helpers.XUnit.V3)
+|**SoloX.CodeQuality.Test.Helpers.NUnit**     |[![NuGet Beta](https://img.shields.io/nuget/v/SoloX.CodeQuality.Test.Helpers.NUnit.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Test.Helpers.NUnit)       |[![NuGet Beta](https://img.shields.io/nuget/vpre/SoloX.CodeQuality.Test.Helpers.NUnit.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.Test.Helpers.NUnit)
+|**SoloX.CodeQuality.WebHost**                |[![NuGet Beta](https://img.shields.io/nuget/v/SoloX.CodeQuality.WebHost.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.WebHost)                             |[![NuGet Beta](https://img.shields.io/nuget/vpre/SoloX.CodeQuality.WebHost.svg)](https://www.nuget.org/packages/SoloX.CodeQuality.WebHost)
+
+> Find out the [Breaking changes](documents/BreakingChanges.md) from one version to another.
+
+> Note that from version 3.0.* the `SoloX.CodeQuality.Test.Helpers.XUnit` package is obsolete since [xUnit.net](https://xunit.net) switched to V3.
 
 ## License and credits
 
@@ -42,7 +47,7 @@ This project is not implementing analysis by itself, it is using existing analys
 
 
 **Note that before version 2.1.0 the AnalysisLevel property was set to "latest" resulting in breaking the build just on framework update.**
-**So from version 2.1.0 the analysis level is fixed to a specific version (in our case 8.0)**
+**So from version 2.1.0 the analysis level is fixed to a specific version (currently 10.0 with version 3.0.0)**
 
 * * *
 
@@ -52,26 +57,26 @@ You can checkout this Github repository or you can use the NuGet package:
 
 **Install using the command line from the Package Manager:**
 ```bash
-Install-Package SoloX.CodeQuality.Prod -version 2.3.6
+Install-Package SoloX.CodeQuality.Prod -version 3.0.0-preview.1
 or
-Install-Package SoloX.CodeQuality.Test -version 2.3.6
+Install-Package SoloX.CodeQuality.Test -version 3.0.0-preview.1
 ```
 
 **Install using the .Net CLI:**
 ```bash
-dotnet add package SoloX.CodeQuality.Prod --version 2.3.6
+dotnet add package SoloX.CodeQuality.Prod --version 3.0.0-preview.1
 or
-dotnet add package SoloX.CodeQuality.Test --version 2.3.6
+dotnet add package SoloX.CodeQuality.Test --version 3.0.0-preview.1
 ```
 
 **Install editing your project file (csproj):**
 ```xml
-<PackageReference Include="SoloX.CodeQuality.Prod" Version="2.3.6">
+<PackageReference Include="SoloX.CodeQuality.Prod" Version="3.0.0-preview.1">
   <PrivateAssets>all</PrivateAssets>
   <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
 </PackageReference>
 or
-<PackageReference Include="SoloX.CodeQuality.Test" Version="2.3.6">
+<PackageReference Include="SoloX.CodeQuality.Test" Version="3.0.0-preview.1">
   <PrivateAssets>all</PrivateAssets>
   <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
 </PackageReference>
@@ -218,17 +223,17 @@ You can checkout this Github repository or use the NuGet package:
 
 **Install using the command line from the Package Manager:**
 ```bash
-Install-Package SoloX.CodeQuality.Playwright -version 2.3.6
+Install-Package SoloX.CodeQuality.Playwright -version 3.0.0-preview.1
 ```
 
 **Install using the .Net CLI:**
 ```bash
-dotnet add package SoloX.CodeQuality.Playwright --version 2.3.6
+dotnet add package SoloX.CodeQuality.Playwright --version 3.0.0-preview.1
 ```
 
 **Install editing your project file (csproj):**
 ```xml
-<PackageReference Include="SoloX.CodeQuality.Playwright" Version="2.3.6" />
+<PackageReference Include="SoloX.CodeQuality.Playwright" Version="3.0.0-preview.1" />
 ```
 
 * * *
@@ -309,8 +314,8 @@ builder.WithLocalHost(localHostBuilder =>
     });
 ```
 
-> Note that your host must be based on .Net 8.0 and it must use the `WebApplication.CreateBuilder(args)` method to build your Web host. If
-> you still use the hold way with `Host.CreateDefaultBuilder(args)` and a `Startup.cs` file, you will get an exception like this
+> Note that your host must be based on .NET 8.0 or later and it must use the `WebApplication.CreateBuilder(args)` method to build your Web host. If
+> you still use the old way with `Host.CreateDefaultBuilder(args)` and a `Startup.cs` file, you will get an exception like this
 > `System.InvalidOperationException : Build can only be called once.` and you won't be able to start your test.
 
 On-line host:
@@ -424,29 +429,35 @@ You can checkout this Github repository or you can use the NuGet package:
 
 **Install using the command line from the Package Manager:**
 ```bash
-Install-Package SoloX.CodeQuality.Test.Helpers -version 2.3.6
+Install-Package SoloX.CodeQuality.Test.Helpers -version 3.0.0-preview.1
 
-Install-Package SoloX.CodeQuality.Test.Helpers.XUnit -version 2.3.6
+Install-Package SoloX.CodeQuality.Test.Helpers.XUnit -version 3.0.0-preview.1
 
-Install-Package SoloX.CodeQuality.Test.Helpers.NUnit -version 2.3.6
+Install-Package SoloX.CodeQuality.Test.Helpers.XUnit.V3 -version 3.0.0-preview.1
+
+Install-Package SoloX.CodeQuality.Test.Helpers.NUnit -version 3.0.0-preview.1
 ```
 
 **Install using the .Net CLI:**
 ```bash
-dotnet add package SoloX.CodeQuality.Test.Helpers --version 2.3.6
+dotnet add package SoloX.CodeQuality.Test.Helpers --version 3.0.0-preview.1
+
+dotnet add package SoloX.CodeQuality.Test.Helpers.XUnit --version 3.0.0-preview.1
 
-dotnet add package SoloX.CodeQuality.Test.Helpers.XUnit --version 2.3.6
+dotnet add package SoloX.CodeQuality.Test.Helpers.XUnit.V3 --version 3.0.0-preview.1
 
-dotnet add package SoloX.CodeQuality.Test.Helpers.NUnit --version 2.3.6
+dotnet add package SoloX.CodeQuality.Test.Helpers.NUnit --version 3.0.0-preview.1
 ```
 
 **Install editing your project file (csproj):**
 ```xml
-<PackageReference Include="SoloX.CodeQuality.Test.Helpers" Version="2.3.6" />
+<PackageReference Include="SoloX.CodeQuality.Test.Helpers" Version="3.0.0-preview.1" />
 
-<PackageReference Include="SoloX.CodeQuality.Test.Helpers.XUnit" Version="2.3.6" />
+<PackageReference Include="SoloX.CodeQuality.Test.Helpers.XUnit" Version="3.0.0-preview.1" />
 
-<PackageReference Include="SoloX.CodeQuality.Test.Helpers.NUnit" Version="2.3.6" />
+<PackageReference Include="SoloX.CodeQuality.Test.Helpers.XUnit.V3" Version="3.0.0-preview.1" />
+
+<PackageReference Include="SoloX.CodeQuality.Test.Helpers.NUnit" Version="3.0.0-preview.1" />
 ```
 
  * * *
@@ -479,23 +490,68 @@ var response = await httpClient.GetFromJsonAsync<Person>("target");
 
 ```
 
+ * * *
+
+### Snapshot testing
+
+Snapshot testing is a powerful technique for testing text and image outputs. The `SnapshotHelper` class provided in
+`SoloX.CodeQuality.Test.Helpers` makes it easy to create and maintain snapshot tests.
+
+Snapshots are stored on disk and compared against test outputs. This is useful for testing scenarios such as:
+* Text comparisons (JSON, XML, code generation outputs, etc.)
+* Image comparisons
+* Large data structure validations
+
+#### Basic usage
+
+To use the `SnapshotHelper` in your tests, simply create an instance and use its methods to verify outputs:
+
+```csharp
+using SoloX.CodeQuality.Test.Helpers.Snapshot;
+
+var snapshotHelper = new SnapshotHelper();
+
+// For text snapshots
+string generatedOutput = GenerateContent();
+await snapshotHelper.CompareTextSnapshotAsync(nameof(MyTest), generatedOutput);
+
+// For image snapshots
+Stream generatedPngImage = GeneratePngImage();
+await snapshotHelper.ComparePngSnapshotAsync(nameof(MyTest), generatedImage);
+```
+
+#### Configuration
+
+You can configure the `SnapshotHelper` with custom options:
+
+```csharp
+var snapshotHelper = new SnapshotHelper(options =>
+{
+    options.IntermediateFolder = "CustomSnapshotsFolder";
+    options.RootPath = "/path/to/test/project";
+});
+```
+
+The snapshots are stored in a `Snapshots` folder by default and can be reviewed and updated when the expected output changes.
+
+ * * *
+
 ### ILogger\<T> mocking
 
 We often need to provide a ILogger\<T> instance to the class we want to test. This is easy to provide a
 mock of this interface but sometime it is actually useful to be able to write the logs into the test
 output. In order to write the logs in the test console output you can use the TestLogger available for
 XUnit and NUnit.
 
-#### With XUnit
+#### With XUnit or XUnit.V3
 
-The XUnit TestLogger is provided in the package `SoloX.CodeQuality.Test.Helpers.XUnit` and it can be
-used like this:
+The XUnit TestLogger is provided in the package `SoloX.CodeQuality.Test.Helpers.XUnit.V3` (or
+`SoloX.CodeQuality.Test.Helpers.XUnit` for XUnit V2) and it can be used like this:
 
 ```csharp
 using Microsoft.Extensions.Logging;
-using SoloX.CodeQuality.Test.Helpers.XUnit.Logger;
+using SoloX.CodeQuality.Test.Helpers.XUnit.V3.Logger;
 using Xunit;
-using Xunit.Abstractions;
 
 public class LoggerTest
 {
@@ -524,9 +580,8 @@ some integration tests using a service provider:
 ```csharp
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
-using SoloX.CodeQuality.Test.Helpers.XUnit.Logger;
+using SoloX.CodeQuality.Test.Helpers.XUnit.V3.Logger;
 using Xunit;
-using Xunit.Abstractions;
 
 public class LoggerTest
 {
@@ -555,7 +610,6 @@ public class LoggerTest
 }
 ```
 
-
 #### With NUnit
 
 The NUnit TestLogger is provided in the package `SoloX.CodeQuality.Test.Helpers.NUnit` and it can be
@@ -603,9 +657,8 @@ public class LoggerTest
         var logger = serviceProvider.GetRequiredService<ILogger<LoggerTest>>();
  
         logger.LogError("This is an error log message!");
- 
+
         Assert.Pass();
     }
 }
 ```
-
diff --git a/documents/BreakingChanges.md b/documents/BreakingChanges.md
@@ -0,0 +1,66 @@
+# Breaking Changes
+
+## Since version 3.0.*
+
+### Snapshot Helper Rework
+
+The `SnapshotHelper` API has been significantly reworked with breaking changes to the available methods and their signatures:
+
+#### Key Changes
+- **Moved** from `SoloX.CodeQuality.Test.Helpers.XUnit` to `SoloX.CodeQuality.Test.Helpers` project and namespace.
+
+- **Dependency change**: The `SnapshotHelper` class no longer depends on xUnit-specific types, making it more flexible and reusable
+across different testing frameworks.
+
+- **Static to instance**: The `SnapshotHelper` class is no longer static. You must create an instance of `SnapshotHelper` to use its methods.
+
+- **New asynchronous API**: All snapshot methods are now async (`Task`-based) and must be awaited.
+  - Old: `AssertSnapshot(string generated, string snapshotName, string location)`
+  - New: `await CompareTextSnapshotAsync(string name, string content)`
+
+- **PNG file snapshot support**: New support for comparing PNG image snapshots has been added via `ComparePngSnapshotAsync()`.
+  - Includes configurable `differencesThreshold` parameter for image comparison tolerance.
+
+- **Configuration-based initialization**: The constructor now uses a fluent configuration pattern.
+  - Old: location was specified as parameter of the static AssertSnapshot method.
+  - New: `new SnapshotHelper(options => options.IntermediateFolder = intermediateFolder)`
+
+- **Force replace capability**: All comparison methods now support a `forceReplaceSnapshot` parameter to update existing snapshots.
+
+#### Migration Example
+
+```csharp
+// Old code (no longer works)
+var location = "Path where to read/write snapshot files";
+SnapshotHelper.AssertSnapshot("Some text to match against the snapshot", snapshotName, location);
+
+// New code
+var helper = new SnapshotHelper(options => options.RootPath = "Root path where to read/write snapshot files");
+await helper.CompareTextSnapshotAsync(snapshotName, "Some text to match against the snapshot");
+
+// For PNG snapshots (new capability)
+await helper.ComparePngSnapshotAsync(snapshotName, pngStream, differencesThreshold: 0.01);
+```
+
+#### Migration Steps
+
+1. Setup with `SnapshotHelper` instantiation and use the configuration action.
+2. Change all `SnapshotHelper.AssertSnapshot()` calls to `CompareTextSnapshotAsync()` and add `await`.
+3. Review snapshot test methods and mark them as `async Task`.
+4. Existing snapshot text files (`.snapshot`) are compatible; you just need to rename with (`.snapshot.ref.txt`).
+
+### Dependency Changes
+
+- **FluentAssertions** dependency has been **removed** from the package.
+  - The package no longer includes FluentAssertions as a transitive dependency.
+  - If your project requires FluentAssertions, you can still use it by explicitly adding it as a project dependency.
+  - Consider using alternative assertion libraries such as:
+    - xUnit's built-in assertions
+    - Shouldly (already used in CodeQuality project)
+    - Other assertion frameworks compatible with .NET
+
+### xUnit V3 Support
+
+- New **xUnit V3 support** has been added through the `SoloX.CodeQuality.Test.Helpers.XUnit.V3` package.
+- Projects migrating to xUnit V3 should use the new V3-specific helpers instead of the legacy helpers.
+- The legacy xUnit V2 support is still available but may not receive further updates.
diff --git a/src/SharedProperties.props b/src/SharedProperties.props
@@ -1,7 +1,7 @@
 <Project>
 
   <PropertyGroup>
-    <Version>2.3.6</Version>
+    <Version>3.0.0-preview.1</Version>
     <Authors>Xavier Solau</Authors>
     <Copyright>Copyright © 2021 Xavier Solau</Copyright>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
@@ -14,7 +14,7 @@
     <CodeQualityHeaderLicense>$(PackageLicenseExpression)</CodeQualityHeaderLicense>
     <CodeQualityHeaderLicenseFile>LICENSE</CodeQualityHeaderLicenseFile>
 
-    <AssemblyVersion>2.3.6.0</AssemblyVersion>
+    <AssemblyVersion>3.0.0.0</AssemblyVersion>
     <LangVersion>14</LangVersion>
 
   </PropertyGroup>
