realm-server-test-setup
/realm-server-test-setup
Ustawia realmy w testach packages/realm-server bez indeksowania od zera przed każdym testem, dobierając helper i szablon bazy danych.
- Autor
- cardstack ↗
- Repozytorium
- boxel ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 27.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Ustawia realmy w testach packages/realm-server bez indeksowania od zera przed każdym testem, dobierając helper i szablon bazy danych.
Oryginalny opis (EN)
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
Jak działa
- Pick the helper
- When a test still needs a fresh index
- A before hook is not the same thing
- Checking a module's cost
Podgląd SKILL.md
---
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`.
Wersje
W bazie nie ma innych skilli o nazwie realm-server-test-setup.
Migawka bazy z 13.11.2026 · wersja paczki fbbc6f715719 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 84realm-sync
Przenosi pliki między dyskiem a realmem Boxel: wysyła zmiany, pobiera realm, synchronizuje dwukierunkowo i listuje realmy. - 100boxel-api
Wywołuje API serwera realm Boxel z kodu, głównie wyszukiwanie federacyjne między realmami, i opisuje programowy interfejs boxel-cli (BoxelCLIClient) wraz z odpowiednimi poleceniami CLI. - 100database-test-helper
Prawdopodobnie pomaga w testach baz danych w automatyzacji testów. - 100glua-realms-hooks
Wyjaśnia realmy Lua w Garry's Mod, ładowanie plików AddCSLuaFile i include oraz system hooków przy pisaniu dodatków. - 100keycloak-tests
Pisze i uruchamia testy integracyjne Keycloak z Testcontainers, importuje realm z JSON i sprawdza przepływy OIDC, token exchange, admin REST API oraz uprawnienia UMA. - 100snapshot-test-helper
Prawdopodobnie pomaga w testach snapshotowych w automatyzacji testów i wyzwala się automatycznie na hasła związane z snapshot test helper.