Add exception property to IInvocation

CHANGELOG.md

@@ -10,7 +10,7 @@ The format is loosely based on [Keep a Changelog](http://keepachangelog.com/en/1
 #### Added
 
 * New method overloads for `It.Is`, `It.IsIn`, and `It.IsNotIn` that compare values using a custom `IEqualityComparer<T>` (@weitzhandler, #1064)
-* New property `IInvocation.ReturnValue` to query recorded invocations return values (@MaStr11, #921)
+* New properties `ReturnValue` and `Exception` on `IInvocation` to query recorded invocations return values or exceptions (@MaStr11, #921, #1077)
 
 
 ## 4.14.7 (2020-10-14)

src/Moq/IInvocation.cs

@@ -1,6 +1,7 @@
 // Copyright (c) 2007, Clarius Consulting, Manas Technology Solutions, InSTEDD, and Contributors.
 // All rights reserved. Licensed under the BSD 3-Clause License; see License.txt.
 
+using System;
 using System.Collections.Generic;
 using System.Reflection;
 
@@ -32,8 +33,13 @@ public interface IInvocation
 		bool IsVerified { get; }
 
 		/// <summary>
-		/// Gets the return value of the invocation.
+		/// The value being returned for a non-void method if no exception was thrown.
 		/// </summary>
 		object ReturnValue { get; }
+
+		/// <summary>
+		/// Optional exception if the method invocation results in an exception being thrown.
+		/// </summary>
+		Exception Exception { get; }
 	}
 }

src/Moq/Invocation.cs

@@ -71,14 +71,21 @@ public MethodInfo MethodImplementation
 
 		public object ReturnValue
 		{
-			get => this.returnValue;
+			get => this.returnValue is InvocationExceptionWrapper
+				? null
+				: this.returnValue;
 			set
 			{
 				Debug.Assert(this.returnValue == null);
 				this.returnValue = value;
 			}
 		}
 
+		public Exception Exception
+			=> this.returnValue is InvocationExceptionWrapper wrapper
+				? wrapper.Exception
+				: null;
+
 		public bool IsVerified => this.verified;
 
 		/// <summary>

src/Moq/InvocationExceptionWrapper.cs

@@ -0,0 +1,22 @@
+// Copyright (c) 2007, Clarius Consulting, Manas Technology Solutions, InSTEDD, and Contributors.
+// All rights reserved. Licensed under the BSD 3-Clause License; see License.txt.
+
+using System;
+
+namespace Moq
+{
+	/// <summary>
+	/// Internal type to mark invocation results as "exception occurred during execution". The type just
+	/// wraps the Exception so a thrown exception can be distinguished from an <see cref="System.Exception"/>
+	/// return by the invocation.
+	/// </summary>
+	internal readonly struct InvocationExceptionWrapper
+	{
+		public InvocationExceptionWrapper(Exception exception)
+		{
+			Exception = exception;
+		}
+
+		public Exception Exception { get; }
+	}
+}

src/Moq/ProxyFactories/CastleProxyFactory.cs

@@ -101,6 +101,11 @@ public void Intercept(Castle.DynamicProxy.IInvocation underlying)
 					this.interceptor.Intercept(invocation);
 					underlying.ReturnValue = invocation.ReturnValue;
 				}
+				catch (Exception ex)
+				{
+					invocation.ReturnValue = new InvocationExceptionWrapper(ex);
+					throw;
+				}
 				finally
 				{
 					invocation.DetachFromUnderlying();

tests/Moq.Tests/InvocationsFixture.cs

@@ -2,6 +2,8 @@
 // All rights reserved. Licensed under the BSD 3-Clause License; see License.txt.
 
 using System;
+using System.Collections;
+using System.Collections.Generic;
 using System.Linq;
 
 using Xunit;
@@ -45,11 +47,131 @@ public void MockInvocationsIncludeArguments()
 
 			var invocation = mock.Invocations[0];
 
-			var expectedArguments = new[] {obj};
+			var expectedArguments = new[] { obj };
 
 			Assert.Equal(expectedArguments, invocation.Arguments);
 		}
 
+		[Fact]
+		public void MockInvocationsIncludeReturnValue_NoSetup()
+		{
+			var mock = new Mock<IComparable>();
+
+			var obj = new object();
+
+			mock.Object.CompareTo(obj);
+
+			var invocation = mock.Invocations[0];
+
+			Assert.Equal(0, invocation.ReturnValue);
+			Assert.Null(invocation.Exception);
+		}
+
+		[Fact]
+		public void MockInvocationsIncludeReturnValue_Setup()
+		{
+			var mock = new Mock<IComparable>();
+			var obj = new object();
+			mock.Setup(c => c.CompareTo(obj)).Returns(42);
+
+			mock.Object.CompareTo(obj);
+
+			var invocation = mock.Invocations[0];
+
+			Assert.Equal(42, invocation.ReturnValue);
+			Assert.Null(invocation.Exception);
+		}
+
+		[Fact]
+		public void MockInvocationsIncludeReturnValue_BaseCall()
+		{
+			var mock = new Mock<Random>(1) // seed: 1
+			{
+				CallBase = true,
+			};
+
+			mock.Object.Next();
+
+			var invocation = mock.Invocations[0];
+
+			Assert.Equal(new Random(Seed: 1).Next(), invocation.ReturnValue);
+			Assert.Null(invocation.Exception);
+		}
+
+		[Fact]
+		public void MockInvocationsIncludeReturnValue_ReturnsException()
+		{
+			var mock = new Mock<ICloneable>();
+			var returnValue = new Exception();
+			mock.Setup(c => c.Clone()).Returns(returnValue);
+
+			mock.Object.Clone();
+
+			var invocation = mock.Invocations[0];
+
+			Assert.Equal(returnValue, invocation.ReturnValue);
+			Assert.Null(invocation.Exception);
+		}
+
+		[Fact]
+		public void MockInvocationsIncludeException_Setup()
+		{
+			var mock = new Mock<IComparable>();
+			var exception = new Exception("Message");
+			mock.Setup(c => c.CompareTo(It.IsAny<object>())).Throws(exception);
+
+			var thrown = Assert.Throws<Exception>(() => mock.Object.CompareTo(null));
+
+			Assert.Equal(exception.Message, thrown.Message);
+
+			var invocation = mock.Invocations[0];
+			Assert.Same(thrown, invocation.Exception);
+		}
+
+		[Fact]
+		public void MockInvocationsIncludeException_BaseCall_Nonvirtual()
+		{
+			var mock = new Mock<List<int>>()
+			{
+				CallBase = true,
+			};
+
+			Assert.Throws<ArgumentException>(() => mock.Object.GetRange(1, 1));
+			// Base-call exceptions are not recorded
+			Assert.Empty(mock.Invocations);
+		}
+
+		[Fact]
+		public void MockInvocationsIncludeException_BaseCall_Virtual()
+		{
+			var mock = new Mock<Test>()
+			{
+				CallBase = true,
+			};
+
+			var thrown = Assert.Throws<InvalidOperationException>(() => mock.Object.ThrowingVirtualMethod());
+
+			Assert.Equal("Message", thrown.Message);
+
+			var invocation = mock.Invocations[0];
+			Assert.Same(thrown, invocation.Exception);
+		}
+
+		[Fact]
+		public void MockInvocationsIncludeException_MockException()
+		{
+			var mock = new Mock<ICloneable>(MockBehavior.Strict);
+
+			var thrown = Assert.Throws<MockException>(() => mock.Object.Clone());
+
+			Assert.Equal(
+@"ICloneable.Clone() invocation failed with mock behavior Strict.
+All invocations on the mock must have a corresponding setup.", thrown.Message);
+
+			var invocation = mock.Invocations[0];
+			Assert.Same(thrown, invocation.Exception);
+		}
+
 		[Fact]
 		public void MockInvocationsCanBeEnumerated()
 		{
@@ -269,5 +391,10 @@ public FlagInitiallySetToTrue()
 
 			public virtual bool Flag { get; set; }
 		}
+
+		public class Test
+		{
+			public virtual int ThrowingVirtualMethod() => throw new InvalidOperationException("Message");
+		}
 	}
 }