PostgresTestCluster
Namespace: Ankus.Testing
Assembly: Ankus.Testing.dll
Owns a pgrx-style, per-invocation PostgreSQL cluster and runs backend tests in rollback-only transactions. Dispose the cluster after all parallel test sessions finish. Normal process exit also attempts shutdown.
public sealed class PostgresTestCluster : IAsyncDisposableInheritance: object
Implements: IAsyncDisposable
Properties
Section titled “Properties”DataDirectory
Section titled “DataDirectory”Gets the unique PGDATA directory, removed after a successful shutdown.
public string DataDirectory { get; }Value: string
Installation
Section titled “Installation”Gets the installation whose tools and backend serve this cluster.
public PostgresInstallation Installation { get; }Value: PostgresInstallation
LogFilePath
Section titled “LogFilePath”Gets the retained server log path.
public string LogFilePath { get; }Value: string
On Windows, ReadServerLog() refreshes this file with native file and Event Log messages. Disposal also refreshes the file to retain shutdown diagnostics.
Gets the loopback TCP port selected for this invocation.
public int Port { get; }Value: int
SocketDirectory
Section titled “SocketDirectory”Gets the Unix socket directory, or null when Windows uses loopback TCP only.
public string? SocketDirectory { get; }Value: string
Methods
Section titled “Methods”DisposeAsync()
Section titled “DisposeAsync()”Stops PostgreSQL in fast mode and removes owned data and socket directories, retaining logs. Shutdown uses its own timeout. If shutdown fails, directories remain available for recovery. A later disposal retries a faulted or canceled shutdown after the native server recovers. After successful shutdown, a diagnostic read failure is reported after owned directories are removed.
public ValueTask DisposeAsync()Returns: ValueTask
A task that completes after shutdown and cleanup.
OpenConnectionAsync(CancellationToken)
Section titled “OpenConnectionAsync(CancellationToken)”Opens an unpooled connection to the test database. The caller owns the connection.
public Task<NpgsqlConnection> OpenConnectionAsync(CancellationToken cancellationToken = default)Parameters:
cancellationToken — CancellationToken
Cancels connection establishment.
Returns: Task<NpgsqlConnection>
An open connection.
ReadServerLog()
Section titled “ReadServerLog()”Reads the server log, including startup and shutdown diagnostics.
public string ReadServerLog()Returns: string
The available log text.
RunInTransactionAsync(string, Func<NpgsqlConnection, NpgsqlTransaction, CancellationToken, Task>, CancellationToken)
Section titled “RunInTransactionAsync(string, Func<NpgsqlConnection, NpgsqlTransaction, CancellationToken, Task>, CancellationToken)”Runs a test with its own connection and transaction, rolling back on success, failure, or cancellation. The callback must not commit or replace the transaction. Parallel callbacks use independent sessions.
public Task RunInTransactionAsync(string testName, Func<NpgsqlConnection, NpgsqlTransaction, CancellationToken, Task> test, CancellationToken cancellationToken = default)Parameters:
testName — string
The test name used in failure diagnostics.
test — Func<NpgsqlConnection, NpgsqlTransaction, CancellationToken, Task>
The test operation.
cancellationToken — CancellationToken
Cancels the connection and test operation.
Returns: Task
A task that completes after rollback.
RunTestAsync(string, string, string?, CancellationToken)
Section titled “RunTestAsync(string, string, string?, CancellationToken)”Executes a SQL test function inside PostgreSQL and rolls its transaction back afterward. Expected errors must match the server’s primary message exactly, as in pgrx.
public Task RunTestAsync(string schema, string functionName, string? expectedError = null, CancellationToken cancellationToken = default)Parameters:
schema — string
The SQL schema containing the test function.
functionName — string
The zero-argument SQL test function.
expectedError — string
An expected server error message, or null for success.
cancellationToken — CancellationToken
Cancels the test.
Returns: Task
A task that completes when the backend test and rollback finish.
StartAsync(PostgresTestClusterOptions, CancellationToken)
Section titled “StartAsync(PostgresTestClusterOptions, CancellationToken)”Initializes a fresh cluster, waits for readiness, and creates its test database. A failed startup attempts shutdown and retains the server log in the reported diagnostic.
public static Task<PostgresTestCluster> StartAsync(PostgresTestClusterOptions options, CancellationToken cancellationToken = default)Parameters:
options — PostgresTestClusterOptions
The installation and invocation settings.
cancellationToken — CancellationToken
Cancels startup.
Returns: Task<PostgresTestCluster>
The ready cluster, owned by the caller.
If another process claims an automatically selected port before PostgreSQL binds it, startup retries with a new cluster and port, up to three attempts within the same startup timeout. Explicit ports are never replaced; collisions and other startup failures are reported immediately. Failed attempts remove their data and socket directories and retain their server logs.