Add xmldoc to SutProvider

test/Common/AutoFixture/SutProvider.cs

@@ -4,8 +4,19 @@ using AutoFixture.Kernel;
 
 namespace Bit.Test.Common.AutoFixture;
 
+/// <summary>
+/// A utility class that encapsulates a system under test (sut) and its dependencies.
+/// By default, all dependencies are initialized as mocks using the NSubstitute library.
+/// SutProvider provides an interface for accessing these dependencies in the arrange and assert stages of your tests.
+/// </summary>
+/// <typeparam name="TSut">The concrete implementation of the class being tested.</typeparam>
 public class SutProvider<TSut> : ISutProvider
 {
+    /// <summary>
+    /// A record of the configured dependencies (constructor parameters). The outer Dictionary is keyed by the dependency's
+    /// type, and the inner dictionary is keyed by the parameter name (optionally used to disambiguate parameters with the same type).
+    /// The inner dictionary value is the dependency.
+    /// </summary>
     private Dictionary<Type, Dictionary<string, object>> _dependencies;
     private readonly IFixture _fixture;
     private readonly ConstructorParameterRelay<TSut> _constructorParameterRelay;
@@ -23,9 +34,21 @@ public class SutProvider<TSut> : ISutProvider
         _fixture.Customizations.Add(_constructorParameterRelay);
     }
 
+    /// <summary>
+    /// Registers a dependency to be injected when the sut is created. You must call <see cref="Create"/> after
+    /// this method to (re)create the sut with the dependency.
+    /// </summary>
+    /// <param name="dependency">The dependency to register.</param>
+    /// <param name="parameterName">An optional parameter name to disambiguate the dependency if there are multiple of the same type. You generally don't need this.</param>
+    /// <typeparam name="T">The type to register the dependency under - usually an interface. This should match the type expected by the sut's constructor.</typeparam>
+    /// <returns></returns>
     public SutProvider<TSut> SetDependency<T>(T dependency, string parameterName = "")
         => SetDependency(typeof(T), dependency, parameterName);
-    public SutProvider<TSut> SetDependency(Type dependencyType, object dependency, string parameterName = "")
+
+    /// <summary>
+    /// An overload for <see cref="SetDependency{T}"/> which takes a runtime <see cref="Type"/> object rather than a compile-time type.
+    /// </summary>
+    private SutProvider<TSut> SetDependency(Type dependencyType, object dependency, string parameterName = "")
     {
         if (_dependencies.ContainsKey(dependencyType))
         {
@@ -39,46 +62,69 @@ public class SutProvider<TSut> : ISutProvider
         return this;
     }
 
+    /// <summary>
+    /// Gets a dependency of the sut. Can only be called after the SutProvider has been initialized with <see cref="Create"/>.
+    /// As dependencies are initialized with NSubstitute mocks by default, this is often used to retrieve those mocks in order to
+    /// configure them during the arrange stage, or check received calls in the assert stage.
+    /// </summary>
+    /// <param name="parameterName">An optional parameter name to disambiguate the dependency if there are multiple of the same type. You generally don't need this.</param>
+    /// <typeparam name="T">The type of the dependency you want to get - usually an interface.</typeparam>
+    /// <returns>The dependency.</returns>
     public T GetDependency<T>(string parameterName = "") => (T)GetDependency(typeof(T), parameterName);
-    public object GetDependency(Type dependencyType, string parameterName = "")
+
+    /// <summary>
+    /// An overload for <see cref="GetDependency{T}"/> which takes a runtime <see cref="Type"/> object rather than a compile-time type.
+    /// </summary>
+    private object GetDependency(Type dependencyType, string parameterName = "")
     {
         if (DependencyIsSet(dependencyType, parameterName))
         {
             return _dependencies[dependencyType][parameterName];
         }
-        else if (_dependencies.ContainsKey(dependencyType))
+
+        if (_dependencies.ContainsKey(dependencyType))
         {
             var knownDependencies = _dependencies[dependencyType];
             if (knownDependencies.Values.Count == 1)
             {
                 return _dependencies[dependencyType].Values.Single();
             }
-            else
-            {
+
             throw new ArgumentException(string.Concat($"Dependency of type {dependencyType.Name} and name ",
                 $"{parameterName} does not exist. Available dependency names are: ",
                 string.Join(", ", knownDependencies.Keys)));
         }
-        }
-        else
-        {
+
         throw new ArgumentException($"Dependency of type {dependencyType.Name} and name {parameterName} has not been set.");
     }
-    }
 
+    /// <summary>
+    /// Clear all the dependencies and the sut. This reverts the SutProvider back to a fully uninitialized state.
+    /// </summary>
     public void Reset()
     {
         _dependencies = new Dictionary<Type, Dictionary<string, object>>();
         Sut = default;
     }
 
+    /// <summary>
+    /// Recreate a new sut with all new dependencies. This will reset all dependencies, including mocked return values
+    /// and any dependencies set with <see cref="SetDependency{T}"/>.
+    /// </summary>
     public void Recreate()
     {
         _dependencies = new Dictionary<Type, Dictionary<string, object>>();
         Sut = _fixture.Create<TSut>();
     }
 
+    /// <inheritdoc cref="Create()"/>>
     ISutProvider ISutProvider.Create() => Create();
+
+    /// <summary>
+    /// Creates the sut, injecting any dependencies configured via <see cref="SetDependency{T}"/> and falling back to
+    /// NSubstitute mocks for any dependencies that have not been explicitly configured.
+    /// </summary>
+    /// <returns></returns>
     public SutProvider<TSut> Create()
     {
         Sut = _fixture.Create<TSut>();
@@ -90,6 +136,19 @@ public class SutProvider<TSut> : ISutProvider
 
     private object GetDefault(Type type) => type.IsValueType ? Activator.CreateInstance(type) : null;
 
+    /// <summary>
+    /// A specimen builder which tells Autofixture to use the dependency registered in <see cref="SutProvider{T}"/>
+    /// when creating test data. If no matching dependency exists in <see cref="SutProvider{TSut}"/>, it creates
+    /// an NSubstitute mock and registers it using <see cref="SutProvider{TSut}.SetDependency{T}"/>
+    /// so it can be retrieved later.
+    /// This is the link between <see cref="SutProvider{T}"/> and Autofixture.
+    /// </summary>
+    /// <remarks>
+    /// Autofixture knows how to create sample data of simple types (such as an int or string) but not more complex classes.
+    /// We create our own <see cref="ISpecimenBuilder"/> and register it with the <see cref="Fixture"/> in
+    /// <see cref="SutProvider{TSut}"/> to provide that instruction.
+    /// </remarks>
+    /// <typeparam name="T">The type of the sut.</typeparam>
     private class ConstructorParameterRelay<T> : ISpecimenBuilder
     {
         private readonly SutProvider<T> _sutProvider;
@@ -103,6 +162,7 @@ public class SutProvider<TSut> : ISutProvider
 
         public object Create(object request, ISpecimenContext context)
         {
+            // Basic checks to filter out irrelevant requests from Autofixture
             if (context == null)
             {
                 throw new ArgumentNullException(nameof(context));
@@ -117,16 +177,20 @@ public class SutProvider<TSut> : ISutProvider
                 return new NoSpecimen();
             }
 
+            // Use the dependency set under this parameter name, if any
             if (_sutProvider.DependencyIsSet(parameterInfo.ParameterType, parameterInfo.Name))
             {
                 return _sutProvider.GetDependency(parameterInfo.ParameterType, parameterInfo.Name);
             }
-            // Return default type if set
-            else if (_sutProvider.DependencyIsSet(parameterInfo.ParameterType, ""))
+
+            // Use the default dependency set for this type, if any (i.e. no parameter name has been specified)
+            if (_sutProvider.DependencyIsSet(parameterInfo.ParameterType, ""))
             {
                 return _sutProvider.GetDependency(parameterInfo.ParameterType, "");
             }
 
+            // Fallback: create an NSubstitute mock (assuming the WithAutoNSubstitutions customization has been used)
+            // and register it using SetDependency so it can be retrieved later.
             // This is the equivalent of _fixture.Create<parameterInfo.ParameterType>, but no overload for
             // Create(Type type) exists.
             var dependency = new SpecimenContext(_fixture).Resolve(new SeededRequest(parameterInfo.ParameterType,

test/Core.Test/AdminConsole/OrganizationFeatures/Policies/SavePolicyCommandTests.cs

@@ -288,7 +288,7 @@ public class SavePolicyCommandTests
     {
         return new SutProvider<SavePolicyCommand>()
             .WithFakeTimeProvider()
-            .SetDependency(typeof(IEnumerable<IPolicyValidator>), policyValidators ?? [])
+            .SetDependency(policyValidators ?? [])
             .Create();
     }