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

package/docs/advanced.md

@@ -0,0 +1,140 @@
+# Advanced Fusion app testing
+
+The `/test` entry point extends Vitest's test context with `env`, `configure`, `fusion`, `app`,
+`render`, and `renderHook`. Fixture declarations are reusable, while each test receives fresh
+framework and app module instances.
+
+This guide covers composing and overriding those six Fusion fixture values; see Vitest's own
+[Test Context](https://vitest.dev/guide/test-context) documentation for fixture scope, cleanup,
+and the general `test.extend`/`test.override` mechanics Fusion builds on.
+
+## Choose a rendering API
+
+| API | Use it when |
+| --- | --- |
+| `test` from `/test` | The app's manifest, config, and module configurator should resolve automatically |
+| `render` from `/test` | A standard `describe` or `it` block needs the automatically resolved app scope |
+| `renderAppHook` | A hook needs an app scope with explicitly supplied options |
+| `renderAppComponent` | A component needs explicit `env`, `configure`, or parent `fusion` options |
+| `testApp` | A reusable fixture should not depend on Vite's automatic app-file resolution |
+
+All Fusion rendering APIs initialize modules asynchronously and must be awaited. The lower
+level helpers return `fusion.framework` and `fusion.app`, allowing a test to drive the exact
+module instances consumed by the rendered subject.
+
+## Extend app configuration
+
+Create one reusable extended test when several cases need the same deterministic modules:
+
+```tsx
+import { enableContextMock } from '@equinor/fusion-framework-module-context/mock';
+import { test as baseTest } from '@equinor/fusion-framework-vitest-plugin-react-app/test';
+
+const project = {
+  id: 'project-a',
+  title: 'Project A',
+  type: { id: 'ProjectMaster' },
+  value: {},
+};
+
+export const test = baseTest.extend('configure', ({ configure }) => (configurator, args) => {
+  configure?.(configurator, args);
+  enableContextMock(configurator, (mock) => mock.setCurrentContext(project));
+});
+```
+
+Composing the original `configure` fixture preserves the application's production module
+configuration. See [Module mocks](module-mocks.md) for authentication, context, bookmark,
+feature-flag, HTTP, analytics, and telemetry boundaries.
+
+`.extend(...)` returns a new, separately exported `test` — reach for it when several test
+*files* need the same fixture default. Within one file, prefer `test.override(...)` (below):
+it replaces a fixture in place, so every test in that file keeps importing the same `test`.
+
+## Override a fixture for one test or a `describe` block
+
+`test.override('name', ...)` replaces a fixture's resolved value without creating a new `test`
+export. Called at the top of a `describe` block, the override applies to every test inside it
+and does not leak to sibling blocks or other files — each `describe` starts from the file's
+base `test` again. Called at the top of the file (outside any `describe`), it applies to every
+test in that file.
+
+```tsx
+import { test } from '@equinor/fusion-framework-vitest-plugin-react-app/test';
+import { enableContextMock } from '@equinor/fusion-framework-module-context/mock';
+import { describe } from 'vitest';
+
+import { configure } from '../config'; // the app's own, real module configurator
+
+const project = { id: 'project-a', title: 'Project A', type: { id: 'ProjectMaster' }, value: {} };
+
+describe('with an initial project', () => {
+  test.override('configure', { injected: true }, () => (configurator, args) => {
+    configure(configurator, args); // compose the app's real configure, same as `.extend`
+    enableContextMock(configurator, (mock) => mock.setCurrentContext(project));
+  });
+
+  test('displays the initial context the app resolves on startup', async ({ render }) => {
+    const { getByText } = await render(<App />);
+    await expect.element(getByText(/project-a/)).toBeInTheDocument();
+  });
+});
+```
+
+`fusion` itself can be overridden the same way, when a case needs a differently configured
+parent framework instance rather than a change to the app's own `configure`:
+
+```tsx
+describe('with a parent framework context', () => {
+  test.override('fusion', async ({ env }) =>
+    mockFramework<[AppModule, ContextModule]>((configurator) => {
+      enableAppManifestMock(configurator, env);
+      enableContextMock(configurator, (mock) => mock.setCurrentContext(project));
+    }),
+  );
+
+  test('mirrors the context the parent sets', async ({ render, fusion }) => {
+    /* ... */
+  });
+});
+```
+
+The `{ injected: true }` option matches the fixture's original declaration (see
+`test-app.tsx`/`test.tsx`); it is not required for `.override(...)` itself, but keeping it
+consistent avoids re-deriving whether the base fixture accepts a config-injected value. See
+the [React context cookbook](../../../../cookbooks/app-react-context/src/App.test.tsx) and
+[feature-flag cookbook](../../../../cookbooks/app-react-feature-flag/src/components/FeatureFlags.test.tsx)
+for full working examples, and Vitest's own
+[Test Context](https://vitest.dev/guide/test-context) guide for fixture scope and cleanup
+mechanics beyond what Fusion adds.
+
+## Supply a custom parent framework
+
+Override or explicitly pass `fusion` when the scenario depends on portal-level context,
+service discovery, authentication, or app manifests. Build the parent with `mockFramework`,
+then initialize the app beneath it. This exercises parent-to-app propagation without a
+running portal.
+
+Use [`enableAppManifestMock`](../../../app/docs/testing.md#enableappmanifestmockconfigurator-env)
+when the custom parent must serve the app's manifest and config. Use
+[`mockFramework`](../../../framework/docs/testing.md) to seed the parent modules.
+
+## Test routes and app lifecycle
+
+Render the complete `App` when assertions depend on route loaders, navigation, app
+configuration, or several modules working together. Set the initial browser URL before
+rendering, interact through visible controls or `app.navigation`, and assert the rendered
+result.
+
+The [React router cookbook](../../../../cookbooks/app-react-router/README.md) demonstrates
+route-unit tests, complete application navigation, and HTTP-backed loaders.
+
+## Runner-level advanced behavior
+
+Fusion does not wrap these Vitest capabilities:
+
+- [Browser interactions and assertions](https://vitest.dev/guide/browser/)
+- [Asynchronous tests](https://vitest.dev/guide/learn/async)
+- [Test projects](https://vitest.dev/guide/projects)
+- [Coverage](https://vitest.dev/guide/coverage)
+- [Debugging](https://vitest.dev/guide/debugging)

package/docs/configuration.md

@@ -0,0 +1,109 @@
+# Configure Fusion React app tests
+
+The package exposes three entry points with different responsibilities:
+
+| Import | Responsibility |
+| --- | --- |
+| `@equinor/fusion-framework-vitest-plugin-react-app/config` | Build a browser-ready Vitest project with `defineProject` |
+| `@equinor/fusion-framework-vitest-plugin-react-app/test` | Resolve the app's files and provide `test` and `render` fixtures |
+| `@equinor/fusion-framework-vitest-plugin-react-app` | Configure the Vite plugin manually or render with explicit `env`, `configure`, and `fusion` options |
+
+## `defineProject` defaults
+
+```ts
+import { defineProject } from '@equinor/fusion-framework-vitest-plugin-react-app/config';
+
+export default defineProject();
+```
+
+The default project registers `appTestVitePlugin()` and configures:
+
+- test files under `src/**/*.{test,spec}.{ts,tsx}`
+- Vitest Browser Mode enabled
+- the Playwright provider with one Chromium instance
+- headless browser execution
+- Vite warmup for `src/**/*.{ts,tsx}` to discover lazy imports before tests run
+
+## Merge ordinary Vitest options
+
+Pass an object to deep-merge it with the defaults through Vite's `mergeConfig`:
+
+```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}`,
+    browser: { viewport: { width: 1280, height: 720 } },
+  },
+});
+```
+
+These are standard Vitest and Vite options. Use the official Vitest configuration reference
+for runner behavior rather than looking for Fusion-specific equivalents.
+
+## Replace defaults deliberately
+
+Pass a function only when a deep merge cannot express the change. The function's return value
+replaces the defaults outright, so preserve every default the project still needs:
+
+```ts
+import { defineProject } from '@equinor/fusion-framework-vitest-plugin-react-app/config';
+
+export default defineProject((defaults) => ({
+  ...defaults,
+  test: {
+    ...defaults.test,
+    include: ['tests/browser/**/*.test.tsx'],
+  },
+}));
+```
+
+When test files move outside `src`, update both `test.include` and `server.warmup.clientFiles`
+if those tests load lazy application modules.
+
+## Resolve non-standard app files
+
+Use `appTestVitePlugin` directly when the app manifest, app configuration, or module
+configurator does not use Fusion's normal file conventions:
+
+```ts
+import { playwright } from '@vitest/browser-playwright';
+import { appTestVitePlugin } from '@equinor/fusion-framework-vitest-plugin-react-app';
+import { defineProject } from 'vitest/config';
+
+export default defineProject({
+  plugins: [
+    appTestVitePlugin({
+      manifest: './config/app.manifest.ts',
+      config: './config/app.config.ts',
+      configure: './config/modules.ts',
+    }),
+  ],
+  test: {
+    browser: {
+      enabled: true,
+      provider: playwright(),
+      headless: true,
+      instances: [{ browser: 'chromium' }],
+    },
+  },
+  server: { warmup: { clientFiles: ['src/**/*.{ts,tsx}'] } },
+});
+```
+
+`entrypoint`, `manifest`, and `config` use the same resolution pipeline as `ffc app build`
+and `ffc app dev`. `configure` must identify a real source file because the plugin re-exports
+its live application code into the test bundle. Explicit files that do not exist throw
+`FileNotFoundError`; convention-based lookups fall back to defaults.
+
+## Choose fixtures or explicit render options
+
+Use `/test` when the app's own files should resolve automatically. Use `renderAppHook`,
+`renderAppComponent`, or `testApp` from the root entry point when the test should pass `env`,
+`configure`, or a parent `fusion` instance explicitly.
+
+- [`test` and app rendering](getting-started.md)
+- [Detailed rendering and fixture APIs](../README.md#renderapphook)
+- [Troubleshooting configuration](troubleshooting.md)

package/docs/getting-started.md

@@ -0,0 +1,66 @@
+# Test a Fusion React app with Vitest
+
+Use `@equinor/fusion-framework-vitest-plugin-react-app` to render an existing Fusion React
+app in Vitest Browser Mode. The test runs in Chromium with a fresh framework and application
+module scope, a deterministic signed-in `Test User`, and no running portal or real credentials.
+
+## Install
+
+```sh
+pnpm add -D vitest playwright @vitest/browser-playwright vitest-browser-react \
+  @equinor/fusion-framework-vitest-plugin-react-app
+pnpm exec playwright install chromium
+```
+
+React, React DOM, RxJS, and Vite are peer dependencies that a Fusion React app normally
+already provides.
+
+## Configure Vitest
+
+Create `vitest.config.ts` at the app project root:
+
+```ts
+import { defineProject } from '@equinor/fusion-framework-vitest-plugin-react-app/config';
+
+export default defineProject();
+```
+
+`defineProject` registers `appTestVitePlugin`, enables headless Chromium through Playwright,
+includes `src/**/*.{test,spec}.{ts,tsx}`, and warms application source files so lazy route
+imports do not reload the browser during a test.
+
+## Write the first app test
+
+```tsx
+import { expect } from 'vitest';
+import { test } from '@equinor/fusion-framework-vitest-plugin-react-app/test';
+import { App } from './App';
+
+test('renders the app', async ({ render }) => {
+  const screen = await render(<App />);
+  await expect.element(screen.getByRole('heading')).toBeVisible();
+});
+```
+
+The `/test` entry point resolves the app's manifest, `app.config.ts`, and module configurator
+through the registered Vite plugin. Always await `render`, `renderHook`,
+`renderAppComponent`, and `renderAppHook`; Fusion module initialization completes before the
+first render.
+
+## Run
+
+```sh
+pnpm exec vitest
+pnpm exec vitest run
+```
+
+The first command watches for changes. The second performs one run for CI. A successful run
+reports one passing test and requires no portal, credentials, or backend service.
+
+## Next steps
+
+- [Configure the test project and app-file resolution](configuration.md)
+- [Resolve common setup, browser, and network failures](troubleshooting.md)
+- [Seed Fusion module dependencies](module-mocks.md)
+- [Choose between app, framework, module, and HTTP test layers](../../../framework/docs/testing-choosing-a-layer.md)
+- [Seed authentication, context, service discovery, and HTTP](../README.md#overview)

package/docs/migrating-an-existing-app.md

@@ -0,0 +1,197 @@
+# Migrate an existing app to Fusion Vitest
+
+Use this guide to move existing application tests to
+`@equinor/fusion-framework-vitest-plugin-react-app`. It covers suites built with
+`@testing-library/react`, `jsdom` or `happy-dom`, hand-written Fusion hook mocks, and mock HTTP
+servers such as MirageJS, MSW, or Nock.
+
+You can migrate one test at a time. A mixed suite is a valid final state.
+
+## Choose which tests to migrate
+
+Start with tests that read from the application module scope through
+`useAppModule`, `useAccessToken`, `useCurrentContext`, `useCurrentBookmark`, `useFeature`, or a
+route that uses several Fusion modules. The plugin can replace their hand-written hook mocks
+with the real module pipeline and supported `enable*Mock` configuration.
+
+Keep pure functions, presentational components, and hooks with no Fusion dependency on their
+current runner when that is simpler. A test can also use the real Fusion module setup without
+Browser Mode by providing its own renderer. See
+[Why Browser Mode is the default](why-browser-mode.md#choose-a-different-runtime).
+
+## What changes, concretely
+
+| Existing pattern | Replace with |
+| --- | --- |
+| `@testing-library/react`'s `render`/`renderHook`/`waitFor`/`act`, on `jsdom` or `happy-dom` | `vitest-browser-react`'s `render`/`renderHook` and `vitest`'s `waitFor`/`act`, on real Chromium (Vitest Browser Mode) |
+| `vi.mock('@equinor/fusion-framework-react/hooks', ...)`, `vi.mock('.../feature-flag', ...)`, and similar hand-rolled Fusion hook mocks | The owning module's `enable*Mock` from its own `/mock` entry point. See [Module mocks](module-mocks.md) |
+| A hand-written mock HTTP server (MirageJS, `msw/node`, `nock`) answering every backend call | `configurator.http.addMiddleware(...)` with a hand-written `HttpMiddleware`, or `createRouterMiddleware` for several routes under one base URI. See [HTTP testing](../../../modules/http/docs/testing.md) |
+| A hand-rolled test wrapper composing a router, context providers, and error boundaries around every render | `test.extend(...)` fixtures stacked on the base `render`/`configure` fixtures. See [Compose a router and a domain fixture](#compose-a-router-and-a-domain-fixture) below |
+| Synchronous assertions (`expect(screen.getByText(...))`) | Browser locators and `await expect.element(screen.getByText(...)).toBeVisible()` |
+
+## Step 1: install Browser Mode dependencies
+
+```sh
+pnpm add -D vitest playwright @vitest/browser-playwright vitest-browser-react \
+  @equinor/fusion-framework-vitest-plugin-react-app
+pnpm exec playwright install chromium
+```
+
+Remove `@testing-library/react`, `@testing-library/dom`, `@testing-library/user-event`, and
+whichever `jsdom`/`happy-dom` package the app installed once every test that used them has
+migrated. Keep them if part of the suite intentionally stays on the old renderer.
+
+Replace the app's `vitest.config.ts` with the plugin's project config:
+
+```ts
+import { defineProject } from '@equinor/fusion-framework-vitest-plugin-react-app/config';
+
+export default defineProject();
+```
+
+`defineProject` registers `appTestVitePlugin`, enables headless Chromium, includes
+`src/**/*.{test,spec}.{ts,tsx}`, and warms application source so lazy route imports don't reload
+the browser mid-test. See [Configuration](configuration.md) for overriding any of that.
+
+## Step 2: replace hand-rolled Fusion hook mocks
+
+The `/test` entry point initializes the real module pipeline. This removes most `vi.mock`
+implementations for hooks such as `useCurrentUser`, `useFeature`, and `useHttpClient`. The
+default setup includes a signed-in `Test User` and initialized feature-flag, context, and
+bookmark modules:
+
+```diff
+-vi.mock('@equinor/fusion-framework-react/hooks', async (importOriginal) => ({
+-  ...(await importOriginal()),
+-  useCurrentUser: vi.fn(() => undefined),
+-}));
+-vi.mock('@equinor/fusion-framework-react-app/feature-flag', () => ({
+-  useFeature: vi.fn(() => ({})),
+-}));
++import { enableFeatureFlagMock } from '@equinor/fusion-framework-module-feature-flag/mock';
++import { test as baseTest } from '@equinor/fusion-framework-vitest-plugin-react-app/test';
++
++export const test = baseTest.extend('configure', ({ configure }) => (configurator, args) => {
++  configure?.(configurator, args);
++  configurator.msal.setAccount(null); // was: useCurrentUser returning undefined
++  enableFeatureFlagMock(configurator, (mock) => mock.addFeature({ key: 'new-search', enabled: true }));
++});
+```
+
+Each Fusion module owns its own mock entry point: `enableMsalMock`/`configurator.msal`,
+`enableFeatureFlagMock`, `enableContextMock`, `enableBookmarkMock`, and more. See
+[Module mocks](module-mocks.md) for the full list and each one's defaults. A hook or a small
+piece of app config with no Fusion dependency (for example, reading `environment` from the
+app's own manifest) stays a plain `vi.mock`.
+
+Some suites override `useModuleCurrentContext` directly and change its return value with
+`vi.spyOn`. Replace the initial value with `enableContextMock`. To change context after render,
+call the real module:
+`await fusion.app.context.setCurrentContextByIdAsync(otherProject.id)`. See the first
+[`renderAppComponent`](../README.md#renderappcomponent) example.
+
+## Step 3: port the mock HTTP server
+
+Use `createRouterMiddleware` for a mock server that handles several routes under one base URL:
+
+```diff
+-import { createServer } from 'miragejs';
+-
+-export function createTestServer() {
+-  return createServer({
+-    routes() {
+-      this.get('/activities/:id', (schema, request) => ({ id: request.params.id, ... }));
+-      this.post('/activities', (schema, request) => ({ ... }));
+-    },
+-  });
+-}
++import { createRouterMiddleware } from '@equinor/fusion-framework-module-http/mock';
++
++export const activityRoutes = createRouterMiddleware('https://cpr-api.example.com', (router) => {
++  router.get('/activities/:id', ({ params }) => Response.json({ id: params.id /* ... */ }));
++  router.post('/activities', async ({ request }) => Response.json({ /* ... */ }));
++});
+```
+
+Register the result with `configurator.http.addMiddleware(activityRoutes)` inside a `configure`
+fixture (see step 4). Port one route file at a time. Each ported file is independently testable.
+An unported route can fall through to the real network, so keep the old interceptor
+for tests that have not migrated yet or add a final fail-closed middleware; do not rely on a
+missing route to fail by itself. If the backend has an OpenAPI document, prefer
+`createOpenApiMockMiddleware` (`@equinor/fusion-framework-module-http/mock`) over hand-written
+routes; see [HTTP testing](../../../modules/http/docs/testing.md).
+
+If `useHttpClient` currently returns a plain `fetch` wrapper, remove that hook mock as well. The
+real client reaches middleware registered with `configurator.http.addMiddleware`. Register the
+router for the base URI used by the real client.
+
+## Compose a router and a domain fixture
+
+Use a `render` extension for JSX wrappers such as routers and app-owned React providers. Use a
+`configure` extension for Fusion module state. Stack both extensions when a test needs both:
+
+```tsx
+import type { ReactElement } from 'react';
+import { test as baseTest } from '@equinor/fusion-framework-vitest-plugin-react-app/test';
+import { Router } from '@equinor/fusion-framework-react-router';
+import type { RouteObject } from '@equinor/fusion-framework-react-router';
+import { enableContextMock } from '@equinor/fusion-framework-module-context/mock';
+
+// Every route matches, so the element under test stays mounted.
+const testWithRouter = baseTest.extend('render', () => (ui: ReactElement) => {
+  const routes: RouteObject[] = [{ path: '*', Component: () => ui }];
+  return baseTest.render(<Router routes={routes} />);
+});
+
+// The domain fixture uses the same shape as any other `configure` extension.
+export const test = testWithRouter.extend('configure', ({ configure }) => (configurator, args) => {
+  configure?.(configurator, args);
+  enableContextMock(configurator, (mock) => mock.setCurrentContext(projectA));
+});
+```
+
+A test importing this `test` gets both the router wrapper and seeded Fusion context.
+
+Keep app-owned React providers, such as authorization, schema, or snackbar providers, in the
+`render` extension. Move only Fusion module state to `configure` and `enable*Mock`.
+
+## Step 4: update renders and assertions
+
+Every render/hook helper is `async`, and most assertion helpers from `vitest-browser-react`
+resolve against the real browser rather than synchronously:
+
+```diff
+-const { findByTestId } = render(<WrappedProcessPage {...props} />);
+-await findByTestId('customization-panel');
++const { getByTestId } = await render(<WrappedProcessPage {...props} />);
++await expect.element(getByTestId('customization-panel')).toBeVisible();
+```
+
+`fireEvent`-style interactions become element method calls (`await screen.getByRole('button', {
+name: 'Activate' }).click()`), and `act`/`waitFor` come from `vitest` rather than
+`@testing-library/react`. See the [Vitest Browser Mode](https://vitest.dev/guide/browser/) and
+[mocking](https://vitest.dev/guide/mocking) guides for the general-purpose parts of this that
+aren't Fusion-specific.
+
+## Step 5: reassess DOM-emulation-only workarounds
+
+Review polyfills and component replacements that may only exist for `jsdom` or `happy-dom`.
+Remove one workaround at a time and run the affected tests against the real component.
+
+Do not remove unrelated suppressions automatically. AG Grid license messages, Lit dev-mode
+warnings, network behavior, and app-specific test doubles may still apply in Browser Mode.
+
+## Migrate incrementally
+
+Nothing requires migrating a whole app in one pass. A common order: pick one page or route-level
+test that already hand-mocks several Fusion hooks, migrate it end to end (steps 1-4 above),
+confirm it's green, then migrate the next. Leave tests with no Fusion dependency on their
+current renderer for as long as that remains the cheaper option.
+
+## Related documentation
+
+- [Choose a Fusion testing layer](../../../framework/docs/testing-choosing-a-layer.md)
+- [Module mocks](module-mocks.md)
+- [HTTP testing](../../../modules/http/docs/testing.md)
+- [Advanced usage](advanced.md): composing fixtures and explicit render options
+- [Troubleshooting](troubleshooting.md)

package/docs/module-mocks.md

@@ -0,0 +1,120 @@
+# Mock Fusion dependencies in app tests
+
+Use module-owned `/mock` entry points to seed deterministic Fusion state while retaining each
+module's real configurator, provider, validation, and lifecycle. Import only the boundary the
+app test needs; the React app test fixture already composes the normal framework and app
+module scopes.
+
+| App dependency | Import path | Primary API |
+| --- | --- | --- |
+| Analytics | `@equinor/fusion-framework-module-analytics/mock` | `MockAnalyticsAdapter` |
+| App manifests and config | `@equinor/fusion-framework-module-app/mock` | `MockAppClient` |
+| Browser authentication | `@equinor/fusion-framework-module-msal/mock` | `enableMsalMock`, `MsalMockClient`, `createMockToken` |
+| Node authentication with Azure Identity | `@equinor/fusion-framework-module-azure-identity/mock` | `enableAuthMock`, `MockAuthProvider` |
+| Node authentication with MSAL | `@equinor/fusion-framework-module-msal-node/mock` | `enableAuthMock`, `MockAuthProvider` |
+| Bookmarks | `@equinor/fusion-framework-module-bookmark/mock` | `enableBookmarkMock`, `BookmarkMockConfigurator` |
+| Context | `@equinor/fusion-framework-module-context/mock` | `enableContextMock`, `ContextMockConfigurator` |
+| Context fixture generation | `@equinor/fusion-framework-module-context/mock/fixtures` | `createContextItemFactory`, `createContextItems` |
+| Feature flags | `@equinor/fusion-framework-module-feature-flag/mock` | `enableFeatureFlagMock`, `FeatureFlagMockConfigurator` |
+| HTTP routes and OpenAPI responses | `@equinor/fusion-framework-module-http/mock` | `createRouterMiddleware`, `createOpenApiMockMiddleware` |
+| Service discovery | `@equinor/fusion-framework-module-service-discovery/mock` | `enableServiceDiscoveryMock`, `ServiceDiscoveryMockConfigurator` |
+| Telemetry | `@equinor/fusion-framework-module-telemetry/mock` | `enableTelemetryMock`, `MockTelemetryAdapter` |
+
+The event module has no mock entry point. `waitForEvent` and `watchEvents` from
+`@equinor/fusion-framework-module-event/utils` observe the real event provider initialized by
+the app test fixture.
+
+## Authentication
+
+App tests start with a deterministic signed-in `Test User`. Set a named account or `null`
+through `configurator.msal.setAccount(...)` before rendering. The real MSAL provider still
+runs its initialization, account, token, and logout behavior against the in-process client.
+
+See [MSAL testing](../../../modules/msal/docs/testing.md) for signed-out startup, login flows,
+deterministic JWTs, and individual client spies.
+
+## App manifest and configuration
+
+The `/test` entry point automatically resolves the current app's manifest, `app.config.ts`,
+and module configurator. Use `enableAppManifestMock` when a custom parent framework must serve
+those values, or `mockAppModules` for app module testing without React.
+
+See [Application module testing](../../../app/docs/testing.md).
+
+## Context
+
+Use `enableContextMock` for known domain state without a context API or HTTP setup. The pool
+starts empty; `setCurrentContext` seeds and selects one item, while `setContexts` only makes
+items resolvable. Use HTTP middleware instead when the context service and transport pipeline
+are part of the test.
+
+See [Context testing](../../../modules/context/README.md#testing) for defaults, related-context
+behavior, and deterministic fixture generators.
+
+## Service discovery and HTTP
+
+Use `enableServiceDiscoveryMock` to resolve services from an in-memory registry. Use
+`configurator.http.addMiddleware` to answer a few explicit requests through the app's real
+named clients. Use `createOpenApiMockMiddleware` when an OpenAPI document describes many
+operations.
+
+- [Service discovery testing](../../../modules/service-discovery/docs/testing.md)
+- [HTTP testing](../../../modules/http/docs/testing.md)
+- [OpenAPI mock](../../../utils/openapi-mock/README.md)
+
+An HTTP middleware handles only requests for which it returns a `Response`. Calling
+`next(uri, init)` delegates to the next middleware and eventually the real network.
+
+## Events, analytics, and telemetry
+
+- Observe the real event provider with `waitForEvent` or `watchEvents` from
+  `@equinor/fusion-framework-module-event/utils`.
+- Register `MockAnalyticsAdapter` to record analytics without exporting them.
+- Use `enableTelemetryMock` and assert through `MockTelemetryAdapter.getItems` or
+  `waitForItem`.
+
+- [Event testing utilities](../../../modules/event/docs/testing.md)
+- [Analytics testing](../../../modules/analytics/docs/testing.md)
+- [Telemetry testing](../../../modules/telemetry/README.md#testing)
+
+## Seed several app dependencies
+
+Compose the app's real configuration with the module mocks required by the scenario:
+
+```tsx
+import { enableContextMock } from '@equinor/fusion-framework-module-context/mock';
+import { enableFeatureFlagMock } from '@equinor/fusion-framework-module-feature-flag/mock';
+import { test as baseTest } from '@equinor/fusion-framework-vitest-plugin-react-app/test';
+
+const project = {
+  id: 'project-a',
+  title: 'Project A',
+  type: { id: 'ProjectMaster' },
+  value: {},
+};
+
+export const test = baseTest.extend('configure', ({ configure }) => (configurator, args) => {
+  configure?.(configurator, args);
+  configurator.msal.setAccount({ name: 'Ada Lovelace' });
+  enableContextMock(configurator, (mock) => mock.setCurrentContext(project));
+  enableFeatureFlagMock(configurator, (mock) => {
+    mock.addFeature({ key: 'new-search', enabled: true });
+  });
+});
+```
+
+The fixture declarations are reusable, while every test still receives fresh framework and
+app module instances.
+
+## Choose direct module mocks or HTTP
+
+- Use a module mock for known domain state such as one current context, one account, or a set
+  of feature flags.
+- Use `configurator.http.addMiddleware` when the test must exercise the module's production
+  service-discovery, HTTP-client, and response-handling pipeline.
+- Use `createOpenApiMockMiddleware` when an OpenAPI document describes many operations.
+- Use Vitest `vi.fn`, `vi.spyOn`, or `vi.mock` for individual JavaScript calls rather than a
+  Fusion-specific wrapper.
+
+See each owning package README or `docs/testing.md` for its defaults, builder methods, and
+failure behavior.