@equinor/fusion-framework-app 13.0.0 → 14.0.0-next.0

package/src/mock/enable-app-manifest-mock.ts

@@ -0,0 +1,62 @@
+import type { FrameworkMockConfigurator } from '@equinor/fusion-framework/mock';
+import { AppConfig, enableAppModule, type AppModule } from '@equinor/fusion-framework-module-app';
+import { MockAppClient } from '@equinor/fusion-framework-module-app/mock';
+import type { ConfigEnvironment } from '@equinor/fusion-framework-module-app';
+
+import type { AppEnv } from '../types.js';
+
+/**
+ * Enables the `app` module on a parent framework configurator, wrapping its
+ * client in a {@link MockAppClient} so this app's manifest and config resolve
+ * locally.
+ *
+ * @remarks
+ * The underlying http client is still resolved the same way `AppConfigurator`
+ * resolves it (a pre-configured client, falling back to service discovery), so
+ * a caller pointing `serviceDiscovery` at something else — e.g. a real local
+ * mock server — is honored for every request `MockAppClient` doesn't answer
+ * itself. {@link mockAppModules} uses this to wire its zero-config default
+ * parent; call it directly when building a custom parent (via
+ * {@link mockFramework}) that also needs this app's own manifest servable.
+ *
+ * @param configurator - The parent framework's mock configurator, with `app` in its module set.
+ * @param env - The application environment whose manifest (and optional config) should be served.
+ * @param assetUri - Overrides the base URI a loaded app's script is imported from.
+ * @template TEnv - The application environment descriptor.
+ *
+ * @example Custom service discovery, same manifest resolution
+ * ```typescript
+ * const fusion = await mockFramework<[AppModule]>((configurator) => {
+ *   configurator.serviceDiscovery.setBaseUri('http://localhost:9999');
+ *   enableAppManifestMock(configurator, env);
+ * });
+ * const modules = await mockAppModules(undefined, env, fusion);
+ * ```
+ */
+export function enableAppManifestMock<TEnv extends AppEnv>(
+  configurator: FrameworkMockConfigurator<[AppModule]>,
+  env: TEnv,
+  assetUri?: string,
+): void {
+  enableAppModule(configurator, (builder) => {
+    // only override the default asset base when the caller supplies one; an
+    // explicit empty string is meaningful (selects a root-relative script path)
+    if (assetUri !== undefined) {
+      builder.setAssetUri(assetUri);
+    }
+    builder.setClient(async ({ requireInstance }) => {
+      const http = await requireInstance('http');
+      const client = http.hasClient('apps')
+        ? http.createClient('apps')
+        : await (await requireInstance('serviceDiscovery')).createClient('apps');
+      // fall back to a trivial config so `App.initialize()` can resolve without a caller-supplied one
+      return new MockAppClient(
+        client,
+        env.manifest,
+        env.config ?? new AppConfig<ConfigEnvironment>({ environment: {} }),
+      );
+    });
+  });
+}
+
+export default enableAppManifestMock;

package/src/mock/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Zero-configuration application module pipelines for tests.
+ *
+ * @remarks
+ * Lets a test initialize an application's real module pipeline — real
+ * `event`/`http`/`msal` modules, real configuration pipeline, real lifecycle —
+ * while the boundaries that reach outside the process are substituted with the
+ * same deterministic fakes {@link https://www.npmjs.com/package/@equinor/fusion-framework | @equinor/fusion-framework}'s
+ * own `/mock` entry point uses. No credentials, no network access and no
+ * running parent portal are required.
+ *
+ * This entry point is test-runner agnostic: it contains no dependency on
+ * Vitest or any other test framework, so the same helpers work under any
+ * runner.
+ *
+ * @packageDocumentation
+ */
+
+export { mockAppModules, type AppMockConfigureFn } from './mock-app-modules.js';
+export { AppMockConfigurator } from './AppMockConfigurator.js';
+export { enableAppManifestMock } from './enable-app-manifest-mock.js';

package/src/mock/mock-app-modules.ts

@@ -0,0 +1,109 @@
+import type { Fusion } from '@equinor/fusion-framework';
+import { mockFramework } from '@equinor/fusion-framework/mock';
+
+import type { AnyModule } from '@equinor/fusion-framework-module';
+import type { AppModule } from '@equinor/fusion-framework-module-app';
+
+import { initializeAppModules } from '../initialize-app-modules.js';
+import type { AppEnv, AppModulesInstance } from '../types.js';
+
+import { AppMockConfigurator } from './AppMockConfigurator.js';
+import { enableAppManifestMock } from './enable-app-manifest-mock.js';
+
+/**
+ * Configuration callback for {@link mockAppModules}.
+ */
+export type AppMockConfigureFn<
+  TModules extends Array<AnyModule> | unknown = unknown,
+  TEnv extends AppEnv = AppEnv,
+> = (
+  configurator: AppMockConfigurator<TModules, Fusion['modules'], TEnv>,
+  args: { fusion: Fusion; env: TEnv },
+) => void | Promise<void>;
+
+/**
+ * Runs an application's module pipeline with no real credentials required,
+ * from either the parent framework or the app's own `http`/`msal`
+ * registrations.
+ *
+ * @remarks
+ * The real `AppConfigurator` pipeline is run — the real module set, the real
+ * configuration pipeline and the real lifecycle. Only the boundaries that
+ * would need credentials are substituted by default; the `http` module is
+ * the real `HttpClientConfigurator`, so a registered client only avoids the
+ * network for requests a middleware short-circuits with a response — a
+ * client with no matching middleware, or a middleware that calls `next`,
+ * still reaches the real network. A test exercises the wiring an
+ * application actually depends on rather than a reimplementation of it.
+ *
+ * The configurator passed to `cb` is an {@link AppMockConfigurator}, which *is*
+ * an `AppConfigurator`. `useFrameworkServiceClient`, `configureHttpClient` and
+ * any callback written for a real app work against it unchanged.
+ *
+ * `fusion` defaults to a fresh {@link mockFramework} instance with a real `app`
+ * module already enabled and this app's own manifest served at whatever URI
+ * service discovery resolves `'apps'` to, so a test needs no parent Fusion
+ * instance of its own — but an already-mocked (or real) instance can be passed
+ * to compose with other framework-level setup. To point the parent's service
+ * discovery at something else (e.g. a real local mock server) while keeping
+ * the manifest served consistently, build that `fusion` with
+ * {@link mockFramework} and call {@link enableAppManifestMock} yourself,
+ * after customizing `serviceDiscovery`.
+ *
+ * @template TModules - Module descriptors beyond the default set. Supply this
+ *   when a test registers application modules, so they are typed on the result.
+ * @template TEnv - The application environment descriptor.
+ * @param cb - Configuration callback invoked before module initialization, or `undefined` to skip it.
+ * @param env - The application environment (manifest, config, basename).
+ * @param fusion - The parent Fusion instance; defaults to a fresh {@link mockFramework} instance.
+ * @returns The initialized application module instance.
+ *
+ * @example Zero configuration
+ * ```typescript
+ * const manifest = { appKey: 'my-app', displayName: 'My App', description: 'My app', type: 'standalone' } as const;
+ * const modules = await mockAppModules(undefined, { manifest });
+ * ```
+ *
+ * @example Register a client answered by the app's own mocked HTTP module
+ * ```typescript
+ * const manifest = { appKey: 'my-app', displayName: 'My App', description: 'My app', type: 'standalone' } as const;
+ * const modules = await mockAppModules(
+ *   (configurator) => {
+ *     configurator.useFrameworkServiceClient('portal-api');
+ *     configurator.http.addMiddleware(async (uri, init, next) =>
+ *       uri === 'https://portal-api.fusion.test/items' ? Response.json([{ id: 1 }]) : next(uri, init),
+ *     );
+ *   },
+ *   { manifest },
+ * );
+ *
+ * const items = await modules.http.createClient('portal-api').json('/items');
+ * ```
+ */
+export async function mockAppModules<
+  TModules extends Array<AnyModule> | unknown = unknown,
+  TEnv extends AppEnv = AppEnv,
+>(
+  cb: AppMockConfigureFn<TModules, TEnv> | undefined,
+  env: TEnv,
+  fusion?: Fusion,
+): Promise<AppModulesInstance<TModules>> {
+  // `await` is illegal in a parameter default, so an omitted fusion is resolved here instead.
+  // The default parent also carries a real `app` module, serving this app's own manifest at
+  // whatever URI service discovery is currently configured to resolve `'apps'` to, so a test
+  // exercises the same portal wiring a real parent framework would provide.
+  const resolvedFusion: Fusion =
+    fusion ??
+    (await mockFramework<[AppModule]>((configurator) => enableAppManifestMock(configurator, env)));
+  const configurator = new AppMockConfigurator<TModules, Fusion['modules'], TEnv>(env);
+  // Cast is safe: `initializeAppModules` returns the exact module instance produced by
+  // `configurator`, which was constructed with this same `TModules`. TypeScript widens
+  // `TModules` to its constraint (`AnyModule[]`) when inferring through the generic
+  // `TConfigurator` parameter, so the assignment needs an explicit assertion here.
+  return initializeAppModules(configurator, cb, {
+    fusion: resolvedFusion,
+    env,
+  }) as Promise<AppModulesInstance<TModules>>;
+}
+
+export default mockAppModules;

package/src/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '13.0.0';
+export const version = '14.0.0-next.0';

package/vitest.config.ts

@@ -1,6 +1,6 @@
 import { defineProject } from 'vitest/config';
 
-import { name, version } from './package.json';
+import { name, version } from './package.json' with { type: 'json' };
 
 export default defineProject({
   test: {