feat: add TUnit.Assertions.Should package

README.md

@@ -139,6 +139,7 @@ See the [documentation](https://tunit.dev/docs/getting-started/attributes) for m
 | `TUnit.Core` | Shared test library components without an execution engine |
 | `TUnit.Engine` | Execution engine for test projects |
 | `TUnit.Assertions` | Standalone assertions — works with other test frameworks too |
+| `TUnit.Assertions.Should` | Optional FluentAssertions-style `value.Should().BeEqualTo(...)` syntax over `TUnit.Assertions` (beta) |
 | `TUnit.Playwright` | Playwright integration with automatic browser lifecycle management |
 
 ## Migrating from xUnit, NUnit, or MSTest?

SharedTestHelpers/AnalyzerTestCompatibility.cs

@@ -0,0 +1,39 @@
+using System;
+using System.IO;
+using System.Reflection;
+
+namespace TUnit.Tests.Shared;
+
+/// <summary>
+/// Shared resolution helper for the analyzer-test framework's reference-assembly mismatch.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The Microsoft.CodeAnalysis.Testing 1.1.2 framework targets net9.0 reference assemblies. Loading
+/// TUnit's net10.0 builds via <c>typeof(...).Assembly.Location</c> raises CS1705 (referenced
+/// assembly has a higher System.Runtime version), which the verifier suppresses via
+/// <c>CompilerDiagnostics = None</c>. The suppression silently breaks symbol resolution for every
+/// extension method (IsEqualTo, Throws, etc.) in the test compilation — analyzers find nothing
+/// to flag and tests report "expected 1 diagnostic, actual 0" with no compiler errors visible.
+/// </para>
+/// <para>
+/// The fix is to load the netstandard2.0 builds (compatible with both Net90 ref assemblies and the
+/// test runtime). Each analyzer test csproj copies the relevant netstandard2.0 build into the test
+/// bin via a <c>&lt;None Include="..." Link="X.netstandard2.0.dll" CopyToOutputDirectory="..."&gt;</c>
+/// item; this helper resolves the copy when present, falling back to the runtime assembly path so
+/// the build doesn't hard-fail before the copy item runs.
+/// </para>
+/// <para>
+/// Linked into multiple test projects via <c>&lt;Compile Include="..\SharedTestHelpers\..."&gt;</c>;
+/// see <c>TUnit.Assertions.Should.SourceGenerator</c> for the same pattern with
+/// <c>CovarianceHelper</c>/<c>EquatableArray</c>.
+/// </para>
+/// </remarks>
+internal static class AnalyzerTestCompatibility
+{
+    public static string GetCompatibleDllPath(string assemblyName, Assembly fallback)
+    {
+        var ns20Path = Path.Combine(AppContext.BaseDirectory, $"{assemblyName}.netstandard2.0.dll");
+        return File.Exists(ns20Path) ? ns20Path : fallback.Location;
+    }
+}

TUnit.Analyzers.Tests/AnalyzerTestHelpers.cs

@@ -34,9 +34,9 @@ public static CSharpAnalyzerTest<TAnalyzer, DefaultVerifier> CreateAnalyzerTest<
         csTest.TestState.AdditionalReferences
             .AddRange(
                 [
-                    MetadataReference.CreateFromFile(typeof(TUnitAttribute).Assembly.Location),
+                    MetadataReference.CreateFromFile(TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.Core", typeof(TUnitAttribute).Assembly)),
                     MetadataReference.CreateFromFile(typeof(CircuitState).Assembly.Location),
-                    MetadataReference.CreateFromFile(typeof(ProjectReferenceEnum).Assembly.Location)
+                    MetadataReference.CreateFromFile(TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.TestProject.Library", typeof(ProjectReferenceEnum).Assembly))
                 ]
             );
 
@@ -145,9 +145,9 @@ public static CSharpSuppressorTest<TSuppressor, DefaultVerifier> CreateSuppresso
 
         test.TestState.AdditionalReferences
             .AddRange([
-                MetadataReference.CreateFromFile(typeof(TUnitAttribute).Assembly.Location),
+                MetadataReference.CreateFromFile(TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.Core", typeof(TUnitAttribute).Assembly)),
                 MetadataReference.CreateFromFile(typeof(CircuitState).Assembly.Location),
-                MetadataReference.CreateFromFile(typeof(ProjectReferenceEnum).Assembly.Location)
+                MetadataReference.CreateFromFile(TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.TestProject.Library", typeof(ProjectReferenceEnum).Assembly))
             ]);
 
         return test;

TUnit.Analyzers.Tests/TUnit.Analyzers.Tests.csproj

@@ -22,6 +22,27 @@
     <ProjectReference Include="..\TUnit.Assertions\TUnit.Assertions.csproj" />
   </ItemGroup>
 
+  <!-- Copy netstandard2.0 builds into the test bin so the analyzer-test framework's
+       Net90 reference assemblies don't trigger CS1705 against the net10.0 builds otherwise
+       loaded via typeof(...).Assembly.Location. CS1705 is suppressed silently and the resulting
+       symbol-resolution failures cause analyzers to find nothing to flag. -->
+  <ItemGroup>
+    <None Include="..\TUnit.Core\bin\$(Configuration)\netstandard2.0\TUnit.Core.dll"
+          Link="TUnit.Core.netstandard2.0.dll"
+          CopyToOutputDirectory="PreserveNewest"
+          Visible="false" />
+    <None Include="..\TUnit.Assertions\bin\$(Configuration)\netstandard2.0\TUnit.Assertions.dll"
+          Link="TUnit.Assertions.netstandard2.0.dll"
+          CopyToOutputDirectory="PreserveNewest"
+          Visible="false" />
+    <None Include="..\TUnit.TestProject.Library\bin\$(Configuration)\netstandard2.0\TUnit.TestProject.Library.dll"
+          Link="TUnit.TestProject.Library.netstandard2.0.dll"
+          CopyToOutputDirectory="PreserveNewest"
+          Visible="false" />
+    <Compile Include="..\SharedTestHelpers\AnalyzerTestCompatibility.cs"
+             Link="Shared\AnalyzerTestCompatibility.cs" />
+  </ItemGroup>
+
   <ItemGroup Condition="'$(TargetFramework)' == 'net8.0'">
     <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" VersionOverride="9.0.0" PrivateAssets="all" GeneratePathProperty="true" />
     <Reference Include="$(PkgMicrosoft_CodeAnalysis_NetAnalyzers)\analyzers\dotnet\cs\Microsoft.CodeAnalysis.NetAnalyzers.dll" Analyzer="false" />

TUnit.Analyzers.Tests/Verifiers/CSharpAnalyzerVerifier`1.cs

@@ -32,17 +32,21 @@ public static Task VerifyAnalyzerAsync([StringSyntax("c#")] string source, param
     /// <inheritdoc cref="AnalyzerVerifier{TAnalyzer, TTest, TVerifier}.VerifyAnalyzerAsync(string, DiagnosticResult[])"/>
     public static async Task VerifyAnalyzerAsync([StringSyntax("c#")] string source, Action<Test> configureTest, params DiagnosticResult[] expected)
     {
+        // Microsoft.Bcl.AsyncInterfaces is required by TUnit.Core.netstandard2.0.dll's typeforward
+        // of IAsyncEnumerable; without it, tests that use IAsyncEnumerable in their source see
+        // CS0012/CS0508 alongside the expected analyzer diagnostic.
         var test = new Test
         {
             TestCode = source,
-            ReferenceAssemblies = ReferenceAssemblies.Net.Net90,
+            ReferenceAssemblies = ReferenceAssemblies.Net.Net90
+                .AddPackages([new PackageIdentity("Microsoft.Bcl.AsyncInterfaces", "9.0.0")]),
             TestState =
             {
                 AdditionalReferences =
                 {
-                    typeof(TUnitAttribute).Assembly.Location,
+                    TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.Core", typeof(TUnitAttribute).Assembly),
                     typeof(CircuitState).Assembly.Location,
-                    typeof(ProjectReferenceEnum).Assembly.Location,
+                    TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.TestProject.Library", typeof(ProjectReferenceEnum).Assembly),
                 },
             },
         };

TUnit.Analyzers.Tests/Verifiers/CSharpCodeFixVerifier`2.cs

@@ -47,7 +47,7 @@ params DiagnosticResult[] expected
             {
                 AdditionalReferences =
                 {
-                    typeof(TUnitAttribute).Assembly.Location,
+                    TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.Core", typeof(TUnitAttribute).Assembly),
                 },
             }
         };
@@ -97,7 +97,7 @@ Action<Test> configureTest
             {
                 AdditionalReferences =
                 {
-                    typeof(TUnitAttribute).Assembly.Location,
+                    TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.Core", typeof(TUnitAttribute).Assembly),
                 },
             },
             CodeActionValidationMode = CodeActionValidationMode.SemanticStructure,

TUnit.AspNetCore.Analyzers.Tests/TUnit.AspNetCore.Analyzers.Tests.csproj

@@ -20,5 +20,16 @@
     <ProjectReference Include="..\TUnit.Core\TUnit.Core.csproj" />
   </ItemGroup>
 
+  <!-- Copy netstandard2.0 build of TUnit.Core into the test bin so Net90 ref assemblies don't
+       trigger CS1705 against the test process's net10.0 build. -->
+  <ItemGroup>
+    <None Include="..\TUnit.Core\bin\$(Configuration)\netstandard2.0\TUnit.Core.dll"
+          Link="TUnit.Core.netstandard2.0.dll"
+          CopyToOutputDirectory="PreserveNewest"
+          Visible="false" />
+    <Compile Include="..\SharedTestHelpers\AnalyzerTestCompatibility.cs"
+             Link="Shared\AnalyzerTestCompatibility.cs" />
+  </ItemGroup>
+
   <Import Project="..\TestProject.targets" />
 </Project>

TUnit.AspNetCore.Analyzers.Tests/Verifiers/CSharpAnalyzerVerifier`1.cs

@@ -33,12 +33,13 @@ public static async Task VerifyAnalyzerAsync([StringSyntax("c#")] string source,
         var test = new Test
         {
             TestCode = source,
-            ReferenceAssemblies = ReferenceAssemblies.Net.Net90,
+            ReferenceAssemblies = ReferenceAssemblies.Net.Net90
+                .AddPackages([new PackageIdentity("Microsoft.Bcl.AsyncInterfaces", "9.0.0")]),
             TestState =
             {
                 AdditionalReferences =
                 {
-                    typeof(TUnit.Core.TUnitAttribute).Assembly.Location,
+                    TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.Core", typeof(TUnit.Core.TUnitAttribute).Assembly),
                 },
             },
         };

TUnit.Assertions.Analyzers.CodeFixers.Tests/TUnit.Assertions.Analyzers.CodeFixers.Tests.csproj

@@ -5,6 +5,24 @@
         <ProjectReference Include="..\TUnit.Assertions.Analyzers.CodeFixers\TUnit.Assertions.Analyzers.CodeFixers.csproj" />
         <ProjectReference Include="..\TUnit.Assertions.Analyzers\TUnit.Assertions.Analyzers.csproj" />
     </ItemGroup>
+
+    <!-- Copy netstandard2.0 builds of TUnit.Core / TUnit.Assertions into the test bin so the
+         analyzer-test framework's net9.0 reference assemblies don't trigger CS1705 against the
+         net10.0 builds otherwise loaded via typeof(...).Assembly.Location. CS1705 is suppressed
+         silently by CompilerDiagnostics.None and the resulting symbol-resolution failures
+         appear as analyzers/codefixers seeing zero diagnostics. -->
+    <ItemGroup>
+        <None Include="..\TUnit.Core\bin\$(Configuration)\netstandard2.0\TUnit.Core.dll"
+              Link="TUnit.Core.netstandard2.0.dll"
+              CopyToOutputDirectory="PreserveNewest"
+              Visible="false" />
+        <None Include="..\TUnit.Assertions\bin\$(Configuration)\netstandard2.0\TUnit.Assertions.dll"
+              Link="TUnit.Assertions.netstandard2.0.dll"
+              CopyToOutputDirectory="PreserveNewest"
+              Visible="false" />
+        <Compile Include="..\SharedTestHelpers\AnalyzerTestCompatibility.cs"
+                 Link="Shared\AnalyzerTestCompatibility.cs" />
+    </ItemGroup>
     <ItemGroup>
         <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Analyzer.Testing" />
         <PackageReference Include="Microsoft.CodeAnalysis.CSharp.CodeFix.Testing" />

TUnit.Assertions.Analyzers.CodeFixers.Tests/Verifiers/CSharpCodeFixVerifier`2.cs

@@ -60,8 +60,8 @@ params DiagnosticResult[] expected
             {
                 AdditionalReferences =
                 {
-                    typeof(TUnitAttribute).Assembly.Location,
-                    typeof(Assert).Assembly.Location,
+                    TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.Core", typeof(TUnitAttribute).Assembly),
+                    TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.Assertions", typeof(Assert).Assembly),
                 },
             },
         };
@@ -102,8 +102,8 @@ public static async Task VerifyCodeFixAsync(
             {
                 AdditionalReferences =
                 {
-                    typeof(TUnitAttribute).Assembly.Location,
-                    typeof(Assert).Assembly.Location,
+                    TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.Core", typeof(TUnitAttribute).Assembly),
+                    TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.Assertions", typeof(Assert).Assembly),
                 },
             },
             CodeActionValidationMode = CodeActionValidationMode.SemanticStructure,

TUnit.Assertions.Analyzers.Tests/AnalyzerTestHelpers.cs

@@ -32,8 +32,9 @@ public static CSharpAnalyzerTest<TAnalyzer, DefaultVerifier> CreateAnalyzerTest<
         csTest.TestState.AdditionalReferences
             .AddRange(
                 [
-                    MetadataReference.CreateFromFile(typeof(TUnitAttribute).Assembly.Location),
-                    MetadataReference.CreateFromFile(typeof(Assert).Assembly.Location),
+                    MetadataReference.CreateFromFile(TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.Core", typeof(TUnitAttribute).Assembly)),
+                    MetadataReference.CreateFromFile(TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.Assertions", typeof(Assert).Assembly)),
+                    MetadataReference.CreateFromFile(TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.Assertions.Should", typeof(TUnit.Assertions.Should.ShouldExtensions).Assembly)),
                 ]
             );
 
@@ -139,8 +140,9 @@ public static CSharpSuppressorTest<TSuppressor, DefaultVerifier> CreateSuppresso
 
         test.TestState.AdditionalReferences
             .AddRange([
-                MetadataReference.CreateFromFile(typeof(TUnitAttribute).Assembly.Location),
-                MetadataReference.CreateFromFile(typeof(Assert).Assembly.Location),
+                MetadataReference.CreateFromFile(TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.Core", typeof(TUnitAttribute).Assembly)),
+                MetadataReference.CreateFromFile(TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.Assertions", typeof(Assert).Assembly)),
+                MetadataReference.CreateFromFile(TUnit.Tests.Shared.AnalyzerTestCompatibility.GetCompatibleDllPath("TUnit.Assertions.Should", typeof(TUnit.Assertions.Should.ShouldExtensions).Assembly)),
             ]);
 
         return test;
@@ -152,9 +154,7 @@ private static ReferenceAssemblies GetReferenceAssemblies()
         return ReferenceAssemblies.NetFramework.Net472.Default;
 #elif NET8_0
         return ReferenceAssemblies.Net.Net80;
-#elif NET9_0
-        return ReferenceAssemblies.Net.Net90;
-#elif NET10_0_OR_GREATER
+#elif NET9_0_OR_GREATER
         return ReferenceAssemblies.Net.Net90;
 #else
         return ReferenceAssemblies.Net.Net80; // Default fallback

TUnit.Assertions.Analyzers.Tests/ShouldAnalyzerTests.cs

@@ -0,0 +1,133 @@
+using AwaitVerifier = TUnit.Assertions.Analyzers.Tests.Verifiers.CSharpAnalyzerVerifier<TUnit.Assertions.Analyzers.AwaitAssertionAnalyzer>;
+using MixVerifier = TUnit.Assertions.Analyzers.Tests.Verifiers.CSharpAnalyzerVerifier<TUnit.Assertions.Analyzers.MixAndOrOperatorsAnalyzer>;
+
+namespace TUnit.Assertions.Analyzers.Tests;
+
+public class ShouldAnalyzerTests
+{
+    [Test]
+    public async Task Should_chain_not_awaited_is_flagged()
+    {
+        await AwaitVerifier
+            .VerifyAnalyzerAsync(
+                """
+                using System.Threading.Tasks;
+                using TUnit.Assertions.Should;
+                using TUnit.Assertions.Should.Extensions;
+
+                public class MyClass
+                {
+                    public async Task MyTest()
+                    {
+                        var one = 1;
+                        {|#0:one.Should()|}.BeEqualTo(1);
+                    }
+                }
+                """,
+
+                AwaitVerifier.Diagnostic(Rules.AwaitAssertion)
+                    .WithLocation(0)
+            );
+    }
+
+    [Test]
+    public async Task Should_chain_awaited_is_clean()
+    {
+        await AwaitVerifier
+            .VerifyAnalyzerAsync(
+                """
+                using System.Threading.Tasks;
+                using TUnit.Assertions.Should;
+                using TUnit.Assertions.Should.Extensions;
+
+                public class MyClass
+                {
+                    public async Task MyTest()
+                    {
+                        var one = 1;
+                        await one.Should().BeEqualTo(1);
+                    }
+                }
+                """
+            );
+    }
+
+    [Test]
+    public async Task Mixed_And_Or_in_Should_chain_is_flagged()
+    {
+        await MixVerifier
+            .VerifyAnalyzerAsync(
+                """
+                using System.Threading.Tasks;
+                using TUnit.Assertions.Should;
+                using TUnit.Assertions.Should.Extensions;
+
+                public class MyClass
+                {
+                    public async Task MyTest()
+                    {
+                        var one = 1;
+                        {|#0:await one.Should().BeEqualTo(1).And.BeEqualTo(1).Or.BeEqualTo(2)|};
+                    }
+                }
+                """,
+
+                MixVerifier.Diagnostic(Rules.MixAndOrConditionsAssertion)
+                    .WithLocation(0)
+            );
+    }
+
+    [Test]
+    public async Task Pure_And_in_Should_chain_is_clean()
+    {
+        await MixVerifier
+            .VerifyAnalyzerAsync(
+                """
+                using System.Threading.Tasks;
+                using TUnit.Assertions.Should;
+                using TUnit.Assertions.Should.Extensions;
+
+                public class MyClass
+                {
+                    public async Task MyTest()
+                    {
+                        var one = 1;
+                        await one.Should().BeEqualTo(1).And.NotBeEqualTo(7);
+                    }
+                }
+                """
+            );
+    }
+
+    [Test]
+    public async Task Unrelated_Should_extension_in_other_namespace_is_not_flagged()
+    {
+        // Confirms the analyzer's TUnit-namespace check rules out unrelated `Should()`
+        // extensions (e.g. FluentAssertions, custom user libraries) from triggering
+        // TUnitAssertions0002.
+        await AwaitVerifier
+            .VerifyAnalyzerAsync(
+                """
+                using System.Threading.Tasks;
+
+                namespace OtherLibrary
+                {
+                    public class Wrapper { public Wrapper Should() => this; public void BeFoo() { } }
+                    public static class WrapperExtensions
+                    {
+                        public static Wrapper Should(this object value) => new Wrapper();
+                    }
+                }
+
+                public class MyClass
+                {
+                    public async Task MyTest()
+                    {
+                        var one = 1;
+                        OtherLibrary.WrapperExtensions.Should(one).BeFoo();
+                    }
+                }
+                """
+            );
+    }
+}