Class ProtoContainerResource<TContainer>

Namespace
ProtoTest.Testcontainers
Assembly
ProtoTest.Testcontainers.dll

Base for a container owned by the run. The host starts it before the run, the started connection string fills a configuration key so tests and an in-process application see the same value, and the run releases it after the reports are written. Technology packages supply the builder and the connection accessor; the base depends on no container library.

public abstract class ProtoContainerResource<TContainer> : IProtoConnectionInfrastructure, IProtoConfiguredInfrastructure, IProtoInfrastructure, IProtoResource, IProtoStartupEvidence, IAsyncDisposable where TContainer : IAsyncDisposable

Type Parameters

TContainer
Inheritance
ProtoContainerResource<TContainer>
Implements
Derived
Inherited Members
Extension Methods

Constructors

ProtoContainerResource(Func<TContainer>, Func<TContainer, CancellationToken, Task>, Func<TContainer, string>) 

protected ProtoContainerResource(Func<TContainer> build, Func<TContainer, CancellationToken, Task> start, Func<TContainer, string> connectionString)

Parameters

build Func<TContainer>
start Func<TContainer, CancellationToken, Task>
connectionString Func<TContainer, string>

Properties

ConnectionString

Gets the connection string; empty until the container started.

public string ConnectionString { get; }

Property Value

string

Description

Gets a single line describing the resource for the trace, report and viewer.

public abstract string Description { get; }

Property Value

string

Id

Gets the stable identity of the resource, for example customer:42.

public abstract string Id { get; }

Property Value

string

IsStarted 

public bool IsStarted { get; }

Property Value

bool

Kind

Gets the resource kind, for example database or entity.

public abstract string Kind { get; }

Property Value

string

ReadinessInterval

Gets or sets the pause between readiness checks. Defaults to 100 milliseconds.

protected TimeSpan ReadinessInterval { get; set; }

Property Value

TimeSpan

ReadinessTimeout

Gets or sets how long the readiness checks may take after the container starts when the container is started directly. Defaults to 30 seconds; a technology package may tighten it. When the host starts the container, the run's ProtoReadinessOptions wins.

protected TimeSpan ReadinessTimeout { get; set; }

Property Value

TimeSpan

Scope

Gets how long the resource lives. Defaults to the test that registered it.

public ProtoResourceScope Scope { get; }

Property Value

ProtoResourceScope

StartupEvidence

Gets what the readiness checks observed while the container started.

public IReadOnlyDictionary<string, string?> StartupEvidence { get; }

Property Value

IReadOnlyDictionary<string, string>

Methods

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

public ValueTask DisposeAsync()

Returns

ValueTask

A task that represents the asynchronous dispose operation.

EffectiveReadinessPort(int)

Gets the port a readiness check should use: the one ReadyOn(int) set, or the image's standard port.

protected int EffectiveReadinessPort(int defaultPort)

Parameters

defaultPort int

Returns

int

ReadyOn(int)

Sets the container port the default readiness check waits for, for images that do not listen on their standard port. Returns the resource for chaining; call it before the run starts.

public ProtoContainerResource<TContainer> ReadyOn(int port)

Parameters

port int

Returns

ProtoContainerResource<TContainer>

ReadyWhen(string, Func<TContainer, CancellationToken, ValueTask<bool>>)

Registers a readiness check evaluated against the started container before the host moves on; use ReadyWhenTcp(string, int, Func<TContainer, int, (string Host, int Port)>) for the common "the endpoint answers" case. A check that never becomes ready fails the start with the probe's name, and the container is released like any failed start.

protected void ReadyWhen(string name, Func<TContainer, CancellationToken, ValueTask<bool>> ready)

Parameters

name string
ready Func<TContainer, CancellationToken, ValueTask<bool>>

ReadyWhenTcp(string, int, Func<TContainer, int, (string Host, int Port)>)

Declares the container's default readiness check: a TCP connection to the endpoint the endpoint resolver returns for the image's standard defaultPort must succeed. Override the port with ReadyOn(int) when the image listens elsewhere.

protected void ReadyWhenTcp(string name, int defaultPort, Func<TContainer, int, (string Host, int Port)> endpoint)

Parameters

name string
defaultPort int
endpoint Func<TContainer, int, (string Host, int Port)>

ReleaseAsync(ProtoResourceReleaseContext)

Releases the resource. Each resource is released at most once, so implementations do not have to guard against repeated calls, but must tolerate a failed release being reported.

public ValueTask ReleaseAsync(ProtoResourceReleaseContext context)

Parameters

context ProtoResourceReleaseContext

Returns

ValueTask

StartAsync(ProtoInfrastructureContext, CancellationToken)

Starts the piece with the run's collected state, so the run's readiness policy (Readiness, set by ConfigureReadiness or ProtoTest:Readiness) governs this container's waits like every host probe. The host prefers this overload; a direct StartAsync(CancellationToken) uses the container's own ReadinessTimeout/ReadinessInterval.

public ValueTask StartAsync(ProtoInfrastructureContext context, CancellationToken cancellationToken = default)

Parameters

context ProtoInfrastructureContext
cancellationToken CancellationToken

Returns

ValueTask

StartAsync(CancellationToken)

Starts the piece; a failure must explain what could not start and why.

public ValueTask StartAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

ValueTask

TryStartContainer<TResource>(TResource)

Starts a caller-built resource without throwing; returns the start failure for the caller to handle, so a machine without a container runtime can fall back or skip rather than fail the run. The asynchronous start runs on the thread pool, so a synchronous caller cannot deadlock on its own synchronization context. StartAsync(CancellationToken) already releases the built container when starting fails, so the candidate stays retryable; the caller can adopt it, retry, or let it go.

protected static ContainerStartResult<TResource> TryStartContainer<TResource>(TResource resource) where TResource : ProtoContainerResource<TContainer>

Parameters

resource TResource

Returns

ContainerStartResult<TResource>

Type Parameters

TResource
Edit this page