Class ProtoExecutionContext

Namespace
ProtoTest.Core
Assembly
ProtoTest.Core.dll

Provides the public per-test facade for metadata, services, state, clients, attachments, and observations.

public sealed class ProtoExecutionContext : IAsyncDisposable
Inheritance
ProtoExecutionContext
Implements
Inherited Members
Extension Methods

Constructors

ProtoExecutionContext(string, IServiceScope, ProtoTestId, MethodInfo)

Creates the execution context for a test from an already parsed id.

public ProtoExecutionContext(string testName, IServiceScope scope, ProtoTestId id, MethodInfo testMethod)

Parameters

testName string

The test's display name in the trace.

scope IServiceScope

The service scope the test resolves its services from.

id ProtoTestId

The test's numeric id.

testMethod MethodInfo

The test method the context belongs to.

ProtoExecutionContext(string, IServiceScope, string, MethodInfo)

Creates the execution context for a test, parsing testId with Parse(string).

public ProtoExecutionContext(string testName, IServiceScope scope, string testId, MethodInfo testMethod)

Parameters

testName string

The test's display name in the trace.

scope IServiceScope

The service scope the test resolves its services from.

testId string

The test's numeric id, 1 to 18 decimal digits.

testMethod MethodInfo

The test method the context belongs to.

Properties

Attachments

Gets a snapshot of the artifacts registered for this test.

public IReadOnlyList<ProtoTestAttachment> Attachments { get; }

Property Value

IReadOnlyList<ProtoTestAttachment>

CancellationToken

Gets the token the test lifecycle observes, so a test that honours cancellation ends at the same point the runner stopped it. Setup I/O that can observe it passes it to the provider.

public CancellationToken CancellationToken { get; }

Property Value

CancellationToken

Clock

Gets this test's clock. Time-dependent code reads it, and the test advances it instead of sleeping; the application under test receives it as its TimeProvider.

public ProtoClock Clock { get; }

Property Value

ProtoClock

Configuration

Retrieves the global configuration registered in the ProtoHost.

public IConfiguration Configuration { get; }

Property Value

IConfiguration

Id

Numeric execution ID generated by the owning host. The string form preserves leading zeroes.

public ProtoTestId Id { get; }

Property Value

ProtoTestId

RecordedObservations

Gets a snapshot of observations recorded for this test.

public IReadOnlyCollection<ProtoObservation> RecordedObservations { get; }

Property Value

IReadOnlyCollection<ProtoObservation>

Resources

Gets a snapshot of the resources owned by this test, in registration order.

public IReadOnlyList<ProtoResourceSnapshot> Resources { get; }

Property Value

IReadOnlyList<ProtoResourceSnapshot>

Services

Gets the service scope this test resolves from, so the scope closes with the test.

public IServiceProvider Services { get; }

Property Value

IServiceProvider

TestId

Gets Id as the string the trace and reports key on.

public string TestId { get; }

Property Value

string

TestMethod

Gets the test method this context belongs to.

public MethodInfo TestMethod { get; }

Property Value

MethodInfo

TestName

Gets the test's display name as shown in the trace.

public string TestName { get; }

Property Value

string

TestNumber

Gets Id as the number a test id preserves; 0 is not a test.

public long TestNumber { get; }

Property Value

long

Trace

Records automatic execution diagnostics for ProtoTest integrations.

public IProtoTraceWriter Trace { get; }

Property Value

IProtoTraceWriter

Methods

AddAttachment(ProtoTestAttachment)

Registers a prepared artifact and records it on the trace.

public ProtoTestAttachment AddAttachment(ProtoTestAttachment attachment)

Parameters

attachment ProtoTestAttachment

Returns

ProtoTestAttachment

AddAttachment(string, ReadOnlyMemory<byte>, string, string?)

Registers a binary artifact and records it on the trace.

public ProtoTestAttachment AddAttachment(string name, ReadOnlyMemory<byte> content, string mediaType = "application/octet-stream", string? description = null)

Parameters

name string
content ReadOnlyMemory<byte>
mediaType string
description string

Returns

ProtoTestAttachment

AddAttachment(string, string, string, string?)

Registers a text artifact and records it on the trace.

public ProtoTestAttachment AddAttachment(string name, string content, string mediaType = "text/plain", string? description = null)

Parameters

name string
content string
mediaType string
description string

Returns

ProtoTestAttachment

AddAttachmentFile(string, string?, string, string?)

Registers a file as an artifact; the file is captured with the test's artifacts.

public ProtoTestAttachment AddAttachmentFile(string filePath, string? name = null, string mediaType = "application/octet-stream", string? description = null)

Parameters

filePath string
name string
mediaType string
description string

Returns

ProtoTestAttachment

AddFinding(string, ProtoReportStatus, string?, string?, string?, IReadOnlyList<string>?, IReadOnlyDictionary<string, object>?)

Records a finding: something worth reporting that is deliberately not a test failure. Findings reach the run's reports and run gates, and are traced so they appear in ProtoTrace.

public ProtoReportItem AddFinding(string message, ProtoReportStatus status = ProtoReportStatus.Warning, string? identifier = null, string? category = null, string? targetName = null, IReadOnlyList<string>? tags = null, IReadOnlyDictionary<string, object>? metadata = null)

Parameters

message string
status ProtoReportStatus
identifier string
category string
targetName string
tags IReadOnlyList<string>
metadata IReadOnlyDictionary<string, object>

Returns

ProtoReportItem

Client<TClient>(string)

Retrieves a required named client.

public TClient Client<TClient>(string name = "Default") where TClient : class

Parameters

name string

Returns

TClient

Type Parameters

TClient

DisposeAsync()

Releases owned resources, disposes owned clients and the service scope. A second call waits for the first and does not release a resource again. An early release still running is awaited, with no timeout, before the service scope is disposed. A release that already failed is not retried; that failure is still included in the aggregated cleanup outcome.

public ValueTask DisposeAsync()

Returns

ValueTask

Exceptions

InvalidOperationException

A release callback disposed its own context.

RecordObservation(ProtoObservation)

Stores and dispatches an observation to every collector that accepts it.

public void RecordObservation(ProtoObservation observation)

Parameters

observation ProtoObservation

RecordObservation(string, string, string, object?, IReadOnlyDictionary<string, object>?)

Convenience overload for recording an observation.

public void RecordObservation(string targetName, string kind, string identifier, object? data = null, IReadOnlyDictionary<string, object>? metadata = null)

Parameters

targetName string
kind string
identifier string
data object
metadata IReadOnlyDictionary<string, object>

RegisterClient<TClient>(TClient, string, ProtoClientOwnership)

Registers a named client for this test. A Context client is released once when the test completes, however many names point at it; a Caller client is shared and its lifetime is managed elsewhere. The same instance under the same type and name (the name is case-insensitive) is a no-op when the ownership matches. Another name, or the same instance registered as another type, is an alias and does not add a release.

public void RegisterClient<TClient>(TClient client, string name = "Default", ProtoClientOwnership ownership = ProtoClientOwnership.Context) where TClient : class

Parameters

client TClient
name string
ownership ProtoClientOwnership

Type Parameters

TClient

Exceptions

InvalidOperationException

A different instance is already registered under the type and name, or this instance is already registered with a different ProtoClientOwnership.

RegisterResource(IProtoResource)

Registers a resource owned by this test. Owned resources are released in reverse registration order during teardown, after hooks and attributes and before clients are disposed. Resources registered here reach the run's report; framework-managed clients do not, unless their release fails.

public void RegisterResource(IProtoResource resource)

Parameters

resource IProtoResource

RegisterResource(string, string, string, Func<ProtoResourceReleaseContext, ValueTask>)

Registers a resource described by a release callback.

public void RegisterResource(string id, string kind, string description, Func<ProtoResourceReleaseContext, ValueTask> release)

Parameters

id string
kind string
description string
release Func<ProtoResourceReleaseContext, ValueTask>

RegisterResource<T>(T)

Registers a resource and returns it, so ownership can be expressed inline.

public T RegisterResource<T>(T resource) where T : class, IProtoResource

Parameters

resource T

Returns

T

Type Parameters

T

ReleaseResourceAsync(string)

Releases one owned resource before teardown. Returns false when the id is unknown or a release for it has already started. A release this call runs that fails is recorded as ReleaseFailed and then thrown; dispose does not retry it, but that failure still counts in the test's cleanup outcome.

public ValueTask<bool> ReleaseResourceAsync(string id)

Parameters

id string

Returns

ValueTask<bool>

Exceptions

InvalidOperationException

The release callback for id called this method for the same resource.

ReplaceClient<TClient>(TClient, string, ProtoClientOwnership)

Replaces a named client registered for this test and traces the replacement. The instance that lost its last name keeps the one release from when it was first registered. An instance another name still references is not released again, and a replacement that is already registered does not gain a second release. Replacing a name with the instance already registered there is a no-op when the ownership matches.

public void ReplaceClient<TClient>(TClient client, string name = "Default", ProtoClientOwnership ownership = ProtoClientOwnership.Context) where TClient : class

Parameters

client TClient
name string
ownership ProtoClientOwnership

Type Parameters

TClient

Exceptions

InvalidOperationException

Nothing is registered under name, or client is already registered with a different ProtoClientOwnership. A replacement always follows a registration; it never creates one.

Resolve<T>()

Retrieves required contextual state.

public T Resolve<T>() where T : class, IProtoContext

Returns

T

Type Parameters

T

Resolve<T>(string)

Retrieves required contextual state registered under a key.

public T Resolve<T>(string key) where T : class, IProtoContext

Parameters

key string

Returns

T

Type Parameters

T

Service<T>()

Resolves a required service from this test's scope.

public T Service<T>() where T : notnull

Returns

T

Type Parameters

T

SetContext<T>(string, T)

Registers or replaces contextual state under a key, so two protocols can store the same state type without overwriting each other's instance.

public void SetContext<T>(string key, T context) where T : class, IProtoContext

Parameters

key string
context T

Type Parameters

T

SetContext<T>(T)

Registers or replaces contextual state for this test.

public void SetContext<T>(T context) where T : class, IProtoContext

Parameters

context T

Type Parameters

T

TryClient<TClient>(string)

Retrieves a named client when it is present.

public TClient? TryClient<TClient>(string name = "Default") where TClient : class

Parameters

name string

Returns

TClient

Type Parameters

TClient

TryResolve<T>()

Retrieves contextual state when it is present.

public T? TryResolve<T>() where T : class, IProtoContext

Returns

T

Type Parameters

T

TryResolve<T>(string)

Retrieves contextual state registered under a key when it is present.

public T? TryResolve<T>(string key) where T : class, IProtoContext

Parameters

key string

Returns

T

Type Parameters

T

TryService<T>()

Resolves a service from this test's scope when it is registered.

public T? TryService<T>()

Returns

T

Type Parameters

T

UniqueName(string, int)

Creates a name for a record that must outlive the test process, such as a tenant, an operator, an account or a customer. The name derives from TestId, so parallel tests in one host never collide. Across runs or processes, give each a distinct RunPrefix through ConfigureTestIds; the default prefix is random per run. A rerun gets the same name only with an IProtoTestIdGenerator that derives the id from the test. Pass sequence when one test creates several records of the same kind; the default (0) omits it.

public string UniqueName(string name, int sequence = 0)

Parameters

name string
sequence int

Returns

string

Examples

var tenant = context.UniqueName("tenant");        // "tenant-0042317"
var second = context.UniqueName("member", 2);     // "member-0042317-2"
Edit this page