@canonical/vitest-config-react 0.29.0

package/README.md

@@ -0,0 +1,95 @@
+# Canonical Vitest Configuration (React)
+
+This package provides a reusable configuration factory for the Vitest `test`
+block of Canonical's React packages. It replaces the near-identical `test`
+blocks that were previously copy-pasted into every package's `vite.config.ts`.
+
+Every React vitest posture in the monorepo — jsdom component tests, the
+client/SSR project split, coverage-gated packages, and node-only packages — is
+a point in one option space, so this is a single factory rather than a set of
+per-shape variants.
+
+## Getting started
+
+1. Add the package as a dev dependency: `bun add -d @canonical/vitest-config-react`.
+2. In your `vite.config.ts`, import the factory and spread its result into
+   `test`:
+
+```typescript
+import react from "@vitejs/plugin-react";
+import { reactTestConfig } from "@canonical/vitest-config-react";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: { tsconfigPaths: true },
+  build: { sourcemap: true },
+  test: reactTestConfig({
+    glob: "tests",
+    setupFiles: ["./vitest.setup.ts"],
+  }),
+});
+```
+
+The factory owns only the `test` block. `plugins`, `resolve` and `build` stay
+in each package's config, because those legitimately differ (for example, some
+packages run in `jsdom` while framework-agnostic/SSR packages run in `node`).
+
+## Options
+
+| Option        | Type                              | Default   | Notes                                                                                          |
+| ------------- | --------------------------------- | --------- | ---------------------------------------------------------------------------------------------- |
+| `glob`        | `"test" \| "tests"`, or an array of those | — | **Required.** The test-file suffix convention(s). See the caveat below.                        |
+| `environment` | `"jsdom" \| "node"`               | `"jsdom"` | `"node"` for framework-agnostic / SSR-only packages.                                           |
+| `ssr`         | `boolean`                         | `false`   | Adds a second `node` project running `**/*.ssr.<glob>.tsx` (the client project excludes them). |
+| `coverage`    | `boolean \| { … }`                | `false`   | `true` enables v8 coverage with 100% thresholds; pass an object to override.                   |
+| `setupFiles`  | `string[]`                        | `[]`      | e.g. `["./vitest.setup.ts"]`; omitted when empty.                                              |
+| `plugins`     | `Plugin[]`                        | —         | Attached to each project (Vitest resolves plugins per project).                                |
+
+### Coverage
+
+Coverage is **off by default**, preserving the behaviour of packages that do
+not gate coverage today. When enabled, thresholds default to
+`100/100/100/100`, following the storybook-config convention of "sensible
+defaults you pass through":
+
+```typescript
+// 100% thresholds
+reactTestConfig({ glob: "test", coverage: true });
+
+// keep 100% for everything except lines
+reactTestConfig({ glob: "test", coverage: { thresholds: { lines: 80 } } });
+
+// runtime-only include (SSR adapters)
+reactTestConfig({ glob: "tests", environment: "node", coverage: { include: ["src/lib/**/*.ts"] } });
+```
+
+## Caveat: `glob` is load-bearing
+
+`glob` has no default because `.test.` and `.tests.` are **not**
+interchangeable: choosing the wrong convention silently matches zero files — a
+green run that ran nothing. Always pass the convention(s) the package's test
+files actually use.
+
+### Interim: running both conventions
+
+A package whose test files are split between `.test.` and `.tests.` (for
+example `react-ds-global`, whose `_work_in_progress` scaffolds use `.test.`
+while the promoted components use `.tests.`) can pass both:
+
+```typescript
+reactTestConfig({ glob: ["test", "tests"], ssr: true });
+```
+
+Both conventions are then matched by the client project and, with `ssr: true`,
+by the SSR project (`**/*.ssr.test.tsx` and `**/*.ssr.tests.tsx`); coverage
+excludes test files of both conventions. This is an **interim** escape hatch:
+once the repo-wide test-file naming unification lands, packages should return
+to a single convention and the array form should disappear.
+
+## Roadmap: browser mode
+
+`jsdom` is the interim environment. The forward path is Vitest browser mode
+with Playwright (see the `svelte-ds-global` migration). This factory will gain
+a `browser` option so each package can flip to browser mode without rewriting
+its config — only its test files.

package/biome.json

@@ -0,0 +1,6 @@
+{
+  "extends": ["@canonical/biome-config"],
+  "files": {
+    "includes": ["src", "*.json"]
+  }
+}

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+export { reactTestConfig } from "./reactTestConfig.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/reactTestConfig.js

@@ -0,0 +1,99 @@
+/** Standard coverage excludes shared by every coverage-gated package. */
+const BASE_COVERAGE_EXCLUDE = [
+    "**/index.ts",
+    "**/*.d.ts",
+    "**/types.ts",
+];
+const FULL_THRESHOLDS = {
+    branches: 100,
+    functions: 100,
+    lines: 100,
+    statements: 100,
+};
+/**
+ * Build the v8 coverage block. Test files are always excluded (both `.test.`
+ * and `.tests.` plus their `.ssr.` variants) so coverage measures runtime code
+ * only. Thresholds default to 100% and are overridable per the storybook-config
+ * convention of "sensible defaults you pass through".
+ */
+const buildCoverage = (coverage, globs) => {
+    const overrides = coverage === true ? {} : coverage;
+    const testExclude = globs.flatMap((glob) => [
+        `**/*.${glob}.ts`,
+        `**/*.${glob}.tsx`,
+        `**/*.ssr.${glob}.ts`,
+        `**/*.ssr.${glob}.tsx`,
+    ]);
+    return {
+        provider: "v8",
+        include: overrides.include ?? ["src/**/*.{ts,tsx}"],
+        exclude: [
+            ...BASE_COVERAGE_EXCLUDE,
+            ...testExclude,
+            ...(overrides.exclude ?? []),
+        ],
+        thresholds: { ...FULL_THRESHOLDS, ...overrides.thresholds },
+    };
+};
+/**
+ * Canonical's standard Vitest `test` configuration for React packages.
+ *
+ * Returns the `test` block to spread into `defineConfig` from `vitest/config`.
+ * Every distinct React vitest posture in the monorepo is a point in this
+ * option space — DOM-plain, DOM+SSR split, coverage-gated, and node-only — so
+ * there is a single factory rather than per-shape variants.
+ *
+ * `import { reactTestConfig } from "@canonical/vitest-config-react";`
+ *
+ * @example jsdom component package (ds-app family)
+ * ```ts
+ * test: reactTestConfig({ glob: "tests", setupFiles: ["./vitest.setup.ts"] })
+ * ```
+ * @example client + ssr split with 100% coverage (hooks, router)
+ * ```ts
+ * test: reactTestConfig({ glob: "test", ssr: true, coverage: true, plugins, setupFiles: ["./vitest.setup.ts"] })
+ * ```
+ * @example node-only adapter with overridden coverage include
+ * ```ts
+ * test: reactTestConfig({ glob: "tests", environment: "node", coverage: { include: ["src/lib/**\/*.ts"] } })
+ * ```
+ */
+export const reactTestConfig = ({ glob, environment = "jsdom", ssr = false, coverage = false, setupFiles, plugins, }) => {
+    const hasSetup = setupFiles !== undefined && setupFiles.length > 0;
+    // Normalise to an array: a single convention is the common case, the array
+    // form covers packages whose files are split between `.test.` and `.tests.`.
+    const globs = Array.isArray(glob) ? glob : [glob];
+    // The client project: DOM (or node) tests, excluding the `.ssr.` variants
+    // when an ssr project will pick them up.
+    const clientTest = {
+        name: "client",
+        environment,
+        globals: true,
+        ...(hasSetup ? { setupFiles } : {}),
+        include: globs.flatMap((g) => [`src/**/*.${g}.ts`, `src/**/*.${g}.tsx`]),
+        ...(ssr ? { exclude: globs.map((g) => `src/**/*.ssr.${g}.tsx`) } : {}),
+    };
+    const coverageBlock = coverage === false ? {} : { coverage: buildCoverage(coverage, globs) };
+    // No split: return a flat single-project test block (the common case).
+    if (!ssr) {
+        // The client project's identity (`name`) is only meaningful in a split, so
+        // a flat config omits it to match the hand-written single-project shape.
+        const { name: _name, ...flat } = clientTest;
+        return { ...flat, ...coverageBlock };
+    }
+    // Split: a jsdom/node client project plus a node ssr project that runs only
+    // the `.ssr.` files.
+    const ssrTest = {
+        name: "ssr",
+        environment: "node",
+        include: globs.map((g) => `src/**/*.ssr.${g}.tsx`),
+    };
+    return {
+        ...coverageBlock,
+        projects: [
+            { ...(plugins ? { plugins } : {}), test: clientTest },
+            { ...(plugins ? { plugins } : {}), test: ssrTest },
+        ],
+    };
+};
+//# sourceMappingURL=reactTestConfig.js.map

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export type { CoverageOption, ReactTestConfigOptions, TestGlob, } from "./reactTestConfig.js";
+export { reactTestConfig } from "./reactTestConfig.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/reactTestConfig.d.ts

@@ -0,0 +1,89 @@
+import type { PluginOption } from "vite";
+import type { ViteUserConfig } from "vitest/config";
+/** The `test` block of a Vitest config, as consumed by `defineConfig({ test })`. */
+type TestConfig = NonNullable<ViteUserConfig["test"]>;
+/**
+ * The two test-file glob conventions in use across the React packages. This is
+ * a REQUIRED option with no default: `.test.` and `.tests.` are load-bearing,
+ * and a wrong choice silently matches zero files — a green run that ran
+ * nothing. Packages whose files are split between the two conventions pass
+ * both as an array until the repo-wide naming unification lands. See
+ * pragma-adrs (Track: unified config).
+ */
+export type TestGlob = "test" | "tests";
+/** Coverage options. `true` enables v8 coverage with 100% thresholds. */
+export type CoverageOption = boolean | {
+    /** Threshold overrides; each defaults to 100 when coverage is enabled. */
+    thresholds?: Partial<Record<"branches" | "functions" | "lines" | "statements", number>>;
+    /** Extra `coverage.include` globs (defaults to `src/**` for the runtime). */
+    include?: string[];
+    /** Extra `coverage.exclude` globs, merged after the standard excludes. */
+    exclude?: string[];
+};
+export interface ReactTestConfigOptions {
+    /**
+     * Test-file glob convention. REQUIRED — no default; see {@link TestGlob}.
+     *
+     * Pass an array to run BOTH conventions (e.g. `["test", "tests"]`) in a
+     * package whose files are mid-migration between the two. This is an interim
+     * escape hatch until the repo-wide naming unification lands — see the README.
+     */
+    glob: TestGlob | TestGlob[];
+    /**
+     * Test environment. `"jsdom"` (default) for DOM component tests, `"node"`
+     * for framework-agnostic / SSR-only packages.
+     *
+     * @note jsdom is the interim environment. The forward path is Vitest browser
+     * mode with Playwright (see the svelte-ds-global migration); this factory
+     * will gain a `browser` option to drive that per-package flip without a
+     * config rewrite.
+     */
+    environment?: "jsdom" | "node";
+    /**
+     * When true, adds a second `node`-environment project that runs
+     * `**\/*.ssr.<glob>.tsx` files (client project excludes them). Mirrors the
+     * client/ssr split used by ds-global, hooks, head, router and tokens.
+     */
+    ssr?: boolean;
+    /**
+     * v8 coverage. `false` (default) attaches no coverage block — preserving the
+     * behaviour of packages that do not currently gate coverage. `true` enables
+     * coverage with 100/100/100/100 thresholds. Pass an object to override
+     * thresholds/include/exclude while keeping the 100% defaults for any omitted
+     * threshold.
+     */
+    coverage?: CoverageOption;
+    /** Setup files (e.g. `["./vitest.setup.ts"]`); omitted when empty. */
+    setupFiles?: string[];
+    /**
+     * Vite plugins to attach to each project. Vitest resolves plugins per
+     * project, so packages with a split pass their `[react()]` here.
+     */
+    plugins?: any[] | PluginOption[];
+}
+/**
+ * Canonical's standard Vitest `test` configuration for React packages.
+ *
+ * Returns the `test` block to spread into `defineConfig` from `vitest/config`.
+ * Every distinct React vitest posture in the monorepo is a point in this
+ * option space — DOM-plain, DOM+SSR split, coverage-gated, and node-only — so
+ * there is a single factory rather than per-shape variants.
+ *
+ * `import { reactTestConfig } from "@canonical/vitest-config-react";`
+ *
+ * @example jsdom component package (ds-app family)
+ * ```ts
+ * test: reactTestConfig({ glob: "tests", setupFiles: ["./vitest.setup.ts"] })
+ * ```
+ * @example client + ssr split with 100% coverage (hooks, router)
+ * ```ts
+ * test: reactTestConfig({ glob: "test", ssr: true, coverage: true, plugins, setupFiles: ["./vitest.setup.ts"] })
+ * ```
+ * @example node-only adapter with overridden coverage include
+ * ```ts
+ * test: reactTestConfig({ glob: "tests", environment: "node", coverage: { include: ["src/lib/**\/*.ts"] } })
+ * ```
+ */
+export declare const reactTestConfig: ({ glob, environment, ssr, coverage, setupFiles, plugins, }: ReactTestConfigOptions) => TestConfig;
+export {};
+//# sourceMappingURL=reactTestConfig.d.ts.map

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@canonical/vitest-config-react",
+  "version": "0.29.0",
+  "type": "module",
+  "description": "Canonical's standard Vitest configuration factory for React packages",
+  "main": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/esm/index.js"
+    }
+  },
+  "author": {
+    "email": "webteam@canonical.com",
+    "name": "Canonical Webteam"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/canonical/pragma"
+  },
+  "license": "LGPL-3.0",
+  "bugs": {
+    "url": "https://github.com/canonical/pragma/issues"
+  },
+  "homepage": "https://github.com/canonical/pragma#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:all": "tsc -p tsconfig.build.json",
+    "check": "bun run check:biome",
+    "check:fix": "bun run check:biome:fix && bun run check:ts",
+    "check:biome": "biome check",
+    "check:biome:fix": "biome check --write",
+    "check:ts": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3",
+    "vite": "^8.0.1",
+    "vitest": "^4.0.18"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.9",
+    "@canonical/biome-config": "^0.29.0",
+    "@canonical/typescript-config": "^0.29.0",
+    "@types/node": "^24.12.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.1",
+    "vitest": "^4.0.18"
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export type {
+  CoverageOption,
+  ReactTestConfigOptions,
+  TestGlob,
+} from "./reactTestConfig.js";
+export { reactTestConfig } from "./reactTestConfig.js";

package/src/reactTestConfig.ts

@@ -0,0 +1,197 @@
+import type { PluginOption } from "vite";
+import type { ViteUserConfig } from "vitest/config";
+
+/** The `test` block of a Vitest config, as consumed by `defineConfig({ test })`. */
+type TestConfig = NonNullable<ViteUserConfig["test"]>;
+
+/**
+ * Vitest's coverage options. Derived from the public `test` type rather than
+ * importing the internal `CoverageV8Options` name, which `vitest/config` does
+ * not re-export.
+ */
+type CoverageConfig = NonNullable<TestConfig["coverage"]>;
+
+/**
+ * The two test-file glob conventions in use across the React packages. This is
+ * a REQUIRED option with no default: `.test.` and `.tests.` are load-bearing,
+ * and a wrong choice silently matches zero files — a green run that ran
+ * nothing. Packages whose files are split between the two conventions pass
+ * both as an array until the repo-wide naming unification lands. See
+ * pragma-adrs (Track: unified config).
+ */
+export type TestGlob = "test" | "tests";
+
+/** Coverage options. `true` enables v8 coverage with 100% thresholds. */
+export type CoverageOption =
+  | boolean
+  | {
+      /** Threshold overrides; each defaults to 100 when coverage is enabled. */
+      thresholds?: Partial<
+        Record<"branches" | "functions" | "lines" | "statements", number>
+      >;
+      /** Extra `coverage.include` globs (defaults to `src/**` for the runtime). */
+      include?: string[];
+      /** Extra `coverage.exclude` globs, merged after the standard excludes. */
+      exclude?: string[];
+    };
+
+export interface ReactTestConfigOptions {
+  /**
+   * Test-file glob convention. REQUIRED — no default; see {@link TestGlob}.
+   *
+   * Pass an array to run BOTH conventions (e.g. `["test", "tests"]`) in a
+   * package whose files are mid-migration between the two. This is an interim
+   * escape hatch until the repo-wide naming unification lands — see the README.
+   */
+  glob: TestGlob | TestGlob[];
+  /**
+   * Test environment. `"jsdom"` (default) for DOM component tests, `"node"`
+   * for framework-agnostic / SSR-only packages.
+   *
+   * @note jsdom is the interim environment. The forward path is Vitest browser
+   * mode with Playwright (see the svelte-ds-global migration); this factory
+   * will gain a `browser` option to drive that per-package flip without a
+   * config rewrite.
+   */
+  environment?: "jsdom" | "node";
+  /**
+   * When true, adds a second `node`-environment project that runs
+   * `**\/*.ssr.<glob>.tsx` files (client project excludes them). Mirrors the
+   * client/ssr split used by ds-global, hooks, head, router and tokens.
+   */
+  ssr?: boolean;
+  /**
+   * v8 coverage. `false` (default) attaches no coverage block — preserving the
+   * behaviour of packages that do not currently gate coverage. `true` enables
+   * coverage with 100/100/100/100 thresholds. Pass an object to override
+   * thresholds/include/exclude while keeping the 100% defaults for any omitted
+   * threshold.
+   */
+  coverage?: CoverageOption;
+  /** Setup files (e.g. `["./vitest.setup.ts"]`); omitted when empty. */
+  setupFiles?: string[];
+  /**
+   * Vite plugins to attach to each project. Vitest resolves plugins per
+   * project, so packages with a split pass their `[react()]` here.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: Vite 8 plugin types are incompatible with vitest's Vite 7 re-exports (matches per-package configs).
+  plugins?: any[] | PluginOption[];
+}
+
+/** Standard coverage excludes shared by every coverage-gated package. */
+const BASE_COVERAGE_EXCLUDE = [
+  "**/index.ts",
+  "**/*.d.ts",
+  "**/types.ts",
+] as const;
+
+const FULL_THRESHOLDS = {
+  branches: 100,
+  functions: 100,
+  lines: 100,
+  statements: 100,
+} as const;
+
+/**
+ * Build the v8 coverage block. Test files are always excluded (both `.test.`
+ * and `.tests.` plus their `.ssr.` variants) so coverage measures runtime code
+ * only. Thresholds default to 100% and are overridable per the storybook-config
+ * convention of "sensible defaults you pass through".
+ */
+const buildCoverage = (
+  coverage: Exclude<CoverageOption, false>,
+  globs: readonly TestGlob[],
+): CoverageConfig => {
+  const overrides = coverage === true ? {} : coverage;
+  const testExclude = globs.flatMap((glob) => [
+    `**/*.${glob}.ts`,
+    `**/*.${glob}.tsx`,
+    `**/*.ssr.${glob}.ts`,
+    `**/*.ssr.${glob}.tsx`,
+  ]);
+  return {
+    provider: "v8",
+    include: overrides.include ?? ["src/**/*.{ts,tsx}"],
+    exclude: [
+      ...BASE_COVERAGE_EXCLUDE,
+      ...testExclude,
+      ...(overrides.exclude ?? []),
+    ],
+    thresholds: { ...FULL_THRESHOLDS, ...overrides.thresholds },
+  };
+};
+
+/**
+ * Canonical's standard Vitest `test` configuration for React packages.
+ *
+ * Returns the `test` block to spread into `defineConfig` from `vitest/config`.
+ * Every distinct React vitest posture in the monorepo is a point in this
+ * option space — DOM-plain, DOM+SSR split, coverage-gated, and node-only — so
+ * there is a single factory rather than per-shape variants.
+ *
+ * `import { reactTestConfig } from "@canonical/vitest-config-react";`
+ *
+ * @example jsdom component package (ds-app family)
+ * ```ts
+ * test: reactTestConfig({ glob: "tests", setupFiles: ["./vitest.setup.ts"] })
+ * ```
+ * @example client + ssr split with 100% coverage (hooks, router)
+ * ```ts
+ * test: reactTestConfig({ glob: "test", ssr: true, coverage: true, plugins, setupFiles: ["./vitest.setup.ts"] })
+ * ```
+ * @example node-only adapter with overridden coverage include
+ * ```ts
+ * test: reactTestConfig({ glob: "tests", environment: "node", coverage: { include: ["src/lib/**\/*.ts"] } })
+ * ```
+ */
+export const reactTestConfig = ({
+  glob,
+  environment = "jsdom",
+  ssr = false,
+  coverage = false,
+  setupFiles,
+  plugins,
+}: ReactTestConfigOptions): TestConfig => {
+  const hasSetup = setupFiles !== undefined && setupFiles.length > 0;
+  // Normalise to an array: a single convention is the common case, the array
+  // form covers packages whose files are split between `.test.` and `.tests.`.
+  const globs = Array.isArray(glob) ? glob : [glob];
+
+  // The client project: DOM (or node) tests, excluding the `.ssr.` variants
+  // when an ssr project will pick them up.
+  const clientTest: TestConfig = {
+    name: "client",
+    environment,
+    globals: true,
+    ...(hasSetup ? { setupFiles } : {}),
+    include: globs.flatMap((g) => [`src/**/*.${g}.ts`, `src/**/*.${g}.tsx`]),
+    ...(ssr ? { exclude: globs.map((g) => `src/**/*.ssr.${g}.tsx`) } : {}),
+  };
+
+  const coverageBlock =
+    coverage === false ? {} : { coverage: buildCoverage(coverage, globs) };
+
+  // No split: return a flat single-project test block (the common case).
+  if (!ssr) {
+    // The client project's identity (`name`) is only meaningful in a split, so
+    // a flat config omits it to match the hand-written single-project shape.
+    const { name: _name, ...flat } = clientTest;
+    return { ...flat, ...coverageBlock };
+  }
+
+  // Split: a jsdom/node client project plus a node ssr project that runs only
+  // the `.ssr.` files.
+  const ssrTest: TestConfig = {
+    name: "ssr",
+    environment: "node",
+    include: globs.map((g) => `src/**/*.ssr.${g}.tsx`),
+  };
+
+  return {
+    ...coverageBlock,
+    projects: [
+      { ...(plugins ? { plugins } : {}), test: clientTest },
+      { ...(plugins ? { plugins } : {}), test: ssrTest },
+    ],
+  };
+};

package/tsconfig.build.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist/esm",
+    "declaration": true,
+    "declarationDir": "dist/types",
+    "declarationMap": true,
+    "sourceMap": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  }
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "@canonical/typescript-config",
+  "compilerOptions": {
+    "baseUrl": "src",
+    "moduleResolution": "NodeNext",
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}