feat(module-event): add mock entry point for recording and intercepting events

Add @equinor/fusion-framework-module-event/mock: EventMockConfigurator
records every event dispatched through the framework and lets a test
intercept or cancel one before its listeners run, closing the gap the
existing event$ observable can't (subscribers there run strictly after
dispatch, so preventDefault() has no effect from there).

- EventMockConfigurator: events/getEvents/lastEvent for assertions,
  intercept(type, handler) for pre-listener interception/cancellation,
  clear() to reset recorded history.
- enableEventMock / createEventMockModule: pins a single configurator
  instance while still wiring onBubble from ref at configure time, since
  the real module's bubbling decision can only be made then.
- FrameworkMockConfigurator.event: pinned alongside .msal/.serviceDiscovery/
  .http, using the same ref-aware wiring rather than the generic _pin
  (which would freeze the bubbling decision before ref could be known).
- docs/testing.md + README Testing section, following the http module's
  established doc convention.
- Tests: 9 new in the event module, 2 new in FrameworkMockConfigurator's
  suite, all passing alongside the existing 853.

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

Author: odinr

.changeset/module-event_mock-entry-point.md

@@ -0,0 +1,19 @@
+---
+"@equinor/fusion-framework-module-event": minor
+"@equinor/fusion-framework": minor
+---
+
+Add a `mock` entry point (`@equinor/fusion-framework-module-event/mock`) so a test can record every event dispatched through the framework and intercept or cancel one before its listeners run.
+
+```typescript
+import { enableEventMock } from '@equinor/fusion-framework-module-event/mock';
+
+const event = enableEventMock(configurator);
+
+await fusion.modules.event.dispatchEvent('myFeature', { detail: { id: 1 } });
+expect(event.lastEvent('myFeature')?.detail).toEqual({ id: 1 });
+```
+
+`EventMockConfigurator.intercept(type, handler)` runs before `addEventListener` handlers, for the same reason `event$` alone was not enough: canceling a cancelable event through `preventDefault()` only stops listeners if it happens before dispatch, which `event$` subscribers, running strictly after dispatch, cannot do.
+
+`@equinor/fusion-framework`'s `FrameworkMockConfigurator` now pins this through `.event`, alongside `.msal`, `.serviceDiscovery` and `.http` — reachable synchronously right after construction, the same way the others are, while the real module's `onBubble` wiring to a parent event provider still happens at configure time.

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

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 
 import type { Module } from '@equinor/fusion-framework-module';
 import { enableMsalMock } from '@equinor/fusion-framework-module-msal/mock';
@@ -171,6 +171,31 @@ describe('FrameworkMockConfigurator', () => {
     expect(fusion.modules.http.createClient('my-api')).toBeDefined();
   });
 
+  it('records every event dispatched through the framework, including onModulesLoaded', async () => {
+    const configurator = new FrameworkMockConfigurator();
+
+    const fusion = await init(configurator);
+    await fusion.modules.event.dispatchEvent('myFeature', { detail: { id: 1 } });
+
+    expect(configurator.event.getEvents('onModulesLoaded')).toHaveLength(1);
+    expect(configurator.event.lastEvent('myFeature')?.detail).toEqual({ id: 1 });
+  });
+
+  it('lets a test cancel an event before its listeners run', async () => {
+    const configurator = new FrameworkMockConfigurator();
+    configurator.event.intercept('myFeature', (event) => event.preventDefault());
+
+    const fusion = await init(configurator);
+    const listener = vi.fn();
+    fusion.modules.event.addEventListener('myFeature', listener);
+    await fusion.modules.event.dispatchEvent('myFeature', {
+      detail: null,
+      cancelable: true,
+    });
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+
   it('exposes the same services configurator the services module is built from', () => {
     const configurator = new FrameworkMockConfigurator();
 

packages/framework/src/mock/FrameworkMockConfigurator.ts

@@ -3,6 +3,11 @@ import type { AnyModule } from '@equinor/fusion-framework-module';
 import contextModule, {
   type ContextModuleConfigurator,
 } from '@equinor/fusion-framework-module-context';
+import { eventModuleKey } from '@equinor/fusion-framework-module-event';
+import {
+  createEventMockModule,
+  type EventMockConfigurator,
+} from '@equinor/fusion-framework-module-event/mock';
 import {
   httpMockModule,
   type HttpMockConfigurator,
@@ -43,10 +48,13 @@ import { FrameworkConfigurator } from '../FrameworkConfigurator.js';
  * are reachable the same way `.msal` is, since their `configure` factories
  * take no `ref` and so lose nothing by being pinned early.
  *
- * `event` is deliberately not pinned: its `configure` factory reads `ref` to
- * wire bubbling to a parent event provider when this configurator is hoisted
- * inside a host framework, and pinning would freeze that decision before a
- * `ref` could ever be known.
+ * `event` is pinned through {@link createEventMockModule} rather than
+ * {@link _pin}: its `configure` factory reads `ref` to wire bubbling to a
+ * parent event provider when this configurator is hoisted inside a host
+ * framework, a decision `_pin` would freeze before any `ref` could be known.
+ * `.event` still records every dispatched event and lets a test intercept or
+ * cancel one, so a test never subscribes to `event$` or races
+ * `addEventListener` against dispatch order just to observe what fired.
  *
  * Because this *is* a `FrameworkConfigurator`, every `enableX` helper an
  * application already uses accepts it unchanged — including the ones an
@@ -90,6 +98,12 @@ export class FrameworkMockConfigurator<
     this._pin(servicesModule);
     this._pin(contextModule);
     this._pin(telemetryModule);
+
+    // `event`'s configure factory needs `ref` at configure time to wire
+    // bubbling, so it is pinned by hand instead of through `_pin`.
+    const { configurator: eventConfigurator, module: eventMockModule } = createEventMockModule();
+    this.#configurators.set(eventMockModule.name, eventConfigurator);
+    this.addConfig({ module: eventMockModule });
   }
 
   /**
@@ -175,6 +189,20 @@ export class FrameworkMockConfigurator<
     return this._getConfig<MsalMockConfigurator>(msalMockModule.name);
   }
 
+  /**
+   * Records and intercepts every event dispatched through the framework.
+   *
+   * @remarks
+   * The same {@link EventMockConfigurator} the event module is configured
+   * from, so a change made here — such as canceling an event through
+   * {@link EventMockConfigurator.intercept} — is what the module sees.
+   *
+   * @returns The event mock configurator.
+   */
+  public get event(): EventMockConfigurator {
+    return this._getConfig<EventMockConfigurator>(eventModuleKey);
+  }
+
   /**
    * Configures the registry services are resolved from.
    *

packages/modules/event/README.md

@@ -193,4 +193,10 @@ await modules.event.dispatchEvent('myEvent', {
   detail: data,
   canBubble: false,
 });
-```
+```
+
+## Testing
+
+Import from `@equinor/fusion-framework-module-event/mock` to record every event dispatched through the framework and intercept or cancel one before its listeners run, instead of subscribing to `event$` or racing `addEventListener` against dispatch order.
+
+See [Testing](docs/testing.md) for `enableEventMock`, `EventMockConfigurator`, and `FrameworkMockConfigurator.event`.

packages/modules/event/docs/testing.md

@@ -0,0 +1,97 @@
+# Testing
+
+`@equinor/fusion-framework-module-event/mock` swaps the event module's configurator for one that records every dispatched event and lets a test intercept or cancel one before its listeners run — without changing the provider, the dispatcher, or any other part of the module's behavior.
+
+## Why not just use `event$`?
+
+The real module already exposes `event$`, an observable of every dispatched event (see the main [README](../README.md#observable-event-stream)). That is enough for read-only assertions, but two things it cannot do:
+
+- **Cancel or rewrite an event before listeners run.** Subscribers to `event$` receive events strictly after dispatch — calling `preventDefault()` there has no effect on whether `addEventListener` handlers ran.
+- **Look events up synchronously by type**, without setting up a subscription before the event you care about fires and buffering it yourself.
+
+`EventMockConfigurator` is `onDispatch` itself: it records the event and runs any registered interceptor, all inside the same hook the real event module calls before invoking listeners.
+
+## Enabling the mock
+
+### Through `FrameworkMockConfigurator`
+
+```ts
+import { FrameworkMockConfigurator } from '@equinor/fusion-framework/mock';
+
+const configurator = new FrameworkMockConfigurator();
+configurator.event.intercept('analytics', (event) => event.preventDefault());
+
+const fusion = await init(configurator);
+```
+
+`FrameworkMockConfigurator` already pins an `EventMockConfigurator` for you — reach it through `.event`, the same way `.msal` and `.serviceDiscovery` work.
+
+### Through `enableEventMock` directly
+
+Use this when composing a custom modules configurator that does not extend `FrameworkMockConfigurator`:
+
+```ts
+import { ModulesConfigurator } from '@equinor/fusion-framework-module';
+import { enableEventMock } from '@equinor/fusion-framework-module-event/mock';
+
+const configurator = new ModulesConfigurator([/* ... */]);
+const event = enableEventMock(configurator, (builder) => {
+  builder.intercept('analytics', (e) => e.preventDefault());
+});
+
+const instances = await configurator.initialize();
+// `event` is the same configurator instance `instances.event` was built from
+```
+
+`enableEventMock` returns the `EventMockConfigurator` it built the module around, so there is no second lookup needed.
+
+## Asserting on dispatched events
+
+Every event dispatched through the provider — including the framework's own `onModulesLoaded` — is recorded, in dispatch order:
+
+```ts
+await fusion.modules.event.dispatchEvent('myFeature', { detail: { id: 1 } });
+
+configurator.event.events; // readonly FrameworkEvent[] — every event recorded so far
+configurator.event.getEvents('myFeature'); // only events of that type
+configurator.event.lastEvent('myFeature')?.detail; // { id: 1 }
+```
+
+`lastEvent` and `getEvents` both accept an optional `type` filter; omit it to look across every event type.
+
+Call `configurator.event.clear()` between assertions (or between test cases) to reset the recorded history without needing a fresh configurator. Registered interceptors are unaffected by `clear()`.
+
+## Intercepting and canceling events
+
+`intercept(type, handler)` registers a callback that runs **before** any `addEventListener` handler, for every event of the given type, in registration order:
+
+```ts
+const teardown = configurator.event.intercept('tokenAcquired', (event) => {
+  // A cancelable event canceled here never reaches addEventListener handlers.
+  event.preventDefault();
+});
+
+// later, to stop intercepting
+teardown();
+```
+
+`preventDefault()` only has an effect on a `cancelable` event — declare the event as `cancelable: true` when dispatching it if a test needs to cancel it:
+
+```ts
+await fusion.modules.event.dispatchEvent('myFeature', {
+  detail: null,
+  cancelable: true,
+});
+```
+
+An interceptor can also just observe (for logging or an assertion) without calling `preventDefault()` — nothing about registering one requires canceling.
+
+## Bubbling to a parent framework
+
+The real event module's `configure` factory reads a `ref` argument, present when this configurator's framework instance is hoisted inside a host framework, to wire `onBubble` and forward events to the parent's event provider. `EventMockConfigurator` does not decide this itself — `enableEventMock`'s module wiring still reads `ref` at configure time and assigns `onBubble` on the same pinned configurator, so a mock hoisted as a child framework still bubbles events exactly like the real module does.
+
+This is also why `FrameworkMockConfigurator` does not use its usual `_pin` helper for the event module: `_pin` calls `configure()` once, synchronously, with no `ref` — which would freeze the bubbling decision before a `ref` could ever be known.
+
+## Multiple named event configurators
+
+Nothing about `EventMockConfigurator` is tied to a single framework instance — a test composing more than one `ModulesConfigurator` (for example, a host framework and a hoisted child) gets one recording configurator per `enableEventMock`/`FrameworkMockConfigurator` call, so events dispatched on one never appear on the other's `events` unless bubbling forwards them there.

packages/modules/event/package.json

@@ -9,12 +9,19 @@
     ".": {
       "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"
     }
   },
   "typesVersions": {
     "*": {
       ".": [
         "dist/types/index.d.ts"
+      ],
+      "mock": [
+        "dist/types/mock/index.d.ts"
       ]
     }
   },

packages/modules/event/src/__tests__/mock/event-mock.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ModulesConfigurator } from '@equinor/fusion-framework-module';
+
+import type { IEventModuleProvider } from '../../provider';
+import { module as realModule } from '../../module';
+import { EventMockConfigurator, createEventMockModule, enableEventMock } from '../../mock';
+
+/**
+ * Initializes the mock module through the real module system.
+ *
+ * @remarks
+ * Deliberately avoids hand-building initialization arguments — the module
+ * system's configure/initialize/post-initialize pipeline is exactly what a
+ * test should exercise, since that pipeline (not a hand-rolled provider) is
+ * what an application actually runs.
+ *
+ * @param configure - Optional callback receiving the mock configurator.
+ * @returns The provider the module produced and the configurator it was
+ *   pinned to.
+ */
+const initializeMockWith = async (
+  configure?: (builder: EventMockConfigurator) => void,
+): Promise<{ provider: IEventModuleProvider; configurator: EventMockConfigurator }> => {
+  const configurator = new ModulesConfigurator([]);
+  const eventConfigurator = enableEventMock(configurator, configure);
+  const instances = await configurator.initialize();
+  return {
+    provider: (instances as unknown as { event: IEventModuleProvider }).event,
+    configurator: eventConfigurator,
+  };
+};
+
+describe('eventMockModule', () => {
+  it('changes nothing but the configurator', () => {
+    const { module: eventMockModule } = createEventMockModule();
+    expect(eventMockModule.name).toBe(realModule.name);
+    expect(eventMockModule.version).toBe(realModule.version);
+    expect(eventMockModule.initialize).toBe(realModule.initialize);
+    expect(eventMockModule.postInitialize).toBe(realModule.postInitialize);
+    expect(eventMockModule.dispose).toBe(realModule.dispose);
+  });
+
+  it('records every dispatched event, in dispatch order', async () => {
+    const { provider, configurator } = await initializeMockWith();
+
+    await provider.dispatchEvent('first', { detail: 1 });
+    await provider.dispatchEvent('second', { detail: 2 });
+
+    expect(configurator.events.map((e) => e.type)).toEqual([
+      // `onModulesLoaded` is dispatched by the module's own `postInitialize`
+      'onModulesLoaded',
+      'first',
+      'second',
+    ]);
+  });
+
+  it('filters recorded events by type', async () => {
+    const { provider, configurator } = await initializeMockWith();
+
+    await provider.dispatchEvent('myEvent', { detail: 1 });
+    await provider.dispatchEvent('myEvent', { detail: 2 });
+    await provider.dispatchEvent('otherEvent', { detail: 3 });
+
+    expect(configurator.getEvents('myEvent').map((e) => e.detail)).toEqual([1, 2]);
+    expect(configurator.lastEvent('myEvent')?.detail).toBe(2);
+  });
+
+  it('returns undefined from lastEvent when nothing of that type dispatched', async () => {
+    const { configurator } = await initializeMockWith();
+    expect(configurator.lastEvent('neverDispatched')).toBeUndefined();
+  });
+
+  it('clears recorded history without touching interceptors', async () => {
+    const { provider, configurator } = await initializeMockWith();
+
+    await provider.dispatchEvent('myEvent', { detail: 1 });
+    configurator.clear();
+    expect(configurator.events).toEqual([]);
+
+    const intercept = vi.fn();
+    configurator.intercept('myEvent', intercept);
+    configurator.clear();
+    await provider.dispatchEvent('myEvent', { detail: 2 });
+    expect(intercept).toHaveBeenCalledTimes(1);
+  });
+
+  it('runs a registered interceptor before listeners', async () => {
+    const { provider, configurator } = await initializeMockWith();
+    const order: string[] = [];
+
+    configurator.intercept('myEvent', () => {
+      order.push('intercepted');
+    });
+    provider.addEventListener('myEvent', () => {
+      order.push('listened');
+    });
+
+    await provider.dispatchEvent('myEvent', { detail: null });
+
+    expect(order).toEqual(['intercepted', 'listened']);
+  });
+
+  it('lets an interceptor cancel a cancelable event before listeners run', async () => {
+    const { provider, configurator } = await initializeMockWith();
+    const listener = vi.fn();
+
+    configurator.intercept('myEvent', (event) => event.preventDefault());
+    provider.addEventListener('myEvent', listener);
+
+    await provider.dispatchEvent('myEvent', { detail: null, cancelable: true });
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it('removes an interceptor through its teardown', async () => {
+    const { provider, configurator } = await initializeMockWith();
+    const intercept = vi.fn();
+
+    const teardown = configurator.intercept('myEvent', intercept);
+    teardown();
+    await provider.dispatchEvent('myEvent', { detail: null });
+
+    expect(intercept).not.toHaveBeenCalled();
+  });
+
+  it('configures the recorder through enableEventMock', async () => {
+    const { configurator } = await initializeMockWith((builder) => {
+      builder.intercept('myEvent', (event) => event.preventDefault());
+    });
+
+    expect(configurator).toBeInstanceOf(EventMockConfigurator);
+  });
+});