Class PhobosSpec

Test fixture class for performing assertions against Phobos infrastructure.

Inheritance
object
TestKitBase
TestKit
PhobosSpec
Implements
IAsyncLifetime
Inherited Members
Namespace: Phobos.TestKit
Assembly: Phobos.TestKit.dll
Syntax
public abstract class PhobosSpec : TestKit, IActorRefFactory, IDisposable, IAsyncLifetime

Constructors

PhobosSpec(ActorSystemSetup, ITestOutputHelper)

Declaration
protected PhobosSpec(ActorSystemSetup setup, ITestOutputHelper helper)
Parameters
Type Name Description
ActorSystemSetup setup
ITestOutputHelper helper

PhobosSpec(Config, ITestOutputHelper)

Declaration
protected PhobosSpec(Config configuration, ITestOutputHelper helper)
Parameters
Type Name Description
Config configuration
ITestOutputHelper helper

PhobosSpec(ITestOutputHelper)

Declaration
protected PhobosSpec(ITestOutputHelper helper)
Parameters
Type Name Description
ITestOutputHelper helper

Fields

LocalPhobos

Declaration
public static readonly Config LocalPhobos
Field Value
Type Description
Config

Properties

CompletedActivities

Declaration
public IReadOnlyList<Activity> CompletedActivities { get; }
Property Value
Type Description
IReadOnlyList<Activity>

CompletedMetrics

All of the completed metrics that were captured.

Declaration
public List<Metric> CompletedMetrics { get; }
Property Value
Type Description
List<Metric>

InstrumentationSettings

The InstrumentationSettings for the current ActorSystem.

Declaration
public PhobosSettings InstrumentationSettings { get; }
Property Value
Type Description
PhobosSettings

MockTracer

The tracer used to record traces for these specs

Declaration
public Tracer MockTracer { get; }
Property Value
Type Description
Tracer

Monitor

The monitor used to record metrics

Declaration
public Meter Monitor { get; }
Property Value
Type Description
Meter

Tracer

The current OTel tracer

Declaration
public Tracer Tracer { get; }
Property Value
Type Description
Tracer

Methods

AfterAll()

This method is called when a test ends.

Declaration
protected override void AfterAll()
Overrides

AwaitNSpans(int, TimeSpan?)

Declaration
public Task<IReadOnlyList<Activity>> AwaitNSpans(int count, TimeSpan? timeout = null)
Parameters
Type Name Description
int count
TimeSpan? timeout
Returns
Type Description
Task<IReadOnlyList<Activity>>

AwaitUntilFoundSpan(Func<Activity, bool>, TimeSpan?)

Block until a span arrives that matches the predicate

Declaration
public Task<IReadOnlyList<Activity>> AwaitUntilFoundSpan(Func<Activity, bool> predicate, TimeSpan? timeout = null)
Parameters
Type Name Description
Func<Activity, bool> predicate

A predicate filter function.
TimeSpan? timeout

An optional timeout.
Returns
Type Description
Task<IReadOnlyList<Activity>>

Bootstrap(Config)

Declaration
public static BootstrapSetup Bootstrap(Config c = null)
Parameters
Type Name Description
Config c
Returns
Type Description
BootstrapSetup

Dispose(bool)

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

Declaration
protected override void Dispose(bool disposing)
Parameters
Type Name Description
bool disposing

if set to true the method has been called directly or indirectly by a user's code. Managed and unmanaged resources will be disposed.
if set to false the method has been called by the runtime from inside the finalizer and only unmanaged resources can be disposed.
Overrides

DisposeAsync()

Called when an object is no longer needed. Called just before Dispose() if the class also implements that.

Declaration
public virtual Task DisposeAsync()
Returns
Type Description
Task

ExpectNoMetricsFrom(string, TimeSpan?)

Declaration
public Task ExpectNoMetricsFrom(string targetActorType, TimeSpan? timeout = null)
Parameters
Type Name Description
string targetActorType
TimeSpan? timeout
Returns
Type Description
Task

ExpectNoMetricsFrom(Type, TimeSpan?)

Declaration
public Task ExpectNoMetricsFrom(Type actorType, TimeSpan? timeout = null)
Parameters
Type Name Description
Type actorType
TimeSpan? timeout
Returns
Type Description
Task

ExpectNoTraces(TimeSpan?)

Declaration
public Task ExpectNoTraces(TimeSpan? duration = null)
Parameters
Type Name Description
TimeSpan? duration
Returns
Type Description
Task

ExpectNoTracesFrom(ActorPath, TimeSpan?)

Declaration
public Task ExpectNoTracesFrom(ActorPath path, TimeSpan? timeout = null)
Parameters
Type Name Description
ActorPath path
TimeSpan? timeout
Returns
Type Description
Task

ExpectNoTracesFrom(IActorRef, TimeSpan?)

Declaration
public Task ExpectNoTracesFrom(IActorRef targetActor, TimeSpan? timeout = null)
Parameters
Type Name Description
IActorRef targetActor
TimeSpan? timeout
Returns
Type Description
Task

ExpectNoTracesFrom(string, TimeSpan?)

Declaration
public Task ExpectNoTracesFrom(string targetActorPath, TimeSpan? timeout = null)
Parameters
Type Name Description
string targetActorPath
TimeSpan? timeout
Returns
Type Description
Task

ExpectTracesFrom(ActorPath, TimeSpan?)

Declaration
public Task<IReadOnlyList<Activity>> ExpectTracesFrom(ActorPath path, TimeSpan? timeout = null)
Parameters
Type Name Description
ActorPath path
TimeSpan? timeout
Returns
Type Description
Task<IReadOnlyList<Activity>>

ExpectTracesFrom(IActorRef, int, TimeSpan?)

Declaration
public Task<IReadOnlyList<Activity>> ExpectTracesFrom(IActorRef targetActor, int count, TimeSpan? timeout = null)
Parameters
Type Name Description
IActorRef targetActor
int count
TimeSpan? timeout
Returns
Type Description
Task<IReadOnlyList<Activity>>

ExpectTracesFrom(IActorRef, TimeSpan?)

Declaration
public Task<IReadOnlyList<Activity>> ExpectTracesFrom(IActorRef targetActor, TimeSpan? timeout = null)
Parameters
Type Name Description
IActorRef targetActor
TimeSpan? timeout
Returns
Type Description
Task<IReadOnlyList<Activity>>

ExpectTracesFrom(string, int, TimeSpan?)

Declaration
public Task<IReadOnlyList<Activity>> ExpectTracesFrom(string targetActorPath, int count, TimeSpan? timeout = null)
Parameters
Type Name Description
string targetActorPath
int count
TimeSpan? timeout
Returns
Type Description
Task<IReadOnlyList<Activity>>

ExpectTracesFrom(string, TimeSpan?)

Declaration
public Task<IReadOnlyList<Activity>> ExpectTracesFrom(string targetActorPath, TimeSpan? timeout = null)
Parameters
Type Name Description
string targetActorPath
TimeSpan? timeout
Returns
Type Description
Task<IReadOnlyList<Activity>>

FilterActivitiesByActorPath(Activity, string)

Declaration
public static bool FilterActivitiesByActorPath(Activity activity, string targetActorPath)
Parameters
Type Name Description
Activity activity
string targetActorPath
Returns
Type Description
bool

FilterActivitiesByActorType(Activity, string)

Declaration
public static bool FilterActivitiesByActorType(Activity activity, string targetActorType)
Parameters
Type Name Description
Activity activity
string targetActorType
Returns
Type Description
bool

FilterMetricsByActorType(Metric, string)

Declaration
public static bool FilterMetricsByActorType(Metric metric, string targetActorType)
Parameters
Type Name Description
Metric metric
string targetActorType
Returns
Type Description
bool

ForceFlush(int)

Forces all OpenTelemetry Activitys and OpenTelemetry.Metrics.Metrics to be flushed to their exporters.

Declaration
public bool ForceFlush(int timeoutMilliseconds = -1)
Parameters
Type Name Description
int timeoutMilliseconds
Returns
Type Description
bool

IgnoreSpansAsync(TimeSpan)

Will ignore all actively collected Activity instances for the provided duration and will reset the MockTracer once the duration has passed.

Declaration
public Task IgnoreSpansAsync(TimeSpan duration)
Parameters
Type Name Description
TimeSpan duration

The amount of time we should ignore the collection of new spans.
Returns
Type Description
Task

InitializeAsync()

Called immediately after the class has been created, before it is used.

Declaration
public virtual Task InitializeAsync()
Returns
Type Description
Task

LogSpan(LogLevel, Activity)

Declaration
public void LogSpan(LogLevel level, Activity span)
Parameters
Type Name Description
LogLevel level
Activity span

LogSpansOnFail(Func<IReadOnlyList<Activity>>, Action<IReadOnlyList<Activity>>)

Declaration
public void LogSpansOnFail(Func<IReadOnlyList<Activity>> getTraces, Action<IReadOnlyList<Activity>> assertion)
Parameters
Type Name Description
Func<IReadOnlyList<Activity>> getTraces
Action<IReadOnlyList<Activity>> assertion

PrintIfFailed(Action<IReadOnlyList<Activity>>, IReadOnlyList<Activity>, string)

Execute the assertion against the set of spans and if it fails, log the spans with the appropriate debug message. ENHANCED: Now captures comprehensive evidence for debugging race conditions.

Declaration
public void PrintIfFailed(Action<IReadOnlyList<Activity>> assertion, IReadOnlyList<Activity> spans, string message = null)
Parameters
Type Name Description
Action<IReadOnlyList<Activity>> assertion

The assertion to execute.
IReadOnlyList<Activity> spans

The set of spans to print and format.
string message

An optional message to include in the debug log.

PrintSpans(IEnumerable<Activity>, string)

Used to dump a list of all spans for debugging purposes.

Declaration
public void PrintSpans(IEnumerable<Activity> spans, string message = null)
Parameters
Type Name Description
IEnumerable<Activity> spans

The set of spans to print and format.
string message

An optional message to include in the debug log.

PrintSpansText(IEnumerable<Activity>)

Used in approval specs when plain text mode is enabled

Declaration
public static string PrintSpansText(IEnumerable<Activity> spans)
Parameters
Type Name Description
IEnumerable<Activity> spans
Returns
Type Description
string

ResetMetrics()

Declaration
public void ResetMetrics()

ResetTracer(int)

Calls ForceFlush(int) and clears the CompletedActivities afterwards.

Declaration
public bool ResetTracer(int timeoutMilliseconds = -1)
Parameters
Type Name Description
int timeoutMilliseconds

Optional. The blocking delay in the timeout for flushing Activity
Returns
Type Description
bool

The outcome of the ForceFlush(int) operation.

Setup(BootstrapSetup)

Declaration
public static ActorSystemSetup Setup(BootstrapSetup setup)
Parameters
Type Name Description
BootstrapSetup setup
Returns
Type Description
ActorSystemSetup

Setup(BootstrapSetup, PhobosConfigBuilder)

Declaration
public static ActorSystemSetup Setup(BootstrapSetup setup, PhobosConfigBuilder phobosBuilder)
Parameters
Type Name Description
BootstrapSetup setup
PhobosConfigBuilder phobosBuilder
Returns
Type Description
ActorSystemSetup

Setup(Config)

Declaration
public static ActorSystemSetup Setup(Config c = null)
Parameters
Type Name Description
Config c
Returns
Type Description
ActorSystemSetup

WaitForMetricsToStabilize(Func<IReadOnlyList<Metric>, bool>, TimeSpan?, TimeSpan?)

Waits for metrics to meet a specific condition.

Declaration
public Task WaitForMetricsToStabilize(Func<IReadOnlyList<Metric>, bool> condition, TimeSpan? checkInterval = null, TimeSpan? waitTime = null)
Parameters
Type Name Description
Func<IReadOnlyList<Metric>, bool> condition

The condition that must be met for the wait to complete.
TimeSpan? checkInterval

The frequency with which to check the condition. Defaults to 50ms.
TimeSpan? waitTime

The maximum time to wait for the condition. Defaults to RemainingOrDefault
Returns
Type Description
Task

WaitForMinimumMetrics(int, TimeSpan?, TimeSpan?)

Waits for at least the specified number of metrics to be collected.

Declaration
public Task WaitForMinimumMetrics(int expectedMinCount, TimeSpan? checkInterval = null, TimeSpan? waitTime = null)
Parameters
Type Name Description
int expectedMinCount

The minimum number of metrics expected.
TimeSpan? checkInterval

The frequency with which to check. Defaults to 50ms.
TimeSpan? waitTime

The maximum time to wait. Defaults to RemainingOrDefault
Returns
Type Description
Task

WaitForTracerToResetAsync()

Continuously resets the tracer until there are no more spans received for up to 250ms.

Declaration
public Task WaitForTracerToResetAsync()
Returns
Type Description
Task

WaitForTracesToStabilize(TimeSpan?, TimeSpan?, TimeSpan?)

Wait for traces in the MockTracer to stabilize before continuing. IMPORTANT: This method includes ForceFlush() calls to handle timing issues with OpenTelemetry's SimpleActivityExportProcessor. Use this method after actor operations to ensure all traces are fully processed and collected before making assertions.

Declaration
public Task WaitForTracesToStabilize(TimeSpan? checkInterval = null, TimeSpan? waitTime = null, TimeSpan? maxTimeout = null)
Parameters
Type Name Description
TimeSpan? checkInterval

The frequency with which to check the metric interval. Defaults to 50ms.
TimeSpan? waitTime

The length of time metrics need to be stable prior to moving on. Defaults to RemainingOrDefault
TimeSpan? maxTimeout

The maximum amount of time we'll wait for traces to stabilize before aborting.
Returns
Type Description
Task

WaitForUniqueMetricNames(params string[])

Waits for metrics with specific names to be collected.

Declaration
public Task WaitForUniqueMetricNames(params string[] expectedMetricNames)
Parameters
Type Name Description
string[] expectedMetricNames

The names of metrics that must be present.
Returns
Type Description
Task

Implements

Xunit.IAsyncLifetime