diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..776059c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,76 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Build Commands + +### Primary Commands + +- `dotnet run --project build/Build` - Main build command that restores, builds the solution +- `dotnet run --project build/Build -- --target=Test` - Run unit tests with coverage +- `dotnet run --project build/Build -- --target=Package` - Build and package for NuGet +- `dotnet run --project build/Publish -- --target=PublishNuGet` - Publish to NuGet (CI only) + +### Testing Commands + +- `dotnet test src/Mimic.UnitTests/Mimic.UnitTests.csproj` - Run tests directly +- `dotnet test src/Mimic.UnitTests/Mimic.UnitTests.csproj --framework net8.0` - Test specific framework +- `dotnet test src/Mimic.UnitTests/Mimic.UnitTests.csproj --framework net9.0` - Test on .NET 9 + +## Project Structure + +### Core Architecture + +Mimic is a .NET mocking library built on Castle DynamicProxy with a fluent API design: + +- **Main Library** (`src/Mimic/`): The core mocking functionality + - `Mimic` - Main generic mimic class for creating mock objects + - `Setup/` - Fluent API for configuring method/property behaviours + - `Proxy/` - Castle DynamicProxy integration for runtime proxy generation + - `Expressions/` - Expression tree handling for type-safe setup syntax + +- **Test Project** (`src/Mimic.UnitTests/`): Comprehensive unit tests + - Multi-target framework support (net8.0, net9.0) + - Uses xUnit, Shouldly, and AutoFixture + - Organised by feature area (Setup/, Expressions/, Core/, etc.) + +### Key Components + +- **Mimic**: Generic wrapper providing fluent API for mock configuration +- **Setup System**: Expression-based method/property setup with behaviours +- **Proxy Generation**: Runtime proxy creation using Castle DynamicProxy +- **Argument Matching**: Type-safe argument matchers (`Arg.Any()`, etc.) +- **Verification**: Post-execution verification of method calls + +### Build System + +Custom Cake-based build system in `build/` directory: + +- **Build Project**: Main build tasks (Clean, Build, Test, Package) +- **Publish Project**: NuGet publishing tasks +- **Common**: Shared utilities and models +- Uses GitVersion for semantic versioning +- Coverlet for code coverage with Codecov integration + +## Development Guidelines + +### Testing Framework + +- Primary: xUnit with Shouldly assertions +- Test data: AutoFixture for test data generation +- Coverage: Coverlet with 80%+ target coverage +- Multi-framework testing on net8.0 and net9.0 + +### Code Organisation + +- Follow existing namespace patterns (Mimic.Core, Mimic.Setup, etc.) +- Use fluent interface patterns for public APIs +- Internal classes use Castle DynamicProxy conventions +- Expression trees for type-safe configuration + +### Package Management + +- Central Package Management via Directory.Packages.props +- Package lock files are enabled for reproducible builds +- Castle.Core dependency for proxy generation +- JetBrains.Annotations for code contracts diff --git a/src/Mimic/Exceptions/MimicException.cs b/src/Mimic/Exceptions/MimicException.cs index 3a45f55..431ce28 100644 --- a/src/Mimic/Exceptions/MimicException.cs +++ b/src/Mimic/Exceptions/MimicException.cs @@ -4,17 +4,38 @@ namespace Mimic.Exceptions; +/// +/// Represents errors that occur during Mimic library operations. This is the primary exception type thrown by +/// Mimic to indicate various categories of errors such as usage errors, incompatible types, unsupported expressions, +/// and expectation failures. +/// [PublicAPI] public class MimicException : Exception { + /// + /// Gets the reason category that describes the type of mimic-related error that occurred. + /// + /// A value indicating the category of error. public Reason Reason { get; } + /// + /// Initialises a new instance of the class with the specified reason and message. + /// + /// The reason category that describes the type of error. + /// The message that describes the error, or null to use a default message. public MimicException(Reason reason, string? message) : base(message) { Reason = reason; } + /// + /// Initialises a new instance of the class with the specified reason, message, + /// and inner exception. + /// + /// The reason category that describes the type of error. + /// The message that describes the error, or null to use a default message. + /// The exception that is the cause of the current exception or null if no inner exception is specified. public MimicException(Reason reason, string? message, Exception? innerException) : base(message, innerException) { diff --git a/src/Mimic/Extensions/DelayableExtensions.cs b/src/Mimic/Extensions/DelayableExtensions.cs index 79c528d..de3919b 100644 --- a/src/Mimic/Extensions/DelayableExtensions.cs +++ b/src/Mimic/Extensions/DelayableExtensions.cs @@ -1,15 +1,44 @@ namespace Mimic; +/// +/// Provides extension methods for adding random delays to mimic setups, enhancing the realism of mock behaviours by introducing timing variability. +/// [PublicAPI] public static class DelayableExtensions { #region IDelayable + /// + /// Adds a random delay between the specified minimum and maximum values to the mimic setup using . + /// + /// The mimic instance to add the delay to. + /// The minimum delay duration. + /// The maximum delay duration. + /// An that can be used to continue configuring the mimic setup. + /// Thrown when is not less than . + /// + /// This method uses for generating random delays, making it suitable for most scenarios. + /// For deterministic testing or when you need control over the randomisation, use the overload that accepts a parameter. + /// public static IDelayableResult WithDelay(this IDelayable mimic, TimeSpan minDelay, TimeSpan maxDelay) { return mimic.WithDelay(minDelay, maxDelay, Random.Shared); } + /// + /// Adds a random delay between the specified minimum and maximum values to the mimic setup using the provided random number generator. + /// + /// The mimic instance to add the delay to. + /// The minimum delay duration. + /// The maximum delay duration. + /// The random number generator to use for generating delays. + /// An that can be used to continue configuring the mimic setup. + /// Thrown when is not less than . + /// Thrown when is null. + /// + /// This overload allows you to provide your own instance, which is useful for deterministic testing + /// or when you need to control the seed for reproducible random delays. + /// public static IDelayableResult WithDelay(this IDelayable mimic, TimeSpan minDelay, TimeSpan maxDelay, Random random) { Guard.Assert(minDelay < maxDelay, $"{nameof(minDelay)} must be less than {nameof(maxDelay)}"); @@ -22,11 +51,39 @@ public static IDelayableResult WithDelay(this IDelayable mimic, TimeSpan minDela #region ISequenceDelayable + /// + /// Adds a random delay between the specified minimum and maximum values to the sequence mimic setup using . + /// + /// The sequence Mimic instance to add the delay to. + /// The minimum delay duration. + /// The maximum delay duration. + /// An that can be used to continue configuring the sequence mimic setup. + /// Thrown when is not less than . + /// + /// This method uses for generating random delays, making it suitable for most scenarios. + /// For deterministic testing or when you need control over the randomisation, use the overload that accepts a parameter. + /// This overload is specifically designed for sequence-based mimic setups where the delay applies to sequential calls. + /// public static IExpected WithDelay(this ISequenceDelayable mimic, TimeSpan minDelay, TimeSpan maxDelay) { return mimic.WithDelay(minDelay, maxDelay, Random.Shared); } + /// + /// Adds a random delay between the specified minimum and maximum values to the sequence mimic setup using the provided random number generator. + /// + /// The sequence Mimic instance to add the delay to. + /// The minimum delay duration. + /// The maximum delay duration. + /// The random number generator to use for generating delays. + /// An that can be used to continue configuring the sequence mimic setup. + /// Thrown when is not less than . + /// Thrown when is null. + /// + /// This overload allows you to provide your own instance, which is useful for deterministic testing + /// or when you need to control the seed for reproducible random delays. + /// This method is specifically designed for sequence-based mimic setups where the delay applies to sequential calls. + /// public static IExpected WithDelay(this ISequenceDelayable mimic, TimeSpan minDelay, TimeSpan maxDelay, Random random) { Guard.Assert(minDelay < maxDelay, $"{nameof(minDelay)} must be less than {nameof(maxDelay)}"); @@ -37,6 +94,13 @@ public static IExpected WithDelay(this ISequenceDelayable mimic, TimeSpan minDel #endregion + /// + /// Generates a random between the specified minimum and maximum delays. + /// + /// The random number generator to use. + /// The minimum delay duration. + /// The maximum delay duration. + /// A random between and . private static TimeSpan GetRandomDelay(Random random, TimeSpan minDelay, TimeSpan maxDelay) => new(random.Next((int)minDelay.Ticks, (int)maxDelay.Ticks)); } diff --git a/src/Mimic/Extensions/ReturnsExtensions.cs b/src/Mimic/Extensions/ReturnsExtensions.cs index 3d93e0a..a027e2a 100644 --- a/src/Mimic/Extensions/ReturnsExtensions.cs +++ b/src/Mimic/Extensions/ReturnsExtensions.cs @@ -1,90 +1,416 @@ namespace Mimic; +/// +/// Provides extension methods for simplifying the configuration of async return values in mimic setups. +/// These methods eliminate the need to manually wrap values in Task.FromResult() or create ValueTask<T> instances. +/// [PublicAPI] public static class ReturnsExtensions { #region Task + /// + /// Configures the setup to return the specified value wrapped in a completed . + /// + /// The type of the value to be returned. + /// The returns configuration instance. + /// The value to return wrapped in a task. + /// An that can be used to configure additional return behaviours. + /// + /// This method simplifies async setup by automatically wrapping the value in Task.FromResult(value). + /// Instead of writing .Returns(() => Task.FromResult(42)), you can simply write .Returns(42). + /// public static IReturnsResult Returns(this IReturns> mimic, TResult value) { return mimic.Returns(() => Task.FromResult(value)); } + /// + /// Configures the setup to return a value computed by the specified function, wrapped in a completed . + /// + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that computes the value to return wrapped in a task. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows for dynamic value computation at invocation time while automatically handling the task wrapping. + /// The function is executed each time the mocked method is called. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns(() => Task.FromResult(valueFunction())); } + /// + /// Configures the setup to return a value computed by the specified function using the method's single argument, + /// wrapped in a completed . + /// + /// The type of the method's argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's argument and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's argument while automatically handling the task wrapping. + /// The function receives the argument passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T t) => Task.FromResult(valueFunction(t))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's two arguments, + /// wrapped in a completed . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the task wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2) => Task.FromResult(valueFunction(t1, t2))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's three arguments, + /// wrapped in a completed . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the task wrapping. + /// Additional overloads are available for methods with up to 15 parameters following the same pattern. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3) => Task.FromResult(valueFunction(t1, t2, t3))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's four arguments, + /// wrapped in a completed . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the task wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4) => Task.FromResult(valueFunction(t1, t2, t3, t4))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's five arguments, + /// wrapped in a completed . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the task wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5) => Task.FromResult(valueFunction(t1, t2, t3, t4, t5))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's six arguments, + /// wrapped in a completed . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the task wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6) => Task.FromResult(valueFunction(t1, t2, t3, t4, t5, t6))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's seven arguments, + /// wrapped in a completed . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the method's seventh argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the task wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7) => Task.FromResult(valueFunction(t1, t2, t3, t4, t5, t6, t7))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's eight arguments, + /// wrapped in a completed . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the method's seventh argument. + /// The type of the method's eighth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the task wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7, T8 t8) => Task.FromResult(valueFunction(t1, t2, t3, t4, t5, t6, t7, t8))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's nine arguments, + /// wrapped in a completed . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the method's seventh argument. + /// The type of the method's eighth argument. + /// The type of the method's ninth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the task wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7, T8 t8, T9 t9) => Task.FromResult(valueFunction(t1, t2, t3, t4, t5, t6, t7, t8, t9))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's ten arguments, + /// wrapped in a completed . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the method's seventh argument. + /// The type of the method's eighth argument. + /// The type of the method's ninth argument. + /// The type of the method's tenth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the task wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7, T8 t8, T9 t9, T10 t10) => Task.FromResult(valueFunction(t1, t2, t3, t4, t5, t6, t7, t8, t9, t10))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's eleven arguments, + /// wrapped in a completed . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the method's seventh argument. + /// The type of the method's eighth argument. + /// The type of the method's ninth argument. + /// The type of the method's tenth argument. + /// The type of the method's eleventh argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the task wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7, T8 t8, T9 t9, T10 t10, T11 t11) => Task.FromResult(valueFunction(t1, t2, t3, t4, t5, t6, t7, t8, t9, t10, t11))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's twelve arguments, + /// wrapped in a completed . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the method's seventh argument. + /// The type of the method's eighth argument. + /// The type of the method's ninth argument. + /// The type of the method's tenth argument. + /// The type of the method's eleventh argument. + /// The type of the method's twelfth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the task wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7, T8 t8, T9 t9, T10 t10, T11 t11, T12 t12) => Task.FromResult(valueFunction(t1, t2, t3, t4, t5, t6, t7, t8, t9, t10, t11, t12))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's thirteen arguments, + /// wrapped in a completed . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the method's seventh argument. + /// The type of the method's eighth argument. + /// The type of the method's ninth argument. + /// The type of the method's tenth argument. + /// The type of the method's eleventh argument. + /// The type of the method's twelfth argument. + /// The type of the method's thirteenth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the task wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7, T8 t8, T9 t9, T10 t10, T11 t11, T12 t12, T13 t13) => Task.FromResult(valueFunction(t1, t2, t3, t4, t5, t6, t7, t8, t9, t10, t11, t12, t13))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's fourteen arguments, + /// wrapped in a completed . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the method's seventh argument. + /// The type of the method's eighth argument. + /// The type of the method's ninth argument. + /// The type of the method's tenth argument. + /// The type of the method's eleventh argument. + /// The type of the method's twelfth argument. + /// The type of the method's thirteenth argument. + /// The type of the method's fourteenth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the task wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7, T8 t8, T9 t9, T10 t10, T11 t11, T12 t12, T13 t13, T14 t14) => Task.FromResult(valueFunction(t1, t2, t3, t4, t5, t6, t7, t8, t9, t10, t11, t12, t13, t14))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's fifteen arguments, + /// wrapped in a completed . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the method's seventh argument. + /// The type of the method's eighth argument. + /// The type of the method's ninth argument. + /// The type of the method's tenth argument. + /// The type of the method's eleventh argument. + /// The type of the method's twelfth argument. + /// The type of the method's thirteenth argument. + /// The type of the method's fourteenth argument. + /// The type of the method's fifteenth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the task wrapping. + /// This is the maximum parameter count supported by these extension methods. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7, T8 t8, T9 t9, T10 t10, T11 t11, T12 t12, T13 t13, T14 t14, T15 t15) => Task.FromResult(valueFunction(t1, t2, t3, t4, t5, t6, t7, t8, t9, t10, t11, t12, t13, t14, t15))); @@ -94,86 +420,409 @@ public static IReturnsResult Returns + /// + /// Configures the setup to return the specified value wrapped in a . + /// + /// The type of the value to be returned. + /// The returns configuration instance. + /// The value to return wrapped in a ValueTask. + /// An that can be used to configure additional return behaviours. + /// + /// This method simplifies async setup by automatically wrapping the value in a ValueTask<TResult>. + /// Instead of writing .Returns(() => new ValueTask<int>(42)), you can simply write .Returns(42). + /// ValueTask provides better performance than Task for scenarios where the result is immediately available. + /// public static IReturnsResult Returns(this IReturns> mimic, TResult value) { return mimic.Returns(() => new ValueTask(value)); } + /// + /// Configures the setup to return a value computed by the specified function, wrapped in a . + /// + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that computes the value to return wrapped in a ValueTask. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows for dynamic value computation at invocation time while automatically handling the ValueTask wrapping. + /// The function is executed each time the mocked method is called. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns(() => new ValueTask(valueFunction())); } + /// + /// Configures the setup to return a value computed by the specified function using the method's single argument, + /// wrapped in a . + /// + /// The type of the method's argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's argument and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's argument while automatically handling the ValueTask wrapping. + /// The function receives the argument passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T t) => new ValueTask(valueFunction(t))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's two arguments, + /// wrapped in a . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the ValueTask wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2) => new ValueTask(valueFunction(t1, t2))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's three arguments, + /// wrapped in a . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the ValueTask wrapping. + /// Additional overloads are available for methods with up to 15 parameters following the same pattern. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3) => new ValueTask(valueFunction(t1, t2, t3))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's four arguments, + /// wrapped in a . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the ValueTask wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4) => new ValueTask(valueFunction(t1, t2, t3, t4))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's five arguments, + /// wrapped in a . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the ValueTask wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5) => new ValueTask(valueFunction(t1, t2, t3, t4, t5))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's six arguments, + /// wrapped in a . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the ValueTask wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6) => new ValueTask(valueFunction(t1, t2, t3, t4, t5, t6))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's seven arguments, + /// wrapped in a . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the method's seventh argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the ValueTask wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7) => new ValueTask(valueFunction(t1, t2, t3, t4, t5, t6, t7))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's eight arguments, + /// wrapped in a . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the method's seventh argument. + /// The type of the method's eighth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the ValueTask wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7, T8 t8) => new ValueTask(valueFunction(t1, t2, t3, t4, t5, t6, t7, t8))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's nine arguments, + /// wrapped in a . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the method's seventh argument. + /// The type of the method's eighth argument. + /// The type of the method's ninth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the ValueTask wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7, T8 t8, T9 t9) => new ValueTask(valueFunction(t1, t2, t3, t4, t5, t6, t7, t8, t9))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's ten arguments, + /// wrapped in a . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the method's seventh argument. + /// The type of the method's eighth argument. + /// The type of the method's ninth argument. + /// The type of the method's tenth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the ValueTask wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7, T8 t8, T9 t9, T10 t10) => new ValueTask(valueFunction(t1, t2, t3, t4, t5, t6, t7, t8, t9, t10))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's eleven arguments, + /// wrapped in a . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the method's seventh argument. + /// The type of the method's eighth argument. + /// The type of the method's ninth argument. + /// The type of the method's tenth argument. + /// The type of the method's eleventh argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the ValueTask wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7, T8 t8, T9 t9, T10 t10, T11 t11) => new ValueTask(valueFunction(t1, t2, t3, t4, t5, t6, t7, t8, t9, t10, t11))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's twelve arguments, + /// wrapped in a . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the method's seventh argument. + /// The type of the method's eighth argument. + /// The type of the method's ninth argument. + /// The type of the method's tenth argument. + /// The type of the method's eleventh argument. + /// The type of the method's twelfth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the ValueTask wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7, T8 t8, T9 t9, T10 t10, T11 t11, T12 t12) => new ValueTask(valueFunction(t1, t2, t3, t4, t5, t6, t7, t8, t9, t10, t11, t12))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's thirteen arguments, + /// wrapped in a . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the method's seventh argument. + /// The type of the method's eighth argument. + /// The type of the method's ninth argument. + /// The type of the method's tenth argument. + /// The type of the method's eleventh argument. + /// The type of the method's twelfth argument. + /// The type of the method's thirteenth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the ValueTask wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7, T8 t8, T9 t9, T10 t10, T11 t11, T12 t12, T13 t13) => new ValueTask(valueFunction(t1, t2, t3, t4, t5, t6, t7, t8, t9, t10, t11, t12, t13))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's fourteen arguments, + /// wrapped in a . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the method's seventh argument. + /// The type of the method's eighth argument. + /// The type of the method's ninth argument. + /// The type of the method's tenth argument. + /// The type of the method's eleventh argument. + /// The type of the method's twelfth argument. + /// The type of the method's thirteenth argument. + /// The type of the method's fourteenth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the ValueTask wrapping. + /// The function receives the arguments passed to the mocked method at invocation time. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7, T8 t8, T9 t9, T10 t10, T11 t11, T12 t12, T13 t13, T14 t14) => new ValueTask(valueFunction(t1, t2, t3, t4, t5, t6, t7, t8, t9, t10, t11, t12, t13, t14))); } + /// + /// Configures the setup to return a value computed by the specified function using the method's fifteen arguments, + /// wrapped in a . + /// + /// The type of the method's first argument. + /// The type of the method's second argument. + /// The type of the method's third argument. + /// The type of the method's fourth argument. + /// The type of the method's fifth argument. + /// The type of the method's sixth argument. + /// The type of the method's seventh argument. + /// The type of the method's eighth argument. + /// The type of the method's ninth argument. + /// The type of the method's tenth argument. + /// The type of the method's eleventh argument. + /// The type of the method's twelfth argument. + /// The type of the method's thirteenth argument. + /// The type of the method's fourteenth argument. + /// The type of the method's fifteenth argument. + /// The type of the value to be returned. + /// The returns configuration instance. + /// A function that takes the method's arguments and computes the return value. + /// An that can be used to configure additional return behaviours. + /// + /// This method allows the return value to be computed based on the method's arguments while automatically handling the ValueTask wrapping. + /// This is the maximum parameter count supported by these extension methods. + /// public static IReturnsResult Returns(this IReturns> mimic, Func valueFunction) { return mimic.Returns((T1 t1, T2 t2, T3 t3, T4 t4, T5 t5, T6 t6, T7 t7, T8 t8, T9 t9, T10 t10, T11 t11, T12 t12, T13 t13, T14 t14, T15 t15) => new ValueTask(valueFunction(t1, t2, t3, t4, t5, t6, t7, t8, t9, t10, t11, t12, t13, t14, t15))); diff --git a/src/Mimic/Fluent/ICallback.cs b/src/Mimic/Fluent/ICallback.cs index 07fd8ae..a13dd5a 100644 --- a/src/Mimic/Fluent/ICallback.cs +++ b/src/Mimic/Fluent/ICallback.cs @@ -1,42 +1,276 @@ namespace Mimic; +/// +/// Provides callback functionality for mock setups that do not return values. +/// This interface allows you to specify actions to execute when a mocked method is called. +/// +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it's part of the internal fluent API chain. Users typically access callback functionality +/// through method chaining on setup expressions. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface ICallback : IFluent { + /// + /// Specifies a delegate callback to execute when the mocked method is called. + /// + /// The delegate to execute. The delegate signature should match the mocked method. + /// A that allows further configuration of the mock setup. ICallbackResult Callback(Delegate callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The action to execute with no parameters. + /// A that allows further configuration of the mock setup. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The action to execute with one parameter. + /// A that allows further configuration of the mock setup. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The action to execute with two parameters. + /// A that allows further configuration of the mock setup. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The action to execute with three parameters. + /// A that allows further configuration of the mock setup. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// Additional overloads are provided to support methods with varying parameter counts (4-16 parameters). + /// + /// + /// The remaining callback overloads follow the same pattern, supporting methods with 4 to 16 parameters. + /// Each overload provides strongly-typed parameter access to the callback action. + /// ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The action to execute with five parameters. + /// A that allows further configuration of the mock setup. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The action to execute with six parameters. + /// A that allows further configuration of the mock setup. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The action to execute with seven parameters. + /// A that allows further configuration of the mock setup. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The type of the eighth parameter. + /// The action to execute with eight parameters. + /// A that allows further configuration of the mock setup. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The type of the eighth parameter. + /// The type of the ninth parameter. + /// The action to execute with nine parameters. + /// A that allows further configuration of the mock setup. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The type of the eighth parameter. + /// The type of the ninth parameter. + /// The type of the tenth parameter. + /// The action to execute with ten parameters. + /// A that allows further configuration of the mock setup. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The type of the eighth parameter. + /// The type of the ninth parameter. + /// The type of the tenth parameter. + /// The type of the eleventh parameter. + /// The action to execute with eleven parameters. + /// A that allows further configuration of the mock setup. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The type of the eighth parameter. + /// The type of the ninth parameter. + /// The type of the tenth parameter. + /// The type of the eleventh parameter. + /// The type of the twelfth parameter. + /// The action to execute with twelve parameters. + /// A that allows further configuration of the mock setup. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The type of the eighth parameter. + /// The type of the ninth parameter. + /// The type of the tenth parameter. + /// The type of the eleventh parameter. + /// The type of the twelfth parameter. + /// The type of the thirteenth parameter. + /// The action to execute with thirteen parameters. + /// A that allows further configuration of the mock setup. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The type of the eighth parameter. + /// The type of the ninth parameter. + /// The type of the tenth parameter. + /// The type of the eleventh parameter. + /// The type of the twelfth parameter. + /// The type of the thirteenth parameter. + /// The type of the fourteenth parameter. + /// The action to execute with fourteen parameters. + /// A that allows further configuration of the mock setup. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The type of the eighth parameter. + /// The type of the ninth parameter. + /// The type of the tenth parameter. + /// The type of the eleventh parameter. + /// The type of the twelfth parameter. + /// The type of the thirteenth parameter. + /// The type of the fourteenth parameter. + /// The type of the fifteenth parameter. + /// The action to execute with fifteen parameters. + /// A that allows further configuration of the mock setup. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The type of the eighth parameter. + /// The type of the ninth parameter. + /// The type of the tenth parameter. + /// The type of the eleventh parameter. + /// The type of the twelfth parameter. + /// The type of the thirteenth parameter. + /// The type of the fourteenth parameter. + /// The type of the fifteenth parameter. + /// The type of the sixteenth parameter. + /// The action to execute with sixteen parameters. + /// A that allows further configuration of the mock setup. ICallbackResult Callback(Action callback); } diff --git a/src/Mimic/Fluent/ICallbackResult.cs b/src/Mimic/Fluent/ICallbackResult.cs index 6fb976e..fc3b2d5 100644 --- a/src/Mimic/Fluent/ICallbackResult.cs +++ b/src/Mimic/Fluent/ICallbackResult.cs @@ -1,5 +1,15 @@ namespace Mimic; +/// +/// Represents the result of configuring a callback for a mock setup that does not return a value. +/// This interface combines multiple fluent interfaces to provide method chaining capabilities after a callback has been configured. +/// +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it's part of the internal fluent API chain. Users interact with this interface through method chaining +/// after calling or its overloads. +/// The interface provides access to throwing exceptions, adding delays, setting call limits, and marking setups as expected. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface ICallbackResult : IThrows, IThrowsResult, IDelayable, ILimitable, IExpected, IFluent; diff --git a/src/Mimic/Fluent/ICallbackResult`1.cs b/src/Mimic/Fluent/ICallbackResult`1.cs index 8253301..5c86c71 100644 --- a/src/Mimic/Fluent/ICallbackResult`1.cs +++ b/src/Mimic/Fluent/ICallbackResult`1.cs @@ -1,5 +1,16 @@ namespace Mimic; +/// +/// Represents the result of configuring a callback for a mock setup that returns a value of type . +/// This interface combines multiple fluent interfaces to provide method chaining capabilities after a callback has been configured. +/// +/// The type of value returned by the mocked method. +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it's part of the internal fluent API chain. Users interact with this interface through method chaining +/// after calling or its overloads. +/// The interface provides access to configuring return values, throwing exceptions, adding delays, setting call limits, and marking setups as expected. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface ICallbackResult : IReturns, IThrows, IDelayable, ILimitable, IExpected, IFluent; diff --git a/src/Mimic/Fluent/ICallback`1.cs b/src/Mimic/Fluent/ICallback`1.cs index b1ac35d..eddb66f 100644 --- a/src/Mimic/Fluent/ICallback`1.cs +++ b/src/Mimic/Fluent/ICallback`1.cs @@ -1,42 +1,277 @@ namespace Mimic; +/// +/// Provides callback functionality for mock setups that return values of type . +/// This interface allows you to specify actions to execute when a mocked method is called, while also supporting return value configuration. +/// +/// The type of value returned by the mocked method. +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it's part of the internal fluent API chain. Users typically access callback functionality +/// through method chaining on setup expressions for methods that return values. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface ICallback : IFluent { + /// + /// Specifies a delegate callback to execute when the mocked method is called. + /// + /// The delegate to execute. The delegate signature should match the mocked method. + /// A that allows further configuration of the mock setup including return value specification. ICallbackResult Callback(Delegate callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The action to execute with no parameters. + /// A that allows further configuration of the mock setup including return value specification. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The action to execute with one parameter. + /// A that allows further configuration of the mock setup including return value specification. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The action to execute with two parameters. + /// A that allows further configuration of the mock setup including return value specification. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The action to execute with three parameters. + /// A that allows further configuration of the mock setup including return value specification. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// Additional overloads are provided to support methods with varying parameter counts (4-16 parameters). + /// + /// + /// The remaining callback overloads follow the same pattern, supporting methods with 4 to 16 parameters. + /// Each overload provides strongly-typed parameter access to the callback action. + /// ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The action to execute with five parameters. + /// A that allows further configuration of the mock setup including return value specification. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The action to execute with six parameters. + /// A that allows further configuration of the mock setup including return value specification. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The action to execute with seven parameters. + /// A that allows further configuration of the mock setup including return value specification. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The type of the eighth parameter. + /// The action to execute with eight parameters. + /// A that allows further configuration of the mock setup including return value specification. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The type of the eighth parameter. + /// The type of the ninth parameter. + /// The action to execute with nine parameters. + /// A that allows further configuration of the mock setup including return value specification. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The type of the eighth parameter. + /// The type of the ninth parameter. + /// The type of the tenth parameter. + /// The action to execute with ten parameters. + /// A that allows further configuration of the mock setup including return value specification. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The type of the eighth parameter. + /// The type of the ninth parameter. + /// The type of the tenth parameter. + /// The type of the eleventh parameter. + /// The action to execute with eleven parameters. + /// A that allows further configuration of the mock setup including return value specification. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The type of the eighth parameter. + /// The type of the ninth parameter. + /// The type of the tenth parameter. + /// The type of the eleventh parameter. + /// The type of the twelfth parameter. + /// The action to execute with twelve parameters. + /// A that allows further configuration of the mock setup including return value specification. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The type of the eighth parameter. + /// The type of the ninth parameter. + /// The type of the tenth parameter. + /// The type of the eleventh parameter. + /// The type of the twelfth parameter. + /// The type of the thirteenth parameter. + /// The action to execute with thirteen parameters. + /// A that allows further configuration of the mock setup including return value specification. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The type of the eighth parameter. + /// The type of the ninth parameter. + /// The type of the tenth parameter. + /// The type of the eleventh parameter. + /// The type of the twelfth parameter. + /// The type of the thirteenth parameter. + /// The type of the fourteenth parameter. + /// The action to execute with fourteen parameters. + /// A that allows further configuration of the mock setup including return value specification. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The type of the eighth parameter. + /// The type of the ninth parameter. + /// The type of the tenth parameter. + /// The type of the eleventh parameter. + /// The type of the twelfth parameter. + /// The type of the thirteenth parameter. + /// The type of the fourteenth parameter. + /// The type of the fifteenth parameter. + /// The action to execute with fifteen parameters. + /// A that allows further configuration of the mock setup including return value specification. ICallbackResult Callback(Action callback); + /// + /// Specifies an action callback to execute when the mocked method is called. + /// + /// The type of the first parameter. + /// The type of the second parameter. + /// The type of the third parameter. + /// The type of the fourth parameter. + /// The type of the fifth parameter. + /// The type of the sixth parameter. + /// The type of the seventh parameter. + /// The type of the eighth parameter. + /// The type of the ninth parameter. + /// The type of the tenth parameter. + /// The type of the eleventh parameter. + /// The type of the twelfth parameter. + /// The type of the thirteenth parameter. + /// The type of the fourteenth parameter. + /// The type of the fifteenth parameter. + /// The type of the sixteenth parameter. + /// The action to execute with sixteen parameters. + /// A that allows further configuration of the mock setup including return value specification. ICallbackResult Callback(Action callback); } diff --git a/src/Mimic/Fluent/IConditionalSetup`1.cs b/src/Mimic/Fluent/IConditionalSetup`1.cs index ffab34c..d80b59b 100644 --- a/src/Mimic/Fluent/IConditionalSetup`1.cs +++ b/src/Mimic/Fluent/IConditionalSetup`1.cs @@ -1,17 +1,55 @@ namespace Mimic; +/// +/// Provides conditional setup functionality for configuring mock behaviour based on specific conditions. +/// This interface allows you to set up method calls, property getters, and property setters when certain conditions are met. +/// +/// The type being mocked. Must be a reference type. +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it's part of the internal fluent API chain. Users typically access conditional setup functionality +/// through method chaining after specifying conditions on the mock. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface IConditionalSetup where TMimic : class { + /// + /// Sets up a mock method or property setter that does not return a value. + /// + /// An expression that specifies the method or property setter to set up. + /// A that allows further configuration of the mock behavior. ISetup Setup(Expression> expression); + /// + /// Sets up a mock method or property getter that returns a value of type . + /// + /// The type of value returned by the method or property. + /// An expression that specifies the method or property getter to set up. + /// A that allows further configuration of the mock behaviour including return values. ISetup Setup(Expression> expression); + /// + /// Sets up a mock property getter specifically. + /// + /// The type of the property. + /// An expression that specifies the property getter to set up. + /// A that allows configuration specific to property getters. IGetterSetup SetupGet(Expression> expression); + /// + /// Sets up a mock property setter without specifying the property type. + /// + /// An action that specifies the property setter to set up. + /// A that allows further configuration of the mock behaviour. ISetup SetupSet(Action setterExpression); + /// + /// Sets up a mock property setter with a specific property type. + /// + /// The type of the property being set. + /// An action that specifies the property setter to set up. + /// A that allows configuration specific to property setters. ISetterSetup SetupSet(Action setterExpression); } diff --git a/src/Mimic/Fluent/IDelayable.cs b/src/Mimic/Fluent/IDelayable.cs index 5fbadf7..4e7cee4 100644 --- a/src/Mimic/Fluent/IDelayable.cs +++ b/src/Mimic/Fluent/IDelayable.cs @@ -1,10 +1,33 @@ namespace Mimic; +/// +/// Provides delay functionality for mock setups, allowing you to introduce timing delays before method execution or return values. +/// This interface enables realistic timing behavior in mock scenarios by adding configurable delays. +/// +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it's part of the internal fluent API chain. Users typically access delay functionality +/// through method chaining on setup expressions. Delays can be fixed or dynamic based on call count. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface IDelayable : IFluent { + /// + /// Adds a fixed delay before the mocked method execution completes. + /// + /// The amount of time to delay before completing the method call. + /// A that allows further configuration of the mock setup. IDelayableResult WithDelay(TimeSpan delay); + /// + /// Adds a dynamic delay before the mocked method execution completes, based on the call count. + /// + /// A function that takes the call count (starting from 0) and returns the delay duration for that call. + /// A that allows further configuration of the mock setup. + /// + /// The delay function receives the zero-based call count, allowing for different delays based on how many times the method has been called. + /// This enables scenarios like simulating increasing latency or timeout patterns. + /// IDelayableResult WithDelay(Func delayFunction); } diff --git a/src/Mimic/Fluent/IDelayableResult.cs b/src/Mimic/Fluent/IDelayableResult.cs index 8d9a08d..41def6f 100644 --- a/src/Mimic/Fluent/IDelayableResult.cs +++ b/src/Mimic/Fluent/IDelayableResult.cs @@ -1,5 +1,15 @@ namespace Mimic; +/// +/// Represents the result of configuring a delay for a mock setup. +/// This interface combines multiple fluent interfaces to provide method chaining capabilities after a delay has been configured. +/// +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it's part of the internal fluent API chain. Users interact with this interface through method chaining +/// after calling or its overloads. +/// The interface provides access to setting call limits and marking setups as expected. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface IDelayableResult : ILimitable, IExpected, IFluent; diff --git a/src/Mimic/Fluent/IExpected.cs b/src/Mimic/Fluent/IExpected.cs index ac75b76..e020853 100644 --- a/src/Mimic/Fluent/IExpected.cs +++ b/src/Mimic/Fluent/IExpected.cs @@ -1,8 +1,26 @@ namespace Mimic; +/// +/// Provides functionality to mark a mock setup as expected, indicating that the setup must be called during testing. +/// This interface is used to enforce verification that certain mock behaviours are actually invoked. +/// +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it's part of the internal fluent API chain. Users typically access expected functionality +/// through method chaining on setup expressions. Marking a setup as expected means verification will fail +/// if the setup is not called during test execution. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface IExpected : IFluent { + /// + /// Marks this mock setup as expected, meaning it must be called during testing for verification to pass. + /// + /// + /// When a setup is marked as expected, the mock framework will track whether this particular setup + /// was invoked during test execution. If verification is performed and an expected setup was not called, + /// the verification will fail. This is useful for ensuring that critical code paths are executed. + /// void Expected(); } diff --git a/src/Mimic/Fluent/IFluent.cs b/src/Mimic/Fluent/IFluent.cs index b2e1a2f..9f8992c 100644 --- a/src/Mimic/Fluent/IFluent.cs +++ b/src/Mimic/Fluent/IFluent.cs @@ -1,5 +1,16 @@ namespace Mimic; +/// +/// Base interface for all fluent API interfaces in the Mimic library. +/// This interface provides a clean fluent interface experience by hiding common Object methods from IntelliSense. +/// +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it serves as the foundation for the fluent API chain. It explicitly declares and hides common Object methods +/// (GetType, GetHashCode, ToString, Equals) to prevent them from appearing in IntelliSense when using the fluent API, +/// providing a cleaner development experience focused on the actual mock configuration methods. +/// All other fluent interfaces in the library inherit from this interface. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface IFluent diff --git a/src/Mimic/Fluent/IGetterCallbackResult`1.cs b/src/Mimic/Fluent/IGetterCallbackResult`1.cs index eebfe3c..f9c791c 100644 --- a/src/Mimic/Fluent/IGetterCallbackResult`1.cs +++ b/src/Mimic/Fluent/IGetterCallbackResult`1.cs @@ -1,5 +1,16 @@ namespace Mimic; +/// +/// Represents the result of configuring a callback for a property getter mock setup. +/// This interface combines multiple fluent interfaces to provide method chaining capabilities after a getter callback has been configured. +/// +/// The type of the property being mocked. +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it's part of the internal fluent API chain. Users interact with this interface through method chaining +/// after calling . +/// The interface provides access to configuring return values, throwing exceptions, adding delays, setting call limits, and marking setups as expected. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface IGetterCallbackResult : IGetterReturns, IThrows, IDelayable, ILimitable, IExpected, IFluent; diff --git a/src/Mimic/Fluent/IGetterCallback`1.cs b/src/Mimic/Fluent/IGetterCallback`1.cs index afa271f..5dec2b2 100644 --- a/src/Mimic/Fluent/IGetterCallback`1.cs +++ b/src/Mimic/Fluent/IGetterCallback`1.cs @@ -1,8 +1,23 @@ namespace Mimic; +/// +/// Provides callback functionality for property getter mock setups. +/// This interface allows you to specify actions to execute when a mocked property getter is accessed. +/// +/// The type of the property being mocked. +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it's part of the internal fluent API chain. Users typically access this functionality +/// through method chaining on property getter setup expressions. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface IGetterCallback : IFluent { + /// + /// Specifies an action callback to execute when the mocked property getter is accessed. + /// + /// The action to execute when the property getter is called. + /// A that allows further configuration of the property getter setup. IGetterCallbackResult Callback(Action callback); } diff --git a/src/Mimic/Fluent/IGetterReturns`1.cs b/src/Mimic/Fluent/IGetterReturns`1.cs index aa3528a..bc0dd93 100644 --- a/src/Mimic/Fluent/IGetterReturns`1.cs +++ b/src/Mimic/Fluent/IGetterReturns`1.cs @@ -1,10 +1,33 @@ namespace Mimic; +/// +/// Provides return value configuration functionality for property getter mock setups. +/// This interface allows you to specify what value should be returned when a mocked property getter is accessed. +/// +/// The type of the property being mocked. +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it's part of the internal fluent API chain. Users typically access this functionality +/// through method chaining on property getter setup expressions. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface IGetterReturns : IFluent { + /// + /// Specifies the value to return when the mocked property getter is accessed. + /// + /// The value to return when the property getter is called. + /// A that allows further configuration of the mock setup. IReturnsResult Returns(TProperty? value); + /// + /// Specifies a function to compute the value to return when the mocked property getter is accessed. + /// + /// A function that computes the value to return when the property getter is called. + /// A that allows further configuration of the mock setup. + /// + /// The function is executed each time the property getter is accessed, allowing for dynamic value computation. + /// IReturnsResult Returns(Func valueFunction); } diff --git a/src/Mimic/Fluent/IGetterSetup`2.cs b/src/Mimic/Fluent/IGetterSetup`2.cs index 4f3d7bf..fb54f0a 100644 --- a/src/Mimic/Fluent/IGetterSetup`2.cs +++ b/src/Mimic/Fluent/IGetterSetup`2.cs @@ -1,5 +1,17 @@ namespace Mimic; +/// +/// Provides comprehensive setup functionality for property getter mock configurations. +/// This interface combines all available property getter configuration options including callbacks, return values, exceptions, delays, call limits, and expectations. +/// +/// The type being mocked. +/// The type of the property being mocked. +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it's part of the internal fluent API chain. Users typically access this interface through method chaining +/// after calling property getter setup methods. This interface serves as the main entry point for configuring +/// property getter behavior, combining all available configuration options into a single fluent interface. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface IGetterSetup : IGetterCallback, IGetterReturns, IThrows, IDelayable, ILimitable, IExpected, IFluent; diff --git a/src/Mimic/Fluent/ILimitable.cs b/src/Mimic/Fluent/ILimitable.cs index 01b3ffd..6e42be0 100644 --- a/src/Mimic/Fluent/ILimitable.cs +++ b/src/Mimic/Fluent/ILimitable.cs @@ -1,8 +1,28 @@ namespace Mimic; +/// +/// Provides functionality to limit the number of times a mock setup can be executed. +/// This interface allows you to specify execution constraints on mock behaviors for precise control over call expectations. +/// +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it's part of the internal fluent API chain. Users typically access limit functionality +/// through method chaining on setup expressions. Setting execution limits helps ensure that mocked +/// methods are called the expected number of times during testing. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface ILimitable : IFluent { + /// + /// Sets the maximum number of times this mock setup can be executed. + /// + /// The maximum number of times the setup can be executed. Default is 1. + /// An that allows marking the setup as expected for verification. + /// + /// When a setup reaches its execution limit, subsequent calls will not match this setup and may result + /// in different behavior depending on the mock's configuration. This is useful for testing scenarios + /// where you want to ensure a method is called a specific number of times. + /// IExpected Limit(int executionLimit = 1); } diff --git a/src/Mimic/Fluent/IProceed.cs b/src/Mimic/Fluent/IProceed.cs index f6d10a9..30496fd 100644 --- a/src/Mimic/Fluent/IProceed.cs +++ b/src/Mimic/Fluent/IProceed.cs @@ -1,8 +1,41 @@ namespace Mimic; +/// +/// Provides functionality to allow the original method implementation to execute while maintaining the mock setup. +/// This interface enables scenarios where you want to combine real method execution with mock behaviors. +/// +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it serves as part of the fluent API chain. It allows the setup to proceed with the original method +/// implementation, which is useful for: +/// +/// Partial mocking - Where some methods are mocked and others execute normally +/// Spy scenarios - Where you want to observe method calls while preserving functionality +/// Decorator patterns - Where you want to add behavior before/after real method execution +/// +/// When is called, the original method implementation will be invoked with the provided arguments, +/// and any return value will be preserved. This can be combined with other mock behaviors like callbacks or verification. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface IProceed : IFluent { + /// + /// Configures the setup to proceed with the original method implementation. + /// When the mocked method is called, it will execute the actual method implementation. + /// + /// + /// A instance that allows for further configuration + /// such as exception throwing behavior after the original method executes. + /// + /// + /// This method enables the original method implementation to be called, making it useful for: + /// + /// Testing wrapper classes where you want to verify the wrapper logic but preserve the wrapped functionality + /// Implementing spy patterns where you observe method calls without changing behavior + /// Partial mocking scenarios where only specific methods are overridden + /// + /// The returned interface allows you to configure additional behaviors that occur after the original method executes. + /// IProceedResult Proceed(); } diff --git a/src/Mimic/Fluent/IProceedResult.cs b/src/Mimic/Fluent/IProceedResult.cs index bdfbb61..77c75c3 100644 --- a/src/Mimic/Fluent/IProceedResult.cs +++ b/src/Mimic/Fluent/IProceedResult.cs @@ -1,5 +1,23 @@ namespace Mimic; +/// +/// Represents the result interface after configuring a method setup to proceed with its original implementation. +/// This interface provides limited additional configuration options for scenarios that combine real method execution with mock behaviors. +/// +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it serves as part of the fluent API chain. It inherits from exception throwing interfaces to provide +/// the ability to conditionally throw exceptions even when proceeding with the original implementation: +/// +/// - For configuring exception throwing behavior that can override the proceed behavior +/// - Provides the result interface capabilities after exception configuration +/// +/// This interface is typically reached after calling on a setup. +/// It provides a more limited set of configuration options compared to other result interfaces because +/// the method execution is delegated to the original implementation. +/// Note that return value configuration, callbacks, and delays are not available since the behavior +/// is determined by the original method implementation. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface IProceedResult : IThrows, IThrowsResult, IFluent; diff --git a/src/Mimic/Fluent/IReturnsResult.cs b/src/Mimic/Fluent/IReturnsResult.cs index ec80cf5..5d9f1e2 100644 --- a/src/Mimic/Fluent/IReturnsResult.cs +++ b/src/Mimic/Fluent/IReturnsResult.cs @@ -1,5 +1,23 @@ namespace Mimic; +/// +/// Represents the result interface after configuring a return value in a mimic setup. +/// This interface provides additional configuration options that can be applied after defining what a method should return. +/// +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it serves as part of the fluent API chain. It inherits from multiple interfaces to provide +/// additional configuration capabilities after a return value has been specified: +/// +/// - For defining callback actions when the method is invoked +/// - For introducing delays before method execution +/// - For limiting the number of times the setup can be matched +/// - For defining verification expectations +/// +/// This interface is typically reached after calling a Returns method on a setup, allowing you to +/// further customize the behavior with callbacks, delays, occurrence limits, or verification requirements. +/// It serves as the continuation point in the fluent API chain for return-value-configured setups. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface IReturnsResult : ICallback, IDelayable, ILimitable, IExpected, IFluent; diff --git a/src/Mimic/Fluent/IReturns`1.cs b/src/Mimic/Fluent/IReturns`1.cs index 4c9b8be..e32e588 100644 --- a/src/Mimic/Fluent/IReturns`1.cs +++ b/src/Mimic/Fluent/IReturns`1.cs @@ -1,5 +1,18 @@ namespace Mimic; +/// +/// Provides functionality to configure return values for methods in a mimic setup. +/// This is a simplified version of that returns . +/// +/// The type of value that the configured method should return. +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it serves as part of the fluent API chain. It inherits from +/// with as the continuation type, providing a simplified interface for +/// return value configuration where the next step in the fluent chain is predetermined. +/// This interface is typically used in setups where return value configuration is the primary concern, +/// and the user doesn't need access to additional configuration options. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface IReturns : IReturns; diff --git a/src/Mimic/Fluent/IReturns`2.cs b/src/Mimic/Fluent/IReturns`2.cs index c3672c2..2d1eb75 100644 --- a/src/Mimic/Fluent/IReturns`2.cs +++ b/src/Mimic/Fluent/IReturns`2.cs @@ -1,45 +1,300 @@ namespace Mimic; +/// +/// Provides comprehensive functionality to configure return values for methods in a mimic setup with fluent continuation. +/// This interface supports both direct value returns and computed returns using function delegates with various parameter counts. +/// +/// The type of value that the configured method should return. +/// The type of the next interface in the fluent chain, which must implement . +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it serves as part of the fluent API chain. It provides extensive overloads for return value configuration: +/// +/// Direct value returns - Returns a specific value +/// Computed returns - Uses functions to compute return values based on method arguments +/// Parameterless functions - Returns values computed without method arguments +/// Parameterized functions - Returns values computed using method arguments (up to 16 parameters) +/// Proceed functionality - Allows the original method to execute and return its result +/// +/// The function-based overloads support up to 16 parameters, covering virtually all practical method signatures. +/// Each method returns to continue the fluent API chain. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface IReturns : IFluent where TNext : IFluent { + /// + /// Configures the setup to return a specific value. + /// + /// The value to return when the method is called. Can be null. + /// The next interface in the fluent chain for further configuration. TNext Returns(TResult? value); + /// + /// Configures the setup to return a value computed by a function. + /// + /// A function that computes the return value. Can return null. + /// The next interface in the fluent chain for further configuration. TNext Returns(Func valueFunction); + /// + /// Configures the setup to return a value computed by a function that takes one method argument. + /// + /// The type of the method argument. + /// A function that takes the method argument and computes the return value. + /// The next interface in the fluent chain for further configuration. TNext Returns(Func valueFunction); + /// + /// Configures the setup to return a value computed by a function that takes two method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// A function that takes the method arguments and computes the return value. + /// The next interface in the fluent chain for further configuration. TNext Returns(Func valueFunction); + /// + /// Configures the setup to return a value computed by a function that takes three method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// A function that takes the method arguments and computes the return value. + /// The next interface in the fluent chain for further configuration. TNext Returns(Func valueFunction); + /// + /// Configures the setup to return a value computed by a function that takes four method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// A function that takes the method arguments and computes the return value. + /// The next interface in the fluent chain for further configuration. TNext Returns(Func valueFunction); + /// + /// Configures the setup to return a value computed by a function that takes five method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// A function that takes the method arguments and computes the return value. + /// The next interface in the fluent chain for further configuration. TNext Returns(Func valueFunction); + /// + /// Configures the setup to return a value computed by a function that takes six method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// A function that takes the method arguments and computes the return value. + /// The next interface in the fluent chain for further configuration. TNext Returns(Func valueFunction); + /// + /// Configures the setup to return a value computed by a function that takes seven method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// A function that takes the method arguments and computes the return value. + /// The next interface in the fluent chain for further configuration. TNext Returns(Func valueFunction); + /// + /// Configures the setup to return a value computed by a function that takes eight method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of the eighth method argument. + /// A function that takes the method arguments and computes the return value. + /// The next interface in the fluent chain for further configuration. TNext Returns(Func valueFunction); + /// + /// Configures the setup to return a value computed by a function that takes nine method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of the eighth method argument. + /// The type of the ninth method argument. + /// A function that takes the method arguments and computes the return value. + /// The next interface in the fluent chain for further configuration. TNext Returns(Func valueFunction); + /// + /// Configures the setup to return a value computed by a function that takes ten method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of the eighth method argument. + /// The type of the ninth method argument. + /// The type of the tenth method argument. + /// A function that takes the method arguments and computes the return value. + /// The next interface in the fluent chain for further configuration. TNext Returns(Func valueFunction); + /// + /// Configures the setup to return a value computed by a function that takes eleven method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of the eighth method argument. + /// The type of the ninth method argument. + /// The type of the tenth method argument. + /// The type of the eleventh method argument. + /// A function that takes the method arguments and computes the return value. + /// The next interface in the fluent chain for further configuration. TNext Returns(Func valueFunction); + /// + /// Configures the setup to return a value computed by a function that takes twelve method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of the eighth method argument. + /// The type of the ninth method argument. + /// The type of the tenth method argument. + /// The type of the eleventh method argument. + /// The type of the twelfth method argument. + /// A function that takes the method arguments and computes the return value. + /// The next interface in the fluent chain for further configuration. TNext Returns(Func valueFunction); + /// + /// Configures the setup to return a value computed by a function that takes thirteen method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of the eighth method argument. + /// The type of the ninth method argument. + /// The type of the tenth method argument. + /// The type of the eleventh method argument. + /// The type of the twelfth method argument. + /// The type of the thirteenth method argument. + /// A function that takes the method arguments and computes the return value. + /// The next interface in the fluent chain for further configuration. TNext Returns(Func valueFunction); + /// + /// Configures the setup to return a value computed by a function that takes fourteen method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of the eighth method argument. + /// The type of the ninth method argument. + /// The type of the tenth method argument. + /// The type of the eleventh method argument. + /// The type of the twelfth method argument. + /// The type of the thirteenth method argument. + /// The type of the fourteenth method argument. + /// A function that takes the method arguments and computes the return value. + /// The next interface in the fluent chain for further configuration. TNext Returns(Func valueFunction); + /// + /// Configures the setup to return a value computed by a function that takes fifteen method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of the eighth method argument. + /// The type of the ninth method argument. + /// The type of the tenth method argument. + /// The type of the eleventh method argument. + /// The type of the twelfth method argument. + /// The type of the thirteenth method argument. + /// The type of the fourteenth method argument. + /// The type of the fifteenth method argument. + /// A function that takes the method arguments and computes the return value. + /// The next interface in the fluent chain for further configuration. TNext Returns(Func valueFunction); + /// + /// Configures the setup to return a value computed by a function that takes sixteen method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of the eighth method argument. + /// The type of the ninth method argument. + /// The type of the tenth method argument. + /// The type of the eleventh method argument. + /// The type of the twelfth method argument. + /// The type of the thirteenth method argument. + /// The type of the fourteenth method argument. + /// The type of the fifteenth method argument. + /// The type of the sixteenth method argument. + /// A function that takes the method arguments and computes the return value. + /// The next interface in the fluent chain for further configuration. TNext Returns(Func valueFunction); + /// + /// Configures the setup to proceed with the original method implementation and return its result. + /// This allows the real method to execute while still maintaining the mock setup. + /// + /// The next interface in the fluent chain for further configuration. + /// + /// This is useful when you want to combine real method execution with mock behaviors such as + /// callbacks, delays, or verification. The original method will be called and its return value + /// will be used as the result. + /// TNext Proceed(); } diff --git a/src/Mimic/Fluent/ISequenceDelayable.cs b/src/Mimic/Fluent/ISequenceDelayable.cs index baa4d1f..496696e 100644 --- a/src/Mimic/Fluent/ISequenceDelayable.cs +++ b/src/Mimic/Fluent/ISequenceDelayable.cs @@ -1,10 +1,53 @@ namespace Mimic; +/// +/// Provides functionality to configure delays for sequence setups, allowing different delay behaviors for each step in the sequence. +/// This interface enables time-based behavior control in sequential mock setups. +/// +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it serves as part of the fluent API chain for sequence setups. It provides delay configuration +/// capabilities specifically designed for sequential behaviors where different steps in the sequence +/// may require different delay characteristics: +/// +/// Fixed delays - Each step in the sequence uses the same delay duration +/// Progressive delays - Each step in the sequence can have a different delay based on its position +/// +/// This interface is used within sequence setups to control timing between different behaviors +/// that are executed on consecutive method calls. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface ISequenceDelayable : IFluent { + /// + /// Configures the current step in the sequence to introduce a fixed delay before execution. + /// + /// The amount of time to delay before the method executes. + /// An instance for further configuration of the sequence step. + /// + /// This delay will be applied to the current step in the sequence. Each time this step + /// is reached during sequential execution, the same delay will be applied. + /// IExpected WithDelay(TimeSpan delay); + /// + /// Configures the current step in the sequence to introduce a dynamic delay before execution, + /// where the delay duration can vary based on the sequence position. + /// + /// + /// A function that takes the current sequence position (0-based) and returns the delay duration. + /// This allows for progressive or custom delay patterns across the sequence. + /// + /// An instance for further configuration of the sequence step. + /// + /// The delay function receives the current position in the sequence (starting from 0) and can return + /// different delay values for each step. This is useful for implementing patterns like: + /// + /// Progressive delays (increasing delay with each step) + /// Exponential backoff patterns + /// Custom timing sequences based on business logic + /// + /// IExpected WithDelay(Func delayFunction); } diff --git a/src/Mimic/Fluent/ISequenceSetup.cs b/src/Mimic/Fluent/ISequenceSetup.cs index 2ca990c..9eada7b 100644 --- a/src/Mimic/Fluent/ISequenceSetup.cs +++ b/src/Mimic/Fluent/ISequenceSetup.cs @@ -1,10 +1,55 @@ namespace Mimic; +/// +/// Provides functionality to configure sequential behaviors for void methods in a mimic setup. +/// This interface allows defining different behaviors that will be executed in order on consecutive method calls. +/// +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it serves as part of the fluent API chain for sequence setups. It inherits from multiple interfaces +/// to provide comprehensive sequential configuration options: +/// +/// - For configuring exception throwing that continues the sequence +/// - For configuring delays in the sequence execution +/// - For defining verification expectations on sequence steps +/// +/// Sequential setups are useful when you need different behaviors for consecutive calls to the same void method. +/// Each call advances to the next step in the sequence. Once all steps are exhausted, subsequent calls +/// will repeat the last configured behavior. +/// This interface is specifically for void methods and doesn't provide return value configuration. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface ISequenceSetup : IThrows, ISequenceDelayable, IExpected, IFluent { + /// + /// Configures the current step in the sequence to proceed with the original method implementation, + /// then continues to allow configuration of the next step. + /// + /// + /// The same instance to continue configuring the sequence + /// or move to the next step using . + /// + /// + /// This method allows the real method implementation to execute for this step in the sequence. + /// After the original method executes, the sequence can continue with additional configuration + /// or advance to the next step. This is useful for partial mocking scenarios where some + /// calls should execute normally while others have mocked behavior. + /// ISequenceSetup Proceed(); + /// + /// Advances to the next step in the sequence, allowing configuration of the behavior + /// for the subsequent method call. + /// + /// + /// The same instance configured for the next step in the sequence. + /// + /// + /// This method moves the sequence configuration to the next step. The behavior configured + /// after calling this method will be applied to the next method call in the sequence. + /// You can continue chaining additional configuration methods or call again + /// to configure further steps in the sequence. + /// ISequenceSetup Next(); } diff --git a/src/Mimic/Fluent/ISequenceSetup`1.cs b/src/Mimic/Fluent/ISequenceSetup`1.cs index 4ae01af..ab39ca9 100644 --- a/src/Mimic/Fluent/ISequenceSetup`1.cs +++ b/src/Mimic/Fluent/ISequenceSetup`1.cs @@ -1,5 +1,26 @@ namespace Mimic; +/// +/// Provides functionality to configure sequential behaviors for methods that return values in a mimic setup. +/// This interface allows defining different return values and behaviors that will be executed in order on consecutive method calls. +/// +/// The type of value returned by the method being configured in the sequence. +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it serves as part of the fluent API chain for sequence setups. It inherits from multiple interfaces +/// to provide comprehensive sequential configuration options for return-value methods: +/// +/// - For configuring return values with sequence continuation +/// - For configuring exception throwing that continues the sequence +/// - For configuring delays in the sequence execution +/// - For defining verification expectations on sequence steps +/// +/// Sequential setups are useful when you need different return values or behaviors for consecutive calls +/// to the same method. Each call advances to the next step in the sequence. Once all steps are exhausted, +/// subsequent calls will repeat the last configured behavior. +/// This interface is specifically for methods that return values and provides full return value configuration +/// capabilities for each step in the sequence. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface ISequenceSetup : IReturns>, IThrows>, ISequenceDelayable, IExpected, IFluent; diff --git a/src/Mimic/Fluent/ISetterCallback`1.cs b/src/Mimic/Fluent/ISetterCallback`1.cs index 0577a75..9cd236e 100644 --- a/src/Mimic/Fluent/ISetterCallback`1.cs +++ b/src/Mimic/Fluent/ISetterCallback`1.cs @@ -1,8 +1,49 @@ namespace Mimic; +/// +/// Provides callback functionality specifically for property setter configurations in a mimic setup. +/// This interface allows defining actions that will be executed when a property setter is invoked. +/// +/// The type of the property being set. +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it serves as part of the fluent API chain for property setter setups. It inherits from multiple interfaces +/// to provide comprehensive configuration options for property setter scenarios: +/// +/// - For introducing delays before the setter executes +/// - For limiting the number of times the setup can be matched +/// - For defining verification expectations +/// +/// This interface is specifically designed for property setter operations and provides access to +/// the value being assigned to the property through callback mechanisms. It's typically used when +/// you need to observe or react to property value changes in a controlled testing environment. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface ISetterCallback : IDelayable, ILimitable, IExpected, IFluent { + /// + /// Configures a callback action that will be executed when the property setter is invoked. + /// The callback receives the value being assigned to the property. + /// + /// + /// An action that will be called when the property setter is invoked. + /// The action receives the value being assigned to the property as its parameter. + /// + /// + /// A instance that allows for further configuration + /// after the callback has been defined. + /// + /// + /// This method allows you to define custom behavior that executes when a property is set. + /// The callback has access to the value being assigned, enabling scenarios such as: + /// + /// Validation of property values during testing + /// Logging or auditing property changes + /// Triggering side effects based on property values + /// Capturing property values for later assertion + /// + /// The callback is executed synchronously as part of the property setter operation. + /// ICallbackResult Callback(Action callback); } diff --git a/src/Mimic/Fluent/ISetterSetup`2.cs b/src/Mimic/Fluent/ISetterSetup`2.cs index 3a87757..cf72491 100644 --- a/src/Mimic/Fluent/ISetterSetup`2.cs +++ b/src/Mimic/Fluent/ISetterSetup`2.cs @@ -1,5 +1,26 @@ namespace Mimic; +/// +/// Defines the setup interface for configuring expectations on property setters of a mimic object. +/// This interface provides comprehensive configuration options for property setter operations. +/// +/// The type of the mimic object being configured. +/// The type of the property being set. +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it serves as part of the fluent API chain for property setter setups. It inherits from multiple interfaces +/// to provide comprehensive configuration options specifically tailored for property setter scenarios: +/// +/// - For defining callback actions when the property setter is invoked +/// - For introducing delays before the setter executes +/// - For limiting the number of times the setup can be matched +/// - For defining verification expectations +/// +/// This interface is typically reached when setting up expectations for property setters using expressions +/// like SetupSet(() => obj.Property = value). It provides specialised functionality for property +/// setting scenarios where you need to observe, validate, or control the assignment of property values. +/// Unlike method setups, property setter setups focus on the value being assigned rather than method parameters. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface ISetterSetup : ISetterCallback, IDelayable, ILimitable, IExpected, IFluent diff --git a/src/Mimic/Fluent/ISetup`1.cs b/src/Mimic/Fluent/ISetup`1.cs index 841b424..fba4ddc 100644 --- a/src/Mimic/Fluent/ISetup`1.cs +++ b/src/Mimic/Fluent/ISetup`1.cs @@ -1,9 +1,42 @@ namespace Mimic; +/// +/// Defines the setup interface for configuring expectations on void methods and property setters of a mimic object. +/// This interface provides the entry point for setting up method call expectations that do not return values. +/// +/// The type of the mimic object being configured. +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it serves as part of the fluent API chain. It inherits from multiple interfaces to provide +/// comprehensive configuration options: +/// +/// - For defining callback actions when the method is invoked +/// - For allowing the original method implementation to execute +/// - For configuring exception throwing behavior +/// - For introducing delays before method execution +/// - For limiting the number of times the setup can be matched +/// - For defining verification expectations +/// +/// This interface is typically used when setting up expectations for void methods, property setters, +/// or other operations that do not return values. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface ISetup : ICallback, IProceed, IThrows, IDelayable, ILimitable, IExpected, IFluent where TMimic : class { + /// + /// Converts this setup into a sequence setup, allowing for ordered configuration of multiple behaviors + /// that will be executed in sequence on subsequent method calls. + /// + /// + /// A instance that allows configuring behaviors to be executed + /// in sequence for consecutive method calls. + /// + /// + /// Sequential setups are useful when you need different behaviors for consecutive calls to the same method. + /// Each call to the method will advance to the next configured behavior in the sequence. + /// Once all behaviors in the sequence have been used, subsequent calls will use the last behavior. + /// ISequenceSetup AsSequence(); } diff --git a/src/Mimic/Fluent/ISetup`2.cs b/src/Mimic/Fluent/ISetup`2.cs index 7034ed6..63ad912 100644 --- a/src/Mimic/Fluent/ISetup`2.cs +++ b/src/Mimic/Fluent/ISetup`2.cs @@ -1,9 +1,43 @@ namespace Mimic; +/// +/// Defines the setup interface for configuring expectations on methods that return values of type . +/// This interface provides the entry point for setting up method call expectations and configuring return behaviors. +/// +/// The type of the mimic object being configured. +/// The type of value returned by the method being configured. +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it serves as part of the fluent API chain. It inherits from multiple interfaces to provide +/// comprehensive configuration options: +/// +/// - For defining callback actions with access to the return value +/// - For configuring what value the method should return +/// - For introducing delays before method execution +/// - For limiting the number of times the setup can be matched +/// - For configuring exception throwing behavior +/// - For defining verification expectations +/// +/// This interface is typically used when setting up expectations for methods, properties, or indexers +/// that return values, allowing you to define both the return behavior and additional actions. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface ISetup : ICallback, IReturns, IDelayable, ILimitable, IThrows, IExpected, IFluent where TMimic : class { + /// + /// Converts this setup into a sequence setup, allowing for ordered configuration of multiple behaviors + /// that will be executed in sequence on subsequent method calls. + /// + /// + /// A instance that allows configuring behaviors to be executed + /// in sequence for consecutive method calls, with support for different return values. + /// + /// + /// Sequential setups are useful when you need different return values or behaviors for consecutive calls + /// to the same method. Each call to the method will advance to the next configured behavior in the sequence. + /// Once all behaviors in the sequence have been used, subsequent calls will use the last behavior. + /// ISequenceSetup AsSequence(); } diff --git a/src/Mimic/Fluent/IThrows.cs b/src/Mimic/Fluent/IThrows.cs index aeb31f2..3c7b2fe 100644 --- a/src/Mimic/Fluent/IThrows.cs +++ b/src/Mimic/Fluent/IThrows.cs @@ -1,5 +1,17 @@ namespace Mimic; +/// +/// Provides functionality to configure exception throwing behavior for methods in a mimic setup. +/// This is a simplified version of that returns . +/// +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it serves as part of the fluent API chain. It inherits from +/// with as the continuation type, providing a simplified interface for +/// exception throwing configuration where the next step in the fluent chain is predetermined. +/// This interface is typically used in setups where exception throwing configuration is the primary concern, +/// and the user doesn't need access to additional configuration options. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface IThrows : IThrows; diff --git a/src/Mimic/Fluent/IThrowsResult.cs b/src/Mimic/Fluent/IThrowsResult.cs index 4c25e79..397aeed 100644 --- a/src/Mimic/Fluent/IThrowsResult.cs +++ b/src/Mimic/Fluent/IThrowsResult.cs @@ -1,5 +1,24 @@ namespace Mimic; +/// +/// Represents the result interface after configuring exception throwing behavior in a mimic setup. +/// This interface provides additional configuration options that can be applied after defining what exception a method should throw. +/// +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it serves as part of the fluent API chain. It inherits from multiple interfaces to provide +/// additional configuration capabilities after an exception throwing behavior has been specified: +/// +/// - For introducing delays before method execution +/// - For limiting the number of times the setup can be matched +/// - For defining verification expectations +/// +/// This interface is typically reached after calling a Throws method on a setup, allowing you to +/// further customize the behavior with delays, occurrence limits, or verification requirements. +/// It serves as the continuation point in the fluent API chain for exception-throwing-configured setups. +/// Note that callback functionality is not available for exception-throwing setups, as the method +/// execution is terminated by the exception. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface IThrowsResult : IDelayable, ILimitable, IExpected, IFluent; diff --git a/src/Mimic/Fluent/IThrows`1.cs b/src/Mimic/Fluent/IThrows`1.cs index cec34f4..95c8161 100644 --- a/src/Mimic/Fluent/IThrows`1.cs +++ b/src/Mimic/Fluent/IThrows`1.cs @@ -1,64 +1,335 @@ namespace Mimic; +/// +/// Provides comprehensive functionality to configure exception throwing behavior for methods in a mimic setup with fluent continuation. +/// This interface supports various ways to throw exceptions including direct exception instances and factory functions with different parameter counts. +/// +/// The type of the next interface in the fluent chain, which must implement . +/// +/// This interface is marked with to hide it from IntelliSense, +/// as it serves as part of the fluent API chain. It provides extensive overloads for exception throwing configuration: +/// +/// Direct exception throwing - Throws a specific exception instance +/// Generic exception creation - Creates exceptions using parameterless constructors +/// Generic delegate factories - Creates exceptions using delegate factories +/// Parameterized factories - Creates exceptions using method arguments (up to 16 parameters) +/// +/// The function-based overloads support up to 16 parameters, covering virtually all practical method signatures. +/// Each method returns to continue the fluent API chain. +/// All exception factory methods are constrained to ensure only valid types are used. +/// [PublicAPI] [EditorBrowsable(EditorBrowsableState.Never)] public interface IThrows : IFluent where TNext : IFluent { + /// + /// Configures the setup to throw a specific exception instance. + /// + /// The exception instance to throw when the method is called. + /// The next interface in the fluent chain for further configuration. TNext Throws(Exception exception); + /// + /// Configures the setup to throw a new instance of the specified exception type using its parameterless constructor. + /// + /// The type of exception to throw. Must inherit from and have a parameterless constructor. + /// The next interface in the fluent chain for further configuration. TNext Throws() where TException : Exception, new(); + /// + /// Configures the setup to throw an exception created by a delegate factory. + /// + /// A delegate that creates the exception to throw. + /// The next interface in the fluent chain for further configuration. TNext Throws(Delegate exceptionFactory); + /// + /// Configures the setup to throw an exception created by a parameterless function. + /// + /// The type of exception to throw. Must inherit from . + /// A function that creates the exception to throw. Can return null. + /// The next interface in the fluent chain for further configuration. TNext Throws(Func exceptionFactory) where TException : Exception; + /// + /// Configures the setup to throw an exception created by a function that takes one method argument. + /// + /// The type of the method argument. + /// The type of exception to throw. Must inherit from . + /// A function that takes the method argument and creates the exception to throw. + /// The next interface in the fluent chain for further configuration. TNext Throws(Func exceptionFactory) where TException : Exception; + /// + /// Configures the setup to throw an exception created by a function that takes two method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of exception to throw. Must inherit from . + /// A function that takes the method arguments and creates the exception to throw. + /// The next interface in the fluent chain for further configuration. TNext Throws(Func exceptionFactory) where TException : Exception; + /// + /// Configures the setup to throw an exception created by a function that takes three method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of exception to throw. Must inherit from . + /// A function that takes the method arguments and creates the exception to throw. + /// The next interface in the fluent chain for further configuration. TNext Throws(Func exceptionFactory) where TException : Exception; + /// + /// Configures the setup to throw an exception created by a function that takes four method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of exception to throw. Must inherit from . + /// A function that takes the method arguments and creates the exception to throw. + /// The next interface in the fluent chain for further configuration. TNext Throws(Func exceptionFactory) where TException : Exception; + /// + /// Configures the setup to throw an exception created by a function that takes five method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of exception to throw. Must inherit from . + /// A function that takes the method arguments and creates the exception to throw. + /// The next interface in the fluent chain for further configuration. TNext Throws(Func exceptionFactory) where TException : Exception; + /// + /// Configures the setup to throw an exception created by a function that takes six method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of exception to throw. Must inherit from . + /// A function that takes the method arguments and creates the exception to throw. + /// The next interface in the fluent chain for further configuration. TNext Throws(Func exceptionFactory) where TException : Exception; + /// + /// Configures the setup to throw an exception created by a function that takes seven method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of exception to throw. Must inherit from . + /// A function that takes the method arguments and creates the exception to throw. + /// The next interface in the fluent chain for further configuration. TNext Throws(Func exceptionFactory) where TException : Exception; + /// + /// Configures the setup to throw an exception created by a function that takes eight method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of the eighth method argument. + /// The type of exception to throw. Must inherit from . + /// A function that takes the method arguments and creates the exception to throw. + /// The next interface in the fluent chain for further configuration. TNext Throws(Func exceptionFactory) where TException : Exception; + /// + /// Configures the setup to throw an exception created by a function that takes nine method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of the eighth method argument. + /// The type of the ninth method argument. + /// The type of exception to throw. Must inherit from . + /// A function that takes the method arguments and creates the exception to throw. + /// The next interface in the fluent chain for further configuration. TNext Throws(Func exceptionFactory) where TException : Exception; + /// + /// Configures the setup to throw an exception created by a function that takes ten method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of the eighth method argument. + /// The type of the ninth method argument. + /// The type of the tenth method argument. + /// The type of exception to throw. Must inherit from . + /// A function that takes the method arguments and creates the exception to throw. + /// The next interface in the fluent chain for further configuration. TNext Throws(Func exceptionFactory) where TException : Exception; + /// + /// Configures the setup to throw an exception created by a function that takes eleven method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of the eighth method argument. + /// The type of the ninth method argument. + /// The type of the tenth method argument. + /// The type of the eleventh method argument. + /// The type of exception to throw. Must inherit from . + /// A function that takes the method arguments and creates the exception to throw. + /// The next interface in the fluent chain for further configuration. TNext Throws(Func exceptionFactory) where TException : Exception; + /// + /// Configures the setup to throw an exception created by a function that takes twelve method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of the eighth method argument. + /// The type of the ninth method argument. + /// The type of the tenth method argument. + /// The type of the eleventh method argument. + /// The type of the twelfth method argument. + /// The type of exception to throw. Must inherit from . + /// A function that takes the method arguments and creates the exception to throw. + /// The next interface in the fluent chain for further configuration. TNext Throws(Func exceptionFactory) where TException : Exception; + /// + /// Configures the setup to throw an exception created by a function that takes thirteen method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of the eighth method argument. + /// The type of the ninth method argument. + /// The type of the tenth method argument. + /// The type of the eleventh method argument. + /// The type of the twelfth method argument. + /// The type of the thirteenth method argument. + /// The type of exception to throw. Must inherit from . + /// A function that takes the method arguments and creates the exception to throw. + /// The next interface in the fluent chain for further configuration. TNext Throws(Func exceptionFactory) where TException : Exception; + /// + /// Configures the setup to throw an exception created by a function that takes fourteen method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of the eighth method argument. + /// The type of the ninth method argument. + /// The type of the tenth method argument. + /// The type of the eleventh method argument. + /// The type of the twelfth method argument. + /// The type of the thirteenth method argument. + /// The type of the fourteenth method argument. + /// The type of exception to throw. Must inherit from . + /// A function that takes the method arguments and creates the exception to throw. + /// The next interface in the fluent chain for further configuration. TNext Throws(Func exceptionFactory) where TException : Exception; + /// + /// Configures the setup to throw an exception created by a function that takes fifteen method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of the eighth method argument. + /// The type of the ninth method argument. + /// The type of the tenth method argument. + /// The type of the eleventh method argument. + /// The type of the twelfth method argument. + /// The type of the thirteenth method argument. + /// The type of the fourteenth method argument. + /// The type of the fifteenth method argument. + /// The type of exception to throw. Must inherit from . + /// A function that takes the method arguments and creates the exception to throw. + /// The next interface in the fluent chain for further configuration. TNext Throws(Func exceptionFactory) where TException : Exception; + /// + /// Configures the setup to throw an exception created by a function that takes sixteen method arguments. + /// + /// The type of the first method argument. + /// The type of the second method argument. + /// The type of the third method argument. + /// The type of the fourth method argument. + /// The type of the fifth method argument. + /// The type of the sixth method argument. + /// The type of the seventh method argument. + /// The type of the eighth method argument. + /// The type of the ninth method argument. + /// The type of the tenth method argument. + /// The type of the eleventh method argument. + /// The type of the twelfth method argument. + /// The type of the thirteenth method argument. + /// The type of the fourteenth method argument. + /// The type of the fifteenth method argument. + /// The type of the sixteenth method argument. + /// The type of exception to throw. Must inherit from . + /// A function that takes the method arguments and creates the exception to throw. + /// The next interface in the fluent chain for further configuration. TNext Throws(Func exceptionFactory) where TException : Exception; }