@equinor/fusion-framework 8.0.15 → 8.1.0-next.1

package/docs/testing.md

@@ -0,0 +1,178 @@
+# Usage
+
+Recipes for the situations a test normally runs into. Every one of them builds a real framework instance — only the boundaries that leave the process are substituted.
+
+`mockFramework` takes a single callback, which receives a [`FrameworkMockConfigurator`](#the-configurator). That configurator **is** a `FrameworkConfigurator`, so everything an application does at configure time works here unchanged.
+
+## Zero configuration
+
+```typescript
+import { mockFramework } from '@equinor/fusion-framework/mock';
+
+const fusion = await mockFramework();
+
+fusion.modules.auth.account?.name; // 'Test User'
+await fusion.modules.serviceDiscovery.resolveService('apps'); // resolves offline
+```
+
+Every module declared by `FrameworkConfigurator` is initialized: `event`, `auth`, `http`, `serviceDiscovery`, `context` and `telemetry`.
+
+## The configurator
+
+Modules whose boundary is mocked expose their mock configurator directly, so a test configures them without registering a callback:
+
+| Property | Type |
+| --- | --- |
+| `msal` | `MsalMockConfigurator` |
+| `serviceDiscovery` | `ServiceDiscoveryMockConfigurator` |
+| `http` | `IHttpClientConfigurator` (the real configurator — see [`.http`](testing-extending.md#http)) |
+| `context` | `ContextMockConfigurator` |
+| `telemetry` | `TelemetryMockConfigurator` |
+
+```typescript
+const fusion = await mockFramework((configurator) => {
+  configurator.msal.setAccount({ name: 'Ada Lovelace' });
+  configurator.serviceDiscovery.setBaseUri('http://localhost:6669');
+});
+```
+
+These are the real module configurators, so the real builder API, the real validation and the real provider are used.
+
+## Choosing the signed-in user
+
+```typescript
+const fusion = await mockFramework((configurator) => {
+  configurator.msal.setAccount({ name: 'Ada Lovelace', username: 'ada@equinor.com' });
+});
+
+const token = await fusion.modules.auth.acquireAccessToken({
+  request: { scopes: ['Files.Read'] },
+});
+```
+
+The token is a structurally valid JWT carrying the claims an application reads. It is unsigned by default and must never be accepted by anything but a test.
+
+`setAccount` records configuration only — the user is signed in on the client before the provider initializes. It takes an object, `null` when nobody is signed in, or an ordinary config-builder callback resolving either:
+
+```typescript
+configurator.msal.setAccount(null);
+configurator.msal.setAccount(async ({ hasModule }) => ({
+  name: hasModule('app') ? 'App User' : 'Portal User',
+}));
+```
+
+Because the user is in place before `MsalProvider.initialize()` runs, the provider's real start-up path acts on it — pair `signedOut` with `setRequiresAuth(true)` to watch the automatic login happen.
+
+The account replaces any previously declared account, and is signed in on whichever client the module authenticates through — the one it builds, one supplied through `setClient`, or the host's when the module is hoisted onto a host application's provider. When that client cannot represent a declared user, it throws rather than failing quietly.
+
+## Testing signed-out behaviour
+
+```typescript
+const fusion = await mockFramework((configurator) => {
+  configurator.msal.setAccount({ signedOut: true });
+});
+
+fusion.modules.auth.account; // null
+```
+
+Silent flows then resolve empty so the provider follows its unauthenticated path, while an explicit `login()` still succeeds — so a test can drive the sign-in journey, not only its end state.
+
+## Composing the service registry
+
+Nothing has to be constructed to add a service, or to move every service to a locally running mock server such as Mockoon or Prism — in which case the application makes real HTTP calls with nothing intercepting them.
+
+```typescript
+const fusion = await mockFramework((configurator) => {
+  configurator.serviceDiscovery.setBaseUri('http://localhost:6669');
+  configurator.serviceDiscovery.addService({ key: 'my-api' });
+  configurator.serviceDiscovery.removeService('bookmarks');
+});
+```
+
+To replace the baseline registry outright rather than compose onto it, use `setServices`:
+
+```typescript
+configurator.serviceDiscovery.setServices([{ key: 'apps', uri: 'http://localhost:3000' }]);
+```
+
+By default an undeclared service resolves to a synthesised entry rather than throwing, so a test does not fail merely because the application resolved something the test did not think to declare. Call `setResolveUnknownServices(false)` to assert the opposite.
+
+> [!WARNING]
+> Built-in modules resolve services **while the framework starts** — the context module resolves `context`, for example. Combining `setResolveUnknownServices(false)` with a `setServices` registry that omits them fails initialization rather than the assertion you were writing. Either keep synthesis on, or declare every service the framework itself needs.
+
+## Seeding context
+
+```typescript
+const fusion = await mockFramework((configurator) => {
+  configurator.context.setCurrentContext({ id: 'project-42', type: { id: 'ProjectMaster' }, value: {} });
+});
+
+fusion.modules.context.currentContext; // the seeded item
+```
+
+`configurator.context` is a `ContextMockConfigurator` — a small, context-domain vocabulary (`setCurrentContext`, `setContexts`, `addContext`, `setRelatedContexts`) covers seeding a known item with no HTTP mock and no service-discovery mock required. `setResolver` is the escape hatch for a custom resolution need the friendly methods do not cover. Real `ContextProvider` behaviour — `validateContext`, `resolveContext`, parent-context propagation — still runs against the seeded data in both.
+
+This is one of two ways to fake context data: seeding an item directly (above) substitutes only the data source, with no transport involved. Mocking the context API's HTTP responses instead, through `.http`, exercises the real `ContextModuleConfigurator`/services/HTTP pipeline — reach for that when the test needs to cover that pipeline itself, optionally paired with `createOpenApiMockMiddleware` for faker-generated data straight from context's OpenAPI spec.
+
+## Mocking an individual call
+
+That is your test runner's job, not this entry point's. Mock clients are plain classes with ordinary methods, so any runner can spy on them with its own tooling — including call assertions and its own reset semantics.
+
+```typescript
+vi.spyOn(fusion.modules.serviceDiscovery.client, 'resolveService').mockResolvedValue(service);
+
+afterEach(() => vi.restoreAllMocks());
+```
+
+The same holds for `bun:test`'s `spyOn` and Node's `t.mock.method`, which is why this entry point introduces no mocking API of its own.
+
+## Configuring the framework as an application does
+
+The configurator is a `FrameworkConfigurator`, so every `enableX` and `configureX` helper is available and behaves normally.
+
+```typescript
+const fusion = await mockFramework((configurator) => {
+  configurator.onConfigured(() => {
+    /* ... */
+  });
+});
+```
+
+Mocks are registered **before** the callback runs, so anything configured there wins — including replacing a mock with a different one.
+
+## Registering your own modules
+
+Pass your module descriptors as a type argument. They are then typed on both the configurator and the returned instance, so no cast is needed to reach them.
+
+```typescript
+const fusion = await mockFramework<[InvoiceModule]>((configurator) => {
+  enableInvoicesMock(configurator, { total: 42 });
+});
+
+await fusion.modules.invoices.getInvoice('inv-1'); // fully typed
+```
+
+`addModule` is available if it reads better at the call site; it is sugar for the same call.
+
+```typescript
+configurator.addModule((c) => enableInvoicesMock(c, { total: 42 }));
+```
+
+> [!NOTE]
+> Only modules that ship a mock configurator get a property such as `configurator.msal`. Everything else is registered exactly as it is in production — through its own `enableX` helper or `configurator.addConfig`. Module *instances* never exist at configure time; they are created by `initialize`.
+
+See [Adding a mock for another module](./testing-extending.md) for how to give your module a test double, and a property on the configurator.
+
+## Bringing your own configurator
+
+`FrameworkMockConfigurator` can be constructed directly and initialized with `init`, which is useful when a test needs to hold on to the configurator.
+
+```typescript
+import { init } from '@equinor/fusion-framework';
+import { FrameworkMockConfigurator } from '@equinor/fusion-framework/mock';
+
+const configurator = new FrameworkMockConfigurator();
+configurator.msal.setAccount({ name: 'Ada Lovelace' });
+
+const fusion = await init(configurator);
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@equinor/fusion-framework",
-  "version": "8.0.15",
+  "version": "8.1.0-next.1",
   "description": "",
   "main": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
@@ -8,12 +8,18 @@
     ".": {
       "import": "./dist/esm/index.js",
       "types": "./dist/types/index.d.ts"
+    },
+    "./mock": {
+      "import": "./dist/esm/mock/index.js",
+      "types": "./dist/types/mock/index.d.ts"
     }
   },
   "keywords": [
     "fusion",
     "fusion-framework",
-    "utility"
+    "utility",
+    "testing",
+    "mock"
   ],
   "homepage": "https://equinor.github.io/fusion-framework/",
   "author": {
@@ -32,18 +38,18 @@
   },
   "dependencies": {
     "rxjs": "^7.8.1",
-    "@equinor/fusion-framework-module-context": "8.0.3",
-    "@equinor/fusion-framework-module-event": "6.0.1",
-    "@equinor/fusion-framework-module-http": "8.0.5",
-    "@equinor/fusion-framework-module": "6.1.2",
-    "@equinor/fusion-framework-module-service-discovery": "10.0.2",
-    "@equinor/fusion-framework-module-msal": "10.0.2",
-    "@equinor/fusion-framework-module-telemetry": "7.0.2",
-    "@equinor/fusion-framework-module-services": "8.1.0"
+    "@equinor/fusion-framework-module": "6.1.3-next.0",
+    "@equinor/fusion-framework-module-event": "6.1.0-next.0",
+    "@equinor/fusion-framework-module-msal": "11.0.0-next.0",
+    "@equinor/fusion-framework-module-context": "9.0.0-next.0",
+    "@equinor/fusion-framework-module-http": "8.1.0-next.0",
+    "@equinor/fusion-framework-module-services": "8.1.1-next.0",
+    "@equinor/fusion-framework-module-service-discovery": "10.1.0-next.0",
+    "@equinor/fusion-framework-module-telemetry": "8.0.0-next.1"
   },
   "devDependencies": {
     "typescript": "^7.0.2",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.10"
   },
   "scripts": {
     "build": "tsc -b",

package/src/__tests__/mock/application-module.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest';
+
+import type { IModulesConfigurator, Module } from '@equinor/fusion-framework-module';
+
+import { mockFramework } from '../../mock/index.js';
+
+/**
+ * A module an application team owns, which the framework knows nothing about.
+ *
+ * @remarks
+ * The point of these tests is that nothing below required support from
+ * `@equinor/fusion-framework/mock`. If an application team can do this, the
+ * extension pattern holds.
+ */
+interface InvoiceClient {
+  getInvoice(id: string): Promise<{ id: string; total: number }>;
+}
+
+class InvoiceConfigurator {
+  #client?: InvoiceClient;
+
+  public setClient(client: InvoiceClient): void {
+    this.#client = client;
+  }
+
+  public createClient(): InvoiceClient {
+    if (!this.#client) {
+      throw new Error('An invoice client is required');
+    }
+    return this.#client;
+  }
+}
+
+type InvoiceModule = Module<'invoices', InvoiceClient, InvoiceConfigurator>;
+
+const invoiceModule: InvoiceModule = {
+  name: 'invoices',
+  configure: () => new InvoiceConfigurator(),
+  initialize: ({ config }) => config.createClient(),
+};
+
+/** The team's own mock, following the pattern the built-in modules use. */
+const enableInvoicesMock = (
+  // biome-ignore lint/suspicious/noExplicitAny: mirrors every enableX helper
+  configurator: IModulesConfigurator<any, any>,
+  options: { total?: number } = {},
+): void => {
+  configurator.addConfig({
+    module: invoiceModule,
+    configure: (builder: InvoiceConfigurator) =>
+      builder.setClient({
+        getInvoice: async (id) => ({ id, total: options.total ?? 0 }),
+      }),
+  } as { module: InvoiceModule });
+};
+
+describe('application modules', () => {
+  it('fails to start without its mock, so the seam is real and not a no-op', async () => {
+    await expect(
+      mockFramework<[InvoiceModule]>((configurator) => {
+        configurator.addConfig({ module: invoiceModule } as { module: InvoiceModule });
+      }),
+    ).rejects.toThrow(/invoice client is required/i);
+  });
+
+  it('composes with the built-in mocks and is typed without a cast', async () => {
+    const fusion = await mockFramework<[InvoiceModule]>((configurator) => {
+      configurator.msal.setAccount({ name: 'Ada Lovelace' });
+      enableInvoicesMock(configurator, { total: 42 });
+    });
+
+    // No cast: `TModules` must flow through to `fusion.modules`.
+    const invoice = await fusion.modules.invoices.getInvoice('inv-1');
+
+    expect(invoice).toEqual({ id: 'inv-1', total: 42 });
+    expect(fusion.modules.auth.account?.name).toBe('Ada Lovelace');
+  });
+
+  it('is registered exactly as it is in production', async () => {
+    // The same helper, against a real FrameworkConfigurator, would behave identically.
+    const fusion = await mockFramework<[InvoiceModule]>((configurator) =>
+      enableInvoicesMock(configurator, { total: 7 }),
+    );
+
+    await expect(fusion.modules.invoices.getInvoice('inv-2')).resolves.toMatchObject({ total: 7 });
+  });
+});

package/src/__tests__/mock/documented-usage.test.ts

@@ -0,0 +1,98 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { decodeJwtSegment } from '@equinor/fusion-framework-module-msal/mock';
+
+import { init } from '../../init.js';
+import { createMockService, FrameworkMockConfigurator, mockFramework } from '../../mock/index.js';
+
+/**
+ * Pins the snippets in `docs/testing.md` and the package README to real
+ * behaviour, so documentation cannot drift away from the API it describes.
+ */
+describe('documented usage', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it('composes the service registry on the builder', async () => {
+    const fusion = await mockFramework((configurator) => {
+      configurator.serviceDiscovery.setBaseUri('http://localhost:6669');
+      configurator.serviceDiscovery.addService({ key: 'my-api' });
+      configurator.serviceDiscovery.removeService('bookmarks');
+    });
+
+    await expect(fusion.modules.serviceDiscovery.resolveService('my-api')).resolves.toMatchObject({
+      key: 'my-api',
+    });
+  });
+
+  it('replaces the baseline registry with setServices', async () => {
+    const fusion = await mockFramework((configurator) => {
+      configurator.serviceDiscovery.setServices([{ key: 'apps', uri: 'http://localhost:3000' }]);
+    });
+
+    await expect(fusion.modules.serviceDiscovery.resolveService('apps')).resolves.toMatchObject({
+      uri: 'http://localhost:3000',
+    });
+  });
+
+  it('keeps startup working when the registry is replaced, because unknown services synthesise', async () => {
+    // The context module resolves `context` while initializing, so a replaced
+    // registry that omits it would break start-up if synthesis were disabled.
+    const fusion = await mockFramework((configurator) => {
+      configurator.serviceDiscovery.setServices([{ key: 'apps', uri: 'http://localhost:3000' }]);
+    });
+
+    await expect(fusion.modules.serviceDiscovery.resolveService('people')).resolves.toBeDefined();
+  });
+
+  it('lets the test runner spy on the discovery client', async () => {
+    const fusion = await mockFramework();
+
+    vi.spyOn(fusion.modules.serviceDiscovery.client, 'resolveService').mockResolvedValue(
+      createMockService({ key: 'apps', uri: 'http://spied' }),
+    );
+
+    await expect(fusion.modules.serviceDiscovery.resolveService('apps')).resolves.toMatchObject({
+      uri: 'http://spied',
+    });
+  });
+
+  it('lets the test runner spy on the auth client', async () => {
+    const fusion = await mockFramework();
+
+    const spy = vi.spyOn(fusion.modules.auth.client, 'acquireToken');
+
+    await fusion.modules.auth.acquireAccessToken({ request: { scopes: ['Files.Read'] } });
+
+    expect(spy).toHaveBeenCalled();
+  });
+
+  it('resolves the real scope through the real provider, not the test double', async () => {
+    const fusion = await mockFramework((configurator) => {
+      // The client is configured with what it talks to, exactly as in production
+      configurator.msal.setClientConfig({ auth: { clientId: 'my-app', tenantId: 'my-tenant' } });
+    });
+
+    const token = await fusion.modules.auth.acquireAccessToken();
+    const claims = JSON.parse(decodeJwtSegment(token?.split('.')[1] ?? ''));
+
+    // MsalProvider — not the mock — turns "no scopes requested" into `${clientId}/.default`
+    expect(claims.scp).toBe('my-app/.default');
+  });
+
+  it('signs nobody in when the account is signed out', async () => {
+    const fusion = await mockFramework((configurator) => {
+      configurator.msal.setAccount({ signedOut: true });
+    });
+
+    expect(fusion.modules.auth.account).toBeFalsy();
+  });
+
+  it('can be constructed directly and initialized with init', async () => {
+    const configurator = new FrameworkMockConfigurator();
+    configurator.msal.setAccount({ name: 'Ada Lovelace' });
+
+    const fusion = await init(configurator);
+
+    expect(fusion.modules.auth.account?.name).toBe('Ada Lovelace');
+  });
+});