feat(vitest): modernize AE and support Vitest 4

Author: IlCallo

packages/e2e-cypress/tsconfig.json

@@ -17,6 +17,7 @@
     // We don't have this problem with Jest twin `installQuasarPlugin` as Jest adds a compilation step anyway and lodash-es
     // transpilation is performed in there
     "module": "commonjs",
+    "moduleResolution": "node",
     "skipLibCheck": true,
     // Without this, TS won't be able to load correctly Quasar deep imports into `injectDevServer` (eg. `@quasar/app/lib/helpers/get-quasar-ctx`)
     "esModuleInterop": true,

packages/unit-vitest/.npmignore

@@ -0,0 +1,5 @@
+.DS_Store
+.thumbs.db
+.eslintignore
+.eslintrc.js
+tsconfig.json

packages/unit-vitest/README.md

@@ -64,16 +64,17 @@ Please check out ["@vue/test-utils" official documentation](https://vue-test-uti
 
 If you're migrating from Jest to Vitest, please check out the official [migration guide](https://vitest.dev/guide/migration.html#migrating-from-jest).
 
-### Upgrade from Vitest AE v0.4 to v1.0 onwards
+### Upgrade from Vitest AE v1.x to v2.0 onwards
 
-All changes are related to Vitest v1.0 breaking changes, Quasar first-party helpers haven't changed.
+Quasar first-party helpers haven't changed.
+All changes are related to Vitest v4.0 breaking changes or ecosystem deprecations.
 
-- Upgrade Node to v18 or newer, v20 is preferred due to some quirks in v18;
-- Upgrade all Vitest related dependencies, especially `@vue/test-utils`, `vitest` and `@vitest/ui`, which minimum peer dependencies versions has been bumped. If you don't want to upgrade these dependencies manually, you can just re-install the AE and it will update all dependencies for you;
+- Upgrade Node to v20.19.0 or newer, but v22.12.0 is preferred. Those versions has been chosen to get `require`-working-with-ESM feature enabled by default, since many packages (e.g. `happy-dom`) rely on;
+- (**optional**) Upgrade `typescript` to v5.8 or later, which supports `require`-working-with-ESM feature;
 - (**optional**) Upgrade `vue` and `quasar` dependencies to the latest version;
-- Rename `vitest.config.[js|ts]` to `vitest.config.[mjs|mts]` or switch your project to "ESM by default" adding `"type": "module"` option in `package.json`. Check out [here](https://vitejs.dev/guide/troubleshooting.html#vite-cjs-node-api-deprecated) why CJS build and syntax are deprecated in Vite 5;
-- Vitest 1.0 requires Vite 5, thus you'll need to upgrade `@quasar/app-vite` to v2. If you can't migrate away from v1 yet, you can use this [workaround](https://github.com/quasarframework/quasar/issues/14077#issuecomment-1851463530) until you can migrate. We do test against the setup using that workaround, to ease the migration, but bear in mind that we don't consider it as "officially supported" and we will stop testing against it in the near future;
-- Follow Vitest [upgrade guide](https://vitest.dev/guide/migration.html#migrating-from-vitest-0-34-6) to upgrade from Vitest v34.6 to v1.0
+- Upgrade `@quasar/app-vite` to v2.4 or later, which uses Vite 7;
+- Upgrade all Vitest related packages, in particular `vitest` and `@vitest/ui` to v4.0 or later. If you don't want to upgrade these dependencies manually, you can just re-install the AE and it will update all dependencies for you. Vitest v1, v2 and v3 are no longer supported;
+- Follow Vitest [upgrade guide](https://vitest.dev/guide/migration#vitest-4) to upgrade from Vitest v3.0 to v4.0;
 
 ### installQuasarPlugin(options)
 

packages/unit-vitest/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@quasar/quasar-app-extension-testing-unit-vitest",
-  "version": "1.2.4",
+  "version": "2.0.0",
+  "type": "module",
   "license": "MIT",
   "description": "A Quasar App Extension for running tests with Vitest",
   "contributors": [
@@ -21,32 +22,50 @@
   "publishConfig": {
     "access": "public"
   },
-  "main": "dist/main.js",
-  "typings": "dist/types/main.d.ts",
+  "main": "./dist/helpers/main.js",
+  "module": "./dist/helpers/main.js",
+  "types": "./dist/helpers/main.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/helpers/main.ts"
+    },
+    "./package.json": "./package.json",
+    "./dist/index": "./src/index.ts",
+    "./dist/install": "./src/install.ts"
+  },
   "engines": {
-    "node": "^30 || ^28 || ^26 || ^24 || ^22 || ^20 || ^18",
-    "npm": ">= 9.5",
+    "node": "^30 || ^28 || ^26 || ^24 || ^22.12.0 || ^20.19.0",
+    "npm": ">= 10",
     "yarn": ">= 1.22.19"
   },
   "dependencies": {
-    "happy-dom": "^15.0.0",
+    "es-toolkit": "^1.42.0",
+    "happy-dom": "^20.0.10",
     "lodash-es": "^4.17.21",
     "vite-tsconfig-paths": "^5.1.4"
   },
+  "devDependenciesComments": {
+    "@quasar/app-vite": "Only used to typecheck AE TS files",
+    "@quasar/vite-plugin": "Only used to typecheck vitest.config.ts, provided by @quasar/app-vite",
+    "@vitejs/plugin-vue": "Only used to typecheck vitest.config.ts"
+  },
   "devDependencies": {
+    "@quasar/app-vite": "^2.4.0",
     "@types/lodash-es": "^4.17.12",
-    "@vitest/ui": "^3.2.4",
+    "@vitejs/plugin-vue": "^6.0.2",
+    "@vitest/ui": "^4.0.13",
     "@vue/test-utils": "^2.4.6",
-    "quasar": "^2.18.1",
-    "rimraf": "^6.0.1",
-    "vitest": "^3.2.4",
-    "vue": "^3.5.13"
+    "quasar": "^2.18.6",
+    "rimraf": "^6.1.2",
+    "vitest": "^4.0.13",
+    "vue": "^3.5.25"
   },
   "peerDependencies": {
-    "@vitest/ui": "^1.1.0 || ^2.0.0 || ^3.0.0",
-    "@vue/test-utils": "^2.4.3",
+    "@quasar/app-vite": "^2.4.0",
+    "@vitest/ui": "^4.0.0",
+    "@vue/test-utils": "^2.4.6",
     "quasar": "^2.12.7",
-    "vitest": "^1.6.1 || ^2.1.9 || ^3.0.5",
+    "vitest": "^4.0.0",
     "vue": "^3.3.4"
   },
   "peerDependenciesMeta": {

packages/unit-vitest/src/index.js

@@ -0,0 +1,13 @@
+/**
+ * Quasar App Extension index/runner script
+ * (runs on each dev/build)
+ *
+ * Docs: https://quasar.dev/app-extensions/development-guide/index-api
+ */
+
+import { IndexAPI } from '@quasar/app-vite';
+
+export default function index(api: IndexAPI) {
+  api.compatibleWith('quasar', '^2.12.7');
+  api.compatibleWith('@quasar/app-vite', '^2.4.0');
+}

packages/unit-vitest/src/index.ts

@@ -0,0 +1,73 @@
+import { InstallAPI } from '@quasar/app-vite';
+import { merge } from 'es-toolkit';
+
+type PackageJson = Record<string, Record<string, string>>;
+
+function getCompatibleDevDependencies(
+  aeDevDependencies: PackageJson[string],
+  packageNames: (keyof typeof aeDevDependencies)[],
+) {
+  const devDependencies: PackageJson[string] = {};
+
+  for (const packageName of packageNames) {
+    devDependencies[packageName] = aeDevDependencies[packageName];
+  }
+
+  return devDependencies;
+}
+
+export default async function (api: InstallAPI) {
+  // We use devDependencies instead of peerDependencies because devDependencies are usually the latest version
+  // and peerDependencies could contain a string supporting multiple major versions (e.g. "cypress": "^12.2.0 || ^13.1.0")
+  const { devDependencies: aeDevDependencies } = (await import(
+    // We can't import it statically, it would cause a problem with the built output folder structure
+    // and `@quasar/app-vite` expects to find AE files (install.js, etc) at the first level of the `dist` folder
+    import.meta.dirname + '../package.json'
+  )) as PackageJson;
+
+  const extendPackageJson: PackageJson = {
+    devDependencies: getCompatibleDevDependencies(aeDevDependencies, [
+      '@vue/test-utils',
+      'vitest',
+    ]),
+  };
+
+  api.compatibleWith('quasar', '^2.12.7');
+  api.compatibleWith('vue', '^3.3.4');
+  api.compatibleWith('@quasar/app-vite', '^2.4.0');
+
+  api.render(
+    `./templates/${(await api.hasTypescript()) ? '' : 'no-'}typescript`,
+  );
+
+  if ((api.prompts.options as string[]).includes('ui')) {
+    const ui: PackageJson = {
+      devDependencies: getCompatibleDevDependencies(aeDevDependencies, [
+        '@vitest/ui',
+      ]),
+    };
+
+    ui.scripts = {
+      'test:unit:ui': 'vitest --ui',
+    };
+
+    merge(extendPackageJson, ui);
+  }
+
+  const scripts = {
+    scripts: {
+      test: 'echo "See package.json => scripts for available tests." && exit 0',
+      'test:unit': 'vitest',
+      'test:unit:ci': 'vitest run',
+    },
+  };
+  merge(extendPackageJson, scripts);
+
+  api.extendPackageJson(extendPackageJson);
+
+  if (await api.hasLint()) {
+    api.onExitLog(
+      'Check out https://github.com/quasarframework/quasar-testing/tree/dev/packages/unit-vitest to see how to add proper Vitest linting configuration to your project.',
+    );
+  }
+}