feat: add HasSingleItem(predicate) overload

TUnit.Analyzers.CodeFixers/TwoPhase/XUnitTwoPhaseAnalyzer.cs

@@ -160,7 +160,7 @@ private bool IsXUnitAssertion(InvocationExpressionSyntax invocation)
             "StrictEqual" => ConvertStrictEqual(arguments),
             "Empty" => ConvertEmpty(arguments),
             "NotEmpty" => ConvertNotEmpty(arguments),
-            "Single" => ConvertSingle(arguments),
+            "Single" => ConvertSingle(memberAccess, arguments),
             "Contains" => ConvertContains(memberAccess, arguments),
             "DoesNotContain" => ConvertDoesNotContain(memberAccess, arguments),
             "Throws" => ConvertThrows(memberAccess, arguments),
@@ -344,11 +344,31 @@ private bool IsXUnitAssertion(InvocationExpressionSyntax invocation)
         return (AssertionConversionKind.NotEmpty, $"await Assert.That({collection}).IsNotEmpty()", true, null);
     }
 
-    private (AssertionConversionKind, string?, bool, string?) ConvertSingle(SeparatedSyntaxList<ArgumentSyntax> args)
+    private (AssertionConversionKind, string?, bool, string?) ConvertSingle(MemberAccessExpressionSyntax memberAccess, SeparatedSyntaxList<ArgumentSyntax> args)
     {
         if (args.Count < 1) return (AssertionConversionKind.Single, null, false, null);
 
         var collection = args[0].Expression.ToString();
+
+        if (args.Count >= 2)
+        {
+            // xUnit has two overloads with a second parameter:
+            //   Assert.Single<T>(IEnumerable<T>, Predicate<T>) - predicate overload
+            //   Assert.Single(IEnumerable, object?) - expected value overload
+            // Only convert the predicate overload to HasSingleItem(predicate).
+            var symbol = SemanticModel.GetSymbolInfo(memberAccess).Symbol;
+            if (symbol is IMethodSymbol { Parameters.Length: 2 } methodSymbol &&
+                methodSymbol.Parameters[1].Type is INamedTypeSymbol { DelegateInvokeMethod: not null })
+            {
+                var predicate = args[1].Expression.ToString();
+                return (AssertionConversionKind.Single, $"await Assert.That({collection}).HasSingleItem({predicate})", true, null);
+            }
+
+            // For the expected value overload, fall back to HasSingleItem() without predicate
+            return (AssertionConversionKind.Single, $"await Assert.That({collection}).HasSingleItem()", true,
+                "// TODO: xUnit Assert.Single(collection, expected) matched by value - verify conversion");
+        }
+
         return (AssertionConversionKind.Single, $"await Assert.That({collection}).HasSingleItem()", true, null);
     }
 

TUnit.Assertions.Analyzers.CodeFixers.Tests/XUnitAssertionCodeFixProviderTests.cs

@@ -419,4 +419,94 @@ public void MyTest()
                 """
             );
     }
+
+    [Test]
+    public async Task Xunit_Single_With_Predicate_Preserves_Lambda()
+    {
+        await Verifier
+            .VerifyCodeFixAsync(
+                """
+                using System.Threading.Tasks;
+                using System.Collections.Generic;
+
+                public class MyClass
+                {
+                    public void MyTest()
+                    {
+                        var properties = new List<Property>
+                        {
+                            new Property { Prop = "myKey" }
+                        };
+
+                        {|#0:Xunit.Assert.Single(properties, p => p.Prop == "myKey")|};
+                    }
+                }
+
+                public class Property
+                {
+                    public string Prop { get; set; }
+                }
+                """,
+                Verifier.Diagnostic(Rules.XUnitAssertion)
+                    .WithLocation(0),
+                """
+                using System.Threading.Tasks;
+                using System.Collections.Generic;
+
+                public class MyClass
+                {
+                    public void MyTest()
+                    {
+                        var properties = new List<Property>
+                        {
+                            new Property { Prop = "myKey" }
+                        };
+
+                        Assert.That(properties).HasSingleItem(p => p.Prop == "myKey");
+                    }
+                }
+
+                public class Property
+                {
+                    public string Prop { get; set; }
+                }
+                """
+            );
+    }
+
+    [Test]
+    public async Task Xunit_Single_Without_Predicate()
+    {
+        await Verifier
+            .VerifyCodeFixAsync(
+                """
+                using System.Threading.Tasks;
+                using System.Collections.Generic;
+
+                public class MyClass
+                {
+                    public void MyTest()
+                    {
+                        var items = new List<int> { 42 };
+                        {|#0:Xunit.Assert.Single(items)|};
+                    }
+                }
+                """,
+                Verifier.Diagnostic(Rules.XUnitAssertion)
+                    .WithLocation(0),
+                """
+                using System.Threading.Tasks;
+                using System.Collections.Generic;
+
+                public class MyClass
+                {
+                    public void MyTest()
+                    {
+                        var items = new List<int> { 42 };
+                        Assert.That(items).HasSingleItem();
+                    }
+                }
+                """
+            );
+    }
 }

TUnit.Assertions.Analyzers.CodeFixers/XUnitAssertionCodeFixProvider.cs

@@ -188,7 +188,7 @@ private static async Task<Document> ConvertAssertionAsync(CodeFixContext context
 
             // "All" is handled separately in ConvertAssertionAsync
 
-            "Single" => SyntaxFactory.ParseExpression($"Assert.That({actual}).HasSingleItem()"),
+            "Single" => await Single(context, memberAccessExpressionSyntax, argumentListArguments),
 
             "IsType" => isGeneric
                 ? SyntaxFactory.ParseExpression($"Assert.That({actual}).IsTypeOf<{genericArgs}>()")
@@ -331,6 +331,32 @@ private static ExpressionSyntax CreateBooleanAssertion(
         return SyntaxFactory.ParseExpression($"Assert.That({condition}).{assertionMethod}()");
     }
 
+    private static async Task<ExpressionSyntax> Single(CodeFixContext context,
+        MemberAccessExpressionSyntax memberAccessExpressionSyntax,
+        SeparatedSyntaxList<ArgumentSyntax> argumentListArguments)
+    {
+        if (argumentListArguments.Count >= 2)
+        {
+            // xUnit has two overloads with a second parameter:
+            //   Assert.Single<T>(IEnumerable<T>, Predicate<T>) - predicate overload
+            //   Assert.Single(IEnumerable, object?) - expected value overload
+            // Only convert the predicate overload to HasSingleItem(predicate).
+            var semanticModel = await context.Document.GetSemanticModelAsync();
+            var symbol = semanticModel?.GetSymbolInfo(memberAccessExpressionSyntax).Symbol;
+
+            if (symbol is IMethodSymbol { Parameters.Length: 2 } methodSymbol &&
+                methodSymbol.Parameters[1].Type is INamedTypeSymbol { DelegateInvokeMethod: not null })
+            {
+                return SyntaxFactory.ParseExpression($"Assert.That({argumentListArguments[0]}).HasSingleItem({argumentListArguments[1]})");
+            }
+
+            // For the expected value overload, fall back to HasSingleItem() without predicate
+            return SyntaxFactory.ParseExpression($"Assert.That({argumentListArguments[0]}).HasSingleItem()");
+        }
+
+        return SyntaxFactory.ParseExpression($"Assert.That({argumentListArguments[0]}).HasSingleItem()");
+    }
+
     private static async Task<ExpressionSyntax> Contains(CodeFixContext context,
         MemberAccessExpressionSyntax memberAccessExpressionSyntax, ArgumentSyntax? actual, ArgumentSyntax? expected)
     {

TUnit.Assertions.Tests/ListAssertionTests.cs

@@ -203,6 +203,30 @@ public async Task Test_List_HasSingleItem()
         await Assert.That(list).HasSingleItem();
     }
 
+    [Test]
+    public async Task Test_List_HasSingleItem_WithPredicate()
+    {
+        IList<int> list = new List<int> { 1, 2, 3, 4, 5 };
+        var item = await Assert.That(list).HasSingleItem(x => x == 3);
+        await Assert.That(item).IsEqualTo(3);
+    }
+
+    [Test]
+    public async Task Test_List_HasSingleItem_WithPredicate_Fails_WhenNoneMatch()
+    {
+        IList<int> list = new List<int> { 1, 2, 3 };
+        var action = async () => await Assert.That(list).HasSingleItem(x => x > 10);
+        await Assert.That(action).ThrowsException();
+    }
+
+    [Test]
+    public async Task Test_List_HasSingleItem_WithPredicate_Fails_WhenMultipleMatch()
+    {
+        IList<int> list = new List<int> { 1, 2, 3, 4, 5 };
+        var action = async () => await Assert.That(list).HasSingleItem(x => x > 3);
+        await Assert.That(action).ThrowsException();
+    }
+
     [Test]
     public async Task Test_List_IsInOrder()
     {

TUnit.Assertions/Collections/CollectionChecks.cs

@@ -174,6 +174,39 @@ public static AssertionResult CheckHasSingleItem<TItem>(ICollectionAdapter<TItem
         return AssertionResult.Failed($"it had {count} item(s)");
     }
 
+    /// <summary>
+    /// Checks if exactly one item in the collection matches the predicate.
+    /// Returns the matching item via out parameter.
+    /// </summary>
+    public static AssertionResult CheckHasSingleItemPredicate<TItem>(
+        ICollectionAdapter<TItem> adapter,
+        Func<TItem, bool> predicate,
+        out TItem? matchingItem)
+    {
+        matchingItem = default;
+        var matchCount = 0;
+
+        foreach (var item in adapter.AsEnumerable())
+        {
+            if (predicate(item))
+            {
+                matchCount++;
+                if (matchCount == 1)
+                {
+                    matchingItem = item;
+                }
+            }
+        }
+
+        if (matchCount == 1)
+        {
+            return AssertionResult.Passed;
+        }
+
+        matchingItem = default;
+        return AssertionResult.Failed($"{matchCount} item(s) matched the predicate");
+    }
+
     /// <summary>
     /// Checks if all items satisfy the predicate.
     /// </summary>

TUnit.Assertions/Conditions/CollectionAssertions.cs

@@ -413,6 +413,65 @@ private async Task<TItem> ExecuteAndReturnItemAsync()
     }
 }
 
+/// <summary>
+/// Asserts that a collection contains exactly one item matching the predicate.
+/// When awaited, returns the matching item for further assertions.
+/// Delegates to CollectionChecks for the actual logic.
+/// </summary>
+[AssertionExtension("HasSingleItem")]
+public class HasSingleItemPredicateAssertion<TCollection, TItem> : Sources.CollectionAssertionBase<TCollection, TItem>
+    where TCollection : IEnumerable<TItem>
+{
+    private readonly Func<TItem, bool> _predicate;
+    private readonly string _predicateDescription;
+    private TItem? _singleItem;
+
+    public HasSingleItemPredicateAssertion(
+        AssertionContext<TCollection> context,
+        Func<TItem, bool> predicate,
+        string predicateDescription)
+        : base(context)
+    {
+        _predicate = predicate ?? throw new ArgumentNullException(nameof(predicate));
+        _predicateDescription = predicateDescription;
+    }
+
+    protected override Task<AssertionResult> CheckAsync(EvaluationMetadata<TCollection> metadata)
+    {
+        if (metadata.Exception != null)
+        {
+            return Task.FromResult(AssertionResult.Failed($"threw {metadata.Exception.GetType().Name}"));
+        }
+
+        if (metadata.Value == null)
+        {
+            return Task.FromResult(AssertionResult.Failed("value was null"));
+        }
+
+        var adapter = new EnumerableAdapter<TItem>(metadata.Value);
+        var result = CollectionChecks.CheckHasSingleItemPredicate(adapter, _predicate, out _singleItem);
+        return Task.FromResult(result);
+    }
+
+    protected override string GetExpectation() => $"to have exactly one item matching {_predicateDescription}";
+
+    /// <summary>
+    /// Enables await syntax that returns the matching item.
+    /// This allows both chaining (.And) and item capture (await).
+    /// </summary>
+    public new System.Runtime.CompilerServices.TaskAwaiter<TItem> GetAwaiter()
+    {
+        return ExecuteAndReturnItemAsync().GetAwaiter();
+    }
+
+    private async Task<TItem> ExecuteAndReturnItemAsync()
+    {
+        await AssertAsync();
+
+        return _singleItem!;
+    }
+}
+
 /// <summary>
 /// Asserts that a collection contains an item matching the predicate.
 /// When awaited, returns the found item for further assertions.

TUnit.Assertions/Sources/CollectionAssertionBase.cs

@@ -260,6 +260,19 @@ public HasSingleItemAssertion<TCollection, TItem> HasSingleItem()
         return new HasSingleItemAssertion<TCollection, TItem>(Context);
     }
 
+    /// <summary>
+    /// Asserts that the collection contains exactly one item matching the predicate.
+    /// This instance method enables calling HasSingleItem with proper type inference.
+    /// Example: await Assert.That(list).HasSingleItem(x => x > 5);
+    /// </summary>
+    public HasSingleItemPredicateAssertion<TCollection, TItem> HasSingleItem(
+        Func<TItem, bool> predicate,
+        [CallerArgumentExpression(nameof(predicate))] string? expression = null)
+    {
+        Context.ExpressionBuilder.Append($".HasSingleItem({expression})");
+        return new HasSingleItemPredicateAssertion<TCollection, TItem>(Context, predicate, expression ?? "predicate");
+    }
+
     /// <summary>
     /// Asserts that the collection contains only distinct (unique) items.
     /// This instance method enables calling HasDistinctItems with proper type inference.