Quality
Testing
The kit has three suites. unit runs server and shared code in plain Node,
nuxt mounts components inside a real Nuxt app, and e2e drives a browser
through nuxt dev with Playwright. You work here when you test your own code.
The kit's suites live in layers/kit/test/; yours go in test/unit/,
test/nuxt/ and test/e2e/ at the root, and the same commands run both.
Changing starter.config.ts fails none of the kit's own suites: Your config
and the kit's suites says why.
| Command | What it runs |
|---|---|
pnpm test --run | unit and nuxt |
pnpm test:unit --run | unit only, in seconds |
pnpm test:nuxt --run | nuxt only |
pnpm test:coverage | Both, with v8 coverage |
pnpm test:e2e | Every Playwright spec, about three minutes |
pnpm test:e2e:smoke | The specs tagged @smoke: sign-in and payments paths |
pnpm test:e2e:ui | Playwright's UI mode |
KIT_SUITES=app pnpm test --run | What your CI runs: your suites and the kit suites that check your app |
pnpm test without --run starts Vitest in watch mode.
How it works
unitrunslayers/kit/test/unit/*.test.tsand your suites anywhere undertest/unit/, in Node.layers/kit/vitest.config.ts(Licensees only) holds both projects' include globs. It givesunitthe#server,#shared,#layers/kit,~and~~aliases, and points every build-generated#*-registrymodule at a stub inlayers/kit/test/unit/with no adapters, so dispatch does nothing unless a test supplies an adapter. Its global setup migrates one PGlite database per run.nuxtrunslayers/kit/test/nuxt/*.test.tsand your suites anywhere undertest/nuxt/through@nuxt/test-utilsin happy-dom. The first mount in a file boots the app, so tests and hooks get 20 seconds.e2eruns every*.spec.tsunderlayers/kit/test/e2e/and yourtest/e2e/againstnuxt devin Chromium, one worker at a time.KIT_SUITES=appnarrows all three to your app.unitandnuxtrun your suites and the kit suiteslayers/kit/test/helpers/app-suites.tsnames, the ones that check your files and config, ande2eruns yourtest/e2e/alone. Your CI sets it (In CI).- A passing test prints nothing. Console output shows only for tests that fail
(
silent: 'passed-only').
Your config and the kit's suites
The kit's suites test the configuration the kit ships, whatever your
starter.config.ts says, so turning payments off or taking a permission from a
role fails none of them. In both vitest projects, every import of
starter.config.ts resolves to
layers/kit/test/helpers/suite-starter-config.ts, which answers according to
the test file that is running:
| Test file | Reads |
|---|---|
A kit suite in layers/kit/test/unit/ or layers/kit/test/nuxt/ | layers/kit/test/shipped/starter.config.ts, the kit's config byte for byte, with your i18n |
A kit suite named in LIVE_CONFIG_SUITES (layers/kit/test/helpers/live-config-suites.ts) | Your starter.config.ts |
Yours, anywhere under test/unit/ or test/nuxt/ | Your starter.config.ts |
- Put your own suites in
test/unit/andtest/nuxt/at the root. Every suite outsidelayers/kit/reads your config. i18nalways comes from your config, because your languages and the built app follow it.- The kit suites that read your config check it against your own files: that
each language has copy for every plan, role and organization level you
declare, that the build accepts the queues your
wrangler.jsoncdeclares while your queue is on, that it hands nitro exactly thescheduleyou declare, and that every image your content's frontmatter names is allowed by your ownimg-src. pnpm typecheckis outside this. It types every kit file against your config, and passes whichever roles, org roles, levels, AI roles and flags you rename, replace or remove.- In the
nuxtproject only what your code imports is pinned. Runtime config, the#*-registrymodules and the i18n setup are built from your config, and so are the exclusions under Configuration. - Your own code runs inside the kit's component suites too, wherever
pnpm testruns them. Thenuxtproject boots the whole app for each one, so your composables, plugins and layouts read the kit's config there. Read your own plans, roles and purposes inside the function that needs them, and treat one the config does not declare as absent: a lookup at a composable's top level fails every kit component suite before its first test. withStarterConfig,vi.mock('~~/starter.config', …)andvi.importActualwork as before, on whichever config the file reads.- The Playwright suite has no such redirect. It reads your
starter.config.tsand skips what you turned off or deleted; see Run the end-to-end suite.
layers/kit/test/unit/schema-cascades.test.ts sweeps every column that
references users, in your tables too. Erasing an account deletes its users
row, so a key that neither cascades nor sets null makes the erasure fail. A
column you set null on purpose, or one that keeps no key so a record outlives
the account, goes in test/helpers/schema-cascades.ts at the root, keyed
table.column:
export const USER_COLUMNS_WITHOUT_FOREIGN_KEY: Record<string, string> = {
'admin_audit.actor_user_id':
'the staff audit trail outlives the staff account, as activity_log does',
}
export const USER_COLUMNS_SET_NULL: string[] = ['creators.user_id']
Test a server route
Import the route's default export and call it with a fake event. The database is
real Postgres (PGlite), migrated and emptied before every test. This is a
trimmed
layers/kit/test/unit/admin-ban.test.ts(Licensees only):
import { eq } from 'drizzle-orm'
import { afterEach, beforeEach, expect, it, vi } from 'vitest'
import { z } from 'zod'
import * as schema from '#layers/kit/server/database/schema'
import { stubDatabaseGlobals } from '../helpers/database-globals'
import { fakeH3Event } from '../helpers/fake-h3-event'
import { useTestDatabase } from '../helpers/test-database'
vi.stubGlobal('defineEventHandler', (handler: unknown) => handler)
vi.stubGlobal('z', z)
const { default: banRoute } =
await import('#layers/kit/server/api/admin/users/ban.post')
const database = useTestDatabase()
beforeEach(() => {
stubDatabaseGlobals(database.orm)
vi.stubGlobal('requirePermission', () => Promise.resolve({ user: { id: 1 } }))
vi.stubGlobal(
'readValidatedBody',
(event: { body: unknown }, parse: (input: unknown) => unknown) =>
Promise.resolve(parse(event.body)),
)
vi.stubGlobal('recordActivity', vi.fn())
})
afterEach(() => {
vi.unstubAllGlobals()
})
it('suspends a customer', async () => {
const [, customer] = await database.orm
.insert(schema.users)
.values([
{ email: 'admin@example.test', role: 'superadmin' },
{ email: 'customer@example.test', role: 'user' },
])
.returning({ id: schema.users.id })
await banRoute(fakeH3Event({ body: { userId: customer!.id, banned: true } }))
const [row] = await database.orm
.select({ bannedAt: schema.users.bannedAt })
.from(schema.users)
.where(eq(schema.users.id, customer!.id))
expect(row?.bannedAt).not.toBeNull()
})
- A suite of yours in
test/unit/imports the helpers through#layers/kit/test/helpers/…, and your own route through#server/…. - Nuxt's auto-imports don't exist in the
unitproject. Stub each one the code reads withvi.stubGlobal, and import the module under test after the stubs, withawait import(). pnpm typecheckcheckstest/unit/,test/e2e/and every job with every name nitro auto-imports, yours inserver/utils/andshared/utils/included, typed as on the server, and with the Cloudflare runtime types. Type a stub by the helper it replaces, such astypeof createError, and install it only withvi.stubGlobal: nitro's and h3's helpers are not properties ofglobalThis. Afetchresponse'sjson()returnsunknown, as on the server, so name its type:response.json<{ total: number }>().stubDatabaseGlobals(orm)installsuseDrizzle,tableswith your tables beside the kit's,createError,setResponseHeader,isUniqueConstraintErrorand the query operators.- Seed without ids and use the ones
returninghands back. Identities restart at 1 before every test, and an insert that names its id doesn't move the sequence, so the next generated id would collide with it. database.clientis the PGlite itself, for a rawquery(text, params)when SQL reads more plainly than the builder.
Test a component
Mount through UApp when the component can show a toast or a tooltip, and pass
the timerless toaster:
import { mountSuspended, registerEndpoint } from '@nuxt/test-utils/runtime'
import UApp from '@nuxt/ui/components/App.vue'
import { flushPromises } from '@vue/test-utils'
import { expect, it } from 'vitest'
import { h } from 'vue'
import ReportCard from '~/components/ReportCard.vue'
import { withStarterConfig } from '#layers/kit/test/helpers/starter-config'
import { TIMERLESS_TOASTER } from '#layers/kit/test/helpers/toaster'
registerEndpoint('/api/reports', () => ({ total: 3 }))
it('shows the report count', () =>
withStarterConfig({ payments: { enabled: false } }, async () => {
const app = await mountSuspended(UApp, {
props: { toaster: TIMERLESS_TOASTER },
slots: { default: () => h(ReportCard) },
})
await flushPromises()
expect(app.text()).toContain('3')
app.unmount()
}))
UAppprovides the tooltip context. A baremountSuspendedof anything that renders aUTooltipthrows from inside Reka UI.- A toast's close timer outlives the test and throws once the file's page is
torn down.
TIMERLESS_TOASTERstops that, andlayers/kit/test/unit/uapp-mount-toaster.test.ts(Licensees only) fails on aUAppmount without it in the kit's suites. - Unmount what you mount. A leftover page keeps following the shared router, re-renders on every later test, and slows the file until it times out.
- Answer requests with
registerEndpoint. To make one fail, mock$fetchwithmockNuxtImport, aslayers/kit/test/nuxt/checkout-button.test.ts(Licensees only) does.vi.stubGlobal('$fetch', …)never reaches a component. - Every
mockNuxtImport('useRoute', …)returns an object with aquery, or the SEO module throws after the test passes.
Helpers and stubs
The shared helpers live in
layers/kit/test/helpers/(Licensees only). The kit's suites
import them by relative path, and yours through #layers/kit/test/helpers/….
| Helper | Use it to |
|---|---|
useTestDatabase() in test-database.ts | Get a migrated PGlite per file, emptied before each test. unit only |
stubDatabaseGlobals(orm) in database-globals.ts | Install the auto-imports a database-backed module reads, with tables holding your tables beside the kit's |
withStarterConfig(patch, fn) in starter-config.ts | Overlay sections of starter.config while fn runs, and restore them when it returns or settles |
withTenancy(fn, orgs?) in orgs-config.ts | Run fn with organizations and invitations on |
withPublicConfig(section, patch, fn) in runtime-config.ts | Patch runtimeConfig.public the same way. nuxt only |
starterConfigFixture(patch) in starter-config-fixture.ts | Build a complete StarterConfig to return from vi.mock |
MONTHLY_PLAN, TWO_INTERVAL_PLAN, ONE_TIME_PLAN | Priced plans to spread into a config patch |
fakeH3Event, fakeNitroApp, fakeRoute, fakeResponse | Type a partial fake of a large external type, with the cast in one place |
TIMERLESS_TOASTER, TIMERLESS_TOASTER_COLLAPSED | Mount UApp with toasts that never close on their own |
rememberCoupon, forgetCoupon, rememberedCoupon | Plant, clear and read the coupon cookie. Call forgetCoupon in beforeEach. nuxt only |
inMemoryThrottles() and fake-durable-object.ts | Run the real rate limiter over in-memory storage |
installEvents() in events.ts | Record what the event bus emits, and run deferred listeners with settled() |
registerListener(listener) in listeners.ts | Run a real listener file on the installEvents() bus, in its own mode |
fake-pg.ts, mocked in as pg | Run the real useDatabase and releaseDatabase over recording pools. unit only |
A module that reads starter.config when it is imported can't be patched
afterwards. Mock the config before the import instead:
vi.mock('~~/starter.config', async () => {
const { MONTHLY_PLAN, starterConfigFixture } =
await import('#layers/kit/test/helpers/starter-config-fixture')
return {
default: starterConfigFixture({
payments: {
enabled: true,
modes: ['subscription'],
providers: ['stripe'],
plans: { pro: { ...MONTHLY_PLAN } },
},
}),
}
})
The fixture's roles and grants are a fixed baseline, independent of your
starter.config.ts, so editing your config doesn't change what these tests
exercise.
To give each test a config of its own, call vi.resetModules() in beforeEach,
then vi.doMock('~~/starter.config', …) and await import() the module inside
the test, as
layers/kit/test/nuxt/oauth-provider-meta.test.ts(Licensees only)
does.
For the rate limiter, mock cloudflare:workers with the fake and put the
throttles on the event's bindings:
vi.mock(
'cloudflare:workers',
() => import('#layers/kit/test/helpers/fake-durable-object'),
)
const event = fakeH3Event({
context: { cloudflare: { env: { AUTH_THROTTLE: inMemoryThrottles() } } },
})
To check that your own task or waitUntil work ends its database pool
(Scheduled tasks), mock pg with the fake
and stub the real database auto-imports from #layers/kit/server/utils/drizzle
instead of calling stubDatabaseGlobals, so useDrizzle opens a pool. Pass a
HYPERDRIVE binding, as a task's context.cloudflare or as the first argument
of withFabricatedEvent:
import * as drizzleAutoImports from '#layers/kit/server/utils/drizzle'
import { resetFakePg } from '#layers/kit/test/helpers/fake-pg'
vi.mock('pg', () => import('#layers/kit/test/helpers/fake-pg'))
const invocation = {
env: { HYPERDRIVE: { connectionString: 'postgres://app@db.test:5432/app' } },
context: {},
}
beforeEach(() => {
for (const [name, value] of Object.entries(drizzleAutoImports)) {
vi.stubGlobal(name, value)
}
resetFakePg()
})
A task's run takes the whole event:
await task.run({
name: 'acme:digest',
payload: {},
context: { cloudflare: invocation },
})
openedPools and latestPool() report each pool's connection string and
whether it ended, sentStatements and releasedClients record the traffic,
and failNextStatements and refuseNextCheckouts queue failures. A pool
rejects every query after end(), with pg's own message.
layers/kit/test/unit/task-database-release.test.ts(Licensees only)
runs every kit task this way.
In the unit project, import.meta.dev reads globalThis.__IMPORT_META_DEV__
and import.meta.prerender reads globalThis.__IMPORT_META_PRERENDER__. Both
are false until a test sets them, for example with
vi.stubGlobal('__IMPORT_META_DEV__', true) to run a dev-only branch.
A new build-generated #…-registry module needs a stub in
layers/kit/test/unit/ and an alias in two places: UNIT_ALIASES in
layers/kit/vitest.config.ts, and
typescript.nodeTsConfig.compilerOptions.paths in layers/kit/nuxt.config.ts,
which typechecks the same files.
Run the end-to-end suite
pnpm exec playwright install chromium
pnpm test:e2e
layers/kit/playwright.config.ts(Licensees only) starts
nuxt dev itself and supplies what a fresh clone lacks: a session password, an
empty NUXT_SITE_URL, NUXT_DEV_PAGE_CACHE=true, so /blog and /legal
pages cache as on a deploy, dummy Stripe keys with a price mapped to the first
ref slot of your first subscription plan (pro's monthly one in the kit), and
a wrangler config without the AI binding. The dev server migrates the PGlite it
serves before it serves the app, so the suite runs on a fresh clone. Global
setup clears the local CACHE KV and Nuxt's dev payload cache before each run,
and keeps the database.
Stop a running pnpm dev first, or point both at one Postgres through
DATABASE_URL: the dev server the suite starts stops while another process of
this checkout has .data/pglite open (Database).
Put your own specs in test/e2e/ at the root. A spec imports test and
expect from #layers/kit/test/e2e/fixtures, never from
@nuxt/test-utils/playwright directly, and a unit test enforces it.
The kit's specs read your starter.config.ts and your files, and skip what your
app turned off or deleted, so the suite passes on your build without an edit.
Most assertions in the default language are the kit's English copy, written
into the specs, so a default locale in another language, or English copy you
rewrote, can still fail them. Your own specs can use the same helpers:
| Helper | What it tells a spec |
|---|---|
shipped in layers/kit/test/e2e/starter.ts(Licensees only) | What your config turns on: the sign-in method, password reset, passkeys, TOTP, photo upload, payments, guest checkout, an organization created at signup, a second language, and the first role granting users:read |
sample in layers/kit/test/e2e/sample.ts(Licensees only) | Whether the blog, the sample posts, the draft legal pages and the security settings page are still on disk. A page counts when your app or the kit has it. Only an app skips them: without .template-base, every sample case runs |
layers/kit/test/e2e/locales.ts(Licensees only) | defaultLocale, otherLocale (the first locale that is not the default), localeOf(code), localized(locale, path) and browserLanguage(locale), and a string from a locale file through localeMessage or optionalLocaleMessage |
This spec, in test/e2e/, signs a registered account in:
import {
PASSWORD,
seedAccount,
uniqueEmail,
} from '#layers/kit/test/e2e/accounts'
import { expectOnDashboard } from '#layers/kit/test/e2e/dashboard'
import { test } from '#layers/kit/test/e2e/fixtures'
import { shipped } from '#layers/kit/test/e2e/starter'
test.skip(!shipped.usesPassword, 'this build has no password registration')
test('a registered account signs in', async ({ page, goto, request }) => {
const email = uniqueEmail()
await seedAccount(request, email)
await goto('/auth/login', { waitUntil: 'hydration' })
await page.getByLabel('Email').fill(email)
await page.getByLabel('Password', { exact: true }).fill(PASSWORD)
await page.getByRole('button', { name: 'Sign in', exact: true }).click()
await expectOnDashboard(page)
})
skipWithout(value, reason) from the fixtures skips the test while value is
undefined and narrows its type otherwise. Call it inside a test or a hook: at
file or describe scope Playwright's test.skip marks the tests and returns, so
the code after it runs with the value still undefined. A test.skip on a
boolean, as above, works at any scope.
Your CI runs every spec in your test/e2e/ (In CI).
pnpm test:e2e:smoke runs only the specs tagged @smoke; pass
{ tag: '@smoke' } as the second argument of test() to add one.
layers/kit/test/e2e/accounts.ts(Licensees only) holds
the shared password, uniqueEmail(), seedAccount(), registerInPage() and
query(sql), which reads the dev server's database. Fresh addresses use the
seed domain, so pnpm db:seed --reset clears what the suite leaves behind.
seedAccount registers through the standalone request fixture; use
registerInPage when the page itself needs the session cookie. Both skip the
calling test on a build without password registration.
To watch the skips on a build that changes nearly everything, change a scratch
clone of the kit the way changed-config does, delete the blog, mark
the clone as an app, and run the suite. The blog pages count while the kit has
them, so the clone deletes the kit's. Nothing should fail, and every skipped
test names its reason:
cp layers/kit/test/changed/starter.config.ts starter.config.ts
cp -R layers/kit/test/changed/server/. server/
rm -r content/sr layers/kit/app/pages/blog content/en/blog
touch .template-base
pnpm test:e2e
In CI
ci.yml(Licensees only) runs lint, format check, typecheck,test:unitandtest:nuxton every pull request and every push tomain, and abuildjob beside it. In your repository the two test steps run withKIT_SUITES=app: your suites, plus the 31 kit suites that check your files and config, such asi18n-locales,migration-freshness,events-catalogueandicon-client-bundle. The kit's other suites pass in the kit's own repository on the samelayers/kit/you have, so your CI skips them, about nine minutes a run;pnpm teststill runs them. A job skips its steps on a git tree that a run of the same commit already passed: the pull request's own head, or onmainthat commit or the pull request that merged as it.ci-tree-pass, one of the 31, fails when yourci.ymltakes a pass any other run recorded. Thechanged-configjob runs only in the kit's own repository, so yours shows it skipped: it checks thatlayers/kit/test/shipped/starter.config.tsstill matches the kit's config, typechecks underlayers/kit/test/changed/typecheck/starter.config.ts, the kit's config with its roles, org roles and levels renamed, flags on and email off, then reruns typecheck and both projects underlayers/kit/test/changed/starter.config.ts, an app's config with nearly every switch flipped and English alone, withcontent/sr/deleted and the app task that config schedules copied in fromlayers/kit/test/changed/server/.commits.yml(Licensees only) runs commitlint over the pull request's title and every commit in it.e2e.yml(Licensees only) runs when you add thee2elabel to a pull request, on every push while the label stays, or by hand. In your repository it runs every spec in yourtest/e2e/and none of the kit's, and passes when you have none; in the kit's own it runstest:e2e:smoke. It needs no secrets and uploads the Playwright report when it fails.
None of these blocks a merge until a ruleset on main requires it. Rulesets
are a repository setting, so your repository needs its own. Require
ci (ubuntu-latest, 22), build and commitlint, with GitHub Actions as the
source. Renaming a job or changing the matrix changes the check name GitHub
waits for.
Configuration
| Setting | Where | Default | What it does |
|---|---|---|---|
hookTimeout | layers/kit/vitest.config.ts | 20_000 in both projects | Time for PGlite to open and Nuxt to boot in beforeAll |
testTimeout | layers/kit/vitest.config.ts | 20_000 in nuxt | Time per component test, including the first boot |
silent | layers/kit/vitest.config.ts | 'passed-only' | Prints console output only for failing tests |
PASSKEY_TESTS, MULTI_LOCALE_TESTS, EMAIL_TEMPLATE_TESTS | layers/kit/vitest.config.ts | excluded when their feature is off | Suites skipped while auth.passkey is off, with one language, or with email off |
workers | layers/kit/playwright.config.ts | 1 | Every worker would start its own nuxt dev |
timeout | layers/kit/playwright.config.ts | 30 s, 90 s on CI | Time per spec |
retries, maxFailures | layers/kit/playwright.config.ts | 0 locally, 2 on CI | Retries per spec, and failed specs before the run stops (0 is no limit) |
serverStartTimeout | layers/kit/playwright.config.ts | 60 s, 240 s on CI | Time for nuxt dev to serve its first page |
Good to know
- A test that hangs inside a transaction is almost always calling
useDrizzle(event)from the transaction callback. PGlite has one connection and the open transaction holds it. Use thetxyou were given. - PGlite can't race two transactions. To test a race, spy on
database.orm.transactionand run the competing write just before the real one opens, asadmin-ban.test.tsdoes. - unovis charts never settle under happy-dom. Replace
DashboardStackedBarChartwithmockComponentin any test that mounts a card holding one. - happy-dom's
:has()ignores descendant combinators, sobody:has(A B)matches whenever anAexists. QueryA Bdirectly instead. - A
vi.mock('drizzle-orm', …)that replaces the whole module breaks a suite whose imports reach#layers/kit/server/database/connection, asemitdoes: loading the schema needssqlfrom it, and whatever your own schema imports. SpreadimportOriginal()and replace only what the test fakes, aslink-tokens.test.tsdoes. - A type-level test is a
// @ts-expect-errorabove a call in a closure that never runs, withexpect.assertions(0).pnpm typecheckcoverslayers/kit/test/unit/and yourtest/unit/, so the directive fails the build once the error goes away.
A link with a lock opens the kit’s private repository, which every licensee can read.