nuxt-vitest-shared-app 0.1.0 → 0.1.1

package/README.md

@@ -15,7 +15,7 @@ Tests that need plugins re-initialized or a different startup config belong in a
 - [The problem](#the-problem)
 - [Install](#install)
 - [Quick start](#quick-start)
-- [Migrating an existing suite](#migrating-an-existing-suite)
+- [Switching from per-file startup](#switching-from-per-file-startup)
 - [Per-test overrides](#per-test-overrides)
 - [Project resets](#project-resets)
 - [Worker state](#worker-state)
@@ -64,9 +64,8 @@ import { defineSharedNuxtVitestConfig } from "nuxt-vitest-shared-app/config"
 
 export default defineSharedNuxtVitestConfig({
   test: {
-    include: ["**/*.vitest.ts"],
+    include: ["test/nuxt/**/*.test.ts"],
     environment: "nuxt",
-    pool: "threads",
     isolate: false,
   },
 })
@@ -92,24 +91,23 @@ defineSharedNuxtVitestConfig(config, { silenceSuspenseInfo: true })
 
 With `silenceSuspenseInfo: true`, Vue's `<Suspense> is an experimental feature and its API will likely change.` message, which every `mountSuspended` call prints, is filtered through `test.onConsoleLog`; your own `onConsoleLog` still receives all other messages.
 
-## Migrating an existing suite
+## Switching from per-file startup
 
-Remove what the library now does:
+With plain `@nuxt/test-utils`, every test file starts from fresh modules and globals.
+With a shared app, modules stay cached for the following files of the worker, so objects created at module level live for the whole environment.
+Tests that passed with per-file startup may rely on that implicitly and start to depend on the order of files.
 
-- `enableAutoUnmount` calls in project setup files: the library installs its own, and `@vue/test-utils` rejects a second call;
-- hooks that clean up what the library [cleans up](#cleanup), such as Nuxt state, storage, cookies, timers, and stubbed globals;
-- local patches or workarounds that start Nuxt once per worker.
-
-Keep project-specific cleanup, and move hooks that must run after every test into [project resets](#project-resets).
-
-Because modules stay cached, objects created at module level live for the whole environment, not for one file.
-A global replaced by one test file affects every file that runs after it in the worker, including objects that other modules already created from the previous global.
+A typical case is a global replaced by one test file.
+It affects every file that runs after it in the worker, including objects that other modules already created from the previous global.
 For example, a test file that imports a forced `Intl` polyfill replaces the global constructor, while a formatter created earlier at module level still belongs to the previous implementation.
 
 - Install global polyfills once in a project setup file, before components are imported, and prefer polyfills that keep an existing implementation.
 - Do not replace global constructors with side-effect imports in individual test files.
 - Review module-level objects that depend on such globals, such as formatters, clients, and caches.
-- After the migration, run the suite on one worker with shuffled files, so all files share one environment in a different order, e.g. `vitest run --maxWorkers=1 --sequence.shuffle.files --sequence.seed=1`.
+- Run the suite on one worker with shuffled files, so all files share one environment in a different order, e.g. `vitest run --maxWorkers=1 --sequence.shuffle.files --sequence.seed=1`.
+
+Remove `enableAutoUnmount` calls from project setup files: the library installs its own, and `@vue/test-utils` throws on a second call.
+Hooks that clean up what the library [cleans up](#cleanup) keep working, and you can remove them.
 
 ## Per-test overrides
 
@@ -123,13 +121,13 @@ Register overridable imports in a project setup file:
 export default defineSharedNuxtVitestConfig({
   test: {
     // ...
-    setupFiles: ["./testing/nuxt/setup.ts"],
+    setupFiles: ["./test/nuxt/setup.ts"],
   },
 })
 ```
 
 ```ts
-// testing/nuxt/setup.ts
+// test/nuxt/setup.ts
 import { mockNuxtImport } from "@nuxt/test-utils/runtime"
 import { overridableNuxtImport } from "nuxt-vitest-shared-app"
 
@@ -174,7 +172,7 @@ Use a fallback for behavior that the app needs while it starts.
 First add `useUser` and its type to `TestNuxtImports`, as in the setup file above, then:
 
 ```ts
-// testing/nuxt/setup.ts
+// test/nuxt/setup.ts
 mockNuxtImport(
   "useUser",
   overridableNuxtImport("useUser", () => ref(null)),
@@ -218,11 +216,11 @@ It requires `useRoute` in `TestNuxtImports` and an overridable `useRoute` mock.
 registerNuxtTestReset(key: string, reset: () => unknown): () => void
 ```
 
-Registers a reset that runs after each test, see step 6 of the [cleanup](#cleanup).
+Registers a reset that runs after each test, see step 7 of the [cleanup](#cleanup).
 Use it for application resources that the library does not know about, such as test API clients, subscriptions, and caches:
 
 ```ts
-// testing/nuxt/setup.ts
+// test/nuxt/setup.ts
 import { registerNuxtTestReset } from "nuxt-vitest-shared-app"
 
 import { testApiClient } from "./api-client"
@@ -303,20 +301,21 @@ In such files, `overridableNuxtImport` factories return the fallback or the orig
 After each test, the library runs these steps in order.
 They run after all `afterEach` hooks of the project, also when one of these hooks fails.
 
-1. unmounts wrappers mounted in the test through `@vue/test-utils` (including `mountSuspended`), using `enableAutoUnmount`;
-2. `await nextTick()` and `await flushPromises()`;
-3. navigates the app's own router back to the route baseline with `router.replace` if the route differs, and verifies the resulting route;
-4. clears import overrides;
-5. `await clearError()`, `clearNuxtData()`, `clearNuxtState(undefined, { reset: false })`;
-6. runs project resets registered with `registerNuxtTestReset`, in registration order, awaiting each;
-7. `localStorage.clear()`, `sessionStorage.clear()`, and expires every cookie visible in `document.cookie` for path `/` of the current origin;
-8. `vi.clearAllTimers()`, `vi.useRealTimers()`, `vi.unstubAllEnvs()`, `vi.unstubAllGlobals()`;
-9. removes direct children of `document.body` that were not present at startup.
+1. `vi.clearAllTimers()` and `vi.useRealTimers()`, so the following steps and project resets run under real timers and the test does not need to restore them;
+2. unmounts wrappers mounted in the test through `@vue/test-utils` (including `mountSuspended`), using `enableAutoUnmount`;
+3. `await nextTick()` and `await flushPromises()`;
+4. navigates the app's own router back to the route baseline with `router.replace` if the route differs, and verifies the resulting route;
+5. clears import overrides;
+6. `await clearError()`, `clearNuxtData()`, `clearNuxtState(undefined, { reset: false })`;
+7. runs project resets registered with `registerNuxtTestReset`, in registration order, awaiting each;
+8. `localStorage.clear()`, `sessionStorage.clear()`, and expires every cookie visible in `document.cookie` for path `/` of the current origin;
+9. `vi.unstubAllEnvs()` and `vi.unstubAllGlobals()`;
+10. removes direct children of `document.body` that were not present at startup.
 
 The exact scope:
 
 - `flushPromises` only settles handlers of promises that are already resolved; subscriptions, requests, and other background work need their own project resets;
-- step 3 uses the router instance of the app, never the overridable `useRoute`/`navigateTo`;
+- step 4 uses the router instance of the app, never the overridable `useRoute`/`navigateTo`;
 - DOM cleanup removes only new direct children of `document.body`; changes to nodes that existed at startup are not reverted;
 - cookies are expired only as listed above; `HttpOnly` cookies and cookies of other paths or domains are not touched;
 - state created by startup plugins is not re-created.
@@ -355,7 +354,7 @@ import { defineVitestConfig } from "@nuxt/test-utils/config"
 
 export default defineVitestConfig({
   test: {
-    include: ["**/*.isolated.vitest.ts"],
+    include: ["test/nuxt-isolated/**/*.test.ts"],
     environment: "nuxt",
   },
 })
@@ -366,7 +365,7 @@ vitest run
 vitest run --config vitest.isolated.config.ts
 ```
 
-Exclude the isolated files from the shared-app config.
+Keep the `include` patterns of the two configs from overlapping, so each file runs in one of them.
 
 ## Compatibility and upstream
 

package/dist/runtime/lifecycle.mjs

@@ -42,6 +42,7 @@ async function cleanupAfterTest(store, baseline, unmountWrappers) {
 			});
 		}
 	}
+	for (const [name, run] of TIMER_STEPS) await step(name, run);
 	await step("unmount wrappers", () => unmountWrappers?.());
 	await step("flush promises", async () => {
 		await nextTick();
@@ -73,7 +74,7 @@ async function cleanupAfterTest(store, baseline, unmountWrappers) {
 	await step("clear localStorage", () => localStorage.clear());
 	await step("clear sessionStorage", () => sessionStorage.clear());
 	await step("expire cookies", expireCookies);
-	for (const [name, run] of RUNNER_STEPS) await step(name, run);
+	for (const [name, run] of STUB_STEPS) await step(name, run);
 	await step("remove body children", () => {
 		for (const child of Array.from(document.body.children)) if (!baseline.bodyChildren.has(child)) child.remove();
 	});
@@ -82,12 +83,9 @@ async function cleanupAfterTest(store, baseline, unmountWrappers) {
 function importNuxt() {
 	return import("nuxt/app");
 }
-const RUNNER_STEPS = [
-	["clear timers", () => vi.clearAllTimers()],
-	["use real timers", () => vi.useRealTimers()],
-	["unstub envs", () => vi.unstubAllEnvs()],
-	["unstub globals", () => vi.unstubAllGlobals()]
-];
+const TIMER_STEPS = [["clear timers", () => vi.clearAllTimers()], ["use real timers", () => vi.useRealTimers()]];
+const STUB_STEPS = [["unstub envs", () => vi.unstubAllEnvs()], ["unstub globals", () => vi.unstubAllGlobals()]];
+const RUNNER_STEPS = [...TIMER_STEPS, ...STUB_STEPS];
 /** Restores timers, envs and globals as far as possible, ignoring failures, for an environment that is already contaminated. */
 function restoreTestRunner() {
 	for (const [, run] of RUNNER_STEPS) try {
@@ -132,9 +130,9 @@ function installLifecycle() {
 	beforeAll(async () => {
 		const store = getEnvironmentStore();
 		assertNotContaminated(store);
+		if (store.startupFailure) throw new Error("nuxt-vitest-shared-app: Nuxt startup failed earlier in this environment.", { cause: store.startupFailure });
 		const { tryUseNuxtApp } = await import("nuxt/app");
 		const nuxtApp = assertAppRunning(tryUseNuxtApp(), document);
-		if (store.startupFailure) throw new Error("nuxt-vitest-shared-app: Nuxt startup failed earlier in this environment.", { cause: store.startupFailure });
 		if (!store.baseline) {
 			const startupError = getStartupError(nuxtApp);
 			if (startupError) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-vitest-shared-app",
-  "version": "0.1.0",
-  "description": "Run Nuxt component tests in Vitest on one Nuxt app per worker, with deterministic per-test cleanup and typed auto-import overrides.",
+  "version": "0.1.1",
+  "description": "Run Nuxt component tests in Vitest on one shared app per worker, with per-test cleanup.",
   "keywords": [
     "nuxt",
     "nuxt-test-utils",