NpgsqlRest

Appearance

Comments
AI-assisted, verified against source

TEST @connection ​

Test files only

This annotation applies only to test files run by the SQL test runner (npgsqlrest --test). It is distinct from the endpoint CONNECTION annotation, which selects a connection for a routine endpoint.

Run this test file on a named ConnectionStrings entry instead of the test runner's default connection (TestRunner.ConnectionName or the app's main connection).

Syntax ​

Placed in the file's header — the leading -- line comments before the first SQL statement or HTTP block:

sql
sql
-- @connection Name

The whole file — its SQL statements and the endpoints invoked by its HTTP blocks — runs on a non-pooled connection built from that entry. This is the key to perfect per-test isolation: point the file at a database that its own @setup step just created.

Example ​

Config:

json
json
{
  "ConnectionStrings": {
    "Admin": "Host=localhost;Database=postgres;...",
    "Test": "Host=localhost;Database=app_test_{rnd5};...",
    "Isolated": "Host=localhost;Database=app_iso_{rnd5_1};..."
  }
}

Test file — gets its own clone, invisible to every other test:

sql
sql
-- @setup CreateIsolatedDb
-- @teardown DropIsolatedDb
-- @connection Isolated

/*
POST /api/create-user
Content-Type: application/json

{"name": "Ada", "email": "ada@example.com"}
*/
select body::jsonb ->> 'id' = '4',
       'sequence ids are deterministic in a fresh clone'
from _response;

Sequences are the classic motivation: nextval() is non-transactional (it sticks even through rollback), so on a shared test database a generated id depends on which other tests ran first. In a private clone the id is deterministic.

Notes ​

  • The endpoint pipeline still type-checks (Describe) against the run-level test connection at startup; @connection switches the execution connection for this file. The databases must therefore be structurally compatible — which they are by construction when both are created from the same template or migrations.
  • {rnd} tokens in the connection string resolve once per run; use indexed tokens ({rnd5_1}, {rnd5_2}) when several files each need their own database name.

Comments