feat(framework): let any module get the same accessor .msal has

FrameworkMockConfigurator hand-pinned the msal and service-discovery mock
configurators to expose `.msal` and `.serviceDiscovery` as stable, synchronously
reachable properties. Nothing let a module supplied through TModules — an
application's own — do the same; that pinning trick was inline in the
constructor twice, with no way to reuse it a third time.

Extracted it into `_pin(module)` / `_getConfig(name)`, a protected pair a
subclass calls the same way this class does for its own built-ins:

    class AppMockConfigurator extends FrameworkMockConfigurator<[InvoiceModule]> {
      constructor() {
        super();
        this._pin(invoiceMockModule);
      }
      get invoices(): InvoiceMockConfigurator {
        return this._getConfig('invoices');
      }
    }

`_pin` replaces a module's `configure` factory with one that always returns the
same instance and registers it; `_getConfig` looks that instance up by name.
Both guard the cases that would otherwise fail silently or asynchronously: a
module with no `configure` factory, and one whose factory returns a promise
(pinning must be synchronous, or a test couldn't reach the accessor before
initialization runs).

Also dropped two `as { module: X }` casts in the constructor that tsc did not
actually need.

`.msal` and `.serviceDiscovery` are unchanged for consumers; they are now built
from `_pin`/`_getConfig` rather than from two private fields carrying the same
logic twice. `testing-extending.md` documents the pattern for a module that
needs it.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: odinr

.changeset/framework-mock-configurator-pin.md

@@ -0,0 +1,24 @@
+---
+"@equinor/fusion-framework": minor
+---
+
+Add `_pin` and `_getConfig` to `FrameworkMockConfigurator`, so a module supplied through `TModules` can get the same kind of named accessor `.msal` and `.serviceDiscovery` already have.
+
+Previously that pinning was hand-written twice, once per built-in mock, with no way for anything else to do the same. A subclass now reuses it directly:
+
+```typescript
+class AppMockConfigurator extends FrameworkMockConfigurator<[InvoiceModule]> {
+  constructor() {
+    super();
+    this._pin(invoiceMockModule);
+  }
+
+  get invoices(): InvoiceMockConfigurator {
+    return this._getConfig('invoices');
+  }
+}
+```
+
+`_pin(module)` replaces the module's own `configure` factory with one that always returns the same instance, and registers it — pinning it before initialization runs is what lets a test reach the accessor synchronously and have it be the configurator the module is actually built from. `_getConfig(name)` looks that instance up by the module's name, throwing if nothing was pinned for it.
+
+`.msal` and `.serviceDiscovery` are unchanged for consumers; they are now built from `_pin`/`_getConfig` themselves rather than from two private fields.

packages/framework/docs/testing-extending.md

@@ -39,6 +39,27 @@ const fusion = await mockFramework<[InvoiceModule]>((configurator) => {
 await fusion.modules.invoices.getInvoice('inv-1'); // typed, no cast
 ```
 
+### Giving your module the same accessor as `.msal` and `.serviceDiscovery`
+
+`enableInvoicesMock(configurator, options)` is enough on its own — the configurator it builds is discarded once configuration runs, which is fine when a test only ever sets options up front. Reach for an accessor when a test needs the configurator itself, for example to assert against it after the fact.
+
+Subclass `FrameworkMockConfigurator` and use the protected `_pin`/`_getConfig` pair it exposes for exactly this — the same mechanism `.msal` and `.serviceDiscovery` are built from:
+
+```typescript
+class AppMockConfigurator extends FrameworkMockConfigurator<[InvoiceModule]> {
+  constructor() {
+    super();
+    this._pin(invoiceMockModule);
+  }
+
+  get invoices(): InvoiceMockConfigurator {
+    return this._getConfig('invoices');
+  }
+}
+```
+
+`_pin` replaces the module's own `configure` factory with one that always returns the same instance — pinning it before initialization runs is what lets a test reach `.invoices` synchronously and have it be the configurator the module is actually built from. `_getConfig` looks that instance up by name, throwing if nothing was pinned for it.
+
 ## What is not covered yet
 
-The `http`, `services`, `context` and `telemetry` modules initialize but are not yet backed by test doubles, so anything issuing an actual request still reaches the network. Adding one means creating a `src/mock/` folder in **that module**, then pinning its configurator as a property on `FrameworkMockConfigurator` — the two lines the built-in mocks already use.
+The `http`, `services`, `context` and `telemetry` modules initialize but are not yet backed by test doubles, so anything issuing an actual request still reaches the network. Adding one means creating a `src/mock/` folder in **that module**, then pinning its configurator with `_pin` and exposing it with `_getConfig` on `FrameworkMockConfigurator` — the two lines the built-in mocks already use.

packages/framework/src/__tests__/mock/mock-framework.test.ts

@@ -1,12 +1,33 @@
 import { describe, expect, it } from 'vitest';
 
+import type { Module } from '@equinor/fusion-framework-module';
 import { enableMsalMock } from '@equinor/fusion-framework-module-msal/mock';
 import { enableServiceDiscoveryMock } from '@equinor/fusion-framework-module-service-discovery/mock';
 
 import { FrameworkConfigurator } from '../../FrameworkConfigurator.js';
 import { init } from '../../init.js';
 import { FrameworkMockConfigurator, mockFramework } from '../../mock/index.js';
 
+/** A minimal configurator, standing in for an application's own. */
+class WidgetsConfigurator {
+  #name = 'default';
+  setName(name: string): this {
+    this.#name = name;
+    return this;
+  }
+  get name(): string {
+    return this.#name;
+  }
+}
+
+/** A minimal module, standing in for one an application supplies through `TModules`. */
+type WidgetsModule = Module<'widgets', { name: string }, WidgetsConfigurator>;
+const widgetsModule: WidgetsModule = {
+  name: 'widgets',
+  configure: () => new WidgetsConfigurator(),
+  initialize: ({ config }) => ({ name: config.name }),
+};
+
 describe('mockFramework', () => {
   it('initializes every built-in module without configuration', async () => {
     const fusion = await mockFramework();
@@ -139,4 +160,61 @@ describe('FrameworkMockConfigurator', () => {
 
     expect(configurator.addModule(() => undefined)).toBe(configurator);
   });
+
+  it('lets a module supplied through TModules get the same kind of accessor as msal and serviceDiscovery', async () => {
+    // Standing in for an application subclassing FrameworkMockConfigurator to
+    // expose its own module the same way the built-ins are exposed.
+    class AppMockConfigurator extends FrameworkMockConfigurator<[WidgetsModule]> {
+      constructor() {
+        super();
+        this._pin(widgetsModule);
+      }
+      get widgets(): WidgetsConfigurator {
+        return this._getConfig('widgets');
+      }
+    }
+
+    const configurator = new AppMockConfigurator();
+    configurator.widgets.setName('Ada');
+
+    const fusion = await init(configurator);
+
+    expect(fusion.modules.widgets.name).toBe('Ada');
+  });
+
+  it('pins the same instance across repeated reads, so declarations accumulate on one configurator', () => {
+    class AppMockConfigurator extends FrameworkMockConfigurator<[WidgetsModule]> {
+      constructor() {
+        super();
+        this._pin(widgetsModule);
+      }
+      get widgets(): WidgetsConfigurator {
+        return this._getConfig('widgets');
+      }
+    }
+
+    const configurator = new AppMockConfigurator();
+
+    expect(configurator.widgets).toBe(configurator.widgets);
+  });
+
+  it('throws from _getConfig when nothing was pinned for that name', () => {
+    class AppMockConfigurator extends FrameworkMockConfigurator {
+      readMissing(): unknown {
+        return this._getConfig('widgets');
+      }
+    }
+
+    expect(() => new AppMockConfigurator().readMissing()).toThrow(/widgets/);
+  });
+
+  it('throws from _pin when the module declares no configure factory', () => {
+    class AppMockConfigurator extends FrameworkMockConfigurator {
+      pinMissingConfigure(): void {
+        this._pin({ ...widgetsModule, configure: undefined } as WidgetsModule);
+      }
+    }
+
+    expect(() => new AppMockConfigurator().pinMissingConfigure()).toThrow(/configure factory/);
+  });
 });

packages/framework/src/mock/FrameworkMockConfigurator.ts

@@ -1,11 +1,12 @@
 import type { AnyModule } from '@equinor/fusion-framework-module';
 
-import type { MsalModule } from '@equinor/fusion-framework-module-msal';
-import { msalMockModule, MsalMockConfigurator } from '@equinor/fusion-framework-module-msal/mock';
-import type { ServiceDiscoveryModule } from '@equinor/fusion-framework-module-service-discovery';
+import {
+  msalMockModule,
+  type MsalMockConfigurator,
+} from '@equinor/fusion-framework-module-msal/mock';
 import {
   serviceDiscoveryMockModule,
-  ServiceDiscoveryMockConfigurator,
+  type ServiceDiscoveryMockConfigurator,
 } from '@equinor/fusion-framework-module-service-discovery/mock';
 
 import { FrameworkConfigurator } from '../FrameworkConfigurator.js';
@@ -46,23 +47,82 @@ export class FrameworkMockConfigurator<
 > extends FrameworkConfigurator<TModules> {
   static override readonly className: string = 'FrameworkMockConfigurator';
 
-  #msal = new MsalMockConfigurator();
-  #serviceDiscovery = new ServiceDiscoveryMockConfigurator();
+  // Keyed by module name, so `_getConfig` can look a pinned configurator up
+  // without needing the module descriptor again.
+  #configurators = new Map<string, unknown>();
 
   constructor() {
     super();
 
-    // The module system builds a fresh configurator during the configure phase.
-    // Pinning our instances is what lets a test reach `.msal` and
-    // `.serviceDiscovery` before initialization and configure them directly.
-    const msal: MsalModule = { ...msalMockModule, configure: () => this.#msal };
-    const serviceDiscovery: ServiceDiscoveryModule = {
-      ...serviceDiscoveryMockModule,
-      configure: () => this.#serviceDiscovery,
-    };
+    // Pinning the built-in mocks up front — rather than waiting for `.msal` or
+    // `.serviceDiscovery` to be read — is what replaces the real `auth` and
+    // `serviceDiscovery` modules registered by `FrameworkConfigurator`'s own
+    // constructor, whether or not a test ever touches the accessor.
+    this._pin(msalMockModule);
+    this._pin(serviceDiscoveryMockModule);
+  }
 
-    this.addConfig({ module: msal } as { module: MsalModule });
-    this.addConfig({ module: serviceDiscovery } as { module: ServiceDiscoveryModule });
+  /**
+   * Pins a module to a single configurator instance for the lifetime of this
+   * configurator, so it can be reached by name through {@link _getConfig}.
+   *
+   * @remarks
+   * The module system otherwise builds a fresh configurator from its own
+   * `configure` factory during the configure phase — too late for a test to
+   * reach, and a new instance on every call besides. This replaces that
+   * factory with one that always returns the same instance, and registers the
+   * result under the module's own name.
+   *
+   * A subclass registering a module supplied through {@link TModules} uses
+   * this the same way `.msal` and `.serviceDiscovery` do, to expose its own
+   * named accessor:
+   *
+   * ```typescript
+   * class MyMockConfigurator extends FrameworkMockConfigurator<[InvoiceModule]> {
+   *   constructor() {
+   *     super();
+   *     this._pin(invoiceMockModule);
+   *   }
+   *
+   *   public get invoices(): InvoiceMockConfigurator {
+   *     return this._getConfig('invoices');
+   *   }
+   * }
+   * ```
+   *
+   * @param module - The module descriptor to pin a configurator for.
+   * @throws {Error} If the module declares no `configure` factory to pin, or
+   *   the factory returns a promise instead of a configurator — pinning is
+   *   synchronous, so a test can reach the accessor immediately.
+   */
+  protected _pin<TModule extends AnyModule>(module: TModule): void {
+    if (!module.configure) {
+      throw new Error(`Cannot pin "${module.name}": it declares no configure factory.`);
+    }
+    const instance = module.configure();
+    if (instance instanceof Promise) {
+      throw new Error(
+        `Cannot pin "${module.name}": its configure factory returns a promise, so it cannot be resolved synchronously.`,
+      );
+    }
+    this.#configurators.set(module.name, instance);
+    this.addConfig({ module: { ...module, configure: () => instance } as TModule });
+  }
+
+  /**
+   * Returns the configurator pinned for a module by name.
+   *
+   * @param name - The module's name, as passed to {@link _pin}.
+   * @throws {Error} If no configurator has been pinned for that name.
+   */
+  protected _getConfig<TConfig>(name: string): TConfig {
+    const config = this.#configurators.get(name);
+    if (config === undefined) {
+      throw new Error(
+        `No configurator is pinned for module "${name}" — call this._pin(module) before this._getConfig("${name}").`,
+      );
+    }
+    return config as TConfig;
   }
 
   /**
@@ -73,7 +133,7 @@ export class FrameworkMockConfigurator<
    * a change made here is what the module sees.
    */
   public get msal(): MsalMockConfigurator {
-    return this.#msal;
+    return this._getConfig<MsalMockConfigurator>(msalMockModule.name);
   }
 
   /**
@@ -84,7 +144,7 @@ export class FrameworkMockConfigurator<
    * module is configured from, so a change made here is what the module sees.
    */
   public get serviceDiscovery(): ServiceDiscoveryMockConfigurator {
-    return this.#serviceDiscovery;
+    return this._getConfig<ServiceDiscoveryMockConfigurator>(serviceDiscoveryMockModule.name);
   }
 
   /**