@nuxt/test-utils 3.8.1 → 3.9.0-alpha.2

package/README.md

@@ -1,68 +1,18 @@
-[![Nuxt banner](./.github/assets/banner.svg)](https://nuxt.com)
+# Nuxt Test Utils
 
-# Nuxt
+🧪 [Nuxt](https://nuxt.com/) Test Utils
 
-<p>
-  <a href="https://www.npmjs.com/package/nuxt"><img src="https://img.shields.io/npm/v/nuxt.svg?style=flat&colorA=18181B&colorB=28CF8D" alt="Version"></a>
-  <a href="https://www.npmjs.com/package/nuxt"><img src="https://img.shields.io/npm/dm/nuxt.svg?style=flat&colorA=18181B&colorB=28CF8D" alt="Downloads"></a>
-  <a href="./LICENSE"><img src="https://img.shields.io/github/license/nuxt/nuxt.svg?style=flat&colorA=18181B&colorB=28CF8D" alt="License"></a>
-  <a href="https://nuxt.com"><img src="https://img.shields.io/badge/Nuxt%20Docs-18181B?logo=nuxt.js" alt="Website"></a>
-  <a href="https://chat.nuxt.dev"><img src="https://img.shields.io/badge/Nuxt%20Discord-18181B?logo=discord" alt="Discord"></a>
-</p>
+## Overview
 
-Nuxt is a free and open-source framework with an intuitive and extendable way to create type-safe, performant and production-grade full-stack web applications and websites with Vue.js.
+Nuxt offers first-class support for e2e and unit testing of your Nuxt applications.
 
-It provides a number of features that make it easy to build fast, SEO-friendly, and scalable web applications, including:
-- Server-side rendering, Static Site Generation or Hybrid Rendering
-- Automatic routing with code-splitting
-- State management
-- SEO Optimization
-- Extensible with [100+ modules](https://nuxt.com/modules)
-- Deployment to a variety of hosting platforms
-- ...[and much more](https://nuxt.com) 🚀
+Nuxt Test Utils is currently powering [the tests we use on Nuxt itself](https://github.com/nuxt/nuxt/tree/main/test), as well as tests used throughout the module ecosystem.
 
-## Getting Started
+You can find out more about how to use Nuxt Test Utils:
 
-Use the following command to create a new starter project. This will create a starter project with all the necessary files and dependencies:
-
-```bash
-npx nuxi@latest init <my-project>
-```
-
-Discover also [nuxt.new](https://nuxt.new): Open a Nuxt starter on CodeSandbox, StackBlitz or locally to get up and running in a few seconds.
-
-## Documentation
-
-We highly recommend you take a look at the [Nuxt documentation](https://nuxt.com/docs) to level up. It’s a great resource for learning more about the framework. It covers everything from getting started to advanced topics.
-
-## Modules
-
-Discover our [list of modules](https://nuxt.com/modules) to supercharge your Nuxt project, created by the Nuxt team and community.
-
-## Contribute
-
-We invite you to contribute and help improve Nuxt 💚
-
-Here are a few ways you can get involved:
-- **Reporting Bugs:** If you come across any bugs or issues, please check out the [reporting bugs guide](https://nuxt.com/docs/community/reporting-bugs) to learn how to submit a bug report.
-- **Suggestions:** Have ideas to enhance Nuxt? We'd love to hear them! Check out the [contribution guide](https://nuxt.com/docs/community/contribution#creating-an-issue) to share your suggestions.
-- **Questions:** If you have questions or need assistance, the [getting help guide](https://nuxt.com/docs/community/getting-help) provides resources to help you out.
-
-## Local Development
-
-Follow the docs to [Set Up Your Local Development Environment](https://nuxt.com/docs/community/framework-contribution#setup) to contribute to the framework and documentation.
-
-## Nuxt 2
-
-You can find the code for Nuxt 2 on the [`2.x` branch](https://github.com/nuxt/nuxt/tree/2.x) and the documentation at [v2.nuxt.com](https://v2.nuxt.com).
-
-## Follow us
-
-<p valign="center">
-  <a href="https://chat.nuxt.dev"><img width="20px" src="./.github/assets/discord.svg" alt="Discord"></a>&nbsp;&nbsp;<a href="https://twitter.nuxt.dev"><img width="20px" src="./.github/assets/twitter.svg" alt="Twitter"></a>&nbsp;&nbsp;<a href="https://github.nuxt.dev"><img width="20px" src="./.github/assets/github.svg" alt="GitHub"></a>
-</p>
+- in [a general overview](https://nuxt.com/docs/getting-started/testing)
+- in [an in-depth guide for module authors](https://nuxt.com/docs/guide/going-further/modules/#testing)
 
 ## License
 
 [MIT](./LICENSE)
-

package/config.d.ts

@@ -0,0 +1 @@
+export * from './dist/config'

package/dist/config.d.mts

@@ -0,0 +1,58 @@
+import * as vite from 'vite';
+import { InlineConfig } from 'vite';
+import { NuxtConfig, Nuxt } from '@nuxt/schema';
+import { InlineConfig as InlineConfig$1 } from 'vitest';
+import { DotenvOptions } from 'c12';
+
+interface GetVitestConfigOptions {
+    nuxt: Nuxt;
+    viteConfig: InlineConfig;
+}
+interface LoadNuxtOptions {
+    dotenv?: Partial<DotenvOptions>;
+    overrides?: Partial<NuxtConfig>;
+}
+declare function getVitestConfigFromNuxt(options?: GetVitestConfigOptions, loadNuxtOptions?: LoadNuxtOptions): Promise<InlineConfig & {
+    test: InlineConfig$1;
+}>;
+declare function defineVitestConfig(config?: InlineConfig & {
+    test?: InlineConfig$1;
+}): vite.UserConfig & Promise<vite.UserConfig> & vite.UserConfigFnObject & vite.UserConfigExport;
+declare module 'vitest' {
+    interface EnvironmentOptions {
+        nuxt?: {
+            rootDir?: string;
+            /**
+             * The starting URL for your Nuxt window environment
+             * @default {http://localhost:3000}
+             */
+            url?: string;
+            /**
+             * You can define how environment options are read when loading the Nuxt configuration.
+             */
+            dotenv?: Partial<DotenvOptions>;
+            /**
+             * Configuration that will override the values in your `nuxt.config` file.
+             */
+            overrides?: NuxtConfig;
+            /**
+             * The id of the root div to which the app should be mounted. You should also set `app.rootId` to the same value.
+             * @default {nuxt-test}
+             */
+            rootId?: string;
+            /**
+             * The name of the DOM environment to use.
+             *
+             * It also needs to be installed as a dev dependency in your project.
+             * @default {happy-dom}
+             */
+            domEnvironment?: 'happy-dom' | 'jsdom';
+            mock?: {
+                intersectionObserver?: boolean;
+                indexedDb?: boolean;
+            };
+        };
+    }
+}
+
+export { defineVitestConfig, getVitestConfigFromNuxt };

package/dist/config.d.ts

@@ -0,0 +1,58 @@
+import * as vite from 'vite';
+import { InlineConfig } from 'vite';
+import { NuxtConfig, Nuxt } from '@nuxt/schema';
+import { InlineConfig as InlineConfig$1 } from 'vitest';
+import { DotenvOptions } from 'c12';
+
+interface GetVitestConfigOptions {
+    nuxt: Nuxt;
+    viteConfig: InlineConfig;
+}
+interface LoadNuxtOptions {
+    dotenv?: Partial<DotenvOptions>;
+    overrides?: Partial<NuxtConfig>;
+}
+declare function getVitestConfigFromNuxt(options?: GetVitestConfigOptions, loadNuxtOptions?: LoadNuxtOptions): Promise<InlineConfig & {
+    test: InlineConfig$1;
+}>;
+declare function defineVitestConfig(config?: InlineConfig & {
+    test?: InlineConfig$1;
+}): vite.UserConfig & Promise<vite.UserConfig> & vite.UserConfigFnObject & vite.UserConfigExport;
+declare module 'vitest' {
+    interface EnvironmentOptions {
+        nuxt?: {
+            rootDir?: string;
+            /**
+             * The starting URL for your Nuxt window environment
+             * @default {http://localhost:3000}
+             */
+            url?: string;
+            /**
+             * You can define how environment options are read when loading the Nuxt configuration.
+             */
+            dotenv?: Partial<DotenvOptions>;
+            /**
+             * Configuration that will override the values in your `nuxt.config` file.
+             */
+            overrides?: NuxtConfig;
+            /**
+             * The id of the root div to which the app should be mounted. You should also set `app.rootId` to the same value.
+             * @default {nuxt-test}
+             */
+            rootId?: string;
+            /**
+             * The name of the DOM environment to use.
+             *
+             * It also needs to be installed as a dev dependency in your project.
+             * @default {happy-dom}
+             */
+            domEnvironment?: 'happy-dom' | 'jsdom';
+            mock?: {
+                intersectionObserver?: boolean;
+                indexedDb?: boolean;
+            };
+        };
+    }
+}
+
+export { defineVitestConfig, getVitestConfigFromNuxt };

package/dist/config.mjs

@@ -0,0 +1,205 @@
+import { defineConfig } from 'vite';
+import { setupDotenv } from 'c12';
+import { defu } from 'defu';
+import { createResolver } from '@nuxt/kit';
+import destr from 'destr';
+import { snakeCase } from 'scule';
+
+function getEnv(key, opts) {
+  const env = opts.env ?? process.env;
+  const envKey = snakeCase(key).toUpperCase();
+  return destr(
+    env[opts.prefix + envKey] ?? env[opts.altPrefix + envKey]
+  );
+}
+function _isObject(input) {
+  return typeof input === "object" && !Array.isArray(input);
+}
+function applyEnv(obj, opts, parentKey = "") {
+  for (const key in obj) {
+    const subKey = parentKey ? `${parentKey}_${key}` : key;
+    const envValue = getEnv(subKey, opts);
+    if (_isObject(obj[key])) {
+      if (_isObject(envValue)) {
+        obj[key] = { ...obj[key], ...envValue };
+        applyEnv(obj[key], opts, subKey);
+      } else if (envValue === void 0) {
+        applyEnv(obj[key], opts, subKey);
+      } else {
+        obj[key] = envValue ?? obj[key];
+      }
+    } else {
+      obj[key] = envValue ?? obj[key];
+    }
+  }
+  return obj;
+}
+
+async function startNuxtAndGetViteConfig(rootDir = process.cwd(), options = {}) {
+  const { loadNuxt, buildNuxt } = await import('@nuxt/kit');
+  const nuxt = await loadNuxt({
+    cwd: rootDir,
+    dev: false,
+    dotenv: defu(options.dotenv, {
+      cwd: rootDir,
+      fileName: ".env.test"
+    }),
+    overrides: defu(
+      {
+        ssr: false,
+        test: true,
+        modules: ["@nuxt/test-utils/module"]
+      },
+      options.overrides
+    )
+  });
+  if (!nuxt.options._installedModules.find((i) => i?.meta?.name === "@nuxt/test-utils")) {
+    throw new Error(
+      "Failed to load `@nuxt/test-utils/module`. You may need to add it to your nuxt.config."
+    );
+  }
+  const promise = new Promise((resolve, reject) => {
+    nuxt.hook("vite:configResolved", (viteConfig, { isClient }) => {
+      if (isClient) {
+        resolve({ nuxt, viteConfig });
+        throw new Error("_stop_");
+      }
+    });
+    buildNuxt(nuxt).catch((err) => {
+      if (!err.toString().includes("_stop_")) {
+        reject(err);
+      }
+    });
+  }).finally(() => nuxt.close());
+  return promise;
+}
+const excludedPlugins = [
+  "nuxt:import-protection",
+  "vite-plugin-checker"
+];
+async function getVitestConfigFromNuxt(options, loadNuxtOptions = {}) {
+  const { rootDir = process.cwd(), ..._overrides } = loadNuxtOptions.overrides || {};
+  if (!options) {
+    options = await startNuxtAndGetViteConfig(rootDir, {
+      dotenv: loadNuxtOptions.dotenv,
+      overrides: {
+        test: true,
+        ..._overrides
+      }
+    });
+  }
+  options.viteConfig.plugins = (options.viteConfig.plugins || []).filter((p) => !excludedPlugins.includes(p?.name));
+  const resolvedConfig = defu(
+    // overrides
+    {
+      define: {
+        ["process.env.NODE_ENV"]: "process.env.NODE_ENV"
+      },
+      test: {
+        dir: process.cwd(),
+        environmentOptions: {
+          nuxtRuntimeConfig: applyEnv(structuredClone(options.nuxt.options.runtimeConfig), {
+            prefix: "NUXT_",
+            env: await setupDotenv(defu(loadNuxtOptions.dotenv, {
+              cwd: rootDir,
+              fileName: ".env.test"
+            }))
+          }),
+          nuxtRouteRules: defu(
+            {},
+            options.nuxt.options.routeRules,
+            options.nuxt.options.nitro?.routeRules
+          )
+        },
+        environmentMatchGlobs: [
+          ["**/*.nuxt.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}", "nuxt"],
+          ["{test,tests}/nuxt/**.*", "nuxt"]
+        ],
+        server: {
+          deps: {
+            inline: [
+              // vite-node defaults
+              /\/node_modules\/(.*\/)?(nuxt|nuxt3|nuxt-nightly)\//,
+              /^#/,
+              // additional deps
+              "@nuxt/test-utils",
+              "@nuxt/test-utils-nightly",
+              "@nuxt/test-utils-edge",
+              "vitest-environment-nuxt",
+              ...options.nuxt.options.build.transpile.filter(
+                (r) => typeof r === "string" || r instanceof RegExp
+              )
+            ]
+          }
+        },
+        deps: {
+          optimizer: {
+            web: {
+              enabled: false
+            }
+          }
+        }
+      }
+    },
+    {
+      server: { middlewareMode: false },
+      plugins: [
+        {
+          name: "disable-auto-execute",
+          enforce: "pre",
+          transform(code, id) {
+            if (id.match(/nuxt(3|-nightly)?\/.*\/entry\./)) {
+              return code.replace(
+                /(?<!vueAppPromise = )entry\(\)/,
+                "Promise.resolve()"
+              );
+            }
+          }
+        }
+      ]
+    },
+    // resolved vite config
+    options.viteConfig,
+    // (overrideable) defaults
+    {
+      test: {
+        environmentOptions: {
+          nuxt: {
+            rootId: options.nuxt.options.app.rootId || void 0,
+            mock: {
+              intersectionObserver: true,
+              indexedDb: false
+            }
+          }
+        }
+      }
+    }
+  );
+  delete resolvedConfig.define["process.browser"];
+  if (!Array.isArray(resolvedConfig.test.setupFiles)) {
+    resolvedConfig.test.setupFiles = [resolvedConfig.test.setupFiles].filter(Boolean);
+  }
+  const resolver = createResolver(import.meta.url);
+  resolvedConfig.test.setupFiles.unshift(resolver.resolve("./runtime/entry"));
+  return resolvedConfig;
+}
+function defineVitestConfig(config = {}) {
+  return defineConfig(async () => {
+    if (process.env.__NUXT_VITEST_RESOLVED__)
+      return config;
+    const overrides = config.test?.environmentOptions?.nuxt?.overrides || {};
+    overrides.rootDir = config.test?.environmentOptions?.nuxt?.rootDir;
+    if (config.test?.setupFiles && !Array.isArray(config.test.setupFiles)) {
+      config.test.setupFiles = [config.test.setupFiles].filter(Boolean);
+    }
+    return defu(
+      config,
+      await getVitestConfigFromNuxt(void 0, {
+        dotenv: config.test?.environmentOptions?.nuxt?.dotenv,
+        overrides: structuredClone(overrides)
+      })
+    );
+  });
+}
+
+export { defineVitestConfig, getVitestConfigFromNuxt };

package/dist/{index.d.mts → e2e.d.mts}

@@ -37,6 +37,11 @@ interface TestContext {
     url?: string;
     serverProcess?: ExecaChildProcess;
     mockFn?: Function;
+    /**
+     * Functions to run on the vitest `afterAll` hook.
+     * Useful for removing anything created during the test.
+     */
+    teardown?: (() => void)[];
 }
 interface TestHooks {
     beforeEach: () => void;

package/dist/{index.d.ts → e2e.d.ts}

@@ -37,6 +37,11 @@ interface TestContext {
     url?: string;
     serverProcess?: ExecaChildProcess;
     mockFn?: Function;
+    /**
+     * Functions to run on the vitest `afterAll` hook.
+     * Useful for removing anything created during the test.
+     */
+    teardown?: (() => void)[];
 }
 interface TestHooks {
     beforeEach: () => void;

package/dist/{index.mjs → e2e.mjs}

@@ -1,7 +1,7 @@
-import { u as useTestContext, a as url, c as createTestContext, s as setTestContext, b as stopServer, d as startServer } from './shared/test-utils.8f432eb9.mjs';
-export { $ as $fetch, e as exposeContextToEnv, f as fetch, i as isDev, r as recoverContextFromEnv } from './shared/test-utils.8f432eb9.mjs';
+import { u as useTestContext, a as url, c as createTestContext, s as setTestContext, b as stopServer, d as startServer } from './shared/test-utils.B1uaYm8K.mjs';
+export { $ as $fetch, e as exposeContextToEnv, f as fetch, i as isDev, r as recoverContextFromEnv } from './shared/test-utils.B1uaYm8K.mjs';
 import { consola } from 'consola';
-import { promises, existsSync } from 'node:fs';
+import { existsSync, promises } from 'node:fs';
 import { resolve } from 'node:path';
 import { defu } from 'defu';
 import * as _kit from '@nuxt/kit';
@@ -15,7 +15,10 @@ async function createBrowser() {
   const ctx = useTestContext();
   let playwright;
   try {
-    playwright = await import(String("playwright-core"));
+    playwright = await import(
+      /* vite-ignore */
+      'playwright-core'
+    );
   } catch {
     throw new Error(`
       The dependency 'playwright-core' not found.
@@ -80,12 +83,12 @@ async function loadFixture() {
   ctx.options.rootDir = resolveRootDir();
   if (!ctx.options.dev) {
     const randomId = Math.random().toString(36).slice(2, 8);
-    const buildDir = resolve(ctx.options.rootDir, ".nuxt", randomId);
+    const buildDir2 = ctx.options.buildDir || resolve(ctx.options.rootDir, ".nuxt", "test", randomId);
     ctx.options.nuxtConfig = defu(ctx.options.nuxtConfig, {
-      buildDir,
+      buildDir: buildDir2,
       nitro: {
         output: {
-          dir: resolve(buildDir, "output")
+          dir: resolve(buildDir2, "output")
         }
       }
     });
@@ -96,7 +99,12 @@ async function loadFixture() {
     overrides: ctx.options.nuxtConfig,
     configFile: ctx.options.configFile
   });
-  await promises.mkdir(ctx.nuxt.options.buildDir, { recursive: true });
+  const buildDir = ctx.nuxt.options.buildDir;
+  if (!existsSync(buildDir)) {
+    await promises.mkdir(buildDir, { recursive: true });
+    ctx.teardown = ctx.teardown || [];
+    ctx.teardown.push(() => promises.rm(buildDir, { recursive: true, force: true }));
+  }
 }
 async function buildFixture() {
   const ctx = useTestContext();
@@ -148,6 +156,7 @@ function createTest(options) {
     if (ctx.browser) {
       await ctx.browser.close();
     }
+    await Promise.all((ctx.teardown || []).map((fn) => fn()));
   };
   const setup2 = async () => {
     if (ctx.options.fixture) {
@@ -218,6 +227,7 @@ async function runTests(opts) {
           inline: [
             distDir,
             "@nuxt/test-utils",
+            "@nuxt/test-utils-nightly",
             "@nuxt/test-utils-edge"
           ]
         },

package/dist/experimental.mjs

@@ -1,6 +1,6 @@
 import { resolve } from 'pathe';
 import { stringifyQuery } from 'ufo';
-import { $ as $fetch, u as useTestContext } from './shared/test-utils.8f432eb9.mjs';
+import { $ as $fetch, u as useTestContext } from './shared/test-utils.B1uaYm8K.mjs';
 import 'execa';
 import 'get-port-please';
 import 'ofetch';

package/dist/module.d.mts

@@ -0,0 +1,11 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { UserConfig } from 'vitest';
+
+interface NuxtVitestOptions {
+    startOnBoot?: boolean;
+    logToConsole?: boolean;
+    vitestConfig?: UserConfig;
+}
+declare const _default: _nuxt_schema.NuxtModule<NuxtVitestOptions>;
+
+export { type NuxtVitestOptions, _default as default };

package/dist/module.d.ts

@@ -0,0 +1,11 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { UserConfig } from 'vitest';
+
+interface NuxtVitestOptions {
+    startOnBoot?: boolean;
+    logToConsole?: boolean;
+    vitestConfig?: UserConfig;
+}
+declare const _default: _nuxt_schema.NuxtModule<NuxtVitestOptions>;
+
+export { type NuxtVitestOptions, _default as default };