Class TestInstruction

Contains extension methods on ITestInstruction<T>, for executing, sequencing and transforming their results.

Inheritance

TestInstruction

Namespace: Responsible

Assembly: Responsible.dll

Syntax

public static class TestInstruction

Methods

BoxResult<T>(ITestInstruction<T>)

Converts a test instruction returning a value type into one returning the same value boxed into object. Can be useful for example in conjunction with Sequence(IEnumerable<ITestInstruction<object>>, string, string, int, string) together with value types.

Declaration

[Pure]
public static ITestInstruction<object> BoxResult<T>(this ITestInstruction<T> instruction) where T : struct

Parameters

Type	Name	Description
ITestInstruction<T>	instruction	Instruction to wrap.

Returns

Type	Description
ITestInstruction<object>	A test instruction which behaves otherwise identically to `instruction`, but returns its result as a boxed object.

Type Parameters

Name	Description
T	Return type of the instruction to convert.

ContinueWith<T1, T2>(ITestInstruction<T1>, ITestInstruction<T2>, string, string, int)

Sequences two test instructions to be executed in order, into one instruction returning the result of the second instruction. The second instruction will not execute, if the first instruction fails.

Declaration

[Pure]
public static ITestInstruction<T2> ContinueWith<T1, T2>(this ITestInstruction<T1> first, ITestInstruction<T2> second, string memberName = "", string sourceFilePath = "", int sourceLineNumber = 0)

Parameters

Type	Name	Description
ITestInstruction<T1>	first	Instruction to execute first.
ITestInstruction<T2>	second	Instruction which will be executed after `first`.
string	memberName	Caller member name provided by compiler. May be overridden for custom operators.
string	sourceFilePath	Caller file path provided by compiler. May be overridden for custom operators.
int	sourceLineNumber	Source line number provided by compiler. May be overridden for custom operators.

Returns

Type	Description
ITestInstruction<T2>	A test instruction that completes with the result from the second instruction, once both instructions have completed executing.

Type Parameters

Name	Description
T1	Return type of the first instruction.
T2	Return type of the second instruction.

ContinueWith<T1, T2>(ITestInstruction<T1>, Func<T1, ITestInstruction<T2>>, string, string, int)

Constructs a test instruction, which will first construct another instruction using continuation from the result of the first instruction, and then continue executing the constructed instruction. The continuation will not be called, if the first instruction fails.

Declaration

[Pure]
public static ITestInstruction<T2> ContinueWith<T1, T2>(this ITestInstruction<T1> first, Func<T1, ITestInstruction<T2>> continuation, string memberName = "", string sourceFilePath = "", int sourceLineNumber = 0)

Parameters

Type	Name	Description
ITestInstruction<T1>	first	Instruction to execute first.
Func<T1, ITestInstruction<T2>>	continuation	Function that builds the continuation instruction from the result of the first instruction.
string	memberName	Caller member name provided by compiler. May be overridden for custom operators.
string	sourceFilePath	Caller file path provided by compiler. May be overridden for custom operators.
int	sourceLineNumber	Source line number provided by compiler. May be overridden for custom operators.

Returns

Type	Description
ITestInstruction<T2>	A test instruction that completes with the result from the continuation instruction, once both instructions have completed executing.

Type Parameters

Name	Description
T1	Return type of the first instruction.
T2	Return type of the continuation instruction.

Remarks

If the instruction fails or is canceled before continuation has been called, the description of the second instruction isn't included in the state output, as it is unknown. Thus it is better to prefer ContinueWith<T1, T2>(ITestInstruction<T1>, ITestInstruction<T2>, string, string, int) when possible, which will always also include the description of the second instruction.

GroupedAs<T>(ITestInstruction<T>, string)

Wraps a test instruction to produce a state string where the state string of the original instruction is nested and indented under the given description. Most useful for sequenced instructions.

Declaration

[Pure]
public static ITestInstruction<T> GroupedAs<T>(this ITestInstruction<T> instruction, string description)

Parameters

Type	Name	Description
ITestInstruction<T>	instruction	Instruction to wrap.
string	description	Description to use in output

Returns

Type	Description
ITestInstruction<T>	A test instruction which behaves otherwise identically to `instruction`, but produces nested.

Type Parameters

Name	Description
T	Return type of the instruction to wrap.

Examples

EnterUsername()
    .ContinueWith(EnterPassword())
    .GroupAs("Log in")

Would have a string representation similar to

[ ] Log in
   [ ] Enter username
   [ ] Enter password

RepeatUntil<TWait, TInstruction>(ITestInstruction<TInstruction>, ITestWaitCondition<TWait>, int, string, string, int)

Repeats the instruction until condition is completed.

Declaration

[Pure]
public static ITestWaitCondition<TWait> RepeatUntil<TWait, TInstruction>(this ITestInstruction<TInstruction> instruction, ITestWaitCondition<TWait> condition, int maximumRepeatCount, string memberName = "", string sourceFilePath = "", int sourceLineNumber = 0)

Parameters

Type	Name	Description
ITestInstruction<TInstruction>	instruction	Instruction to repeat.
ITestWaitCondition<TWait>	condition	Condition to repeat until.
int	maximumRepeatCount	Maximum repeat count used to prevent an infinite loop.
string	memberName	Caller member name provided by compiler. May be overridden for custom operators.
string	sourceFilePath	Caller file path provided by compiler. May be overridden for custom operators.
int	sourceLineNumber	Source line number provided by compiler. May be overridden for custom operators.

Returns

Type	Description
ITestWaitCondition<TWait>	A wait condition that completes with the result of `condition`.

Type Parameters

Name	Description
TWait	Return type of the wait condition.
TInstruction	Return type of the test instruction.

Remarks

condition is only checked once per frame, so make sure instruction does not complete synchronously!

RunAsLoop<T>(ITestInstruction<T>, Action, CancellationToken, string, string, int)

Synchronously executes a test instruction by repeatedly calling a callback, until the instruction has completed successfully or with an error. The provided callback will be executed before any conditions are polled, and should run any actions required for the instruction to complete.

Declaration

public static T RunAsLoop<T>(this ITestInstruction<T> instruction, Action tick, CancellationToken cancellationToken = default, string memberName = "", string sourceFilePath = "", int sourceLineNumber = 0)

Parameters

Type	Name	Description
ITestInstruction<T>	instruction	Instruction to run.
Action	tick	Action to run for each iteration of the loop.
CancellationToken	cancellationToken	Optional cancellation token to cancel the instruction prematurely.
string	memberName	Caller member name provided by compiler. May be overridden for custom operators.
string	sourceFilePath	Caller file path provided by compiler. May be overridden for custom operators.
int	sourceLineNumber	Source line number provided by compiler. May be overridden for custom operators.

Returns

Type	Description
T	The result of the test instruction, if it completes successfully.

Type Parameters

Name	Description
T	Return type of the instruction to execute.

Remarks

Any timeouts used when executing an instruction using this method will be based on wall-clock time.

RunAsSimulatedUpdateLoop<T>(ITestInstruction<T>, double, Action<TimeSpan>, CancellationToken, string, string, int)

Synchronously executes a test instruction by simulating an update loop at the given frame rate. The provided tick callback will be called fro each simulated frame, with the frame duration as an argument.

Declaration

public static T RunAsSimulatedUpdateLoop<T>(this ITestInstruction<T> instruction, double framesPerSecond, Action<TimeSpan> tick, CancellationToken cancellationToken = default, string memberName = "", string sourceFilePath = "", int sourceLineNumber = 0)

Parameters

Type	Name	Description
ITestInstruction<T>	instruction	Instruction to run.
double	framesPerSecond	Frame rate to simulate
Action<TimeSpan>	tick	Action to run on each simulated frame. Takes the frame duration as an argument.
CancellationToken	cancellationToken	Optional cancellation token to cancel the instruction prematurely.
string	memberName	Caller member name provided by compiler. May be overridden for custom operators.
string	sourceFilePath	Caller file path provided by compiler. May be overridden for custom operators.
int	sourceLineNumber	Source line number provided by compiler. May be overridden for custom operators.

Returns

Type	Description
T	The result of the test instruction, if it completes successfully.

Type Parameters

Name	Description
T	Return type of the instruction to execute.

Remarks

Any timeouts used when executing an instruction using this method will be based on simulated time.

Select<T1, T2>(ITestInstruction<T1>, Func<T1, T2>, string, string, int)

Applies a selector to the result of a test instruction when the instruction completes, transforming the result type to another type.

Declaration

[Pure]
public static ITestInstruction<T2> Select<T1, T2>(this ITestInstruction<T1> instruction, Func<T1, T2> selector, string memberName = "", string sourceFilePath = "", int sourceLineNumber = 0)

Parameters

Type	Name	Description
ITestInstruction<T1>	instruction	A test instruction to apply the selector to.
Func<T1, T2>	selector	A function to apply to the result of the instruction.
string	memberName	Caller member name provided by compiler. May be overridden for custom operators.
string	sourceFilePath	Caller file path provided by compiler. May be overridden for custom operators.
int	sourceLineNumber	Source line number provided by compiler. May be overridden for custom operators.

Returns

Type	Description
ITestInstruction<T2>	A test instruction whose result is the result of invoking `selector` on the result of `instruction`.

Type Parameters

Name	Description
T1	Return type of the initial instruction.
T2	Return type of the selector and the returned instruction.

Sequence(IEnumerable<ITestInstruction<object>>, string, string, int, string)

Runs all provided test instructions in order, or until one of them fails.

Declaration

[Pure]
public static ITestInstruction<object> Sequence(this IEnumerable<ITestInstruction<object>> instructions, string memberName = "", string sourceFilePath = "", int sourceLineNumber = 0, string operationName = "Sequence")

Parameters

Type	Name	Description
IEnumerable<ITestInstruction<object>>	instructions	Instructions to sequence.
string	memberName	Caller member name provided by compiler. May be overridden for custom operators.
string	sourceFilePath	Caller file path provided by compiler. May be overridden for custom operators.
int	sourceLineNumber	Source line number provided by compiler. May be overridden for custom operators.
string	operationName

Returns

Type	Description
ITestInstruction<object>	A test instruction which will complete with a non-null object once all provided instructions have completed, or will fail when any of the instructions fails.

ToTask<T>(ITestInstruction<T>, TestInstructionExecutor, CancellationToken, string, string, int)

Starts executing the instruction as an async task.

Declaration

public static Task<T> ToTask<T>(this ITestInstruction<T> instruction, TestInstructionExecutor executor, CancellationToken cancellationToken = default, string memberName = "", string sourceFilePath = "", int sourceLineNumber = 0)

Parameters

Type	Name	Description
ITestInstruction<T>	instruction	The instruction to execute.
TestInstructionExecutor	executor	Test test instruction executor to use.
CancellationToken	cancellationToken	Optional cancellation token to cancel the instruction prematurely.
string	memberName	Caller member name provided by compiler. May be overridden for custom operators.
string	sourceFilePath	Caller file path provided by compiler. May be overridden for custom operators.
int	sourceLineNumber	Source line number provided by compiler. May be overridden for custom operators.

Returns

Type	Description
Task<T>	A task which will complete with the instructions status.

Type Parameters

Name	Description
T	Return type of the test instruction.

ToYieldInstruction<T>(ITestInstruction<T>, TestInstructionExecutor, bool, CancellationToken, string, string, int)

Unity-only!

Starts executing an instruction, and returns a yield instruction which can be awaited, using yield return in a Unity coroutine.

Declaration

public static TestOperationYieldInstruction<T> ToYieldInstruction<T>(this ITestInstruction<T> instruction, TestInstructionExecutor executor, bool throwOnError = true, CancellationToken cancellationToken = default, string memberName = "", string sourceFilePath = "", int sourceLineNumber = 0)

Parameters

Type	Name	Description
ITestInstruction<T>	instruction	Instruction to execute.
TestInstructionExecutor	executor	Test test instruction executor to use.
bool	throwOnError	Whether or not to throw on cancellation or errors.
CancellationToken	cancellationToken	Optional cancellation token to cancel the instruction prematurely.
string	memberName	Caller member name provided by compiler. May be overridden for custom operators.
string	sourceFilePath	Caller file path provided by compiler. May be overridden for custom operators.
int	sourceLineNumber	Source line number provided by compiler. May be overridden for custom operators.

Returns

Type	Description
TestOperationYieldInstruction<T>	Yield instruction for Unity, which will complete when the instruction has completed.

Type Parameters

Name	Description
T	Return type of the test instruction to start.