Testing

SurrealKit includes a testing framework that lets you write declarative test suites for your SurrealDB schema. Tests run against an isolated ephemeral database per suite, so they are safe to run in any environment without affecting persistent data.

Running tests

surrealkit test

SurrealKit reads all suite files from database/tests/suites/*.toml, runs them in parallel (configurable), and exits non-zero if any case fails.

Project structure

database/tests/
├── config.toml          # global defaults
└── suites/
    ├── security.toml
    └── api.toml

Global config

database/tests/config.toml sets defaults shared across all suites:

[defaults]
timeout_ms = 10000
base_url = "http://localhost:8000"

[actors.root]
kind = "root"

Suite files are parsed strictly: an unknown key in a case, an actor, or the global config is an error rather than being ignored, so a typo fails the run instead of quietly disabling a check.

Test types

SurrealKit supports five test types, specified via the kind field on each test case.

sql_expect

Runs a SurrealQL statement and asserts whether it succeeds or fails:

[[cases]]
name = "guest_cannot_create_order"
kind = "sql_expect"
actor = "guest"
sql = "CREATE order CONTENT { total: 10 };"
allow = false
error_contains = "permission"

Optional assertions check the returned data:

[[cases]]
name = "user_sees_own_profile"
kind = "sql_expect"
actor = "user_alice"
sql = "SELECT * FROM user WHERE id = $auth.id;"
allow = true

[[cases.assertions]]
path = "0.id"
equals_auth = "$auth.id"

Missing paths fail

Available since: v1.0

An assertion whose path is not present in the result fails with path '<path>' not found, rather than the comparison being skipped. The same applies to a header_assertions entry naming a header the response never sent. This catches typos and queries that matched zero rows.

To assert that a value is genuinely absent, state it explicitly. exists = false is the only specification that passes on a missing path:

[[cases.assertions]]
path = "0.secret"
exists = false

Paths are dot-separated. A segment that parses as a number indexes an array, and anything else keys an object, so 0.owner.name reaches the first row's owner name. There is no bracket syntax, no $. prefix, and no escaping, so a field whose name contains a dot cannot be addressed.

permissions_matrix

Validates that a single actor has the expected create / select / update / delete permissions on a table or record:

[[cases]]
name = "reader_cannot_modify_orders"
kind = "permissions_matrix"
actor = "reader"
table = "order"
record_id = "order:test"

[[cases.rules]]
action = "select"
allow = true

[[cases.rules]]
action = "update"
allow = false
error_contains = "permission"

schema_metadata

Asserts structural facts about the schema: that a field exists with a given type, that an index is defined, and so on.

schema_behavior

Tests computed fields, functions, and record relations by asserting on the values returned after specific operations.

api_request

Tests HTTP API endpoints, useful when your SurrealDB instance exposes a custom API layer:

[[cases]]
name = "orders_endpoint_returns_200"
kind = "api_request"
actor = "root"
method = "GET"
path = "/api/orders"
expected_status = 200

[[cases.body_assertions]]
path = "0.id"
exists = true

Actors

Each test case runs as a named actor with a specific authentication method. Actors are defined in config.toml or at the suite level.

[actors.user_alice]
kind = "record"
access = "app_access"

[actors.user_alice.signin_params]
email = "alice@example.com"
password = "secret"

[actors.tenant_a]
kind = "headers"
headers = { "x-tenant-id" = "tenant_a" }

Filtering

Debugging

Next steps

• •

  CI / CD: integrate tests into automated pipelines with GitHub Actions and Docker Compose