@equinor/fusion-framework-vitest-plugin-react-app 0.2.0-next.0

package/docs/overview.md

@@ -0,0 +1,49 @@
+# Test Fusion React apps
+
+Fusion Framework uses Vitest for application tests. Vitest shares Vite's module and
+configuration model, runs components in a real browser, and owns the test runner, assertions,
+fixtures, spies, coverage, and editor integration. Fusion provides only the application scope
+and deterministic platform boundaries needed to test production behavior.
+
+Use `@equinor/fusion-framework-vitest-plugin-react-app` when a React hook, component, route,
+or complete app consumes Fusion modules. The package resolves app files, initializes the real
+framework and app provider nesting, and substitutes supported external clients without
+introducing a second testing language.
+
+## Choose the subject
+
+| Subject | Start with | What the test proves |
+| --- | --- | --- |
+| Pure function or framework-independent hook | Standard Vitest | Local behavior without a Fusion runtime |
+| Hook that consumes Fusion app modules | `renderAppHook` | Hook behavior inside an initialized app scope |
+| Component that consumes Fusion app modules | `/test` `render` fixture or `renderAppComponent` | Rendered behavior with real providers |
+| Route or complete application | `/test` `test` and `render` | App configuration, navigation, loaders, and module lifecycle together |
+| Framework or module integration without React | Package `/mock` entry points | Production provider behavior with external boundaries substituted |
+
+Prefer the smallest layer containing the behavior under assertion. A component test should
+not recreate a portal, while an app lifecycle test should not replace every Fusion hook with
+a JavaScript module mock.
+
+## Start here
+
+Follow [Getting started](getting-started.md) to install the browser dependencies, configure
+Vitest, and run one deterministic app test without credentials, a portal, or backend services.
+
+## Continue by task
+
+- [Configure Vitest defaults and non-standard app files](configuration.md)
+- [Compose fixtures and explicit render options](advanced.md)
+- [Seed Fusion module dependencies](module-mocks.md)
+- [Troubleshoot browser, app-resolution, and network failures](troubleshooting.md)
+- [Understand the Browser Mode default or choose another renderer](why-browser-mode.md)
+- [Migrate an existing app from Testing Library and DOM emulation](migrating-an-existing-app.md)
+- [Choose between app, framework, module, and HTTP testing](../../../framework/docs/testing-choosing-a-layer.md)
+
+Use the official Vitest documentation for generic runner concepts:
+
+- [Why Vitest](https://vitest.dev/guide/why)
+- [Writing tests](https://vitest.dev/guide/learn/writing-tests)
+- [Browser Mode](https://vitest.dev/guide/browser/)
+- [Test context and fixtures](https://vitest.dev/guide/test-context)
+- [Configuration](https://vitest.dev/config/)
+- [Mocking](https://vitest.dev/guide/mocking)

package/docs/troubleshooting.md

@@ -0,0 +1,64 @@
+# Troubleshoot Fusion React app tests
+
+Use this guide when a Fusion app test fails before the assertion, loads real services, cannot
+resolve the app, or behaves differently in Vitest Browser Mode.
+
+## Common symptoms
+
+| Symptom | Likely cause | Resolution |
+| --- | --- | --- |
+| Chromium executable is missing | Playwright installed without its browser binary | Run `pnpm exec playwright install chromium` |
+| The `/test` import cannot resolve Fusion virtual modules | `appTestVitePlugin` is not registered in this Vitest project | Export `defineProject()` from the package's `/config` entry point or register `appTestVitePlugin()` manually |
+| `FileNotFoundError` names a manifest, config, or configurator | An explicit plugin path does not exist | Correct the path relative to the Vitest project root; explicit paths fail instead of falling back |
+| The app's module configuration is not applied | No conventional `src/config.ts(x|js)` file was found | Pass `configure` to `appTestVitePlugin` or override the `configure` fixture |
+| A render result is a Promise or assertions run before initialization | A Fusion render helper was not awaited | Await `render`, `renderHook`, `renderAppComponent`, or `renderAppHook` |
+| A request reaches a live backend or fails with a network error | No HTTP middleware answered it | Add a matching `configurator.http.addMiddleware`; unmatched requests eventually reach the real network |
+| A lazy route import reloads the browser during a test | Source warmup no longer covers the lazy module | Keep `server.warmup.clientFiles` aligned with application source and route locations |
+| No tests are found | Tests are outside the default `src/**/*.{test,spec}.{ts,tsx}` pattern | Override `test.include` in `defineProject` |
+| The app starts signed in unexpectedly | The MSAL mock defaults to `Test User` | Set `configurator.msal.setAccount(null)` before rendering |
+| State configured in one test is missing in another | Framework and app fixtures are test-scoped | Seed the required state per test or publish reusable fixture declarations with `test.extend` |
+| `vi.spyOn` fails on an imported module in Browser Mode | Native ESM module namespace objects are sealed | Use `vi.mock('./module.js', { spy: true })` as documented by Vitest Browser Mode |
+
+## Verify the project wiring
+
+Start with the smallest configuration:
+
+```ts
+import { defineProject } from '@equinor/fusion-framework-vitest-plugin-react-app/config';
+
+export default defineProject();
+```
+
+Then verify the fixture itself before testing application behavior:
+
+```tsx
+import { expect } from 'vitest';
+import { test } from '@equinor/fusion-framework-vitest-plugin-react-app/test';
+
+test('initializes a Fusion app scope', async ({ app, render }) => {
+  expect(app.auth.account?.name).toBe('Test User');
+  const screen = await render(<div>ready</div>);
+  await expect.element(screen.getByText('ready')).toBeVisible();
+});
+```
+
+If this test fails, fix project or app-file resolution before adding module-specific data.
+
+## Keep tests offline
+
+Fusion mocks replace known external boundaries, but an HTTP middleware is an ordered chain.
+Returning `next(uri, init)` delegates to the next middleware and eventually `fetch`. A test
+that must never use the network should register middleware for every expected request and
+fail deliberately on unexpected requests.
+
+Use `createOpenApiMockMiddleware` from
+`@equinor/fusion-framework-module-http/mock` when an OpenAPI document describes many routes.
+Use `vi.fn` around a middleware when the test also needs call assertions.
+
+## Related references
+
+- [Getting started](getting-started.md)
+- [Configuration and app-file resolution](configuration.md)
+- [Choose a Fusion testing layer](../../../framework/docs/testing-choosing-a-layer.md)
+- [HTTP middleware testing](../../../modules/http/docs/testing.md)
+- [Vitest Browser Mode limitations](https://vitest.dev/guide/browser/#limitations)

package/docs/why-browser-mode.md

@@ -0,0 +1,113 @@
+# Why Browser Mode is the default
+
+`@equinor/fusion-framework-vitest-plugin-react-app` runs component and hook tests in headless
+Chromium by default. A real browser gives these tests more accurate DOM behavior, but it is
+slower than `happy-dom` or `jsdom`.
+
+This guide explains that tradeoff and shows how to use a different browser or renderer when a
+test does not need Chromium.
+
+## Performance
+
+A real browser is slower than DOM emulation. `happy-dom` and `jsdom` run in the same Node process
+as the test. Browser Mode starts Chromium through Playwright and communicates with that browser
+process.
+
+Choose Browser Mode for fidelity, not speed. Keep fast unit tests on Node or DOM emulation when
+they do not need browser behavior.
+
+## Why use a real browser
+
+- **React compatibility:** the previous React test setup failed after its React 19 peer
+  dependency update. The repository then moved those tests to Vitest Browser Mode. See the
+  `packages/utils/observable` 8.4.4 changelog and migration commit `059aefae5d`.
+- **Real framework execution:** tests control external boundaries and seed module state through
+  [Module mocks](module-mocks.md), while the actual module configuration, lifecycle, providers,
+  and rendering behavior still run.
+- **Browser fidelity:** Chromium provides real layout, `ResizeObserver`, custom elements, and
+  Shadow DOM. This can remove DOM polyfills and component replacements that only exist because
+  `happy-dom` or `jsdom` cannot provide the required browser behavior.
+
+A real browser does not remove every test workaround. AG Grid license messages and Lit dev-mode
+warnings can still occur in Chromium. Component mocks may also be useful because they simplify
+focused tests. Remove a workaround only after running the affected test against the real
+component.
+
+## Choose a different runtime
+
+You can change either the browser provider or the renderer:
+
+- Stay in Browser Mode and replace Playwright with another Vitest browser provider.
+- Keep the Fusion module setup but render with `happy-dom` or `jsdom`.
+
+### Use another browser provider
+
+Pass `test.browser.provider` to `defineProject` to replace Playwright while staying in Browser
+Mode. This example uses WebdriverIO:
+
+```ts
+import { defineProject } from '@equinor/fusion-framework-vitest-plugin-react-app/config';
+import { webdriverio } from '@vitest/browser-webdriverio';
+
+export default defineProject({
+  test: { browser: { provider: webdriverio() } },
+});
+```
+
+See [Configuration](configuration.md) for the complete `defineProject` behavior.
+
+### Use happy-dom or jsdom
+
+The Fusion module setup does not depend on Browser Mode. Build the same provider tree and pass it
+to another renderer. The example below uses `@testing-library/react` on `happy-dom`:
+
+```tsx
+import { render } from '@testing-library/react';
+import { mockFramework } from '@equinor/fusion-framework/mock';
+import { enableAppManifestMock, mockAppModules } from '@equinor/fusion-framework-app/mock';
+import { FrameworkProvider } from '@equinor/fusion-framework-react';
+import { ModuleProvider } from '@equinor/fusion-framework-react-module';
+import type { AppModule } from '@equinor/fusion-framework-module-app';
+import type { ReactElement } from 'react';
+
+const env = {
+  manifest: {
+    appKey: 'test-app',
+    displayName: 'Test App',
+    description: 'Test app',
+    type: 'standalone',
+  },
+} as const;
+
+async function renderWithHappyDom(ui: ReactElement) {
+  const framework = await mockFramework<[AppModule]>((configurator) =>
+    enableAppManifestMock(configurator, env),
+  );
+  const app = await mockAppModules(undefined, env, framework);
+  return render(ui, {
+    wrapper: ({ children }) => (
+      <FrameworkProvider value={framework}>
+        <ModuleProvider value={app}>{children}</ModuleProvider>
+      </FrameworkProvider>
+    ),
+  });
+}
+```
+
+Run the test in a Vitest project with `environment: 'happy-dom'` instead of
+`browser.enabled`. Use a separate project if the same app also has Browser Mode tests.
+
+Call the same `enable*Mock` functions from the `mockAppModules` configuration callback. These
+mocks configure Fusion modules and do not depend on the renderer. `renderHook` from
+`@testing-library/react` can use the same wrapper for hook tests.
+
+Use Browser Mode when browser behavior matters. Use `happy-dom`, `jsdom`, or no DOM for focused
+tests that only need application logic or simple rendering.
+
+## Related documentation
+
+- [Overview](overview.md)
+- [Configuration](configuration.md)
+- [Module mocks](module-mocks.md)
+- [Migrate an existing app to Fusion Vitest](migrating-an-existing-app.md)
+- [Choose a Fusion testing layer](../../../framework/docs/testing-choosing-a-layer.md)

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@equinor/fusion-framework-vitest-plugin-react-app",
+  "version": "0.2.0-next.0",
+  "description": "Vite plugin resolving an application's manifest, config, and module-configurator as virtual modules for testing.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./test": {
+      "types": "./dist/types/app-test.d.ts",
+      "import": "./dist/esm/app-test.js"
+    },
+    "./config": {
+      "types": "./dist/types/define-project.d.ts",
+      "import": "./dist/esm/define-project.js"
+    }
+  },
+  "types": "dist/types/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "test": [
+        "dist/types/app-test.d.ts"
+      ],
+      "config": [
+        "dist/types/define-project.d.ts"
+      ]
+    }
+  },
+  "directories": {
+    "dist": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/equinor/fusion-framework.git",
+    "directory": "packages/vitest-plugin/react-app"
+  },
+  "keywords": [
+    "vite",
+    "vitest",
+    "fusion-framework",
+    "testing"
+  ],
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@equinor/fusion-framework": "8.1.0-next.0",
+    "@equinor/fusion-framework-app": "14.0.0-next.0",
+    "@equinor/fusion-framework-module-app": "8.1.0-next.0",
+    "@equinor/fusion-framework-react": "9.0.0-next.0",
+    "@equinor/fusion-framework-react-module": "4.0.3-next.0",
+    "@equinor/fusion-imports": "2.0.3-next.0",
+    "@equinor/fusion-framework-cli": "15.2.8-next.0",
+    "@equinor/fusion-framework-module": "6.1.3-next.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/browser-playwright": "^4.1.0",
+    "playwright": "^1.62.1",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1",
+    "rxjs": "^7.8.1",
+    "typescript": "^7.0.2",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.10",
+    "vitest-browser-react": "^2.2.0"
+  },
+  "peerDependencies": {
+    "@types/react": "^18.0.0 || ^19.0.0",
+    "@vitest/browser-playwright": "^4.0.0",
+    "playwright": "^1.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "rxjs": "^7.0.0",
+    "vite": "^8.0.0",
+    "vitest": "^4.0.0",
+    "vitest-browser-react": "^2.2.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest --run"
+  }
+}

package/src/__tests__/app-test-vite-plugin.test.ts

@@ -0,0 +1,109 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { appTestVitePlugin } from '../index.js';
+
+type ResolveIdHook = (id: string) => string | null | undefined;
+type LoadHook = (id: string) => string | null | undefined | Promise<string | null | undefined>;
+type ConfigResolvedHook = (config: { root: string }) => void;
+
+describe('appTestVitePlugin', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'fusion-vitest-plugin-react-app-'));
+    await writeFile(
+      join(dir, 'package.json'),
+      JSON.stringify({ name: '@equinor/my-app', version: '1.2.3' }),
+    );
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('claims only its two virtual specifiers, leaving everything else unresolved', () => {
+    const plugin = appTestVitePlugin({ entrypoint: dir });
+    const resolveId = plugin.resolveId as ResolveIdHook;
+
+    expect(resolveId('virtual:fusion-app-test-env')).toBe('\0virtual:fusion-app-test-env');
+    expect(resolveId('virtual:fusion-app-test-configure')).toBe(
+      '\0virtual:fusion-app-test-configure',
+    );
+    expect(resolveId('some-other-module')).toBeNull();
+  });
+
+  it('serves the resolved manifest/config as the env virtual module', async () => {
+    const plugin = appTestVitePlugin({ entrypoint: dir });
+    const load = plugin.load as LoadHook;
+
+    const source = await load('\0virtual:fusion-app-test-env');
+
+    expect(source).toContain('"appKey":"my-app"');
+    expect(source).toContain('export const config = {"environment":{}};');
+  });
+
+  it('serves an undefined configure export when no config file exists', async () => {
+    const plugin = appTestVitePlugin({ entrypoint: dir });
+    const load = plugin.load as LoadHook;
+
+    const source = await load('\0virtual:fusion-app-test-configure');
+
+    expect(source).toBe('export const configure = undefined;');
+  });
+
+  it('resolves the app from the Vitest project root when no entrypoint is provided', async () => {
+    await mkdir(join(dir, 'src'), { recursive: true });
+    await writeFile(join(dir, 'src', 'index.ts'), 'export {};');
+    await writeFile(join(dir, 'src', 'config.ts'), 'export default () => undefined;');
+    const plugin = appTestVitePlugin();
+    const configResolved = plugin.configResolved as ConfigResolvedHook;
+    const load = plugin.load as LoadHook;
+
+    configResolved({ root: dir });
+
+    expect(await load('\0virtual:fusion-app-test-env')).toContain('"appKey":"my-app"');
+    expect(await load('\0virtual:fusion-app-test-configure')).toBe(
+      `export { default as configure } from ${JSON.stringify(join(dir, 'src', 'config.ts'))};`,
+    );
+  });
+
+  it('re-exports the default candidate config file as the configure virtual module', async () => {
+    await mkdir(join(dir, 'src'), { recursive: true });
+    await writeFile(join(dir, 'src', 'config.ts'), 'export default () => undefined;');
+    const plugin = appTestVitePlugin({ entrypoint: dir });
+    const load = plugin.load as LoadHook;
+
+    const source = await load('\0virtual:fusion-app-test-configure');
+
+    expect(source).toBe(
+      `export { default as configure } from ${JSON.stringify(join(dir, 'src', 'config.ts'))};`,
+    );
+  });
+
+  it('re-exports an explicitly requested configure file', async () => {
+    await writeFile(join(dir, 'my-config.ts'), 'export default () => undefined;');
+    const plugin = appTestVitePlugin({ entrypoint: dir, configure: 'my-config.ts' });
+    const load = plugin.load as LoadHook;
+
+    const source = await load('\0virtual:fusion-app-test-configure');
+
+    expect(source).toBe(
+      `export { default as configure } from ${JSON.stringify(join(dir, 'my-config.ts'))};`,
+    );
+  });
+
+  it('throws when an explicitly requested configure file does not exist', () => {
+    expect(() => appTestVitePlugin({ entrypoint: dir, configure: 'missing.ts' })).toThrow();
+  });
+
+  it('returns null for module ids other than its own virtual specifiers', async () => {
+    const plugin = appTestVitePlugin({ entrypoint: dir });
+    const load = plugin.load as LoadHook;
+
+    expect(await load('some-other-module')).toBeNull();
+  });
+});

package/src/__tests__/resolve-app-test-env.test.ts

@@ -0,0 +1,83 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { resolveAppTestEnv } from '../resolve-app-test-env.js';
+
+describe('resolveAppTestEnv', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'fusion-vitest-plugin-react-app-'));
+    await writeFile(
+      join(dir, 'package.json'),
+      JSON.stringify({ name: '@equinor/my-app', version: '1.2.3', description: 'a test app' }),
+    );
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('falls back to a package-derived manifest and an empty config with no local files', async () => {
+    const { manifest, config } = await resolveAppTestEnv({ entrypoint: dir });
+
+    expect(manifest).toMatchObject({
+      appKey: 'my-app',
+      displayName: '@equinor/my-app',
+      description: 'a test app',
+      type: 'standalone',
+    });
+    expect(config).toEqual({ environment: {} });
+  });
+
+  it('merges a local app.manifest.ts and app.config.ts, same as ffc app build', async () => {
+    await writeFile(
+      join(dir, 'app.manifest.ts'),
+      "export default { displayName: 'My Custom App' };",
+    );
+    await writeFile(
+      join(dir, 'app.config.ts'),
+      "export default { environment: {}, endpoints: { api: { url: 'https://example.com' } } };",
+    );
+
+    const { manifest, config } = await resolveAppTestEnv({ entrypoint: dir });
+
+    expect(manifest).toMatchObject({ appKey: 'my-app', displayName: 'My Custom App' });
+    expect(config).toEqual({
+      environment: {},
+      endpoints: { api: { url: 'https://example.com', scopes: [] } },
+    });
+  });
+
+  it('applies an inline manifest/config function directly, same as a loaded file default export', async () => {
+    const { manifest, config } = await resolveAppTestEnv({
+      entrypoint: dir,
+      manifest: () => ({ displayName: 'Inline App' }),
+      config: () => ({
+        environment: {},
+        endpoints: { api: { url: 'https://inline.example.com' } },
+      }),
+    });
+
+    expect(manifest).toMatchObject({ appKey: 'my-app', displayName: 'Inline App' });
+    expect(config).toEqual({
+      environment: {},
+      endpoints: { api: { url: 'https://inline.example.com', scopes: [] } },
+    });
+  });
+
+  it('propagates an error for an explicitly requested manifest file that does not exist', async () => {
+    await expect(
+      resolveAppTestEnv({ entrypoint: dir, manifest: 'does-not-exist.manifest.ts' }),
+    ).rejects.toThrow();
+  });
+
+  it('propagates an error for an explicitly requested config file that does not exist', async () => {
+    await expect(
+      resolveAppTestEnv({ entrypoint: dir, config: 'does-not-exist.config.ts' }),
+    ).rejects.toThrow();
+  });
+});

package/src/app-test.ts

@@ -0,0 +1,18 @@
+export {
+  renderAppHook,
+  type RenderAppHookOptions,
+  type RenderAppHookResult,
+} from './render-app-hook';
+export {
+  renderAppComponent,
+  type RenderAppComponentOptions,
+  type RenderAppComponentResult,
+} from './render-app-component';
+export { testApp } from './test-app';
+export type { AppMockConfigureFn } from '@equinor/fusion-framework-app/mock';
+
+// `test`/`render` import virtual modules only served once `appTestVitePlugin`
+// (@equinor/fusion-framework-vitest-plugin-react-app) is registered — using any export from
+// this module requires the plugin registered in your `vitest.config.ts` `plugins`.
+export { test } from './test';
+export { render } from './render';

package/src/define-project.ts

@@ -0,0 +1,84 @@
+import { playwright } from '@vitest/browser-playwright';
+import {
+  defineProject as defineVitestProject,
+  mergeConfig,
+  type UserWorkspaceConfig,
+} from 'vitest/config';
+
+import { appTestVitePlugin } from './index.js';
+
+/**
+ * A config override for {@link defineProject}: an object is deep-merged onto the default
+ * config via Vite's own `mergeConfig`; a function receives the default config and returns the
+ * config used outright, for changes `mergeConfig` can't express (e.g. removing a field).
+ */
+export type AppTestConfigOverride =
+  | Partial<UserWorkspaceConfig>
+  | ((config: UserWorkspaceConfig) => UserWorkspaceConfig);
+
+/**
+ * Builds a ready-to-export Vitest project config for testing a Fusion Framework React app:
+ * registers {@link appTestVitePlugin} (with its own defaults) and wires up Vitest browser mode
+ * with the Playwright/`chromium` provider, so a consuming app's own `vitest.config.ts` needs no
+ * browser-provider boilerplate of its own.
+ *
+ * @remarks
+ * Drop-in replacement for Vitest's own `defineProject` — same `export default`, just pre-wired.
+ * Playwright/`chromium` is only the *default* — pass `override` to change or replace anything
+ * (e.g. `test.name`, or swap `test.browser.provider` for a different `@vitest/browser-*`
+ * provider) without hand-rolling `appTestVitePlugin`'s own wiring.
+ *
+ * @example
+ * ```ts
+ * import { defineProject } from '@equinor/fusion-framework-vitest-plugin-react-app/config';
+ * import { name, version } from './package.json' with { type: 'json' };
+ *
+ * export default defineProject({ test: { name: `${name}@${version}` } });
+ * ```
+ *
+ * @example
+ * Overriding the browser provider:
+ * ```ts
+ * import { webdriverio } from '@vitest/browser-webdriverio';
+ *
+ * export default defineProject({ test: { browser: { provider: webdriverio() } } });
+ * ```
+ *
+ * @param override - Deep-merged onto the default config (a plain object), or applied to it
+ * outright (a function receiving the default config); see {@link AppTestConfigOverride}.
+ * @returns A Vitest project config, ready to `export default`.
+ */
+export const defineProject = (override?: AppTestConfigOverride): UserWorkspaceConfig => {
+  const defaults: UserWorkspaceConfig = {
+    plugins: [appTestVitePlugin()],
+    test: {
+      include: ['src/**/*.{test,spec}.{ts,tsx}'],
+      browser: {
+        enabled: true,
+        provider: playwright(),
+        headless: true,
+        instances: [{ browser: 'chromium' }],
+      },
+    },
+    // pre-transforms all source up front so deps only reached via lazy/code-split imports
+    // (e.g. route components) are discovered before the first test request, not mid-run —
+    // the latter forces Vite to reload the page and fails the in-flight test file import
+    server: { warmup: { clientFiles: ['src/**/*.{ts,tsx}'] } },
+    // same reasoning as `server.warmup` above, but for the esbuild dep scanner: without this,
+    // its default entry detection can miss code-split route files entirely, so a package only
+    // ever imported from one of those (e.g. react-router's own deps) is discovered mid-run
+    // instead of up front — statically crawling every source file (which esbuild's scanner
+    // follows through dynamic imports too) avoids that with no per-package name needed
+    optimizeDeps: { entries: ['src/**/*.{ts,tsx}'] },
+  };
+  // a function replaces the config outright; a plain object deep-merges onto it via Vite's own mergeConfig
+  const resolved =
+    typeof override === 'function'
+      ? override(defaults)
+      : override
+        ? (mergeConfig(defaults, override) as UserWorkspaceConfig)
+        : defaults;
+  return defineVitestProject(resolved);
+};
+
+export default defineProject;