Restore Before Tests

Role: Pipeline · API: POST /api/v1/restores then GET /api/v1/executions/{id}

Prefer the quemsi CLI: it posts the restore and waits. Curl below is the same contract. For clicks in the console, use Restore a tagged snapshot. For why known states matter, read Testing with Known Database States.

Before you start

A token with restore and read scopes, stored as QUEMSI_TOKEN. See Create API tokens.
A tagged snapshot already exists (for example use-case=e2e-baseline). If Restore is empty in the UI, take a snapshot first.
You know the data name, agent name, and target datasource name. Names, not numeric ids.
The agent is ONLINE and can read the snapshot’s storage.
Restore overwrites the target. Confirm the datasource is the test database, not production.

Steps

1

Restore with the CLI

--wait is the default. Exit 0 on SUCCESS; non-zero on FAILED or SKIPPED. Then run tests.

quemsi restore --agent ci-staging --target-datasource app-db \
  --data shopping-cart --tag use-case=e2e-baseline

2

Or POST the restore with curl

Pass data and tags to pick the latest matching version, or pass versionId if the job already resolved one.

RESPONSE=$(curl -sS -X POST "$QUEMSI_URL/api/v1/restores" \
  -H "Authorization: Bearer $QUEMSI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "shopping-cart",
    "agent": "ci-staging",
    "targetDatasource": "app-db",
    "tags": { "use-case": "e2e-baseline" }
  }')
EXECUTION_ID=$(printf '%s' "$RESPONSE" | jq -r .id)

3

Poll until terminal (curl only)

Status starts as SCHEDULED. Wait for SUCCESS. Fail the job on FAILED or SKIPPED.

while true; do
  STATUS=$(curl -sS "$QUEMSI_URL/api/v1/executions/$EXECUTION_ID" \
    -H "Authorization: Bearer $QUEMSI_TOKEN" | jq -r .status)
  case "$STATUS" in
    SUCCESS) break ;;
    FAILED|SKIPPED) echo "restore $STATUS"; exit 1 ;;
  esac
  sleep 2
done

4

Run tests

Only start the suite after SUCCESS. Restore again at the start of the next job so leftover rows cannot leak between runs.

If restore fails

Agent offline → start the agent, then retry. The API will not queue work onto an offline agent.
no-available-version → no snapshot has every tag you sent. Take a snapshot with those tags, or list cards with restore-actions (?tag=use-case=e2e-baseline).
token-agent-mismatch → the token is bound to a different agent. Use that agent’s name, or create a token bound to this one.
Need an older version with the same tags → pass versionId instead of data + tags (tags resolve the latest only).

Not this page

Clicks in Restore — Restore a tagged snapshot.
Snapshot a baseline from CI before a deploy — Snapshot before deploy.
The raw HTTP contract — API reference.