Add AssertionResult.Failed overload that accepts an Exception

TUnit.Assertions/Assertions/Regex/GroupAssertion.cs

@@ -58,7 +58,8 @@ protected override async Task<AssertionResult> CheckAsync(EvaluationMetadata<Reg
         }
         catch (Exception ex)
         {
-            return AssertionResult.Failed(ex.Message);
+            var groupDesc = _groupName != null ? $"group '{_groupName}'" : $"group {_groupIndex}";
+            return AssertionResult.Failed($"failed to get {groupDesc}: {ex.Message}", ex);
         }
 
         var groupAssertion = new ValueAssertion<string>(groupValue, _groupName ?? $"group {_groupIndex}");
@@ -133,7 +134,8 @@ protected override async Task<AssertionResult> CheckAsync(EvaluationMetadata<Reg
         }
         catch (Exception ex)
         {
-            return AssertionResult.Failed(ex.Message);
+            var groupDesc = _groupName != null ? $"group '{_groupName}'" : $"group {_groupIndex}";
+            return AssertionResult.Failed($"failed to get {groupDesc}: {ex.Message}", ex);
         }
 
         var groupAssertion = new ValueAssertion<string>(groupValue, _groupName ?? $"group {_groupIndex}");

TUnit.Assertions/Assertions/Regex/MatchAssertion.cs

@@ -49,7 +49,7 @@ protected override async Task<AssertionResult> CheckAsync(EvaluationMetadata<Reg
         }
         catch (Exception ex)
         {
-            return AssertionResult.Failed($"Failed to get match at index {_index}: {ex.Message}");
+            return AssertionResult.Failed($"Failed to get match at index {_index}: {ex.Message}", ex);
         }
 
         var matchAssertion = new ValueAssertion<RegexMatch>(match, $"match at index {_index}");

TUnit.Assertions/Conditions/CollectionAssertions.cs

@@ -688,7 +688,7 @@ protected override async Task<AssertionResult> CheckAsync(EvaluationMetadata<TCo
             }
             catch (Exception ex)
             {
-                return AssertionResult.Failed($"item at index {index} failed assertion: {ex.Message}");
+                return AssertionResult.Failed($"item at index {index} failed assertion: {ex.Message}", ex);
             }
             index++;
         }
@@ -755,7 +755,7 @@ protected override async Task<AssertionResult> CheckAsync(EvaluationMetadata<TCo
             }
             catch (Exception ex)
             {
-                return AssertionResult.Failed($"item at index {index} (mapped by {_mapperDescription}) failed assertion: {ex.Message}");
+                return AssertionResult.Failed($"item at index {index} (mapped by {_mapperDescription}) failed assertion: {ex.Message}", ex);
             }
             index++;
         }

TUnit.Assertions/Conditions/CompletesWithinAssertion.cs

@@ -54,7 +54,7 @@ protected override async Task<AssertionResult> CheckAsync(EvaluationMetadata<obj
         }
         catch (Exception ex)
         {
-            return AssertionResult.Failed($"threw {ex.GetType().FullName}: {ex.Message}");
+            return AssertionResult.Failed($"threw {ex.GetType().FullName}: {ex.Message}", ex);
         }
     }
 
@@ -112,7 +112,7 @@ protected override async Task<AssertionResult> CheckAsync(EvaluationMetadata<obj
         }
         catch (Exception ex)
         {
-            return AssertionResult.Failed($"threw {ex.GetType().FullName}: {ex.Message}");
+            return AssertionResult.Failed($"threw {ex.GetType().FullName}: {ex.Message}", ex);
         }
     }
 

TUnit.Assertions/Conditions/Json/JsonStringAssertionExtensions.cs

@@ -19,7 +19,7 @@ public static AssertionResult IsValidJson(this string value)
         }
         catch (JsonException ex)
         {
-            return AssertionResult.Failed($"is not valid JSON: {ex.Message}");
+            return AssertionResult.Failed($"is not valid JSON: {ex.Message}", ex);
         }
     }
 
@@ -51,7 +51,7 @@ public static AssertionResult IsValidJsonObject(this string value)
         }
         catch (JsonException ex)
         {
-            return AssertionResult.Failed($"is not valid JSON: {ex.Message}");
+            return AssertionResult.Failed($"is not valid JSON: {ex.Message}", ex);
         }
     }
 
@@ -69,7 +69,7 @@ public static AssertionResult IsValidJsonArray(this string value)
         }
         catch (JsonException ex)
         {
-            return AssertionResult.Failed($"is not valid JSON: {ex.Message}");
+            return AssertionResult.Failed($"is not valid JSON: {ex.Message}", ex);
         }
     }
 }

TUnit.Assertions/Conditions/ListAssertions.cs

@@ -463,7 +463,7 @@ protected override async Task<AssertionResult> CheckAsync(EvaluationMetadata<TLi
             }
             catch (Exception ex)
             {
-                return AssertionResult.Failed($"item at index {_index} did not satisfy assertion: {ex.Message}");
+                return AssertionResult.Failed($"item at index {_index} did not satisfy assertion: {ex.Message}", ex);
             }
         }
 
@@ -635,7 +635,7 @@ protected override async Task<AssertionResult> CheckAsync(EvaluationMetadata<TLi
             }
             catch (Exception ex)
             {
-                return AssertionResult.Failed($"last item did not satisfy assertion: {ex.Message}");
+                return AssertionResult.Failed($"last item did not satisfy assertion: {ex.Message}", ex);
             }
         }
 

TUnit.Assertions/Conditions/MappedSatisfiesAssertion.cs

@@ -47,7 +47,7 @@ protected override async Task<AssertionResult> CheckAsync(EvaluationMetadata<TVa
         }
         catch (Exception ex)
         {
-            return AssertionResult.Failed($"selector threw {ex.GetType().Name}: {ex.Message}");
+            return AssertionResult.Failed($"selector threw {ex.GetType().Name}: {ex.Message}", ex);
         }
 
         // Create an assertion for the mapped value
@@ -65,7 +65,7 @@ protected override async Task<AssertionResult> CheckAsync(EvaluationMetadata<TVa
         }
         catch (Exception ex)
         {
-            return AssertionResult.Failed($"mapped value did not satisfy assertions: {ex.Message}");
+            return AssertionResult.Failed($"mapped value did not satisfy assertions: {ex.Message}", ex);
         }
     }
 
@@ -114,7 +114,7 @@ protected override async Task<AssertionResult> CheckAsync(EvaluationMetadata<TVa
         }
         catch (Exception ex)
         {
-            return AssertionResult.Failed($"selector threw {ex.GetType().Name}: {ex.Message}");
+            return AssertionResult.Failed($"selector threw {ex.GetType().Name}: {ex.Message}", ex);
         }
 
         // Create an assertion for the mapped value
@@ -132,7 +132,7 @@ protected override async Task<AssertionResult> CheckAsync(EvaluationMetadata<TVa
         }
         catch (Exception ex)
         {
-            return AssertionResult.Failed($"mapped value did not satisfy assertions: {ex.Message}");
+            return AssertionResult.Failed($"mapped value did not satisfy assertions: {ex.Message}", ex);
         }
     }
 

TUnit.Assertions/Conditions/ReadOnlyListAssertions.cs

@@ -465,7 +465,7 @@ protected override async Task<AssertionResult> CheckAsync(EvaluationMetadata<TLi
             }
             catch (Exception ex)
             {
-                return AssertionResult.Failed($"item at index {_index} did not satisfy assertion: {ex.Message}");
+                return AssertionResult.Failed($"item at index {_index} did not satisfy assertion: {ex.Message}", ex);
             }
         }
 
@@ -637,7 +637,7 @@ protected override async Task<AssertionResult> CheckAsync(EvaluationMetadata<TLi
             }
             catch (Exception ex)
             {
-                return AssertionResult.Failed($"last item did not satisfy assertion: {ex.Message}");
+                return AssertionResult.Failed($"last item did not satisfy assertion: {ex.Message}", ex);
             }
         }
 

TUnit.Assertions/Conditions/WaitsForAssertion.cs

@@ -87,7 +87,7 @@ protected override async Task<AssertionResult> CheckAsync(EvaluationMetadata<TVa
             : "No attempts were made";
 
         return AssertionResult.Failed(
-            $"assertion did not pass within {_timeout.TotalMilliseconds:F0}ms after {attemptCount} attempts. {lastErrorMessage}");
+            $"assertion did not pass within {_timeout.TotalMilliseconds:F0}ms after {attemptCount} attempts. {lastErrorMessage}", lastException);
     }
 
     /// <summary>

TUnit.Assertions/Conditions/WithInnerExceptionsAssertion.cs

@@ -46,7 +46,7 @@ protected override async Task<AssertionResult> CheckAsync(EvaluationMetadata<Agg
             }
             catch (Exception ex)
             {
-                return AssertionResult.Failed($"inner exceptions did not satisfy assertion: {ex.Message}");
+                return AssertionResult.Failed($"inner exceptions did not satisfy assertion: {ex.Message}", ex);
             }
         }
 

TUnit.Assertions/Core/Assertion.cs

@@ -242,7 +242,9 @@ protected Exception CreateException(AssertionResult result)
             at {Context.ExpressionBuilder}
             """;
 
-        return new AssertionException(message);
+        return result.Exception != null
+            ? new AssertionException(message, result.Exception)
+            : new AssertionException(message);
     }
 
     /// <summary>

TUnit.Assertions/Core/AssertionResult.cs

@@ -9,11 +9,13 @@ public readonly struct AssertionResult
 
     public bool IsPassed { get; }
     public string Message { get; }
+    public Exception? Exception { get; }
 
-    private AssertionResult(bool isPassed, string message)
+    private AssertionResult(bool isPassed, string message, Exception? exception = null)
     {
         IsPassed = isPassed;
         Message = message ?? string.Empty;
+        Exception = exception;
     }
 
     /// <summary>
@@ -26,6 +28,11 @@ private AssertionResult(bool isPassed, string message)
     /// </summary>
     public static AssertionResult Failed(string message) => new(false, message);
 
+    /// <summary>
+    /// Creates a failing assertion result with a message and an associated exception.
+    /// </summary>
+    public static AssertionResult Failed(string message, Exception? exception) => new(false, message, exception);
+
     /// <summary>
     /// Helper method to conditionally create a failed result.
     /// Returns Passed if condition is false, Failed with message if condition is true.

TUnit.Assertions/Core/AssertionResult{T}.cs

@@ -11,12 +11,14 @@ public readonly struct AssertionResult<T>
     public bool IsPassed { get; }
     public string Message { get; }
     public T? Value { get; }
+    public Exception? Exception { get; }
 
-    private AssertionResult(bool isPassed, string message, T? value)
+    private AssertionResult(bool isPassed, string message, T? value, Exception? exception = null)
     {
         IsPassed = isPassed;
         Message = message ?? string.Empty;
         Value = value;
+        Exception = exception;
     }
 
     /// <summary>
@@ -39,6 +41,6 @@ public static implicit operator AssertionResult<T>(AssertionResult result)
                 "Cannot convert a passed AssertionResult to AssertionResult<T> without a value. Use AssertionResult<T>.Passed(value) instead.");
         }
 
-        return Failed(result.Message);
+        return new AssertionResult<T>(false, result.Message, default, result.Exception);
     }
 }

TUnit.Mocks.Assertions/WasCalledAssertion.cs

@@ -34,7 +34,7 @@ protected override Task<AssertionResult> CheckAsync(EvaluationMetadata<ICallVeri
         }
         catch (MockVerificationException ex)
         {
-            return Task.FromResult(AssertionResult.Failed(ex.Message));
+            return Task.FromResult(AssertionResult.Failed(ex.Message, ex));
         }
     }
 

TUnit.Mocks.Assertions/WasNeverCalledAssertion.cs

@@ -30,7 +30,7 @@ protected override Task<AssertionResult> CheckAsync(EvaluationMetadata<ICallVeri
         }
         catch (MockVerificationException ex)
         {
-            return Task.FromResult(AssertionResult.Failed(ex.Message));
+            return Task.FromResult(AssertionResult.Failed(ex.Message, ex));
         }
     }
 

TUnit.PublicAPI/Tests.Assertions_Library_Has_No_API_Changes.DotNet10_0.verified.txt

@@ -2405,14 +2405,17 @@ namespace .Core
     }
     public readonly struct AssertionResult
     {
+        public ? Exception { get; }
         public bool IsPassed { get; }
         public string Message { get; }
         public static . Passed { get; }
         public static . FailIf(bool condition, string message) { }
         public static . Failed(string message) { }
+        public static . Failed(string message, ? exception) { }
     }
     public readonly struct AssertionResult<T>
     {
+        public ? Exception { get; }
         public bool IsPassed { get; }
         public string Message { get; }
         public T Value { get; }

TUnit.PublicAPI/Tests.Assertions_Library_Has_No_API_Changes.DotNet8_0.verified.txt

@@ -2384,14 +2384,17 @@ namespace .Core
     }
     public readonly struct AssertionResult
     {
+        public ? Exception { get; }
         public bool IsPassed { get; }
         public string Message { get; }
         public static . Passed { get; }
         public static . FailIf(bool condition, string message) { }
         public static . Failed(string message) { }
+        public static . Failed(string message, ? exception) { }
     }
     public readonly struct AssertionResult<T>
     {
+        public ? Exception { get; }
         public bool IsPassed { get; }
         public string Message { get; }
         public T Value { get; }

TUnit.PublicAPI/Tests.Assertions_Library_Has_No_API_Changes.DotNet9_0.verified.txt

@@ -2405,14 +2405,17 @@ namespace .Core
     }
     public readonly struct AssertionResult
     {
+        public ? Exception { get; }
         public bool IsPassed { get; }
         public string Message { get; }
         public static . Passed { get; }
         public static . FailIf(bool condition, string message) { }
         public static . Failed(string message) { }
+        public static . Failed(string message, ? exception) { }
     }
     public readonly struct AssertionResult<T>
     {
+        public ? Exception { get; }
         public bool IsPassed { get; }
         public string Message { get; }
         public T Value { get; }

TUnit.PublicAPI/Tests.Assertions_Library_Has_No_API_Changes.Net4_7.verified.txt

@@ -2156,14 +2156,17 @@ namespace .Core
     }
     public readonly struct AssertionResult
     {
+        public ? Exception { get; }
         public bool IsPassed { get; }
         public string Message { get; }
         public static . Passed { get; }
         public static . FailIf(bool condition, string message) { }
         public static . Failed(string message) { }
+        public static . Failed(string message, ? exception) { }
     }
     public readonly struct AssertionResult<T>
     {
+        public ? Exception { get; }
         public bool IsPassed { get; }
         public string Message { get; }
         public T Value { get; }