fix: Should().HaveSingleItem() returns the single item

src/TUnit.Assertions.Should.SourceGenerator/ShouldExtensionGenerator.cs

@@ -44,6 +44,7 @@ public sealed class ShouldExtensionGenerator : IIncrementalGenerator
     private const string DynamicallyAccessedMembersAttributeName = "DynamicallyAccessedMembersAttribute";
     private const string ShouldGeneratePartialAttributeFullName = "TUnit.Assertions.Should.Attributes.ShouldGeneratePartialAttribute";
     private const string ShouldExtensionsTypeFullName = "TUnit.Assertions.Should.ShouldExtensions";
+    private const string HasSingleItemAssertionTypeName = "TUnit.Assertions.Conditions.HasSingleItemAssertion";
 
     private static readonly SymbolDisplayFormat NoGlobalFormat =
         SymbolDisplayFormat.FullyQualifiedFormat
@@ -1362,7 +1363,7 @@ private static void EmitWrapperPartial(SourceProductionContext ctx, WrapperData
     private static void EmitWrapperMethod(StringBuilder sb, WrapperData wrapper, WrapperMethodData m)
     {
         var positiveName = NameConjugator.Conjugate(m.SourceMethodName);
-        var returnType = $"global::TUnit.Assertions.Should.Core.ShouldAssertion<{wrapper.AssertionTypeArgDisplay}>";
+        var returnType = GetShouldReturnType(m.ReturnTypeFullName, wrapper.AssertionTypeArgDisplay, m.ReturnTypeGenericArgs);
 
         sb.AppendLine();
         if (!string.IsNullOrEmpty(m.RequiresUnreferencedCodeMessage))
@@ -1424,7 +1425,7 @@ private static void EmitWrapperMethod(StringBuilder sb, WrapperData wrapper, Wra
         sb.AppendLine("        {");
         sb.AppendLine("            inner.Because(__tunit_should_because);");
         sb.AppendLine("        }");
-        sb.AppendLine($"        return new global::TUnit.Assertions.Should.Core.ShouldAssertion<{wrapper.AssertionTypeArgDisplay}>(Context, inner);");
+        sb.AppendLine($"        return new {returnType}(Context, inner);");
         sb.AppendLine("    }");
     }
 
@@ -1479,7 +1480,7 @@ p.DynamicallyAccessedMembersAttribute is null
             .Where(c => c is not null));
 
         var sourceType = $"global::TUnit.Assertions.Should.Core.IShouldSource<{m.SourceTypeArgDisplay}>";
-        var returnType = $"global::TUnit.Assertions.Should.Core.ShouldAssertion<{m.AssertionTypeArgDisplay}>";
+        var returnType = GetShouldReturnType(m.ReturnTypeFullName, m.AssertionTypeArgDisplay, m.ReturnTypeGenericArgs);
 
         sb.AppendLine();
         if (!string.IsNullOrEmpty(m.RequiresUnreferencedCodeMessage))
@@ -1553,13 +1554,32 @@ p.DynamicallyAccessedMembersAttribute is null
         sb.AppendLine("        {");
         sb.AppendLine("            inner.Because(__tunit_should_because);");
         sb.AppendLine("        }");
-        sb.AppendLine($"        return new global::TUnit.Assertions.Should.Core.ShouldAssertion<{m.AssertionTypeArgDisplay}>(innerContext, inner);");
+        sb.AppendLine($"        return new {returnType}(innerContext, inner);");
         sb.AppendLine("    }");
     }
 
     private static string FormatGenericArgs(EquatableArray<string> args)
         => args.Length == 0 ? string.Empty : "<" + string.Join(", ", args) + ">";
 
+    /// <summary>
+    /// <c>HasSingleItemAssertion</c> hides <c>GetAwaiter()</c> and returns the item.
+    /// <c>ShouldAssertion&lt;T&gt;</c> would bind the base awaiter and return the collection,
+    /// so that one return type is wrapped in <c>ShouldSingleItemAssertion</c>. Predicate and
+    /// dictionary overloads keep <c>ShouldAssertion&lt;T&gt;</c> because their return type name differs.
+    /// </summary>
+    private static string GetShouldReturnType(
+        string returnTypeFullName,
+        string assertionTypeArgDisplay,
+        EquatableArray<string> returnTypeGenericArgs)
+    {
+        if (returnTypeFullName == HasSingleItemAssertionTypeName)
+        {
+            return "global::TUnit.Assertions.Should.Core.ShouldSingleItemAssertion" + FormatGenericArgs(returnTypeGenericArgs);
+        }
+
+        return $"global::TUnit.Assertions.Should.Core.ShouldAssertion<{assertionTypeArgDisplay}>";
+    }
+
     private static MethodData[] DeduplicateMethods(MethodData[] methods)
     {
         var seen = new HashSet<string>(StringComparer.Ordinal);

src/TUnit.Assertions.Should/Core/ShouldSingleItemAssertion.cs

@@ -0,0 +1,55 @@
+using System.Collections.Generic;
+using System.ComponentModel;
+using System.Runtime.CompilerServices;
+using TUnit.Assertions.Conditions;
+using TUnit.Assertions.Core;
+
+namespace TUnit.Assertions.Should.Core;
+
+/// <summary>
+/// Per-call result of parameterless <c>HaveSingleItem()</c>. Wraps
+/// <see cref="HasSingleItemAssertion{TCollection, TItem}"/> and forwards <c>await</c> to the
+/// awaiter that type hides, so the awaited value is <typeparamref name="TItem"/>.
+/// </summary>
+/// <remarks>
+/// Class rather than <c>readonly struct</c>, for the same reason as <see cref="ShouldAssertion{T}"/>:
+/// <see cref="GetAwaiter"/> forwards to a state-machine awaiter that mutates the wrapped assertion.
+/// <see cref="And"/> and <see cref="Or"/> are read through <see cref="Assertion{TValue}"/> so the
+/// <c>new</c> collection continuations on <see cref="HasSingleItemAssertion{TCollection, TItem}"/>
+/// are not required; generated extensions continue from <see cref="ShouldContinuation{T}"/>.
+/// </remarks>
+public sealed class ShouldSingleItemAssertion<TCollection, TItem> : IShouldSource<TCollection>, IAssertion
+    where TCollection : IEnumerable<TItem>
+{
+    private readonly HasSingleItemAssertion<TCollection, TItem> _inner;
+
+    public AssertionContext<TCollection> Context { get; }
+
+    [EditorBrowsable(EditorBrowsableState.Never)]
+    public ShouldSingleItemAssertion(AssertionContext<TCollection> context, HasSingleItemAssertion<TCollection, TItem> inner)
+    {
+        Context = context;
+        _inner = inner;
+    }
+
+    public TaskAwaiter<TItem> GetAwaiter() => _inner.GetAwaiter();
+
+    public Task<TCollection?> AssertAsync() => _inner.AssertAsync();
+
+    Task IAssertion.AssertAsync() => _inner.AssertAsync();
+
+    public ShouldSingleItemAssertion<TCollection, TItem> Because(string message)
+    {
+        _inner.Because(message);
+        return this;
+    }
+
+    public ShouldContinuation<TCollection> And => new(CollectionAssertion.And.Context);
+
+    public ShouldContinuation<TCollection> Or => new(CollectionAssertion.Or.Context);
+
+    string? IShouldSource<TCollection>.ConsumeBecauseMessage()
+        => null;
+
+    private Assertion<TCollection> CollectionAssertion => _inner;
+}

tests/TUnit.Assertions.Should.Tests/CollectionTests.cs

@@ -75,6 +75,48 @@
         await list.Should().HaveSingleItem();
     }
 
+    [Test]
+    public async Task HaveSingleItem_returns_the_single_item()
+    {
+        var item = await new int[1] { 1 }.Should().HaveSingleItem();
+        await Assert.That(item).IsEqualTo(1);
+        await (await new int[1] { 1 }.Should().HaveSingleItem()).Should().BeOfType(typeof(int));
+    }
+
+    [Test]
+    public async Task HaveSingleItem_after_And_returns_the_single_item()
+    {
+        var item = await new int[] { 1 }.Should().HaveCount(1).And.HaveSingleItem();
+        await Assert.That(item).IsEqualTo(1);
+    }
+
+    [Test]
+    public async Task HaveSingleItem_returns_the_item_for_list_and_hash_set()
+    {
+        var listItem = await new List<int> { 1 }.Should().HaveSingleItem();
+        await Assert.That(listItem).IsEqualTo(1);
+
+        var setItem = await new HashSet<int> { 1 }.Should().HaveSingleItem();
+        await Assert.That(setItem).IsEqualTo(1);
+    }
+
+    [Test]
+    public async Task HaveSingleItem_throws_when_not_exactly_one_item()
+    {
+        await Assert.That(async () => await new int[0].Should().HaveSingleItem())
+            .Throws<TUnit.Assertions.Exceptions.AssertionException>();
+        await Assert.That(async () => await new int[] { 1, 2 }.Should().HaveSingleItem())
+            .Throws<TUnit.Assertions.Exceptions.AssertionException>();
+    }
+
+    [Test]
+    public async Task Dictionary_HaveSingleItem_returns_the_dictionary()
+    {
+        var dictionary = new Dictionary<string, int> { ["only"] = 1 };
+        var result = await dictionary.Should().HaveSingleItem();
+        await Assert.That(result).IsSameReferenceAs(dictionary);
+    }
+
     [Test]
     public async Task HaveSingleItem_with_predicate()
     {

tests/TUnit.PublicAPI/Tests.Should_Library_Has_No_API_Changes.DotNet10_0.verified.txt

@@ -48,7 +48,7 @@ namespace .
         public ..ShouldAssertion<.<TItem>> HaveCountBetween(int min, int max, [.("min")] string? minExpression = null, [.("max")] string? maxExpression = null) { }
         public ..ShouldAssertion<.<TItem>> HaveDistinctItems() { }
         public ..ShouldAssertion<.<TItem>> HaveDistinctItems(.<TItem> comparer, [.("comparer")] string? comparerExpression = null) { }
-        public ..ShouldAssertion<.<TItem>> HaveSingleItem() { }
+        public ..ShouldSingleItemAssertion<.<TItem>, TItem> HaveSingleItem() { }
         public ..ShouldAssertion<.<TItem>> NotBeEmpty() { }
         public ..ShouldAssertion<.<TItem>> NotContain(TItem expected, [.("expected")] string? expression = null) { }
         public ..ShouldAssertion<.<TItem>> NotContain(TItem expected, .<TItem> comparer, [.("expected")] string? expectedExpression = null, [.("comparer")] string? comparerExpression = null) { }
@@ -142,7 +142,7 @@ namespace .
         public ..ShouldAssertion<.<TItem>> HaveCountBetween(int min, int max, [.("min")] string? minExpression = null, [.("max")] string? maxExpression = null) { }
         public ..ShouldAssertion<.<TItem>> HaveDistinctItems() { }
         public ..ShouldAssertion<.<TItem>> HaveDistinctItems(.<TItem> comparer, [.("comparer")] string? comparerExpression = null) { }
-        public ..ShouldAssertion<.<TItem>> HaveSingleItem() { }
+        public ..ShouldSingleItemAssertion<.<TItem>, TItem> HaveSingleItem() { }
         public ..ShouldAssertion<.<TItem>> NotBeEmpty() { }
         public ..ShouldAssertion<.<TItem>> NotContain(TItem expected, [.("expected")] string? expression = null) { }
         public ..ShouldAssertion<.<TItem>> NotContain(TItem expected, .<TItem> comparer, [.("expected")] string? expectedExpression = null, [.("comparer")] string? comparerExpression = null) { }
@@ -196,7 +196,7 @@ namespace .
         public ..ShouldAssertion<.<TItem>> HaveCountBetween(int min, int max, [.("min")] string? minExpression = null, [.("max")] string? maxExpression = null) { }
         public ..ShouldAssertion<.<TItem>> HaveDistinctItems() { }
         public ..ShouldAssertion<.<TItem>> HaveDistinctItems(.<TItem> comparer, [.("comparer")] string? comparerExpression = null) { }
-        public ..ShouldAssertion<.<TItem>> HaveSingleItem() { }
+        public ..ShouldSingleItemAssertion<.<TItem>, TItem> HaveSingleItem() { }
         public ..ShouldAssertion<.<TItem>> NotBeEmpty() { }
         public ..ShouldAssertion<.<TItem>> NotContain(TItem expected, [.("expected")] string? expression = null) { }
         public ..ShouldAssertion<.<TItem>> NotContain(TItem expected, .<TItem> comparer, [.("expected")] string? expectedExpression = null, [.("comparer")] string? comparerExpression = null) { }
@@ -232,11 +232,22 @@ namespace .
         public ..ShouldAssertion<.<TItem>> HaveCountBetween(int min, int max, [.("min")] string? minExpression = null, [.("max")] string? maxExpression = null) { }
         public ..ShouldAssertion<.<TItem>> HaveDistinctItems() { }
         public ..ShouldAssertion<.<TItem>> HaveDistinctItems(.<TItem> comparer, [.("comparer")] string? comparerExpression = null) { }
-        public ..ShouldAssertion<.<TItem>> HaveSingleItem() { }
+        public ..ShouldSingleItemAssertion<.<TItem>, TItem> HaveSingleItem() { }
         public ..ShouldAssertion<.<TItem>> NotBeEmpty() { }
         public ..ShouldAssertion<.<TItem>> NotContain(TItem expected, [.("expected")] string? expression = null) { }
         public ..ShouldAssertion<.<TItem>> NotContain(TItem expected, .<TItem> comparer, [.("expected")] string? expectedExpression = null, [.("comparer")] string? comparerExpression = null) { }
     }
+    public sealed class ShouldSingleItemAssertion<TCollection, TItem> : ., ..IShouldSource, ..IShouldSource<TCollection>
+        where TCollection : .<TItem>
+    {
+        public ShouldSingleItemAssertion(.<TCollection> context, .<TCollection, TItem> inner) { }
+        public ..ShouldContinuation<TCollection> And { get; }
+        public .<TCollection> Context { get; }
+        public ..ShouldContinuation<TCollection> Or { get; }
+        public .<TCollection?> AssertAsync() { }
+        public ..ShouldSingleItemAssertion<TCollection, TItem> Because(string message) { }
+        public .<TItem> GetAwaiter() { }
+    }
     public abstract class ShouldSourceBase<TValue, TSelf> : ..IShouldSource, ..IShouldSource<TValue>
         where TSelf : ..ShouldSourceBase<TValue, TSelf>
     {
@@ -628,7 +639,8 @@ namespace .
     }
     public static class ShouldHasSingleItemAssertionExtensions
     {
-        public static ..ShouldAssertion<TCollection> HaveSingleItem<TCollection, TItem>(this ..IShouldSource<TCollection> source)
+        public static ..ShouldSingleItemAssertion<.<TItem>, TItem> HaveSingleItem<TItem>(this ..IShouldSource<.<TItem>> source) { }
+        public static ..ShouldSingleItemAssertion<TCollection, TItem> HaveSingleItem<TCollection, TItem>(this ..IShouldSource<TCollection> source)
             where TCollection : .<TItem> { }
     }
     public static class ShouldHasSingleItemPredicateAssertionExtensions

tests/TUnit.PublicAPI/Tests.Should_Library_Has_No_API_Changes.DotNet8_0.verified.txt

@@ -48,7 +48,7 @@ namespace .
         public ..ShouldAssertion<.<TItem>> HaveCountBetween(int min, int max, [.("min")] string? minExpression = null, [.("max")] string? maxExpression = null) { }
         public ..ShouldAssertion<.<TItem>> HaveDistinctItems() { }
         public ..ShouldAssertion<.<TItem>> HaveDistinctItems(.<TItem> comparer, [.("comparer")] string? comparerExpression = null) { }
-        public ..ShouldAssertion<.<TItem>> HaveSingleItem() { }
+        public ..ShouldSingleItemAssertion<.<TItem>, TItem> HaveSingleItem() { }
         public ..ShouldAssertion<.<TItem>> NotBeEmpty() { }
         public ..ShouldAssertion<.<TItem>> NotContain(TItem expected, [.("expected")] string? expression = null) { }
         public ..ShouldAssertion<.<TItem>> NotContain(TItem expected, .<TItem> comparer, [.("expected")] string? expectedExpression = null, [.("comparer")] string? comparerExpression = null) { }
@@ -142,7 +142,7 @@ namespace .
         public ..ShouldAssertion<.<TItem>> HaveCountBetween(int min, int max, [.("min")] string? minExpression = null, [.("max")] string? maxExpression = null) { }
         public ..ShouldAssertion<.<TItem>> HaveDistinctItems() { }
         public ..ShouldAssertion<.<TItem>> HaveDistinctItems(.<TItem> comparer, [.("comparer")] string? comparerExpression = null) { }
-        public ..ShouldAssertion<.<TItem>> HaveSingleItem() { }
+        public ..ShouldSingleItemAssertion<.<TItem>, TItem> HaveSingleItem() { }
         public ..ShouldAssertion<.<TItem>> NotBeEmpty() { }
         public ..ShouldAssertion<.<TItem>> NotContain(TItem expected, [.("expected")] string? expression = null) { }
         public ..ShouldAssertion<.<TItem>> NotContain(TItem expected, .<TItem> comparer, [.("expected")] string? expectedExpression = null, [.("comparer")] string? comparerExpression = null) { }
@@ -196,7 +196,7 @@ namespace .
         public ..ShouldAssertion<.<TItem>> HaveCountBetween(int min, int max, [.("min")] string? minExpression = null, [.("max")] string? maxExpression = null) { }
         public ..ShouldAssertion<.<TItem>> HaveDistinctItems() { }
         public ..ShouldAssertion<.<TItem>> HaveDistinctItems(.<TItem> comparer, [.("comparer")] string? comparerExpression = null) { }
-        public ..ShouldAssertion<.<TItem>> HaveSingleItem() { }
+        public ..ShouldSingleItemAssertion<.<TItem>, TItem> HaveSingleItem() { }
         public ..ShouldAssertion<.<TItem>> NotBeEmpty() { }
         public ..ShouldAssertion<.<TItem>> NotContain(TItem expected, [.("expected")] string? expression = null) { }
         public ..ShouldAssertion<.<TItem>> NotContain(TItem expected, .<TItem> comparer, [.("expected")] string? expectedExpression = null, [.("comparer")] string? comparerExpression = null) { }
@@ -232,11 +232,22 @@ namespace .
         public ..ShouldAssertion<.<TItem>> HaveCountBetween(int min, int max, [.("min")] string? minExpression = null, [.("max")] string? maxExpression = null) { }
         public ..ShouldAssertion<.<TItem>> HaveDistinctItems() { }
         public ..ShouldAssertion<.<TItem>> HaveDistinctItems(.<TItem> comparer, [.("comparer")] string? comparerExpression = null) { }
-        public ..ShouldAssertion<.<TItem>> HaveSingleItem() { }
+        public ..ShouldSingleItemAssertion<.<TItem>, TItem> HaveSingleItem() { }
         public ..ShouldAssertion<.<TItem>> NotBeEmpty() { }
         public ..ShouldAssertion<.<TItem>> NotContain(TItem expected, [.("expected")] string? expression = null) { }
         public ..ShouldAssertion<.<TItem>> NotContain(TItem expected, .<TItem> comparer, [.("expected")] string? expectedExpression = null, [.("comparer")] string? comparerExpression = null) { }
     }
+    public sealed class ShouldSingleItemAssertion<TCollection, TItem> : ., ..IShouldSource, ..IShouldSource<TCollection>
+        where TCollection : .<TItem>
+    {
+        public ShouldSingleItemAssertion(.<TCollection> context, .<TCollection, TItem> inner) { }
+        public ..ShouldContinuation<TCollection> And { get; }
+        public .<TCollection> Context { get; }
+        public ..ShouldContinuation<TCollection> Or { get; }
+        public .<TCollection?> AssertAsync() { }
+        public ..ShouldSingleItemAssertion<TCollection, TItem> Because(string message) { }
+        public .<TItem> GetAwaiter() { }
+    }
     public abstract class ShouldSourceBase<TValue, TSelf> : ..IShouldSource, ..IShouldSource<TValue>
         where TSelf : ..ShouldSourceBase<TValue, TSelf>
     {
@@ -628,7 +639,8 @@ namespace .
     }
     public static class ShouldHasSingleItemAssertionExtensions
     {
-        public static ..ShouldAssertion<TCollection> HaveSingleItem<TCollection, TItem>(this ..IShouldSource<TCollection> source)
+        public static ..ShouldSingleItemAssertion<.<TItem>, TItem> HaveSingleItem<TItem>(this ..IShouldSource<.<TItem>> source) { }
+        public static ..ShouldSingleItemAssertion<TCollection, TItem> HaveSingleItem<TCollection, TItem>(this ..IShouldSource<TCollection> source)
             where TCollection : .<TItem> { }
     }
     public static class ShouldHasSingleItemPredicateAssertionExtensions