PostgresExtensionTest
Namespace: Ankus.Testing
Assembly: Ankus.Testing.dll
Publishes an extension project, loads it into an isolated PostgreSQL cluster, and owns both lifetimes. Ordinary test initialization can use this fixture without environment variables or wrapper commands.
public sealed class PostgresExtensionTest : IAsyncDisposableInheritance: object
Implements: IAsyncDisposable
Properties
Section titled “Properties”Cluster
Section titled “Cluster”Gets the running cluster, with the published extension installed.
public PostgresTestCluster Cluster { get; }Value: PostgresTestCluster
Methods
Section titled “Methods”DisposeAsync()
Section titled “DisposeAsync()”Stops the backend before deleting the temporary published library. Logs remain available.
public ValueTask DisposeAsync()Returns: ValueTask
A task completing after shutdown and file cleanup.
RunTestAsync(PgTestCase, CancellationToken)
Section titled “RunTestAsync(PgTestCase, CancellationToken)”Executes a discovered native test in its own rollback-only transaction, preserving exact expected-error matching.
public Task RunTestAsync(PgTestCase test, CancellationToken cancellationToken = default)Parameters:
test — PgTestCase
A case from the extension’s generated PostgresTests catalog.
cancellationToken — CancellationToken
Cancels connection and test execution.
Returns: Task
A task completing after the test and rollback.
Report ignored cases through the host framework. Invoking an ignored case directly fails instead of reporting false success.
StartAsync(PostgresExtensionTestOptions, CancellationToken)
Section titled “StartAsync(PostgresExtensionTestOptions, CancellationToken)”Publishes and starts an isolated extension with explicit test inclusion, build configuration and server settings.
public static Task<PostgresExtensionTest> StartAsync(PostgresExtensionTestOptions options, CancellationToken cancellationToken = default)Parameters:
options — PostgresExtensionTestOptions
The publication and cluster options. Native tests are excluded unless explicitly enabled.
cancellationToken — CancellationToken
Cancels discovery, publication or startup.
Returns: Task<PostgresExtensionTest>
The fixture that owns the published extension and isolated server.
StartAsync(string, PostgresInstallation?, CancellationToken)
Section titled “StartAsync(string, PostgresInstallation?, CancellationToken)”Publishes for the host architecture using the selected installation’s headers, starts a fresh cluster, and executes CREATE EXTENSION. Build and startup failures fail initialization rather than skip tests.
public static Task<PostgresExtensionTest> StartAsync(string projectPath, PostgresInstallation? installation = null, CancellationToken cancellationToken = default)Parameters:
projectPath — string
The extension project file.
installation — PostgresInstallation
The PostgreSQL installation, or null to use ANKUS_TEST_PG_CONFIG when set and otherwise the build or project selection.
Projects without a selection default to PostgreSQL 18.
cancellationToken — CancellationToken
Cancels discovery, publication, or startup.
Returns: Task<PostgresExtensionTest>
The fixture to dispose after all tests finish.
PostgreSQL 18 and later use a per-cluster extension search path. Earlier versions run from an isolated, relocatable copy of the selected installation. Custom SQL directories are remapped into owned test storage without changing the authored control file. Server logs and build logs remain in the project’s bin/ankus-test-logs directory for seven days after their last write. The publication uses the SDK that the extension’s directory selects, even when another SDK runs the tests.
StartAsync(string, bool, PostgresInstallation?, CancellationToken)
Section titled “StartAsync(string, bool, PostgresInstallation?, CancellationToken)”Publishes and installs an extension in an isolated cluster, optionally loading its library during shared preload.
public static Task<PostgresExtensionTest> StartAsync(string projectPath, bool sharedPreload, PostgresInstallation? installation = null, CancellationToken cancellationToken = default)Parameters:
projectPath — string
The extension project file.
sharedPreload — bool
Whether PostgreSQL must load the published library before starting backends.
installation — PostgresInstallation
The selected installation, or null to use the ordinary fixture discovery.
cancellationToken — CancellationToken
Cancels discovery, publication or startup.
Returns: Task<PostgresExtensionTest>
The fixture that owns the cluster and temporary published library.
StartAsync(string, bool, int, PostgresInstallation?, CancellationToken)
Section titled “StartAsync(string, bool, int, PostgresInstallation?, CancellationToken)”Publishes and installs an extension in an isolated cluster on an exact requested TCP port. The port is validated before publishing and is never replaced with an automatic port.
public static Task<PostgresExtensionTest> StartAsync(string projectPath, bool sharedPreload, int port, PostgresInstallation? installation = null, CancellationToken cancellationToken = default)Parameters:
projectPath — string
The extension project file.
sharedPreload — bool
Whether to load the library during shared preload.
port — int
The requested TCP port, from 1 through 65535.
installation — PostgresInstallation
The selected installation, or null for ordinary fixture discovery.
cancellationToken — CancellationToken
Cancels discovery, publication or startup.
Returns: Task<PostgresExtensionTest>
The fixture that owns the cluster and temporary published library.