ReplProcessProbe
Spawns an application and sends it real operating-system signals, for the guarantees an in-memory test cannot reach: that the process actually terminates, with the exit code the shell sees, after the cleanup it was given time to run.
Use ReplProcessSignalHarness for everything else. It is deterministic, fast, and covers every decision the framework makes. This one exists for the part that is only true of a real process, and it is correspondingly slower and platform-bound.
Signals are sent on Unix only. Delivering one to another process on Windows needs console control events and console attachment rather than a signal, which this deliberately does not do — see issue #83. SendSignalAsync(ReplProcessSignal, CancellationToken) throws PlatformNotSupportedException there, and the rest of the probe still works, so a cross-platform suite can spawn and assert everywhere and skip only the delivery.
- Kind:
Class - Namespace: Repl.Testing
- Assembly:
Repl.Testing - Source: src/Repl.Testing/ReplProcessProbe.cs
Signature
Section titled “Signature”public sealed class ReplProcessProbe : IAsyncDisposableInheritance
Section titled “Inheritance”Implements
Section titled “Implements”Methods
Section titled “Methods”DisposeAsync()
Section titled “DisposeAsync()”Kills the child and its descendants if the child is still running, then releases the process. A test that asserted an exit already has nothing left to kill; this is what keeps a failed assertion from leaking a process into the rest of the suite.
The tree is reachable only while its root is: a child that spawned something long-lived and then exited on its own leaves that descendant running, because there is no longer a parent to walk down from. Holding descendants beyond the parent needs a job object or a process group, which is platform-specific and deliberately not done here — so a probed application that forks background work has to clean up after itself. Walking the tree has the same residual risk as signalling: .NET’s Unix implementation matches descendants by process id without a start-time check, so an id reused before cleanup runs belongs to whoever inherited it.
The wait for the killed child is itself bounded by Timeout and gives up rather than throwing: disposal runs while a test is already failing, and one that cannot finish would replace that failure with a hang.
public ValueTask DisposeAsync()Returns
Section titled “Returns”SendSignalAsync(ReplProcessSignal, CancellationToken)
Section titled “SendSignalAsync(ReplProcessSignal, CancellationToken)”Delivers a real signal to the child through kill.
public ValueTask SendSignalAsync(ReplProcessSignal signal, CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”signal(ReplProcessSignal): The signal to send. Break has no Unix equivalent and is refused.cancellationToken(CancellationToken): Cancels waiting for the sender to finish.
Returns
Section titled “Returns”Start(string, IEnumerable<string>?, Action<ReplProcessProbeOptions>?)
Section titled “Start(string, IEnumerable<string>?, Action<ReplProcessProbeOptions>?)”Starts the process with its output drained from the moment it starts.
public static ReplProcessProbe Start(string fileName, IEnumerable<string>? arguments = null, Action<ReplProcessProbeOptions>? configure = null)Parameters
Section titled “Parameters”fileName(string): The executable to run.arguments(IEnumerable<string>): Arguments, passed without shell interpretation.configure(Action<ReplProcessProbeOptions>): Adjusts the probe options.
Returns
Section titled “Returns”ReplProcessProbe - A running probe. Dispose it to make sure nothing is left behind.
WaitForExitAsync(CancellationToken)
Section titled “WaitForExitAsync(CancellationToken)”Waits for the child to exit and returns its exit code — the one a shell would report.
public ValueTask<int> WaitForExitAsync(CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”cancellationToken(CancellationToken): Cancels the wait.
Returns
Section titled “Returns”ValueTask<int> - The exit code.
WaitForOutputAsync(string, CancellationToken)
Section titled “WaitForOutputAsync(string, CancellationToken)”Waits until the child has written expected, which is how a test knows the application has reached the point worth signalling rather than guessing with a delay.
public ValueTask WaitForOutputAsync(string expected, CancellationToken cancellationToken = default)Parameters
Section titled “Parameters”expected(string): The text to wait for. Redirected output is read a line at a time, so the child has to terminate the marker with a newline —Console.WriteLinedoes, a bareWritedoes not, and a marker left unterminated is not seen until the stream closes.cancellationToken(CancellationToken): Cancels the wait.
Returns
Section titled “Returns”Properties
Section titled “Properties”Output
Section titled “Output”Everything the child has written so far, standard output and standard error interleaved in the order they were read.
Output is drained continuously rather than at exit, so a child that fills its pipe is never blocked by this probe. What a killed child never got to flush is gone, though: to observe what happened during a shutdown that may not complete, have the application append to a file and read that instead.
public string Output { get; }Returns
Section titled “Returns”ProcessId
Section titled “ProcessId”The child’s process id, which is what a signal is addressed to.
public int ProcessId { get; }