/// <summary>
/// Introduces an alternative set of steps that can be chosen given the provided condition.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <param name="caller">The mock or step to which this 'conditional' step is added.</param>
/// <param name="condition">
/// A condition evaluated when an event handler is added or removed. If <c>true</c>, the
/// alternative branch is taken.
/// </param>
/// <param name="branch">
/// An action to set up the alternative branch; it also provides a means of re-joining the normal
/// branch.
/// </param>
/// <returns>An <see cref="ICanHaveNextEventStep{THandler}" /> that can be used to add further steps on the normal branch.</returns>
public static ICanHaveNextEventStep <THandler> If <THandler>(
this ICanHaveNextEventStep <THandler> caller,
Func <THandler?, bool>?condition,
Action <IfEventStepBase <THandler> .IfBranchCaller> branch) where THandler : Delegate
{
return(caller.SetNextStep(new IfEventStep <THandler>(condition, condition, branch)));
}
/// <summary>
/// Introduces an alternative branch that is used in lieu of the normal branch for a given number of uses.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <param name="caller">The mock or step to which this 'log' step is added.</param>
/// <param name="times">The number of times the alternative branch should be used.</param>
/// <param name="branch">An action to set up the alternative branch.</param>
/// <returns>An <see cref="ICanHaveNextEventStep{THandler}" /> that can be used to add further steps.</returns>
public static ICanHaveNextEventStep <THandler> Times <THandler>(
this ICanHaveNextEventStep <THandler> caller,
int times,
Action <ICanHaveNextEventStep <THandler> > branch) where THandler : Delegate
{
return(caller.SetNextStep(new TimesEventStep <THandler>(times, branch)));
}
/// <summary>
/// Introduces a step that will remember ('store') event handlers adder or removed.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <param name="caller">The mock or step to which this 'stored' step is added.</param>
/// <param name="step">
/// Returns the added step itself. It can be used to manipulate the store, check contents of the store,
/// and raise events on added handlers.
/// </param>
/// <returns>An <see cref="ICanHaveNextEventStep{THandler}" /> that can be used to add further steps.</returns>
public static IStoredEvent <THandler> Stored <THandler>(
this ICanHaveNextEventStep <THandler> caller,
out StoredEventStep <THandler> step) where THandler : Delegate
{
step = new StoredEventStep <THandler>();
return(caller.SetNextStep(step));
}
public void SetNextStepRequiresStep()
{
ICanHaveNextEventStep <EventHandler> step = EventStep;
var exception = Assert.Throws <ArgumentNullException>(() => step.SetNextStep((IEventStep <EventHandler>)null !));
Assert.Equal("step", exception.ParamName);
}
/// <summary>
/// Introduces an alternative set of steps that can be chosen given the provided conditions, where the conditions can
/// depend on the state of the entire mock instance.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <param name="caller">The mock or step to which this 'conditional' step is added.</param>
/// <param name="addCondition">
/// A condition evaluated when an event handler is added. If <c>true</c>, the alternative branch
/// is taken.
/// </param>
/// <param name="removeCondition">
/// A condition evaluated when an event handler is removed. If <c>true</c>, the alternative
/// branch is taken.
/// </param>
/// <param name="branch">
/// An action to set up the alternative branch; it also provides a means of re-joining the normal
/// branch.
/// </param>
/// <returns>An <see cref="ICanHaveNextEventStep{THandler}" /> that can be used to add further steps on the normal branch.</returns>
public static ICanHaveNextEventStep <THandler> InstanceIf <THandler>(
this ICanHaveNextEventStep <THandler> caller,
Func <object, THandler?, bool>?addCondition,
Func <object, THandler?, bool>?removeCondition,
Action <IfEventStepBase <THandler> .IfBranchCaller> branch) where THandler : Delegate
{
return(caller.SetNextStep(new InstanceIfEventStep <THandler>(addCondition, removeCondition, branch)));
}
/// <summary>
/// Introduces a step that will record an entry before an event handler is removed.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <typeparam name="TRecord">The type of the entries that will be recorded in the ledger.</typeparam>
/// <param name="caller">The mock or step to which this 'record' step is added.</param>
/// <param name="ledger">A list that contains recorded entries.</param>
/// <param name="selector">
/// A Func that constructs an entry for when an event handler is removed.
/// Takes the event handler as parameter.
/// </param>
/// <returns>An <see cref="ICanHaveNextEventStep{THandler}" /> that can be used to add further steps.</returns>
public static ICanHaveNextEventStep <THandler> RecordBeforeRemove <THandler, TRecord>(
this ICanHaveNextEventStep <THandler> caller,
out IReadOnlyList <TRecord> ledger, Func <THandler?, TRecord> selector) where THandler : Delegate
{
var newStep = new RecordBeforeRemoveEventStep <THandler, TRecord>(selector);
ledger = newStep;
return(caller.SetNextStep(newStep));
}
/// <summary>
/// Introduces a step that will record an entry before an event handler is added.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <param name="caller">The mock or step to which this 'record' step is added.</param>
/// <param name="ledger">A list that contains recorded entries.</param>
/// <returns>An <see cref="ICanHaveNextEventStep{THandler}" /> that can be used to add further steps.</returns>
public static ICanHaveNextEventStep <THandler> RecordBeforeAdd <THandler>(
this ICanHaveNextEventStep <THandler> caller,
out IReadOnlyList <THandler?> ledger) where THandler : Delegate
{
var newStep = new RecordBeforeAddEventStep <THandler, THandler?>(h => h);
ledger = newStep;
return(caller.SetNextStep(newStep));
}
/// <summary>
/// Introduces a step whose only purpose is to be joined to from another step. It forwards all event handler adds and
/// removes.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <param name="caller">The mock or step to which this 'join' step is added.</param>
/// <param name="joinPoint">A reference to this step that can be used in a Join step.</param>
/// <returns>An <see cref="ICanHaveNextEventStep{THandler}" /> that can be used to add further steps.</returns>
public static ICanHaveNextEventStep <THandler> JoinPoint <THandler>(
this ICanHaveNextEventStep <THandler> caller,
out IEventStep <THandler> joinPoint)
where THandler : Delegate
{
var joinStep = new EventStepWithNext <THandler>();
joinPoint = joinStep;
return(caller.SetNextStep(joinStep));
}
/// <summary>
/// Introduces a step that logs all adds and removes of event handlers to the mocked event to a log context, where
/// the log context is provided by an <see cref="ILogContextProvider" />.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <param name="caller">The mock or step to which this 'log' step is added.</param>
/// <param name="logContextProvider">An instance from which we can get an <see cref="ILogContext" /> to use.</param>
/// <returns>An <see cref="ICanHaveNextEventStep{THandler}" /> that can be used to add further steps.</returns>
public static ICanHaveNextEventStep <THandler> Log <THandler>(
this ICanHaveNextEventStep <THandler> caller,
ILogContextProvider logContextProvider) where THandler : Delegate
{
if (logContextProvider == null)
{
throw new ArgumentNullException(nameof(logContextProvider));
}
return(caller.SetNextStep(new LogEventStep <THandler>(logContextProvider.LogContext)));
}
/// <summary>
/// Step that checks the number of times event handlers have been added or removed. Adds the check to the verification
/// group provided.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <param name="caller">The mock or step to which this 'verification' step is added.</param>
/// <param name="verificationGroup">The verification group to which this check is added.</param>
/// <param name="name">A name that can be used to identify the check in its group.</param>
/// <param name="expectedNumberOfAdds">The expected number of times event handlers have been added.</param>
/// <param name="expectedNumberOfRemoves">The expected number of times event handlers have been removed.</param>
/// <returns>An <see cref="ICanHaveNextEventStep{THandler}" /> that can be used to add further steps.</returns>
public static ICanHaveNextEventStep <THandler> ExpectedUsage <THandler>(
this ICanHaveNextEventStep <THandler> caller,
VerificationGroup verificationGroup,
string?name,
int?expectedNumberOfAdds = null,
int?expectedNumberOfRemoves = null) where THandler : Delegate
{
if (verificationGroup == null)
{
throw new ArgumentNullException(nameof(verificationGroup));
}
var step = new ExpectedUsageEventStep <THandler>(name, expectedNumberOfAdds, expectedNumberOfRemoves);
verificationGroup.Add(step);
return(caller.SetNextStep(step));
}
/// <summary>
/// Introduces a step that will ignore all adding and removing of event handlers.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <param name="caller">The mock or step to which this 'dummy' step is added.</param>
public static void Dummy <THandler>(
this ICanHaveNextEventStep <THandler> caller) where THandler : Delegate
{
caller.SetNextStep(DummyEventStep <THandler> .Instance);
}
private static FakeNextEventStep <THandler> NextStepFor <THandler>(ICanHaveNextEventStep <THandler> mock) where THandler : Delegate
{
return(new FakeNextEventStep <THandler>(mock));
}
/// <summary>
/// Introduces a step that will throw an exception whenever an event handler is added or removed.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <param name="caller">The mock or step to which this 'throw' step is added.</param>
/// <param name="exceptionFactory">
/// A Func that creates the exception to be thrown. Takes the mocked instance and event
/// handler as parameters.
/// </param>
public static void InstanceThrow <THandler>(
this ICanHaveNextEventStep <THandler> caller,
Func <object, THandler?, Exception> exceptionFactory) where THandler : Delegate
{
caller.SetNextStep(new ThrowEventStep <THandler>(exceptionFactory));
}
/// <summary>
/// Introduces a step that will throw an exception whenever an event handler is added or removed.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <param name="caller">The mock or step to which this 'throw' step is added.</param>
/// <param name="exceptionFactory">A Func that creates the exception to be thrown. Takes the event handler as parameter.</param>
public static void Throw <THandler>(
this ICanHaveNextEventStep <THandler> caller,
Func <THandler?, Exception> exceptionFactory) where THandler : Delegate
{
caller.InstanceThrow(AddInstanceParameter(exceptionFactory));
}
/// <summary>
/// Introduces a step that will invoke an action when an event handler is removed, while forwarding
/// adds to a next step.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <param name="caller">The mock or step to which this 'lambda' step is added.</param>
/// <param name="action">The action to be taken when an event handler is added.</param>
/// <returns>An <see cref="ICanHaveNextEventStep{THandler}" /> that can be used to add further steps.</returns>
public static ICanHaveNextEventStep <THandler> InstanceRemoveAction <THandler>(
this ICanHaveNextEventStep <THandler> caller,
Action <object, THandler?> action) where THandler : Delegate
{
return(caller.SetNextStep(new InstanceRemoveActionEventStep <THandler>(action)));
}
/// <summary>
/// Introduces a step that will invoke an action when an event handler is added, while forwarding
/// removes to a next step.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <param name="caller">The mock or step to which this 'lambda' step is added.</param>
/// <param name="action">The action to be taken when an event handler is added.</param>
/// <returns>An <see cref="ICanHaveNextEventStep{THandler}" /> that can be used to add further steps.</returns>
public static ICanHaveNextEventStep <THandler> AddAction <THandler>(
this ICanHaveNextEventStep <THandler> caller,
Action <THandler?> action) where THandler : Delegate
{
return(caller.SetNextStep(new AddActionEventStep <THandler>(action)));
}
/// <summary>
/// Introduces a step that will remember ('store') event handlers adder or removed.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <param name="caller">The mock or step to which this 'stored' step is added.</param>
/// <returns>An <see cref="ICanHaveNextEventStep{THandler}" /> that can be used to add further steps.</returns>
public static IStoredEvent <THandler> Stored <THandler>(
this ICanHaveNextEventStep <THandler> caller) where THandler : Delegate
{
return(caller.SetNextStep(new StoredEventStep <THandler>()));
}
/// <summary>
/// Introduces a step that will forward adding and removing of event handlers to another step.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <param name="caller">The mock or step to which this 'join' step is added.</param>
/// <param name="joinPoint">The step to which adding and removing of event handlers will be forwarded.</param>
public static void Join <THandler>(
this ICanHaveNextEventStep <THandler> caller,
IEventStep <THandler> joinPoint) where THandler : Delegate
{
caller.SetNextStep(joinPoint);
}
/// <summary>
/// Introduces an alternative set of steps that is chosen when an event handler is removed.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <param name="caller">The mock or step to which this 'conditional' step is added.</param>
/// <param name="branch">
/// An action to set up the alternative branch; it also provides a means of re-joining the normal
/// branch.
/// </param>
/// <returns>An <see cref="ICanHaveNextEventStep{THandler}" /> that can be used to add further steps on the normal branch.</returns>
public static ICanHaveNextEventStep <THandler> IfRemove <THandler>(
this ICanHaveNextEventStep <THandler> caller,
Action <IfEventStepBase <THandler> .IfBranchCaller> branch) where THandler : Delegate
{
return(caller.SetNextStep(new IfRemoveEventStep <THandler>(branch)));
}
/// <summary>
/// Introduces a step that will throw a <see cref="MockMissingException" /> whenever an event handler is added or
/// removed.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <param name="caller">The mock or step to which this 'missing' step is added.</param>
public static void Missing <THandler>(
this ICanHaveNextEventStep <THandler> caller) where THandler : Delegate
{
caller.SetNextStep(MissingEventStep <THandler> .Instance);
}
public FakeNextEventStep(ICanHaveNextEventStep <THandler> mock)
{
mock.SetNextStep(this);
}
/// <summary>
/// Introduces a step that logs all adds and removes of event handlers to the mocked event to a log context, or the
/// console if none was provided.
/// </summary>
/// <typeparam name="THandler">The event handler type for the event.</typeparam>
/// <param name="caller">The mock or step to which this 'log' step is added.</param>
/// <param name="logContext">
/// The <see cref="ILogContext" /> used to write the log entries. The default will write to the
/// console.
/// </param>
/// <returns>An <see cref="ICanHaveNextEventStep{THandler}" /> that can be used to add further steps.</returns>
public static ICanHaveNextEventStep <THandler> Log <THandler>(
this ICanHaveNextEventStep <THandler> caller,
ILogContext?logContext = null) where THandler : Delegate
{
return(caller.SetNextStep(new LogEventStep <THandler>(logContext ?? WriteLineLogContext.Console)));
}
