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

package/src/index.ts

@@ -0,0 +1,124 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { FileNotFoundError } from '@equinor/fusion-imports';
+import type { Plugin } from 'vite';
+
+import { resolveAppTestEnv, type ResolveAppTestEnvOptions } from './resolve-app-test-env.js';
+
+const ENV_MODULE_ID = 'virtual:fusion-app-test-env';
+const CONFIGURE_MODULE_ID = 'virtual:fusion-app-test-configure';
+const RESOLVED_ENV_MODULE_ID = `\0${ENV_MODULE_ID}`;
+const RESOLVED_CONFIGURE_MODULE_ID = `\0${CONFIGURE_MODULE_ID}`;
+
+const DEFAULT_CONFIGURE_CANDIDATES = ['src/config.ts', 'src/config.tsx', 'src/config.js'];
+
+/**
+ * Options for {@link appTestVitePlugin}.
+ */
+export type AppTestVitePluginOptions = ResolveAppTestEnvOptions & {
+  /**
+   * Path (relative to `entrypoint`) to the app's module-configurator export, mirroring the
+   * `configure` argument passed to `makeComponent` in the app's own entry point. Defaults to the
+   * first of `src/config.ts`, `src/config.tsx`, `src/config.js` that exists.
+   *
+   * @remarks
+   * Unlike `manifest`/`config`, this can't be an inline function: it's live application code
+   * (with its own imports and closures) re-exported as-is into the test bundle rather than
+   * JSON-serialized data, so Vite needs a real file on disk to resolve and transform.
+   */
+  configure?: string;
+};
+
+/**
+ * Vite plugin serving an application's manifest/config (resolved the same way `ffc app build`/
+ * `ffc app dev` do) and its own module-configurator export as virtual modules, so
+ * `@equinor/fusion-framework-vitest-plugin-react-app/test`'s `test`/`render` need no per-test
+ * `env`/`configure` wiring.
+ *
+ * @remarks
+ * A plain Vite plugin — Vitest configs are Vite configs, so this registers directly in your
+ * own `vitest.config.ts`, no CLI command required:
+ * ```ts
+ * import { defineConfig } from 'vitest/config';
+ * import { appTestVitePlugin } from '@equinor/fusion-framework-vitest-plugin-react-app';
+ *
+ * export default defineConfig({
+ *   plugins: [appTestVitePlugin()],
+ *   // ...your own browser-mode config
+ * });
+ * ```
+ * Exposes two virtual modules: `virtual:fusion-app-test-env` (`manifest`/`config`, as JSON) and
+ * `virtual:fusion-app-test-configure` (a re-export of the resolved `configure` module, or
+ * `undefined` if none exists). Not intended to be imported directly by application code.
+ *
+ * @param options - Resolution options; `entrypoint` defaults to the current working directory.
+ * @returns A Vite plugin instance.
+ */
+export const appTestVitePlugin = (options?: AppTestVitePluginOptions): Plugin => {
+  const explicitEntrypoint = options?.entrypoint;
+  let entrypoint = explicitEntrypoint;
+  let configureModulePath = explicitEntrypoint
+    ? resolveConfigureModulePath(explicitEntrypoint, options?.configure)
+    : undefined;
+
+  return {
+    name: 'fusion:app-test',
+    configResolved(config) {
+      // Vitest resolves each workspace project's root from its config file, which identifies the app containing src/index.ts.
+      entrypoint ??= config.root;
+      configureModulePath ??= resolveConfigureModulePath(entrypoint, options?.configure);
+    },
+    resolveId(id) {
+      // claim only our two virtual specifiers, leave everything else to the normal resolvers
+      if (id === ENV_MODULE_ID) return RESOLVED_ENV_MODULE_ID;
+      // second virtual specifier, same rule as above
+      if (id === CONFIGURE_MODULE_ID) return RESOLVED_CONFIGURE_MODULE_ID;
+      return null;
+    },
+    async load(id) {
+      // serves manifest/config resolved lazily here, not at plugin-creation time, so options.entrypoint changes between test runs are respected
+      if (id === RESOLVED_ENV_MODULE_ID) {
+        const { manifest, config } = await resolveAppTestEnv({ ...options, entrypoint });
+        return [
+          `export const manifest = ${JSON.stringify(manifest)};`,
+          `export const config = ${JSON.stringify(config)};`,
+        ].join('\n');
+      }
+      // no conventional module means the app registers no extra modules, same as omitting `configure` from `makeComponent`
+      if (id === RESOLVED_CONFIGURE_MODULE_ID) {
+        return configureModulePath
+          ? `export { default as configure } from ${JSON.stringify(configureModulePath)};`
+          : 'export const configure = undefined;';
+      }
+      return null;
+    },
+  };
+};
+
+/**
+ * Resolves the app's module-configurator file: the explicit `file` if given, otherwise the
+ * first existing candidate in {@link DEFAULT_CONFIGURE_CANDIDATES}.
+ *
+ * @throws {@link FileNotFoundError} If an explicitly requested `file` does not exist — unlike
+ * the convention-based lookup, a typo here should fail loudly instead of silently running the
+ * test suite without the application's modules.
+ */
+const resolveConfigureModulePath = (cwd: string, file?: string): string | undefined => {
+  // an explicit path is a user request, not a convention lookup, so a typo must fail loudly
+  if (file) {
+    const resolved = resolve(cwd, file);
+    // fail fast rather than silently falling back to "no configurator"
+    if (!existsSync(resolved)) {
+      throw new FileNotFoundError(`Configure module not found: ${resolved}`);
+    }
+    return resolved;
+  }
+  // first candidate that exists wins; none existing is a valid "no configurator" state
+  const found = DEFAULT_CONFIGURE_CANDIDATES.find((candidate) =>
+    existsSync(resolve(cwd, candidate)),
+  );
+  return found ? resolve(cwd, found) : undefined;
+};
+
+export default appTestVitePlugin;

package/src/render-app-component.tsx

@@ -0,0 +1,116 @@
+import type { ReactElement } from 'react';
+import { render } from 'vitest-browser-react';
+import type { RenderOptions, RenderResult } from 'vitest-browser-react';
+
+import type { AppMockConfigureFn } from '@equinor/fusion-framework-app/mock';
+import type { AppEnv, AppModulesInstance } from '@equinor/fusion-framework-app';
+import type { Fusion } from '@equinor/fusion-framework';
+import type { AnyModule } from '@equinor/fusion-framework-module';
+
+import { resolveAppScope, createAppScopeWrapper } from './scope';
+
+/**
+ * Options for {@link renderAppComponent}.
+ *
+ * @template TModules - Module descriptors beyond the default set.
+ * @template TEnv - The application environment descriptor.
+ */
+export interface RenderAppComponentOptions<
+  TModules extends Array<AnyModule> | unknown = unknown,
+  TEnv extends AppEnv = AppEnv,
+> extends Omit<RenderOptions, 'wrapper'> {
+  /** Configuration callback forwarded to {@link mockAppModules}. */
+  configure?: AppMockConfigureFn<TModules, TEnv>;
+  /** The application environment; defaults to a generic standalone test app. */
+  env?: TEnv;
+  /**
+   * The parent Fusion instance; defaults to a fresh {@link mockFramework} instance with
+   * this app's own manifest served. Pass one built beforehand to reuse a single instance
+   * across multiple render calls, or to pre-configure parent-level modules (e.g. `http`,
+   * `context`, `serviceDiscovery`, or `app` itself for a component that loads another app).
+   */
+  fusion?: Fusion;
+}
+
+/**
+ * The result of {@link renderAppComponent}: the `vitest-browser-react` render result,
+ * plus the resolved application module scope and its parent Fusion instance.
+ *
+ * @template TModules - Module descriptors beyond the default set.
+ */
+export interface RenderAppComponentResult<TModules extends Array<AnyModule> | unknown = unknown>
+  extends RenderResult {
+  /**
+   * The Fusion instances backing the rendered component, nested under this single key so
+   * `vitest-browser-react`'s own `RenderResult` fields stay free to evolve without ever
+   * colliding with it.
+   */
+  fusion: {
+    /** The parent Fusion instance the component's `FrameworkProvider` was given. */
+    framework: Fusion;
+    /**
+     * The resolved application module instance backing the rendered component — the same
+     * instance a real app would read via `useAppModule`/`useAppModules`. Drive a module
+     * directly (e.g. `fusion.app.context.setCurrentContextByIdAsync(id)`) to exercise a
+     * state change after the initial render, then assert the component re-rendered accordingly.
+     */
+    app: AppModulesInstance<TModules>;
+  };
+}
+
+/**
+ * Renders a component inside a real, mock-backed application module scope.
+ *
+ * @remarks
+ * Wraps `vitest-browser-react`'s `render` with the same provider nesting
+ * `createComponent` uses in production — a `FrameworkProvider` (the parent Fusion
+ * instance, from `mockFramework`) around a `ModuleProvider` (this app's own modules,
+ * from `mockAppModules`, `@equinor/fusion-framework-app/mock`). See {@link renderAppHook}
+ * for the equivalent helper when testing a hook in isolation, rather than a component.
+ *
+ * @template TModules - Module descriptors beyond the default set.
+ * @template TEnv - The application environment descriptor.
+ * @param ui - The component to render.
+ * @param options - A `configure` callback and `env` for `mockAppModules`, plus any other `render` option.
+ * @returns The `render` result plus `fusion.framework` and `fusion.app`, once the mocked application module scope resolves.
+ *
+ * @example
+ * ```tsx
+ * const { getByText } = await renderAppComponent(<Apploader appKey="child-app" />, {
+ *   fusion: await mockFramework<[AppModule]>((configurator) => {
+ *     // register the child app's own manifest against the `app` module
+ *   }),
+ * });
+ * await expect.element(getByText(/mounted/)).toBeInTheDocument();
+ * ```
+ *
+ * @example Drive a module directly and assert the re-render
+ * ```tsx
+ * const { getByText, fusion } = await renderAppComponent<[ContextModule]>(<App />, {
+ *   configure: (configurator) => enableContextMock(configurator, (mock) => mock.setCurrentContext(projectA)),
+ * });
+ * await fusion.app.context.setCurrentContextByIdAsync(projectB.id);
+ * await expect.element(getByText(/project-b/)).toBeInTheDocument();
+ * ```
+ */
+export async function renderAppComponent<
+  TModules extends Array<AnyModule> | unknown = unknown,
+  TEnv extends AppEnv = AppEnv,
+>(
+  ui: ReactElement,
+  options?: RenderAppComponentOptions<TModules, TEnv>,
+): Promise<RenderAppComponentResult<TModules>> {
+  const { configure, env, fusion: providedFusion, ...renderOptions } = options ?? {};
+  const { framework, app } = await resolveAppScope<TModules, TEnv>({
+    configure,
+    env,
+    fusion: providedFusion,
+  });
+  const result = await render(ui, {
+    ...renderOptions,
+    wrapper: createAppScopeWrapper<TModules>({ framework, app }),
+  });
+  return { ...result, fusion: { framework, app } };
+}
+
+export default renderAppComponent;

package/src/render-app-hook.tsx

@@ -0,0 +1,135 @@
+import { renderHook } from 'vitest-browser-react';
+import type { RenderHookOptions, RenderHookResult } from 'vitest-browser-react';
+
+import type { AppMockConfigureFn } from '@equinor/fusion-framework-app/mock';
+import type { AppEnv, AppModulesInstance } from '@equinor/fusion-framework-app';
+import type { Fusion } from '@equinor/fusion-framework';
+import type { AnyModule } from '@equinor/fusion-framework-module';
+
+import { resolveAppScope, createAppScopeWrapper } from './scope';
+
+/**
+ * Options for {@link renderAppHook}.
+ *
+ * @template TModules - Module descriptors beyond the default set.
+ * @template TEnv - The application environment descriptor.
+ * @template Props - The props type accepted by the rendered hook.
+ */
+export interface RenderAppHookOptions<
+  TModules extends Array<AnyModule> | unknown = unknown,
+  TEnv extends AppEnv = AppEnv,
+  Props = undefined,
+> extends Omit<RenderHookOptions<Props>, 'wrapper'> {
+  /** Configuration callback forwarded to {@link mockAppModules}. */
+  configure?: AppMockConfigureFn<TModules, TEnv>;
+  /** The application environment; defaults to a generic standalone test app. */
+  env?: TEnv;
+  /**
+   * The parent Fusion instance; defaults to a fresh {@link mockFramework} instance with
+   * this app's own manifest served. Pass one built beforehand to reuse a single instance
+   * across multiple `renderAppHook` calls, or to pre-configure parent-level modules (e.g.
+   * `http`, `context`, `serviceDiscovery`) the app reads through `useFramework`.
+   */
+  fusion?: Fusion;
+}
+
+/**
+ * The result of {@link renderAppHook}: the `vitest-browser-react` `renderHook` result,
+ * plus the resolved application module scope and its parent Fusion instance.
+ *
+ * @template Result - The value returned by the rendered hook.
+ * @template Props - The props accepted by the rendered hook.
+ * @template TModules - Module descriptors beyond the default set.
+ */
+export interface RenderAppHookResult<
+  Result,
+  Props,
+  TModules extends Array<AnyModule> | unknown = unknown,
+> extends RenderHookResult<Result, Props> {
+  /**
+   * The Fusion instances backing the rendered hook, nested under this single key so
+   * `vitest-browser-react`'s own `RenderHookResult` fields stay free to evolve without
+   * ever colliding with it.
+   */
+  fusion: {
+    /** The parent Fusion instance the hook's `FrameworkProvider` was given. */
+    framework: Fusion;
+    /**
+     * The resolved application module instance backing the rendered hook — the same
+     * instance a real app would read via `useAppModule`/`useAppModules`. Drive a module
+     * not returned by the hook itself (e.g. `fusion.app.context.setCurrentContextByIdAsync(id)`)
+     * to exercise a state change after the initial render.
+     */
+    app: AppModulesInstance<TModules>;
+  };
+}
+
+/**
+ * Renders a hook inside a real, mock-backed application module scope.
+ *
+ * @remarks
+ * Wraps `vitest-browser-react`'s `renderHook` with the same provider nesting
+ * `createComponent` uses in production — a `FrameworkProvider` (the parent Fusion
+ * instance, from `mockFramework`) around a `ModuleProvider` (this app's own modules,
+ * from `mockAppModules`, `@equinor/fusion-framework-app/mock`) — the real
+ * `event`/`http`/`msal` module pipeline. Only requests a seeded middleware answers are
+ * faked; a request with no matching middleware still reaches the real network. Use this
+ * for any hook that reads from the application module scope or the parent framework
+ * (e.g. `useAppModule`, `useAccessToken`, `useFramework`), instead of hand-wiring
+ * `mockFramework`, `mockAppModules`, `FrameworkProvider` and `ModuleProvider` in every test.
+ *
+ * @template Result - The value returned by the rendered hook.
+ * @template Props - The props accepted by the rendered hook.
+ * @template TModules - Module descriptors beyond the default set.
+ * @template TEnv - The application environment descriptor.
+ * @param render - The hook to render, receiving `initialProps`.
+ * @param options - A `configure` callback and `env` for `mockAppModules`, plus any other
+ *   `renderHook` option.
+ * @returns The `renderHook` result plus `fusion.framework` and `fusion.app`, once the mocked application module scope resolves.
+ *
+ * @example
+ * ```tsx
+ * const { result } = await renderAppHook(() => useAccessToken({ scopes: ['User.Read'] }));
+ * await vi.waitFor(() => expect(result.current.pending).toBe(false));
+ * ```
+ *
+ * @example Sign in a named user
+ * ```tsx
+ * const { result } = await renderAppHook(() => useCurrentAccount(), {
+ *   configure: (configurator) => configurator.msal.setAccount({ name: 'Ada Lovelace' }),
+ * });
+ * ```
+ *
+ * @example Reuse a pre-built parent Fusion instance
+ * ```tsx
+ * const fusion = await mockFramework<[AppModule]>((configurator) =>
+ *   enableAppManifestMock(configurator, env),
+ * );
+ *
+ * const { result: a } = await renderAppHook(() => useAccessToken({ scopes: ['User.Read'] }), { fusion });
+ * const { result: b } = await renderAppHook(() => useCurrentAccount(), { fusion });
+ * ```
+ */
+export async function renderAppHook<
+  Result,
+  Props = undefined,
+  TModules extends Array<AnyModule> | unknown = unknown,
+  TEnv extends AppEnv = AppEnv,
+>(
+  render: (initialProps?: Props) => Result,
+  options?: RenderAppHookOptions<TModules, TEnv, Props>,
+): Promise<RenderAppHookResult<Result, Props, TModules>> {
+  const { configure, env, fusion: providedFusion, ...renderHookOptions } = options ?? {};
+  const { framework, app } = await resolveAppScope<TModules, TEnv>({
+    configure,
+    env,
+    fusion: providedFusion,
+  });
+  const result = await renderHook(render, {
+    ...renderHookOptions,
+    wrapper: createAppScopeWrapper<TModules>({ framework, app }),
+  });
+  return { ...result, fusion: { framework, app } };
+}
+
+export default renderAppHook;

package/src/render.tsx

@@ -0,0 +1,64 @@
+import type { ReactElement } from 'react';
+
+import type { AnyModule } from '@equinor/fusion-framework-module';
+import type { AppEnv } from '@equinor/fusion-framework-app';
+import type { AppMockConfigureFn } from '@equinor/fusion-framework-app/mock';
+
+import {
+  renderAppComponent,
+  type RenderAppComponentOptions,
+  type RenderAppComponentResult,
+} from './render-app-component';
+
+// resolved at test-time by `appTestVitePlugin` (@equinor/fusion-framework-vitest-plugin-react-app);
+// see virtual-modules.d.ts for the ambient module declarations
+import { manifest, config } from 'virtual:fusion-app-test-env';
+import { configure } from 'virtual:fusion-app-test-configure';
+
+/**
+ * Renders a component inside the application's own module scope for use in plain `describe`/`it`
+ * tests, using the manifest, config, and module-configurator resolved for this application — no
+ * per-test wiring, and no custom `test` fixture required.
+ *
+ * @remarks
+ * Requires `appTestVitePlugin` (`@equinor/fusion-framework-vitest-plugin-react-app`) registered in
+ * your `vitest.config.ts` `plugins`, which serves the virtual modules backing the resolved
+ * `env`/`configure`. Running the same test file without the plugin registered fails to resolve
+ * those imports.
+ *
+ * Pass `env` or `configure` in `options` to override the resolved values for a single render.
+ *
+ * @template TModules - Module descriptors beyond the default set.
+ * @param ui - The component to render.
+ * @param options - Overrides for `env`/`configure`, plus any other `renderAppComponent` option.
+ * @returns The `render` result plus `fusion.framework` and `fusion.app`, once the mocked application module scope resolves.
+ * @example
+ * ```tsx
+ * import { describe, expect, it } from 'vitest';
+ * import { render } from '@equinor/fusion-framework-vitest-plugin-react-app/test';
+ * import { App } from '../App';
+ *
+ * describe('App', () => {
+ *   it('renders the app', async () => {
+ *     const { getByRole } = await render(<App />);
+ *     await expect.element(getByRole('heading')).toBeVisible();
+ *   });
+ * });
+ * ```
+ */
+export async function render<TModules extends Array<AnyModule> | unknown = unknown>(
+  ui: ReactElement,
+  options?: RenderAppComponentOptions<TModules, AppEnv>,
+): Promise<RenderAppComponentResult<TModules>> {
+  const { configure: configureOverride, env: envOverride, ...renderOptions } = options ?? {};
+  return renderAppComponent<TModules, AppEnv>(ui, {
+    ...renderOptions,
+    env: envOverride ?? { manifest, config },
+    // the resolved `configure` is generic over the app's own module set (`unknown`), while
+    // `TModules` here is caller-supplied *extra* modules — safe to widen for the common case
+    // where callers don't override it with a `TModules`-specific configurator
+    configure: (configureOverride ?? configure) as AppMockConfigureFn<TModules, AppEnv> | undefined,
+  });
+}
+
+export default render;

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

@@ -0,0 +1,132 @@
+import { FileNotFoundError } from '@equinor/fusion-imports';
+import type { AppManifest } from '@equinor/fusion-framework-module-app';
+import type { RuntimeEnv } from '@equinor/fusion-framework-cli';
+import {
+  createAppManifestFromPackage,
+  loadAppManifest,
+  loadAppConfig,
+  mergeAppManifests,
+  ApiAppConfigSchema,
+  type AppManifestFn,
+  type AppConfigFn,
+  type ApiAppConfig,
+} from '@equinor/fusion-framework-cli/app';
+import { resolvePackage } from '@equinor/fusion-framework-cli/utils';
+
+/**
+ * The application manifest and config resolved for a test run.
+ */
+export type AppTestEnv = {
+  manifest: AppManifest;
+  config: ApiAppConfig;
+};
+
+/**
+ * Options for {@link resolveAppTestEnv}.
+ */
+export type ResolveAppTestEnvOptions = {
+  /** Directory to resolve the package, manifest, and config from. Defaults to `process.cwd()`. */
+  entrypoint?: string;
+  /**
+   * An explicit manifest file to load instead of the default `app.manifest(.*)?` lookup, or a
+   * manifest function (same shape as `defineAppManifest`'s argument) applied directly.
+   */
+  manifest?: string | AppManifestFn;
+  /**
+   * An explicit config file to load instead of the default `app.config(.*)?` lookup, or a
+   * config function (same shape as `defineAppConfig`'s argument) applied directly.
+   */
+  config?: string | AppConfigFn;
+};
+
+/**
+ * Resolves an application's manifest and config using the same pipeline `ffc app build`/
+ * `ffc app dev` use: a base manifest generated from `package.json`, merged with a local
+ * `app.manifest.ts` if one exists; and `app.config.ts` for endpoints/environment, falling
+ * back to an empty config if none exists.
+ *
+ * @remarks
+ * Intended to seed `@equinor/fusion-framework-vitest-plugin-react-app/test`'s `testApp` `env` fixture, so
+ * a test suite exercises the application's real manifest/config instead of a hand-maintained
+ * duplicate. Anything a specific test still needs faked (a missing endpoint, a different
+ * `appKey`) can be layered on top with `testApp.extend('env', ...)` or a per-test
+ * `test.override('env', ...)`.
+ *
+ * @param options - Resolution options; `entrypoint` defaults to the current working directory.
+ * @returns The resolved application manifest and config.
+ * @throws If no `package.json` can be found from `entrypoint` upward, or an explicitly requested
+ * `manifest`/`config` file does not exist.
+ * @example
+ * ```ts
+ * import { resolveAppTestEnv } from '@equinor/fusion-framework-vitest-plugin-react-app';
+ * import { testApp } from '@equinor/fusion-framework-vitest-plugin-react-app/test';
+ * import { configure } from '../config';
+ *
+ * const test = testApp
+ *   .extend('env', { injected: true }, () => resolveAppTestEnv())
+ *   .extend('configure', { injected: true }, () => configure);
+ * ```
+ */
+export const resolveAppTestEnv = async (
+  options?: ResolveAppTestEnvOptions,
+): Promise<AppTestEnv> => {
+  const pkg = await resolvePackage({ cwd: options?.entrypoint });
+  const env: RuntimeEnv = { command: 'build', mode: 'test', root: pkg.root, environment: 'test' };
+
+  const baseManifest = createAppManifestFromPackage(env, pkg.packageJson);
+  const [manifest, config] = await Promise.all([
+    resolveManifest(env, baseManifest, options?.manifest),
+    resolveConfig(env, options?.config),
+  ]);
+
+  return { manifest, config };
+};
+
+/**
+ * Loads `app.manifest(.*)?` (or applies an inline {@link AppManifestFn}), falling back to the
+ * package-derived manifest when none exists — mirrors `ffc app build`'s own fallback so a test
+ * env matches a real build with zero manifest file.
+ */
+const resolveManifest = async (
+  env: RuntimeEnv,
+  base: AppManifest,
+  manifest?: string | AppManifestFn,
+): Promise<AppManifest> => {
+  // an inline function is applied directly, the same way a loaded `app.manifest.ts`'s default export would be
+  if (typeof manifest === 'function') {
+    const result = await manifest(env, { base });
+    return mergeAppManifests(base, result ?? {});
+  }
+  try {
+    return (await loadAppManifest(env, { base, file: manifest })).manifest;
+  } catch (err) {
+    // an explicitly requested manifest that's missing is a real error; only the default lookup falls back
+    if (err instanceof FileNotFoundError && !manifest) return base;
+    throw err;
+  }
+};
+
+/**
+ * Loads `app.config(.*)?` (or applies an inline {@link AppConfigFn}), falling back to an empty
+ * config when none exists — mirrors `ffc app build`'s own fallback so a test env matches a real
+ * build with zero config file.
+ */
+const resolveConfig = async (
+  env: RuntimeEnv,
+  config?: string | AppConfigFn,
+): Promise<ApiAppConfig> => {
+  // an inline function is applied directly, the same way a loaded `app.config.ts`'s default export would be
+  if (typeof config === 'function') {
+    const result = await config(env, { base: { environment: {} } });
+    return ApiAppConfigSchema.parse(result ?? { environment: {} });
+  }
+  try {
+    return (await loadAppConfig(env, { file: config })).config;
+  } catch (err) {
+    // an explicitly requested config that's missing is a real error; only the default lookup falls back
+    if (err instanceof FileNotFoundError && !config) return { environment: {} };
+    throw err;
+  }
+};
+
+export default resolveAppTestEnv;

package/src/scope/create-app-scope-wrapper.tsx

@@ -0,0 +1,26 @@
+import type { ReactElement, ReactNode } from 'react';
+
+import { FrameworkProvider } from '@equinor/fusion-framework-react';
+import { ModuleProvider } from '@equinor/fusion-framework-react-module';
+import type { AnyModule } from '@equinor/fusion-framework-module';
+
+import type { AppScope } from './resolve-app-scope';
+
+/**
+ * The provider nesting `createComponent` uses in production, for wrapping a component or
+ * hook under test in its resolved {@link AppScope}.
+ *
+ * @template TModules - Module descriptors beyond the default set.
+ * @param scope - The resolved parent Fusion instance and application module scope.
+ * @returns A wrapper component nesting a `FrameworkProvider` around a `ModuleProvider`.
+ */
+export function createAppScopeWrapper<TModules extends Array<AnyModule> | unknown = unknown>({
+  framework,
+  app,
+}: AppScope<TModules>): (props: { children: ReactNode }) => ReactElement {
+  return ({ children }: { children: ReactNode }) => (
+    <FrameworkProvider value={framework}>
+      <ModuleProvider value={app}>{children}</ModuleProvider>
+    </FrameworkProvider>
+  );
+}

package/src/scope/default-app-env.ts

@@ -0,0 +1,13 @@
+import type { AppEnv } from '@equinor/fusion-framework-app';
+
+/**
+ * The application environment used when a test does not care about its own app identity.
+ */
+export const defaultAppEnv: AppEnv = {
+  manifest: {
+    appKey: 'test-app',
+    displayName: 'Test App',
+    description: 'A test application',
+    type: 'standalone',
+  },
+};

package/src/scope/index.ts

@@ -0,0 +1,4 @@
+export { defaultAppEnv } from './default-app-env';
+export { resolveFusion } from './resolve-fusion';
+export { resolveAppScope, type AppScope } from './resolve-app-scope';
+export { createAppScopeWrapper } from './create-app-scope-wrapper';

package/src/scope/resolve-app-scope.ts

@@ -0,0 +1,46 @@
+import { mockAppModules } from '@equinor/fusion-framework-app/mock';
+import type { AppMockConfigureFn } from '@equinor/fusion-framework-app/mock';
+import type { AppEnv, AppModulesInstance } from '@equinor/fusion-framework-app';
+import type { Fusion } from '@equinor/fusion-framework';
+import type { AnyModule } from '@equinor/fusion-framework-module';
+
+import { resolveFusion } from './resolve-fusion';
+import { defaultAppEnv } from './default-app-env';
+
+/**
+ * The parent Fusion instance and resolved application module scope shared by every
+ * `packages/react/app` testing helper.
+ *
+ * @template TModules - Module descriptors beyond the default set.
+ */
+export interface AppScope<TModules extends Array<AnyModule> | unknown = unknown> {
+  /** The parent Fusion instance the application scope was resolved against. */
+  framework: Fusion;
+  /** The resolved application module instance. */
+  app: AppModulesInstance<TModules>;
+}
+
+/**
+ * Resolves the parent Fusion instance and application module scope shared by every
+ * `packages/react/app` testing helper.
+ *
+ * @template TModules - Module descriptors beyond the default set.
+ * @template TEnv - The application environment descriptor.
+ * @param options - A `configure` callback and `env` for {@link mockAppModules}, plus an
+ *   already-built `fusion` instance to reuse instead of a fresh one.
+ * @returns The resolved {@link AppScope}.
+ */
+export async function resolveAppScope<
+  TModules extends Array<AnyModule> | unknown = unknown,
+  TEnv extends AppEnv = AppEnv,
+>(options?: {
+  configure?: AppMockConfigureFn<TModules, TEnv>;
+  env?: TEnv;
+  fusion?: Fusion;
+}): Promise<AppScope<TModules>> {
+  const { configure, env, fusion: providedFusion } = options ?? {};
+  const resolvedEnv = env ?? (defaultAppEnv as TEnv);
+  const framework = await resolveFusion(resolvedEnv, providedFusion);
+  const app = await mockAppModules(configure, resolvedEnv, framework);
+  return { framework, app };
+}