@equinor/fusion-framework-vitest-plugin-react-app 0.2.0-next.2 → 1.0.0-next.4

package/src/__tests__/merge-env-config.test.ts

@@ -0,0 +1,67 @@
+import { AppConfig } from '@equinor/fusion-framework-module-app';
+import type { AppEnv } from '@equinor/fusion-framework-app';
+import { describe, expect, it } from 'vitest';
+
+import { mergeEnvConfig } from '../merge-env-config.js';
+
+describe('mergeEnvConfig', () => {
+  const baseEnv: AppEnv = {
+    manifest: {
+      appKey: 'test-app',
+      displayName: 'Test App',
+      description: 'A test application',
+      type: 'standalone',
+    },
+    config: new AppConfig({
+      environment: { foo: 'bar' },
+      endpoints: { api: { url: 'https://api.example.com', scopes: ['api.read'] } },
+    }),
+  };
+
+  it('adds a new endpoint without dropping existing ones', () => {
+    const merged = mergeEnvConfig(baseEnv, {
+      endpoints: { 'cpr-api': { url: 'https://cpr.example.com' } },
+    });
+
+    expect(merged.config?.endpoints).toEqual({
+      api: { url: 'https://api.example.com', scopes: ['api.read'] },
+      'cpr-api': { url: 'https://cpr.example.com', scopes: [] },
+    });
+  });
+
+  it('overrides one field of an existing endpoint, keeping the rest', () => {
+    const merged = mergeEnvConfig(baseEnv, {
+      endpoints: { api: { url: 'https://fake.example.com' } },
+    });
+
+    expect(merged.config?.endpoints.api).toEqual({
+      url: 'https://fake.example.com',
+      scopes: ['api.read'],
+    });
+  });
+
+  it('merges environment overrides over the existing environment', () => {
+    const merged = mergeEnvConfig(baseEnv, { environment: { baz: 'qux' } });
+
+    expect(merged.config?.environment).toEqual({ foo: 'bar', baz: 'qux' });
+  });
+
+  it('leaves the original env and its config untouched', () => {
+    mergeEnvConfig(baseEnv, { endpoints: { api: { url: 'https://fake.example.com' } } });
+
+    expect(baseEnv.config?.endpoints.api).toEqual({
+      url: 'https://api.example.com',
+      scopes: ['api.read'],
+    });
+  });
+
+  it('handles an env with no existing config', () => {
+    const env: AppEnv = { manifest: baseEnv.manifest };
+    const merged = mergeEnvConfig(env, { endpoints: { api: { url: 'https://api.example.com' } } });
+
+    expect(merged.config?.endpoints).toEqual({
+      api: { url: 'https://api.example.com', scopes: [] },
+    });
+    expect(merged.config?.environment).toEqual({});
+  });
+});

package/src/app-test.ts

@@ -9,6 +9,7 @@ export {
   type RenderAppComponentResult,
 } from './render-app-component';
 export { testApp } from './test-app';
+export { mergeEnvConfig, type MergeEnvConfigOverrides } from './merge-env-config.js';
 export type { AppMockConfigureFn } from '@equinor/fusion-framework-app/mock';
 
 // `test`/`render` import virtual modules only served once `appTestVitePlugin`

package/src/merge-env-config.ts

@@ -0,0 +1,58 @@
+import { AppConfig } from '@equinor/fusion-framework-module-app';
+import type { ConfigEnvironment } from '@equinor/fusion-framework-module-app';
+import type { AppEnv } from '@equinor/fusion-framework-app';
+
+type EndpointOverride = Partial<NonNullable<AppEnv['config']>['endpoints'][string]>;
+
+/**
+ * Overrides accepted by {@link mergeEnvConfig}.
+ */
+export type MergeEnvConfigOverrides<TConfig extends ConfigEnvironment = ConfigEnvironment> = {
+  environment?: Partial<TConfig>;
+  endpoints?: Record<string, EndpointOverride>;
+};
+
+/**
+ * Merges `environment`/`endpoints` overrides into an `AppEnv`'s `config`.
+ *
+ * @remarks
+ * `AppConfig` stores both behind private fields exposed only through getters, so
+ * `{ ...env.config, endpoints: {...} }` silently drops everything it doesn't explicitly
+ * restate — a plain object spread copies no own enumerable properties off an `AppConfig`
+ * instance. Reach for this instead of hand-rolling that merge in a test fixture.
+ *
+ * @template TEnv - The `AppEnv` shape being merged into.
+ * @param env - The `AppEnv` to merge overrides into; left untouched, `config` may be omitted.
+ * @param overrides - Partial `environment`/`endpoints` values, merged over any existing config.
+ * @returns A new `AppEnv` with a new `AppConfig` reflecting the merge.
+ * @example
+ * ```ts
+ * const test = testApp.extend('appEnv', ({ appEnv }) =>
+ *   mergeEnvConfig(appEnv, { endpoints: { 'cpr-api': { url: backendBaseUrl } } }),
+ * );
+ * ```
+ */
+export function mergeEnvConfig<TEnv extends AppEnv = AppEnv>(
+  env: TEnv,
+  overrides: MergeEnvConfigOverrides<
+    TEnv['config'] extends AppConfig<infer TConfig> ? TConfig : ConfigEnvironment
+  >,
+): TEnv {
+  // each overridden endpoint keeps any field the caller didn't explicitly override
+  const endpoints = Object.entries(overrides.endpoints ?? {}).reduce(
+    // defaults, then any existing endpoint, then the override (override wins)
+    (acc, [key, override]) =>
+      Object.assign(acc, { [key]: Object.assign({ url: '', scopes: [] }, acc[key], override) }),
+    { ...env.config?.endpoints },
+  );
+  // caller-supplied environment values win over the existing ones
+  return {
+    ...env,
+    config: new AppConfig({
+      environment: { ...env.config?.environment, ...overrides.environment },
+      endpoints,
+    }),
+  };
+}
+
+export default mergeEnvConfig;

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

@@ -46,11 +46,11 @@ export type ResolveAppTestEnvOptions = {
  * 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
+ * Intended to seed `@equinor/fusion-framework-vitest-plugin-react-app/test`'s `testApp` `appEnv` 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', ...)`.
+ * `appKey`) can be layered on top with `testApp.extend('appEnv', ...)` or a per-test
+ * `test.override('appEnv', ...)`.
  *
  * @param options - Resolution options; `entrypoint` defaults to the current working directory.
  * @returns The resolved application manifest and config.
@@ -63,8 +63,8 @@ export type ResolveAppTestEnvOptions = {
  * import { configure } from '../config';
  *
  * const test = testApp
- *   .extend('env', { injected: true }, () => resolveAppTestEnv())
- *   .extend('configure', { injected: true }, () => configure);
+ *   .extend('appEnv', { injected: true }, () => resolveAppTestEnv())
+ *   .extend('configureApp', { injected: true }, () => configure);
  * ```
  */
 export const resolveAppTestEnv = async (

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

@@ -40,7 +40,7 @@ export async function resolveAppScope<
 }): Promise<AppScope<TModules>> {
   const { configure, env, fusion: providedFusion } = options ?? {};
   const resolvedEnv = env ?? (defaultAppEnv as TEnv);
-  const framework = await resolveFusion(resolvedEnv, providedFusion);
+  const framework = await resolveFusion({ env: resolvedEnv, fusion: providedFusion });
   const app = await mockAppModules(configure, resolvedEnv, framework);
   return { framework, app };
 }

package/src/scope/resolve-fusion.ts

@@ -1,8 +1,10 @@
 import type { AppEnv } from '@equinor/fusion-framework-app';
 import type { Fusion } from '@equinor/fusion-framework';
-import { mockFramework } from '@equinor/fusion-framework/mock';
+import { mockFramework, type FrameworkMockConfigureFn } from '@equinor/fusion-framework/mock';
 import { enableAppManifestMock } from '@equinor/fusion-framework-app/mock';
 import type { AppModule } from '@equinor/fusion-framework-module-app';
+import { enableNavigation, createHistory } from '@equinor/fusion-framework-module-navigation';
+import type { NavigationModule } from '@equinor/fusion-framework-module-navigation';
 
 import { defaultAppEnv } from './default-app-env';
 
@@ -12,18 +14,27 @@ import { defaultAppEnv } from './default-app-env';
  * given.
  *
  * @template TEnv - The application environment descriptor.
- * @param env - The application environment; defaults to {@link defaultAppEnv}.
- * @param fusion - An already-built parent Fusion instance to reuse instead.
+ * @param options - `env` seeds the built-in app manifest mock; navigation defaults to real
+ *   browser history, matching Browser Mode. `configure` runs afterwards on the same
+ *   configurator — e.g. call `enableNavigation` again to override the history, or register
+ *   extra modules and service discovery entries. `fusion`, an already-built parent instance,
+ *   is reused as-is and skips `configure` entirely.
  * @returns The given `fusion`, or a fresh mocked parent Fusion instance.
  */
-export async function resolveFusion<TEnv extends AppEnv = AppEnv>(
-  env?: TEnv,
-  fusion?: Fusion,
-): Promise<Fusion> {
+export async function resolveFusion<TEnv extends AppEnv = AppEnv>(options?: {
+  env?: TEnv;
+  fusion?: Fusion;
+  configure?: FrameworkMockConfigureFn<[AppModule, NavigationModule]>;
+}): Promise<Fusion> {
+  const { env, fusion, configure } = options ?? {};
   return (
     fusion ??
-    mockFramework<[AppModule]>((configurator) =>
-      enableAppManifestMock(configurator, env ?? (defaultAppEnv as TEnv)),
-    )
+    mockFramework<[AppModule, NavigationModule]>(async (configurator) => {
+      enableAppManifestMock(configurator, env ?? (defaultAppEnv as TEnv));
+      enableNavigation(configurator, {
+        configure: (config) => config.setHistory(createHistory('browser')),
+      });
+      await configure?.(configurator);
+    })
   );
 }

package/src/test-app.tsx

@@ -6,6 +6,9 @@ import type { RenderOptions, RenderHookOptions } from 'vitest-browser-react';
 import { mockAppModules } from '@equinor/fusion-framework-app/mock';
 import type { AppMockConfigureFn } from '@equinor/fusion-framework-app/mock';
 import type { AppEnv } from '@equinor/fusion-framework-app';
+import type { AppModule } from '@equinor/fusion-framework-module-app';
+import type { NavigationModule } from '@equinor/fusion-framework-module-navigation';
+import type { FrameworkMockConfigureFn } from '@equinor/fusion-framework/mock';
 
 import { defaultAppEnv, resolveFusion, createAppScopeWrapper } from './scope';
 
@@ -14,7 +17,7 @@ import { defaultAppEnv, resolveFusion, createAppScopeWrapper } from './scope';
  *
  * @remarks
  * An alternative to {@link renderAppComponent}/{@link renderAppHook} for a test file whose
- * cases share seeded fixture defaults: `env`/`configure` become suite-level concerns,
+ * cases share seeded fixture defaults: `appEnv`/`configureApp` become suite-level concerns,
  * overridden once per file (or per `describe` block) with `testApp.extend(...)`, rather than
  * an options object repeated on every call. `fusion`/`app` are still instantiated fresh per
  * test — only the seeded defaults are shared, not state between tests. They also resolve
@@ -25,6 +28,19 @@ import { defaultAppEnv, resolveFusion, createAppScopeWrapper } from './scope';
  * one-off test whose configuration is not shared by the rest of the file; reach for
  * `testApp` when several cases in a file share one set of seeded fixture defaults.
  *
+ * @remarks `configureApp`/`configureFusion` default to `undefined` here
+ * Unlike `@equinor/fusion-framework-vitest-plugin-react-app/test`'s `test`, this `testApp` does
+ * not resolve the app's real `src/config.ts` — it requires `appTestVitePlugin`'s Vite virtual
+ * modules to load that file as live code, which `testApp` (no Vite dependency) cannot do. Extend
+ * `test` from `/test` instead when a suite needs to compose with the app's real configuration.
+ *
+ * @remarks Overriding `fusion` bypasses `configureFusion`
+ * `fusion` and `configureFusion` are not independent: `fusion`'s default resolver is what
+ * calls `configureFusion`. `.override('fusion', ...)` replaces that resolver outright, so a
+ * `configureFusion` override on the same test/suite is silently never called. Use
+ * `configureFusion` to extend the base framework mock; use `fusion` only to replace it
+ * entirely (e.g. with a fully custom or non-mocked instance).
+ *
  * @example
  * ```tsx
  * testApp('resolves current context', async ({ app, render }) => {
@@ -36,7 +52,7 @@ import { defaultAppEnv, resolveFusion, createAppScopeWrapper } from './scope';
  * @example Seed a module for every test in a suite
  * ```tsx
  * describe('with a seeded context module', () => {
- *   const test = testApp.extend('configure', { injected: true }, () =>
+ *   const test = testApp.extend('configureApp', { injected: true }, () =>
  *     (configurator) => enableContextMock(configurator, (mock) => mock.setCurrentContext(projectA)),
  *   );
  *
@@ -46,15 +62,41 @@ import { defaultAppEnv, resolveFusion, createAppScopeWrapper } from './scope';
  *   });
  * });
  * ```
+ *
+ * @example Extend the parent framework mock with an application module
+ * ```tsx
+ * const test = testApp.extend('configureFusion', { injected: true }, () =>
+ *   (configurator) => {
+ *     enableFeatureFlagMock(configurator);
+ *     configurator.serviceDiscovery.addServices([
+ *       { key: 'people', uri: baseUrl('people') },
+ *       { key: 'context', uri: baseUrl('context') },
+ *     ]);
+ *   },
+ * );
+ * ```
  */
 export const testApp = baseTest
-  .extend('env', { injected: true }, defaultAppEnv)
+  .extend('appEnv', { injected: true }, defaultAppEnv)
   // `test.extend`'s plain-`value` overload rejects function types (ambiguous with the
   // resolver-`fn` overload), so a function-typed fixture default must go through `fn` instead.
-  .extend('configure', { injected: true }, () => undefined as AppMockConfigureFn | undefined)
-  .extend('fusion', async ({ env }) => resolveFusion(env))
-  .extend('app', async ({ configure, env, fusion }) =>
-    mockAppModules<unknown, AppEnv>(configure, env as AppEnv, fusion),
+  .extend('configureApp', { injected: true }, () => undefined as AppMockConfigureFn | undefined)
+  // Runs after the built-in app manifest/navigation setup, so a test can register extra
+  // framework modules, service discovery entries, or call `enableNavigation` again to
+  // override the history, without reimplementing the base setup.
+  .extend(
+    'configureFusion',
+    { injected: true },
+    () => undefined as FrameworkMockConfigureFn<[AppModule, NavigationModule]> | undefined,
+  )
+  // IMPORTANT: `.override('fusion', ...)` replaces this resolver entirely, so `configureFusion`
+  // is never called — reach for `configureFusion` to extend the base mock, `fusion` only to
+  // replace it outright (e.g. with a fully custom or non-mocked instance).
+  .extend('fusion', async ({ appEnv, configureFusion }) =>
+    resolveFusion({ env: appEnv, configure: configureFusion }),
+  )
+  .extend('app', async ({ configureApp, appEnv, fusion }) =>
+    mockAppModules<unknown, AppEnv>(configureApp, appEnv as AppEnv, fusion),
   )
   .extend('render', ({ fusion, app }) => {
     const wrapper = createAppScopeWrapper({ framework: fusion, app });

package/src/test.tsx

@@ -3,7 +3,7 @@ import { testApp as baseTestApp } from './test-app';
 // 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';
+import { configure as configureApp } from 'virtual:fusion-app-test-configure';
 
 /**
  * `vitest`'s `test`, pre-seeded with the application's own manifest, config, and
@@ -14,8 +14,15 @@ import { configure } from 'virtual:fusion-app-test-configure';
  * your `vitest.config.ts` `plugins`, which serves the virtual modules backing this fixture.
  * Running the same test file without the plugin registered fails to resolve those imports.
  *
- * Per-test mocking still works exactly like the base `testApp`: `.extend('configure', ...)` or
- * a per-case `test.override('env', ...)` layers on top of the resolved values.
+ * Per-test mocking still works exactly like the base `testApp`: `.extend('configureApp', ...)` or
+ * a per-case `test.override('appEnv', ...)` layers on top of the resolved values.
+ *
+ * @remarks `.override('configureApp', ...)` replaces the app's real `configure`
+ * This fixture's default value *is* the app's real `src/config.ts` `configure` export.
+ * `.override('configureApp', ...)` replaces that default outright, so an override that doesn't
+ * itself call the real `configure(configurator, args)` skips the app's production module setup
+ * entirely, rather than composing with it. See [Advanced usage](../docs/advanced.md) for the
+ * compose-safely pattern.
  *
  * @example
  * ```tsx
@@ -29,7 +36,7 @@ import { configure } from 'virtual:fusion-app-test-configure';
  * ```
  */
 export const test = baseTestApp
-  .extend('env', { injected: true }, { manifest, config })
-  .extend('configure', { injected: true }, () => configure);
+  .extend('appEnv', { injected: true }, { manifest, config })
+  .extend('configureApp', { injected: true }, () => configureApp);
 
 export default test;

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '0.2.0-next.2';
+export const version = '1.0.0-next.4';

package/tsconfig.json

@@ -15,6 +15,7 @@
     { "path": "../../app" },
     { "path": "../../modules/module" },
     { "path": "../../modules/app" },
+    { "path": "../../modules/navigation" },
     { "path": "../../react/framework" },
     { "path": "../../react/modules/module" },
     { "path": "../../utils/imports" }