boxel: Skill for Claude Code

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