fluentassertions · dennisdoomen · Feb 1, 2025 · Jan 21, 2025 · Jan 26, 2025
diff --git a/Src/FluentAssertions/AssertionExtensions.cs b/Src/FluentAssertions/AssertionExtensions.cs
diff --git a/Src/FluentAssertions/DataRowAssertionExtensions.cs b/Src/FluentAssertions/DataRowAssertionExtensions.cs
@@ -16,7 +16,7 @@ public static class DataRowAssertionExtensions
     /// current <see cref="DataRow"/>.
     /// </summary>
     [Pure]
-    public static DataRowAssertions<TDataRow> Should<TDataRow>(this TDataRow actualValue)
+    public static DataRowAssertions<TDataRow> Should<TDataRow>([System.Diagnostics.CodeAnalysis.NotNullAttribute] this TDataRow actualValue)
         where TDataRow : DataRow
     {
         return new DataRowAssertions<TDataRow>(actualValue);

diff --git a/Src/FluentAssertions/DataSetAssertionExtensions.cs b/Src/FluentAssertions/DataSetAssertionExtensions.cs
@@ -16,7 +16,7 @@ public static class DataSetAssertionExtensions
     /// current <see cref="DataSet"/>.
     /// </summary>
     [Pure]
-    public static DataSetAssertions<TDataSet> Should<TDataSet>(this TDataSet actualValue)
+    public static DataSetAssertions<TDataSet> Should<TDataSet>([System.Diagnostics.CodeAnalysis.NotNullAttribute] this TDataSet actualValue)
         where TDataSet : DataSet
     {
         return new DataSetAssertions<TDataSet>(actualValue);

diff --git a/Src/FluentAssertions/DataTableAssertionExtensions.cs b/Src/FluentAssertions/DataTableAssertionExtensions.cs
@@ -16,7 +16,7 @@ public static class DataTableAssertionExtensions
     /// current <see cref="DataTable"/>.
     /// </summary>
     [Pure]
-    public static DataTableAssertions<TDataTable> Should<TDataTable>(this TDataTable actualValue)
+    public static DataTableAssertions<TDataTable> Should<TDataTable>([System.Diagnostics.CodeAnalysis.NotNullAttribute] this TDataTable actualValue)
         where TDataTable : DataTable
     {
         return new DataTableAssertions<TDataTable>(actualValue);

diff --git a/Src/FluentAssertions/EnumAssertionsExtensions.cs b/Src/FluentAssertions/EnumAssertionsExtensions.cs
@@ -1,5 +1,6 @@
 using System;
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 using System.Diagnostics.Contracts;
 using FluentAssertions.Primitives;
 
@@ -27,7 +28,7 @@ public static EnumAssertions<TEnum> Should<TEnum>(this TEnum @enum)
     /// current <typeparamref name="TEnum"/>.
     /// </summary>
     [Pure]
-    public static NullableEnumAssertions<TEnum> Should<TEnum>(this TEnum? @enum)
+    public static NullableEnumAssertions<TEnum> Should<TEnum>([NotNull] this TEnum? @enum)
         where TEnum : struct, Enum
     {
         return new NullableEnumAssertions<TEnum>(@enum);

diff --git a/Src/FluentAssertions/Xml/XmlAssertionExtensions.cs b/Src/FluentAssertions/Xml/XmlAssertionExtensions.cs
@@ -1,4 +1,5 @@
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 using System.Xml;
 using FluentAssertions.Xml;
 
@@ -7,12 +8,12 @@ namespace FluentAssertions;
 [DebuggerNonUserCode]
 public static class XmlAssertionExtensions
 {
-    public static XmlNodeAssertions Should(this XmlNode actualValue)
+    public static XmlNodeAssertions Should([NotNull] this XmlNode actualValue)
     {
         return new XmlNodeAssertions(actualValue);
     }
 
-    public static XmlElementAssertions Should(this XmlElement actualValue)
+    public static XmlElementAssertions Should([NotNull] this XmlElement actualValue)
     {
         return new XmlElementAssertions(actualValue);
     }

diff --git a/Tests/Approval.Tests/ApprovedApi/FluentAssertions/net47.verified.txt b/Tests/Approval.Tests/ApprovedApi/FluentAssertions/net47.verified.txt
diff --git a/Tests/Approval.Tests/ApprovedApi/FluentAssertions/net6.0.verified.txt b/Tests/Approval.Tests/ApprovedApi/FluentAssertions/net6.0.verified.txt
diff --git a/Tests/Approval.Tests/ApprovedApi/FluentAssertions/netstandard2.0.verified.txt b/Tests/Approval.Tests/ApprovedApi/FluentAssertions/netstandard2.0.verified.txt
diff --git a/Tests/Approval.Tests/ApprovedApi/FluentAssertions/netstandard2.1.verified.txt b/Tests/Approval.Tests/ApprovedApi/FluentAssertions/netstandard2.1.verified.txt
diff --git a/Tests/FluentAssertions.Specs/AssertionExtensionsSpecs.cs b/Tests/FluentAssertions.Specs/AssertionExtensionsSpecs.cs
@@ -1,5 +1,6 @@
-using System;
+using System;
 using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
 using System.Linq;
 using System.Reflection;
 using FluentAssertions.Common;
@@ -157,6 +158,45 @@ public void Should_methods_have_a_matching_overload_to_guard_against_chaining_an
             "AssertionExtensions.cs should have a guard overload of Should calling InvalidShouldCall()");
     }
 
+    [Theory]
+    [MemberData(nameof(GetShouldMethods), true)]
+    public void Should_methods_returning_reference_or_nullable_type_assertions_are_annotated_with_not_null_attribute(MethodInfo method)
+    {
+        var notNullAttribute = method.GetParameters().Single().GetCustomAttribute<NotNullAttribute>();
+        notNullAttribute.Should().NotBeNull();
+    }
+
+    [Theory]
+    [MemberData(nameof(GetShouldMethods), false)]
+    public void Should_methods_not_returning_reference_or_nullable_type_assertions_are_not_annotated_with_not_null_attribute(MethodInfo method)
+    {
+        var notNullAttribute = method.GetParameters().Single().GetCustomAttribute<NotNullAttribute>();
+        notNullAttribute.Should().BeNull();
+    }
+
+    public static IEnumerable<object[]> GetShouldMethods(bool referenceOrNullableTypes)
+    {
+        return AllTypes.From(typeof(FluentAssertions.AssertionExtensions).Assembly)
+            .ThatAreClasses()
+            .ThatAreStatic()
+            .Where(t => t.IsPublic)
+            .SelectMany(t => t.GetMethods(BindingFlags.Static | BindingFlags.Public))
+            .Where(m => m.Name == "Should"
+                && !IsGuardOverload(m)
+                && m.GetParameters().Length == 1
+                && (referenceOrNullableTypes ? IsReferenceOrNullableTypeAssertion(m) : !IsReferenceOrNullableTypeAssertion(m)))
+            .Select(m => new object[] { m });
+    }
+
+    private static bool ReturnsReferenceTypeAssertions(MethodInfo m) =>
+        m.ReturnType.IsAssignableToOpenGeneric(typeof(ReferenceTypeAssertions<,>));
+
+    private static bool IsNullableTypeAssertion(MethodInfo m) =>
+        m.GetParameters()[0].ParameterType.IsAssignableToOpenGeneric(typeof(Nullable<>));
+
+    private static bool IsReferenceOrNullableTypeAssertion(MethodInfo m) =>
+        ReturnsReferenceTypeAssertions(m) || IsNullableTypeAssertion(m);
+
     private static bool IsGuardOverload(MethodInfo m) =>
         m.ReturnType == typeof(void) && m.IsDefined(typeof(ObsoleteAttribute));
 

diff --git a/docs/_pages/releases.md b/docs/_pages/releases.md
@@ -7,6 +7,11 @@ sidebar:
   nav: "sidebar"
 ---
 
+## 7.2.0
+
+### Improvements
+* All `Should()` methods on reference types are now annotated with the `[NotNull]` attribute for a better Fluent Assertions experience when nullable reference types are enabled - [#2987](https://github.com/fluentassertions/fluentassertions/pull/2987)
+
 ## 7.1.0
 
 ### Improvements