::: warning Test files only This annotation applies only to test files run by the SQL test runner (npgsqlrest --test). It has no meaning in endpoint SQL files or routine comments. :::

Run one or more named steps (from the TestRunner.Steps registry) before this test file executes.

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

-- @setup StepName [StepName ...]

• Names may be whitespace- or comma-separated: -- @setup CreateDb SeedData and -- @setup CreateDb, SeedData are equivalent.
• The annotation is repeatable; all listed steps run in the order written.
• Every name must exist in the TestRunner.Steps registry — an unknown name is a loud error, not a silent skip.
• A step with "Enabled": false is the one sanctioned skip: it is ignored wherever referenced (logged at debug level) — the default configuration ships disabled example steps to flip on instead of typing.

Config:

{
  "TestRunner": {
    "Steps": {
      "CreateIsolatedDb": {
        "Sql": "create database app_iso_{rnd5_1} template app_template_{rnd5}",
        "ConnectionName": "Admin"
      },
      "DropIsolatedDb": {
        "Sql": "drop database if exists app_iso_{rnd5_1} with (force)",
        "ConnectionName": "Admin"
      }
    }
  }
}

Test file:

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

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

{"name": "Ada"}
*/
select status = 200, 'user created in the isolated clone' from _response;

The step runs once, immediately before this file (after the run-level Setup). Combined with -- @teardown and -- @connection, this gives a single test file its own private database.

The header ends at the first SQL statement or HTTP block. An included file (\i/\ir) that contains only comments (an annotation profile) continues the header — its annotations count as if written in-place — so a shared profile can carry @setup/@teardown/@connection/@tag for many test files.

::: tip Watch the prose Everything after the step names on the line is treated as more step names. Write explanatory text on its own comment line, not after the names. :::

• TEST @teardown — the mirror, always runs after the file
• TEST @connection — run the file on another connection
• Test Runner configuration — the Steps registry
• Testing Guide