Namespace Microsoft.Accordant

Classes

AfterAllInfo: Information provided to AfterAll hooks.

AfterTestInfo: Information provided to AfterEach hooks.

AsyncOperation: Factory for creating inline async operations (terminating step functions). Use this for simple cases where you don't need to create a separate class.

AtomicAttribute: This attribute marks a property inside a class marked with the StateAttribute attribute as being an atomic property. Properties of types like strings, integers, bools etc are already treated as atomic properties but you might want to treat a complex property (say, List<byte>) as an atomic property. This attribute can be used to mark such complex properties as atomic. You must provide the fully qualified name of a static method that can be used to return a string representation of the property, to be used when generating the string representation of the state.

BaseStepFunction: BaseStepFunction is an intermediate class other steps can inherit from. It chooses a GUID as a StepFunctionId, effectively meaning that two step functions are only equal if they are the same object. It also locks the input and output states to ensure implementations of the step don't inadvertently modify the input state and subsequent code doesn't modify the output states.

BeforeAllInfo: Information provided to BeforeAll hooks.

BeforeTestInfo: Information provided to BeforeEach hooks.

ChoiceSet: This class represents a choice between a set of values for an expression, as well as the index representing the current choice.

Choose: This class represents a choose expression that can choose one or more values. A lambda that contains choose expressions is evaluated multiple times such that each possible choice for each choose expression and all their combinations are exercised.

ChooseExpressionLambda: A choose expression lambda is a lambda that contains zero or more choose expressions. The Run method of this class can be used to run such a lambda. The lambda is invoked multiple times such that all combinations of all choose expressions are exercised.

ConcurrentTestCase

ConcurrentTestCaseAlgorithms

ConcurrentTestCaseFileRecord: This class represents the file layout of ConcurrentTestCase when serialized.

ContractStepFunction: A step function that verifies an observed response against an expected behavior. It is enabled if the verify function deems the observed response to be valid given the request and the state on which the step function is evaluated. If valid, it produces the updated state and any optional step functions that run concurrently with the rest of the system.

Conversions: This class contains methods that convert to/from the file layout classes and in-memory objects representing test cases.

DerivationLabels: Labels for derived request variants.

DerivationSelector: Selects which request derivations should be generated during test case generation. Use For(string) to create instances with a fluent API.

DerivationSelectorBuilder: Fluent builder for DerivationSelector.

DerivationSources: Provides typed access to source operation requests and responses for multi-source derivations.

Derivation<TReq, TResp, TResult>: Fluent API for creating request derivations with types on the left side.

Derive: Fluent API for creating request derivations.

EmptyExpectedOutcomesException

ExecuteBuilder<TTarget, TState>: Fluent builder for binding execution logic to operations. Use ExecuteWith<TTarget>() to obtain an instance.

Expect: Fluent API for defining expected outcomes in Operation.Apply methods. Provides a more readable way to construct ExpectedOutcome and ExpectedOutcomes.

ExpectContext<TResponse, TState>: Provides type-inferred expect methods for use within an Operation. This class knows both the response type and state type, allowing methods like That(Func<TResponse, bool>, string) and ThenState(Action<TState>) to work without explicit generic type parameters.

ExpectedOutcome: An expected outcome includes a response descriptor that can be used to verify whether the observed response from the system is valid or not, an update state as well as an optional step function that runs concurrently with the rest of the system.

ExpectedOutcomeBuilder<TResponse>: Builder for constructing ExpectedOutcome instances fluently.

ExpectedOutcomes: This class contains collection of ExpectedOutcome that represent the different outcomes of invoking an operation.

HttpExecutable: This class sends requests encoded through HttpRequest objects using an HttpClient retrieved via Target<T>(). The results are wrapped in HttpResponse objects and returned to the caller.

HttpExecutableException

HttpRequest: Http request consisting of just the url without any payload.

HttpRequest<TPayload>: Http request with a url and payload.

HttpResponse: Http response consisting of just the status code.

HttpResponse<TPayload>: Http response consisting of the status code and a payload.

HttpVerb

InputFileRecord: This class represents the file layout of an OperationInput when serialized.

InputSet: This class represents a set of operation inputs. Each operation input has a unique name and two inputs cannot share the same name.

InputSetException

InputStepFunction: A test operation step function represents the effect of applying the model of an operation. It is enabled based on the shouldApply predicate. It returns all possible updated states returned by Invoke(object, IState) as the set of updated states the system can transition to.

InvalidOperationNameException

InvalidSpecException

Invariant

Logger

MultiSourceDerivationBuilder: Builder for multi-source derivations. Note: Multi-source derivations are not yet implemented at runtime.

MultipleStateException: This exception is thrown when the user expected the system to transition to a single state but the system can transition to multiple states.

MultipleStepFunctionException: This exception is thrown by TestCaseExecutor when it encounters a next state in which more than one step function becomes available.

NextStates: This class represents the next set of states a given state can transition to as well as the set of new step functions that become available for application in each of those states.

OperationCall: This class represents an invocation of an operation.

OperationCallFileRecord: This class represents the file layout of an OperationCall when serialized.

OperationExtensions: Extension methods for IOperation.

OperationInput: This class represents an operation bound with a request, or an operation whose request can be derived from another operation call.

OperationValidationException

Operation<TRequest, TResponse, TState>

The unified base class for operations.

An Operation defines:

The spec/behavior via Apply(TRequest, TState) (required)
Execution logic via ExecuteAsync(TestingContext, TRequest) (optional)
Request derivations via DerivedFrom (optional)
Polling setup via Polling (optional)

PollingException

PollingSetup

Configuration for polling behavior when an operation triggers background work via a TerminatingStepFunction.

Polling uses a derivation to create the polling request from the original operation's request and response. The derivation must be defined on the polling operation's DerivedFrom property.

RequestDerivation: Defines how a request can be derived from another operation's request/response. Use the Derive(Dictionary<string, (object Request, object Response)>, object) class to create instances.

ResponseValidator: A wrapper type that can validate responses. Supports implicit conversion from Func<T, TResult> predicates.

RetryBehavior: This class indicates whether an operation should be retried.

SequentialTestCase

SequentialTestCaseAlgorithms

SequentialTestCaseFileRecord: This class represents the file layout of SequentialTestCase when serialized.

SharedStateAttribute

Marks a property in a [State] class as shared state.

Shared state properties are:

Cloned by reference (not deep cloned)
Not locked when the containing state is locked
Still contribute to fingerprinting for state equality

Use this for large immutable data (like image content) that should be shared across clones for performance.

For [State] class properties, the default fingerprinting uses StringRepresentation(). For other supported types (primitives, collections), a custom fingerprint method is required.

Example:

[State]
public partial class ImageState
{
    public string Name { get; set; }

    [SharedState(Fingerprint = nameof(ContentFingerprint))]
    public List<byte> Content { get; set; }

    private string ContentFingerprint(List<byte> content) => 
        content == null ? null : Convert.ToBase64String(content.ToArray());
}

SingleSourceDerivationBuilder: Builder for single-source derivations (legacy API - types specified on As()).

Spec: Static factory for creating specs.

SpecException

Spec<TState>: A Spec contains the list of operations that define the behavior of a stateful system. Each operation is registered under a unique name.

State

State class represents the state maintained by the user of a system to make sense of the behavior of the system. It is not the internal state of the system though it is probably similar to the internal state of the system.

This is an abstract class and defines properties and methods that should be implemented by all state objects.

StateAttribute

Marks a POCO class for state source generation.

The source generator will automatically generate:

Clone() implementation for deep copying
StringRepresentationInternal() for fingerprinting
LockComponents() for immutability

Requirements:

Must be a class (not struct or record)
Must be declared as partial
Must be at namespace level (not nested inside another type)
Must have an accessible parameterless constructor

Supported property types:

Primitives (int, bool, string, etc.)
Enums
DateTime, TimeSpan, Guid, DateOnly, TimeOnly
Other [State] classes
List<T>, Dictionary<K,V> (where K is primitive/string/enum), arrays
Tuples
Nullable versions of the above

Not supported:

HashSet (use List instead)
Interface types (IList, IDictionary, etc.)
Records (cannot inherit from State base class)
Nested classes

StateFrozenException

StateGraph: This class contains methods a number of methods related to state graph.

StateGraphEdge: The edge of the state graph. The edge includes the target state graph node and the step function whose application takes the system to the target state graph node.

StateGraphNode: A state graph node represents a unique state along with the set of step functions that can be applied to that state (if enabled). The state and set of step functions lead to a unique node fingerprint.

StateList: This class represents a list of states.

StateProfile

This class tracks the state or set of states the system could be in, as well as active step functions that can further impact that state.

The most frequent use case is the system being in a single state, and each operation optionally transitioning it to a single next state.

There are situations however where the system can be in one of a possible set of states. As an example, consider a web service endpoint that returns a timeout error. A timeout error might not always mean the operation did not finish. Maybe it didn't, or maybe it did but the server's timeout stopwatch expired before it could return a successful response. So the system can be in one of two states: one in which the operation never happened and the other in which it did happen. This class can allow us to represent both the possibilities. In such situations, further operations (say a GET call on the web service endpoint) can help resolve the ambiguity the system is in.

Finally, certain operations can trigger active processes within the system that can transition the system to possible next states without the user taking any explicit action. As an example, consider a web service endpoint that starts a long running background process that can transition the system through a sequence of states. This class can represent such processes by associating a set of step functions associated with each possible state the system can be in.

StepExecutedInfo: Information provided to OnStepExecuted hooks. Called after each operation or batch of concurrent operations executes.

StepFunctionApplicationException: This is an exception thrown during state graph exploration where applying a step function on the state in a state graph node leads to an exception thrown from the step function application code. The step function application code is written by users of this framework and can throw arbitrary exceptions due to bugs. That exception is caught and wrapped up in this exception. It also contains a path from the root node to the target node where the exception was thrown that can help in debugging the issue.

StepFunctionList: This class represents a list of step functions.

StepResult: This class a result of applying a step function.

SystemChecker: This class validates the system behavior by explaining it in terms of stateful contracts.

TerminatingStepFunction

A step function that represents background work which will eventually complete. Subclasses must define IsTerminalState to indicate when the work is done, and GetStepResults(IState) to define how the state transitions.

This is used for:

Test execution: Polling continues until IsTerminalState returns true for all states
Test generation: Unwinding continues until IsTerminalState returns true

For daemon/fire-and-forget step functions that never terminate, use BaseStepFunction instead.

For simple cases, use Create<TState>(Func<TState, bool>, Action<TState>, string) to create an async operation inline without defining a class.

TestCase

TestCaseExecutionResult: This class contains the result of executing a test case.

TestCaseExecutor

TestCaseFileRecord: This class represents the file layout of TestCase when serialized.

TestCaseFileRecordsWithMetadata<TMetadata, TTestCaseFileRecord>

TestCaseGenerationException

TestCaseGenerator

TestCasePersistenceException

TestCaseSegment: Represents a segment within a concurrent test case. A segment contains one or more operation calls. If the segment contains a single operation call, it is executed sequentially. If it contains multiple operation calls, they are executed concurrently.

TestCaseSegmentFileRecord: This class represents the file layout of TestCaseSegment when serialized.

TestExecutionOptions: Options and configurations used during test execution.

TestGenerationOptions: This class contains options and configurations used during the test case generation process.

TestingContext: Testing context that provides access to the system under test during test execution. Provides common functionality for all testing contexts.

TypedExpectBuilderStateExtensions: Extension methods for TypedExpectBuilder<TResponse, TState> that require TState to derive from State (not just implement IState). These methods use CloneWithMap which is a State-specific feature for cycle-aware cloning.

TypedExpectBuilder<TResponse, TState>: A typed builder for constructing ExpectedOutcome instances fluently. This builder knows both the response type and state type, allowing methods like ThenState(Action<TState>) to work without explicit generic type parameters.

TypedSingleSourceDerivationBuilder<TReq, TResp, TResult>: Builder for typed single-source derivations with all type parameters specified upfront. This enables cleaner When() and As() calls without type parameters.

TypedWhenBuilder<TReq, TResp, TResult>: Builder for typed derivations with a When() filter applied.

UnexpectedException

UnexpectedInvariantException

Unit: The unit type - a type with exactly one value. Use this when specifying operations that either take no request (no parameters) or return no response (void). This is the standard name in functional programming (F#, Scala, Rust, Haskell).

UnsupportedDictionaryKeyTypeException: Exception thrown when a JsonState contains a dictionary with an unsupported key type. JsonState requires dictionary keys to be one of the supported types to ensure deterministic serialization and hashing.

UnwindContext: Context provided to the ShouldUnwindStepFunction lambda during test generation.

ValidationResult: Represents the result of validating a response against expected behavior. Can be implicitly converted from a bool for simple cases.

VisualizationOptions: This class contains options and configurations that control the state space visualization.

Interfaces

IOperation: Non-generic interface for operations, allowing type-erased storage in collections. This interface is implemented by Operation<TRequest, TResponse, TState>.

ISpec: Non-generic interface for specs, allowing type-erased usage.

IState

Base interface for all state objects used in specification and state exploration.

States can be either mutable (freeze-on-use) or immutable (always frozen). The framework treats them uniformly through this interface.

IStepFunction

A step function transitions the state of the system to a non-deterministic set of next states, if it is enabled in the source state.

A step function is consumed when applied and can produce new step functions in the set of next states.

ITestingMetadata: This interface should be implemented by classes that store metadata that is persisted along with serialized test cases to disk that contains the information required to re-run those test cases (information that might not be contained in the test cases themselves).

Delegates

ConcurrentTestCaseAlgorithm: This delegate represents the signature of algorithms used to generate concurrent test cases.

Logger.LogDelegate

SequentialTestCaseAlgorithm: This delegate represents the signature of algorithms used to generate sequential test cases.

ShouldRetryOperationLambda: This lambda indicates whether to retry an operation call, given its response and the number of time this operation call has already been retried.

VerifyFunc: A delegate that verifies whether an observed response is valid given a request and state. Returns (isValid, stateProfile) where stateProfile contains the updated state(s) if valid.

Table of Contents

Namespace Microsoft.Accordant

Classes

Interfaces

Delegates