realm-server-test-setup
/realm-server-test-setup
How to set up realms in a packages/realm-server test module without indexing them from scratch before every test — which helper to use (setupPermissionedRealmCached, setupPermissionedRealmsCached, setupTestDatabaseTemplate), when a test genuinely needs a fresh boot index, and how the template database works. Use whenever writing a new realm-server test module, adding a module or test that brings up realms, copying an existing suite as a starting point, or working out why a realm-server module is slow. Triggers on the `@cardstack/boxel/realm-server-test-template-database` lint error, runTestRea
- Author
- cardstack ↗
- Repository
- boxel ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
How to set up realms in a packages/realm-server test module without indexing them from scratch before every test — which helper to use (setupPermissionedRealmCached, setupPermissionedRealmsCached, setupTestDatabaseTemplate), when a test genuinely needs a fresh boot index, and how the template database works. Use whenever writing a new realm-server test module, adding a module or test that brings up realms, copying an existing suite as a starting point, or working out why a realm-server module is slow. Triggers on the `@cardstack/boxel/realm-server-test-template-database` lint error, runTestRea
Original author description
How to set up realms in a packages/realm-server test module without indexing them from scratch before every test — which helper to use (setupPermissionedRealmCached, setupPermissionedRealmsCached, setupTestDatabaseTemplate), when a test genuinely needs a fresh boot index, and how the template database works. Use whenever writing a new realm-server test module, adding a module or test that brings up realms, copying an existing suite as a starting point, or working out why a realm-server module is slow. Triggers on the `@cardstack/boxel/realm-server-test-template-database` lint error, runTestRea
How it works
- Pick the helper
- When a test still needs a fresh index
- A before hook is not the same thing
- Checking a module's cost
SKILL.md preview
---
name: realm-server-test-setup
description: How to set up realms in a packages/realm-server test module without indexing them from scratch before every test — which helper to use (setupPermissionedRealmCached, setupPermissionedRealmsCached, setupTestDatabaseTemplate), when a test genuinely needs a fresh boot index, and how the template database works. Use whenever writing a new realm-server test module, adding a module or test that brings up realms, copying an existing suite as a starting point, or working out why a realm-server module is slow. Triggers on the `@cardstack/boxel/realm-server-test-template-database` lint error, runTestRealmServer, runTestRealmServerWithRealms, setupDB with a beforeEach that starts realms, setupPermissionedRealm(s), or "realm-server tests are slow".
---
# Realm-server test setup
Bringing up a realm on an empty database indexes it from scratch, and that index — not the test body — is usually most of a realm-server test's time. A module that brings up its realms in `beforeEach` pays it once per test. Index once per module instead: every helper below builds a **template database** the first time a module needs it, and each test then starts from a copy of that template. The two cached realm helpers also give each test a fresh realm directory holding the same files. `setupTestDatabaseTemplate` copies only the database, so there the fresh directory is your `start`'s job (see below).
The cost is real. A 40-test suite that brought up two realms before every test took 524s; indexed once into a template it took 85s. Nineteen such suites together went from 46 minutes to 13 minutes of CI time, about five minutes off every Realm Server shard.
The `@cardstack/boxel/realm-server-test-template-database` lint rule enforces this. It reports a `setupDB` whose `beforeEach` brings up realms (`runTestRealmServer`, `runTestRealmServerWithRealms`, `startSimpleRealmServer`, or `start()` on a `createRealm` realm, directly or through a function in the same file) and passes no `templateDatabase`, and a `setupPermissionedRealm` or `setupPermissionedRealms` call without `mode: 'before'`. CI Lint fails on both. The rule checks only that a template is there, not what it holds, so a template that leaves out some of the module's realms passes it: keep `build` and `beforeEach` bringing up the same realms.
## Pick the helper
| Your module brings up | Use |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| One realm | `setupPermissionedRealmCached(hooks, { realmURL, permissions, fileSystem \| fixture, onRealmSetup })` |
| Several realms, each on its own realm server | `setupPermissionedRealmsCached(hooks, { realms: [...], onRealmSetup })` |
| Several realms on **one** realm server, or any other setup of your own | `setupTestDatabaseTemplate` beside `setupDB` (below) |
All three live in `packages/realm-server/tests/helpers/index.ts`. `setupPermissionedRealmsCached` starts every realm on its own server and virtual network, so it does not fit realms that must reach each other through one server — for example a realm whose policy card lives in another realm, which the server loads on its own authority. Use `setupTestDatabaseTemplate` for those.
### `setupTestDatabaseTemplate`
Keep the suite's own `start()`, move its teardown into a function, and hand both to the template:
```ts
async function stop() {
for (let realm of [education, org]) {
realm.__testOnlyClearCaches();
realm.unsubscribe();
}
await closeServer(server);
resetCatalogRealms();
}
let templateDatabase = setupTestDatabaseTemplate(hooks, {
key: import.meta.filename,
build: async (args) => {
await start(args); // the same start() beforeEach calls
return stop;
},
});
setupDB(hooks, {
templateDatabase,
beforeEach: async (dbAdapter, publisher, runner) => {
await start({ dbAdapter, publisher, runner });
},
afterEach: stop,
});
```
`build` runs once per key per test process, against a builder database. The helper waits for its queue to drain (index and prerender jobs both), tears it down with the function `build` returns, and snapshots the database as the template.
- **`key`** must be unique to what `build` writes, across every module in the run: the template cache is shared by the whole test process. The module's full path, `import.meta.filename`, is right when the module has one `start()`. Its `basename` is not, because modules in different directories share names (`realm-endpoints/info-test.ts` and `server-endpoints/info-test.ts`), and the second to build would silently get the first one's snapshot. A module that builds two different setups needs two keys.
- **`build` must bring up exactly what `beforeEach` does.** A realm that boots on a copy finds its index there and skips its boot index (`Realm#startup` runs one only on a new index or with `fullIndexOnStartup`). Anything `beforeEach` adds that `build` didn't is never indexed.
- **`start` must write a fresh realm directory every time it runs.** The helper copies the database and nothing else. Give each call its own directory, as the policy suites do with `realmsRootPath = join(dirSync().name, 'realm_server_1')`, and write the realm's files there. A directory reused between tests carries files an earlier test wrote into the next one, whose copy of the database knows nothing about them.
- `build` runs in a `hooks.before`, so it runs before every `hooks.beforeEach` in the module. A directory a `hooks.beforeEach` creates (`dir = dirSync()`) does not exist yet when `build` runs. Create the directory inside `start`.
- Rows `start()` writes besides the index (realm permissions and the like) are upserts, so writing them again on a copy is safe. A row the module adds with a plain `INSERT` (`insertUser`, a plan, a token) is not: keep it out of `start` and add it in `beforeEach` after `start` returns, or every test's copy fails on a duplicate key.
## When a test still needs a fresh index
Leave a module uncached only when what it tests is the boot index itself: indexing from an empty database, `fullIndexOnStartup`, or what a realm does when its index is missing. Disable the lint rule there, and give the reason in the comment, so the next person doesn't "fix" it:
```ts
setupDB(hooks, {
// eslint-disable-next-line @cardstack/boxel/realm-server-test-template-database -- tests indexing from an empty database
beforeEach: async (dbAdapter, publisher, runner) => {
await start({ dbAdapter, publisher, runner });
},
});
```
A disable with no reason, or a reason other than the boot index, does not pass review.
A test that changes files during the test is not one of these. Write through the realm (`realm.write`, then `await realm.indexing()`) and the index follows, as it would on a fresh database.
## A `before` hook is not the same thing
`setupDB(hooks, { before })` brings the realms up once for the whole module and shares them between tests. That is fast, but every test sees what earlier tests wrote. Use it only when no test changes realm state. When tests do change state, a template plus a fresh directory per test keeps them isolated at nearly the same cost.
## Checking a module's cost
`packages/realm-server/tests/test-module-timings.json` on main holds each module's measured seconds. Divide by the number of `test(` calls for a per-test cost: cached modules typically run 2–4s per test, and a module paying a from-scratch index per test typically runs 6–13s. To measure one module locally, use `./scripts/measure-test-file.sh <file-without-.ts> [runs]` from `packages/realm-server`.
Versions
The database has no other skills named realm-server-test-setup.
Database snapshot: 13.11.2026 · package version fbbc6f715719 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 84realm-sync
Move files between local disk and a Boxel realm. Use when the user wants to push local changes up, pull a realm down, do a bidirectional sync, watch a realm for continuous remote-to-local mirroring, create or remove a realm, or list realms accessible to the active profile. - 100boxel-api
Use when calling Boxel realm-server APIs from code — primarily federated search across realms. Documents the boxel-cli programmatic surface (`BoxelCLIClient`) and the matching CLI commands. Read this whenever you need to query a realm's index. - 100database-test-helper
Assist with database test helper operations. Auto-activating skill for Test Automation. Triggers on: database test helper, database test helper Part of the Test Automation skill category. Use when writing or running tests. Trigger with phrases like "database test helper",… - 100glua-realms-hooks
Explains Garry's Mod Lua realms (server, client, shared, menu), how file location decides where a file runs, the AddCSLuaFile + include loading pattern, and the hook library (hook.Add, hook.Remove, hook.Run). Use when writing or reviewing any GLua addon code, deciding where a… - 100keycloak-tests
Authors and runs integration tests against Keycloak - uses Testcontainers Keycloak module to spin up an isolated server per test class, imports realm JSON for fixtures, exercises OIDC discovery / token endpoint / token introspection / admin REST API; tests password /… - 100snapshot-test-helper
Assist with snapshot test helper operations. Auto-activating skill for Test Automation. Triggers on: snapshot test helper, snapshot test helper Part of the Test Automation skill category. Use when writing or running tests. Trigger with phrases like "snapshot test helper",…