Skip to content

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.

CommandWhat it runs
pnpm test --rununit and nuxt
pnpm test:unit --rununit only, in seconds
pnpm test:nuxt --runnuxt only
pnpm test:coverageBoth, with v8 coverage
pnpm test:e2eEvery Playwright spec, about three minutes
pnpm test:e2e:smokeThe specs tagged @smoke: sign-in and payments paths
pnpm test:e2e:uiPlaywright's UI mode
KIT_SUITES=app pnpm test --runWhat 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

  • unit runs layers/kit/test/unit/*.test.ts and your suites anywhere under test/unit/, in Node. layers/kit/vitest.config.ts(Licensees only) holds both projects' include globs. It gives unit the #server, #shared, #layers/kit, ~ and ~~ aliases, and points every build-generated #*-registry module at a stub in layers/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.
  • nuxt runs layers/kit/test/nuxt/*.test.ts and your suites anywhere under test/nuxt/ through @nuxt/test-utils in happy-dom. The first mount in a file boots the app, so tests and hooks get 20 seconds.
  • e2e runs every *.spec.ts under layers/kit/test/e2e/ and your test/e2e/ against nuxt dev in Chromium, one worker at a time.
  • KIT_SUITES=app narrows all three to your app. unit and nuxt run your suites and the kit suites layers/kit/test/helpers/app-suites.ts names, the ones that check your files and config, and e2e runs your test/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 fileReads
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/ and test/nuxt/ at the root. Every suite outside layers/kit/ reads your config.
  • i18n always 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.jsonc declares while your queue is on, that it hands nitro exactly the schedule you declare, and that every image your content's frontmatter names is allowed by your own img-src.
  • pnpm typecheck is 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 nuxt project only what your code imports is pinned. Runtime config, the #*-registry modules 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 test runs them. The nuxt project 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', …) and vi.importActual work as before, on whichever config the file reads.
  • The Playwright suite has no such redirect. It reads your starter.config.ts and 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 unit project. Stub each one the code reads with vi.stubGlobal, and import the module under test after the stubs, with await import().
  • pnpm typecheck checks test/unit/, test/e2e/ and every job with every name nitro auto-imports, yours in server/utils/ and shared/utils/ included, typed as on the server, and with the Cloudflare runtime types. Type a stub by the helper it replaces, such as typeof createError, and install it only with vi.stubGlobal: nitro's and h3's helpers are not properties of globalThis. A fetch response's json() returns unknown, as on the server, so name its type: response.json<{ total: number }>().
  • stubDatabaseGlobals(orm) installs useDrizzle, tables with your tables beside the kit's, createError, setResponseHeader, isUniqueConstraintError and the query operators.
  • Seed without ids and use the ones returning hands 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.client is the PGlite itself, for a raw query(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()
  }))
  • UApp provides the tooltip context. A bare mountSuspended of anything that renders a UTooltip throws from inside Reka UI.
  • A toast's close timer outlives the test and throws once the file's page is torn down. TIMERLESS_TOASTER stops that, and layers/kit/test/unit/uapp-mount-toaster.test.ts(Licensees only) fails on a UApp mount 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 $fetch with mockNuxtImport, as layers/kit/test/nuxt/checkout-button.test.ts(Licensees only) does. vi.stubGlobal('$fetch', …) never reaches a component.
  • Every mockNuxtImport('useRoute', …) returns an object with a query, 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/….

HelperUse it to
useTestDatabase() in test-database.tsGet a migrated PGlite per file, emptied before each test. unit only
stubDatabaseGlobals(orm) in database-globals.tsInstall the auto-imports a database-backed module reads, with tables holding your tables beside the kit's
withStarterConfig(patch, fn) in starter-config.tsOverlay sections of starter.config while fn runs, and restore them when it returns or settles
withTenancy(fn, orgs?) in orgs-config.tsRun fn with organizations and invitations on
withPublicConfig(section, patch, fn) in runtime-config.tsPatch runtimeConfig.public the same way. nuxt only
starterConfigFixture(patch) in starter-config-fixture.tsBuild a complete StarterConfig to return from vi.mock
MONTHLY_PLAN, TWO_INTERVAL_PLAN, ONE_TIME_PLANPriced plans to spread into a config patch
fakeH3Event, fakeNitroApp, fakeRoute, fakeResponseType a partial fake of a large external type, with the cast in one place
TIMERLESS_TOASTER, TIMERLESS_TOASTER_COLLAPSEDMount UApp with toasts that never close on their own
rememberCoupon, forgetCoupon, rememberedCouponPlant, clear and read the coupon cookie. Call forgetCoupon in beforeEach. nuxt only
inMemoryThrottles() and fake-durable-object.tsRun the real rate limiter over in-memory storage
installEvents() in events.tsRecord what the event bus emits, and run deferred listeners with settled()
registerListener(listener) in listeners.tsRun a real listener file on the installEvents() bus, in its own mode
fake-pg.ts, mocked in as pgRun 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:

HelperWhat 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:unit and test:nuxt on every pull request and every push to main, and a build job beside it. In your repository the two test steps run with KIT_SUITES=app: your suites, plus the 31 kit suites that check your files and config, such as i18n-locales, migration-freshness, events-catalogue and icon-client-bundle. The kit's other suites pass in the kit's own repository on the same layers/kit/ you have, so your CI skips them, about nine minutes a run; pnpm test still 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 on main that commit or the pull request that merged as it. ci-tree-pass, one of the 31, fails when your ci.yml takes a pass any other run recorded. The changed-config job runs only in the kit's own repository, so yours shows it skipped: it checks that layers/kit/test/shipped/starter.config.ts still matches the kit's config, typechecks under layers/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 under layers/kit/test/changed/starter.config.ts, an app's config with nearly every switch flipped and English alone, with content/sr/ deleted and the app task that config schedules copied in from layers/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 the e2e label to a pull request, on every push while the label stays, or by hand. In your repository it runs every spec in your test/e2e/ and none of the kit's, and passes when you have none; in the kit's own it runs test: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

SettingWhereDefaultWhat it does
hookTimeoutlayers/kit/vitest.config.ts20_000 in both projectsTime for PGlite to open and Nuxt to boot in beforeAll
testTimeoutlayers/kit/vitest.config.ts20_000 in nuxtTime per component test, including the first boot
silentlayers/kit/vitest.config.ts'passed-only'Prints console output only for failing tests
PASSKEY_TESTS, MULTI_LOCALE_TESTS, EMAIL_TEMPLATE_TESTSlayers/kit/vitest.config.tsexcluded when their feature is offSuites skipped while auth.passkey is off, with one language, or with email off
workerslayers/kit/playwright.config.ts1Every worker would start its own nuxt dev
timeoutlayers/kit/playwright.config.ts30 s, 90 s on CITime per spec
retries, maxFailureslayers/kit/playwright.config.ts0 locally, 2 on CIRetries per spec, and failed specs before the run stops (0 is no limit)
serverStartTimeoutlayers/kit/playwright.config.ts60 s, 240 s on CITime 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 the tx you were given.
  • PGlite can't race two transactions. To test a race, spy on database.orm.transaction and run the competing write just before the real one opens, as admin-ban.test.ts does.
  • unovis charts never settle under happy-dom. Replace DashboardStackedBarChart with mockComponent in any test that mounts a card holding one.
  • happy-dom's :has() ignores descendant combinators, so body:has(A B) matches whenever an A exists. Query A B directly instead.
  • A vi.mock('drizzle-orm', …) that replaces the whole module breaks a suite whose imports reach #layers/kit/server/database/connection, as emit does: loading the schema needs sql from it, and whatever your own schema imports. Spread importOriginal() and replace only what the test fakes, as link-tokens.test.ts does.
  • A type-level test is a // @ts-expect-error above a call in a closure that never runs, with expect.assertions(0). pnpm typecheck covers layers/kit/test/unit/ and your test/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.