test: `src/runtime/plugins/` is outside the vitest include patterns — the #301 crash could not have been caught

[IgorShevchik]

Follow-up from the review of #306. Not a regression — a structural gap surfaced by #301.

The gap

src/runtime/plugins/ contains three files — colors.ts, platform.ts, ui-version.ts — and none of them can be reached by the test runner. Both vitest projects list only three directories:

// vitest.config.ts:30-33 — project 'nuxt'
include: [
  'components/**/**.spec.ts',
  'composables/**.spec.ts',
  'utils/**/**.spec.ts'
]

// vitest.config.ts:53-56 — project 'vue'
include: [
  'components/**.spec.ts',
  'composables/**.spec.ts',
  'utils/**/**.spec.ts'
]

There is no plugins/** entry in either, and test/ contains no plugin spec at all.

This matters because the crash in #301 — injectHead(...).hooks.hookOnce is not a function, which broke app startup for every SPA user on Nuxt >= 4.5.1 — lived in src/runtime/plugins/colors.ts. The suite was green throughout: it never had the chance to fail.

Adding plugins/** to include is necessary but not sufficient

The vulnerable branch is gated on runtime state that component tests never reproduce:

// src/runtime/plugins/colors.ts:65
if (import.meta.client && nuxtApp.isHydrating && !nuxtApp.payload.serverRendered) {

A plain mountSuspended never enters it — which is corroborated by the fact that the full suite stayed green while the published package was crashing. So a spec has to either:

• set nuxtApp.isHydrating = true and nuxtApp.payload.serverRendered = false explicitly before invoking the plugin — the repo already has this pattern, test/components/nuxt/LinkLocale.spec.ts:11-18 hand-patches nuxtApp.$localePath; or
• extract the SPA branch of colors.ts into a named exported function that can be called directly with a mock head / nuxtApp, without booting Nuxt.

The second option is cleaner and makes the branch testable without fighting the runtime.

Cheap first step, independent of the above

A contract test pinning the shape this code depends on does not need any vitest.config.ts change — createHead from @unhead/vue/client is already imported by test/utils/mount.ts:4, so a spec under test/utils/ runs in both projects as-is.

Worth being careful about how it is written, though: asserting typeof head.hooks.hookOnce !== 'function' pins the absence of a method, and would fail if unhead ever reintroduced it even though nothing would be broken. Better to assert the behaviour we actually rely on — that registering with hook() and self-unhooking fires exactly once and does not throw.

Also uncovered

platform.ts and ui-version.ts sit in the same blind spot, and there is no e2e layer anywhere in .github/workflows/ci.yml (only lint -> typecheck -> test -> build) that would catch a "fails on real client-only boot" class of bug from the side.

Suggested scope

1. Add 'plugins/**/**.spec.ts' to the nuxt project include.
2. Add a contract spec for the unhead hooks shape under test/utils/.
3. Add a spec for the colors.ts SPA branch — refactoring the branch into an exported function first, if that turns out simpler than faking the hydration state.

[IgorShevchik]

Closed by #327 — test/plugins/ is at 15/15 and the blind spot is gone.

It took two steps.

#324 put 'plugins/**/**.spec.ts' into the vitest nuxt project and covered colors.ts, including the exact branch that broke every SPA on Nuxt ≥ 4.5.1. The spec runs the real plugin against a head object shaped like unhead v3's HookableCore — that is, without hookOnce — and patches isHydrating / payload.serverRendered on the real nuxtApp, the way test/components/nuxt/LinkLocale.spec.ts already does for $localePath. Your second bullet turned out to be the right call, but from the other direction: mocking useNuxtApp wholesale broke the harness (useRouter().afterEach disappears with it), so only injectHead / useHead are mocked and the hydration flags are set by hand.

It was verified the only way that means anything: reintroduce the crash, watch the specs go red, put it back. The first draft of that spec was green in both states — it had quietly re-implemented the plugin's logic instead of importing it.

Your warning about the contract test was taken as written. Nothing asserts typeof head.hooks.hookOnce !== 'function' — pinning the absence of a method would have failed the day unhead added it back, for no reason at all. The spec pins the behaviour we actually depend on: register with hook(), self-unhook from inside the callback, fires exactly once, throws nothing.

#327 finished the other two. platform.ts — the only plugin with real branching — is covered for Bitrix Mobile, Bitrix Desktop and plain web, plus marker precedence when a UA carries both, the useState cache guard that skips re-parsing during client navigation, and the htmlAttrs getters. ui-version.ts covers a custom version, the packaged default and the build placeholder.

One incidental find worth passing on, since it will bite the next person writing a browser-API stub here: happy-dom keeps Navigator properties as prototype accessors, so the obvious { ...navigator, userAgent: fake } copies nothing — every property reads back undefined and the spec passes for entirely the wrong reason. It is a delegating Proxy now.

What was deliberately left out is tracked in #329: the module's real setup() (needs a loadNuxt fixture — defineNuxtModule reaches for @nuxt/kit's ambient context, so a direct call cannot reach it), platform.ts's SSR branch, and the "nothing here actually boots the package" point from the end of this issue — which stays the widest of the three gaps, and the one that would have caught #301 from the side.

Thanks for filing this with the vitest.config.ts line numbers and the "necessary but not sufficient" section. It read as an implementation plan and was used as one almost verbatim.

---

Generated by Claude Code