Class ProtoHost

Namespace: ProtoTest.Core

Assembly: ProtoTest.Core.dll

Owns the ProtoTest service provider and exposes the public run and test lifecycle API. The run state machine lives in ProtoTest.Core.Internal.ProtoRunStateMachine; hook sequencing and the test lifecycle are delegated to focused internal components.

public sealed class ProtoHost : IAsyncDisposable

Inheritance: object

ProtoHost

Implements: IAsyncDisposable

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods: SheetModelAssertions.ShouldMatchShape<TRow>(TRow, object, bool, JsonSerializerOptions?)

SheetModelAssertions.ShouldMatchShape<TRow>(TRow, object, JsonSerializerOptions?)

Properties

Clock

Gets the run's clock. Tests get their own clock seeded from it, so advancing time inside a test stays inside that test; advancing this one moves the whole run, including worker hosts.

public ProtoClock Clock { get; }

Property Value

ProtoClock

Configuration

Gets the run's resolved configuration.

public IConfiguration Configuration { get; }

Property Value

IConfiguration

CurrentContext

Gets the current test execution context for this asynchronous control flow.

public static ProtoExecutionContext CurrentContext { get; }

Property Value

ProtoExecutionContext

CurrentContextOrNull

Gets the current test execution context, or null when none is active on this flow - the safe lookup for telemetry callbacks, which can run outside the test's context.

public static ProtoExecutionContext? CurrentContextOrNull { get; }

Property Value

ProtoExecutionContext

CurrentHost

Gets the host owning the current test, or the sole active host outside a test.

public static ProtoHost CurrentHost { get; }

Property Value

ProtoHost

Trace

Gets immutable snapshots of the current run trace.

public IProtoTraceSource Trace { get; }

Property Value

IProtoTraceSource

Methods

CompleteTestAsync()

Completes the active test using the exact lifecycle components that completed setup.

public Task CompleteTestAsync()

Returns

Task

Exceptions

InvalidOperationException: Thrown when no test is active on the current async flow, so a missing or leaked context is reported instead of being silently ignored.

CompleteTestAsync(ProtoTestResult)

Completes the active test and records the result reported by its framework adapter. Unlike the parameterless overload this stays a no-op when no test is active: adapters call it from teardown even when their framework skipped the test before the lifecycle started.

public Task CompleteTestAsync(ProtoTestResult result)

Parameters

result ProtoTestResult

Returns

Task

DisposeAsync()

Stops the run, releases the run-scoped resources and disposes the service provider, so await using alone ends the run. Disposal is idempotent; a run still starting or stopping is rejected rather than torn down halfway.

public ValueTask DisposeAsync()

Returns

ValueTask

Exceptions

InvalidOperationException: A StartAsync(CancellationToken) or StopAsync(CancellationToken) is still in progress on this host.

FindCapabilityReason(string, string?)

Finds the suite-level reason a capability gate reports when it skips, declared through AddCapabilityReason. A reason declared for the exact name wins over one declared for kind as a whole; null when the suite declared no reason (the gate then uses its own default).

public string? FindCapabilityReason(string kind, string? name = null)

Parameters

kind string
name string

Returns

string

FindClock(string)

Finds the clock of the running test with the given id, or null when no such test runs on this host. Scoping the lookup to the owning host keeps two hosts that share a test id from resolving each other's clock.

public ProtoClock? FindClock(string testId)

Parameters

testId string

Returns

ProtoClock

FindTraceWriter(Activity?)

Finds the trace writer for the given activity, or Current when none is given.

public static IProtoTraceWriter? FindTraceWriter(Activity? activity = null)

Parameters

activity Activity

Returns

IProtoTraceWriter

FindTraceWriter(ActivityTraceId)

Finds the trace writer of the test an application span belongs to, matched by its W3C trace id. This is the safe lookup for application telemetry callbacks, which run outside the test's flow: CurrentContextOrNull is empty there and CurrentHost cannot be resolved.

public static IProtoTraceWriter? FindTraceWriter(ActivityTraceId traceId)

Parameters

traceId ActivityTraceId

Returns

IProtoTraceWriter

HasApplication(string)

Returns whether the host declares an application of this name through AddApplication, so a skip condition can answer whether the suite composed the application under test rather than whether an address happens to be configured.

public bool HasApplication(string name)

Parameters

name string

Returns

bool

HasCapability(string, string?)

Returns whether the host is composed with a capability of the given kind (optionally a specific name). Integrations declare capabilities when they are configured, so this answers what the host can actually do rather than what it was asked to do.

public bool HasCapability(string kind, string? name = null)

Parameters

kind string
name string

Returns

bool

HasCapability(string, string?, string?)

Returns whether the host declares a capability of kind narrowed by the descriptor name and/or the instance it describes. A null filter matches anything; every non-null filter must match.

public bool HasCapability(string kind, string? name, string? instance)

Parameters

kind string
name string
instance string

Returns

bool

StartAsync(CancellationToken)

Runs the run lifecycle's start path once: hooks, capability records, skipped declarations and the run's infrastructure, then the trace listener. A repeat call after a successful start is a no-op, and a call while a start is in flight is rejected rather than starting anything twice.

public Task StartAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

Task

StartTestAsync(string, MethodInfo, IEnumerable<ProtoAttribute>?, IProtoTestAttachmentPublisher?)

Starts a test lifecycle with an ID generated by this host.

public Task<ProtoExecutionContext> StartTestAsync(string testName, MethodInfo testMethod, IEnumerable<ProtoAttribute>? attributes = null, IProtoTestAttachmentPublisher? attachmentPublisher = null)

Parameters

testName string
testMethod MethodInfo
attributes IEnumerable<ProtoAttribute>
attachmentPublisher IProtoTestAttachmentPublisher

Returns

Task<ProtoExecutionContext>

StartTestAsync(string, MethodInfo, IEnumerable<ProtoAttribute>?, IProtoTestAttachmentPublisher?, CancellationToken)

Starts a test lifecycle with a caller-supplied attribute set, an attachment publisher and a cancellation token for the test. Setup I/O that can observe cancellation - the SQL connection open and transaction begin - does; the token reaches hooks and attributes through CancellationToken.

public Task<ProtoExecutionContext> StartTestAsync(string testName, MethodInfo testMethod, IEnumerable<ProtoAttribute>? attributes, IProtoTestAttachmentPublisher? attachmentPublisher, CancellationToken cancellationToken)

Parameters

testName string
testMethod MethodInfo
attributes IEnumerable<ProtoAttribute>
attachmentPublisher IProtoTestAttachmentPublisher
cancellationToken CancellationToken

Returns

Task<ProtoExecutionContext>

StartTestAsync(string, MethodInfo, CancellationToken)

Starts a test lifecycle with an ID generated by this host and a cancellation token for the test.

public Task<ProtoExecutionContext> StartTestAsync(string testName, MethodInfo testMethod, CancellationToken cancellationToken)

Parameters

testName string
testMethod MethodInfo
cancellationToken CancellationToken

Returns

Task<ProtoExecutionContext>

StartTestAsync(string, string, MethodInfo, IEnumerable<ProtoAttribute>?, IProtoTestAttachmentPublisher?)

Starts a test lifecycle with an explicit numeric ID.

public Task<ProtoExecutionContext> StartTestAsync(string testName, string testId, MethodInfo testMethod, IEnumerable<ProtoAttribute>? attributes = null, IProtoTestAttachmentPublisher? attachmentPublisher = null)

Parameters

testName string
testId string
testMethod MethodInfo
attributes IEnumerable<ProtoAttribute>
attachmentPublisher IProtoTestAttachmentPublisher

Returns

Task<ProtoExecutionContext>

StartTestAsync(string, string, MethodInfo, CancellationToken)

Starts a test lifecycle with an explicit numeric ID and a cancellation token for the test. Setup I/O that can observe cancellation - the SQL connection open and transaction begin - does; the token reaches hooks and attributes through CancellationToken.

public Task<ProtoExecutionContext> StartTestAsync(string testName, string testId, MethodInfo testMethod, CancellationToken cancellationToken)

Parameters

testName string
testId string
testMethod MethodInfo
cancellationToken CancellationToken

Returns

Task<ProtoExecutionContext>

StopAsync(CancellationToken)

Executes all suite-level AfterRun hooks in descending order. A stop rejected because a start is in flight changes nothing; a stop that ran and failed is remembered and rethrown on retry.

public Task StopAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

Task