@equinor/fusion-framework-vitest-plugin-react-app 1.0.0-next.6 → 1.0.1

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

@@ -1,132 +0,0 @@
-import { FileNotFoundError } from '@equinor/fusion-imports';
-import type { AppManifest } from '@equinor/fusion-framework-module-app';
-import type { RuntimeEnv } from '@equinor/fusion-framework-cli';
-import {
-  createAppManifestFromPackage,
-  loadAppManifest,
-  loadAppConfig,
-  mergeAppManifests,
-  ApiAppConfigSchema,
-  type AppManifestFn,
-  type AppConfigFn,
-  type ApiAppConfig,
-} from '@equinor/fusion-framework-cli/app';
-import { resolvePackage } from '@equinor/fusion-framework-cli/utils';
-
-/**
- * The application manifest and config resolved for a test run.
- */
-export type AppTestEnv = {
-  manifest: AppManifest;
-  config: ApiAppConfig;
-};
-
-/**
- * Options for {@link resolveAppTestEnv}.
- */
-export type ResolveAppTestEnvOptions = {
-  /** Directory to resolve the package, manifest, and config from. Defaults to `process.cwd()`. */
-  entrypoint?: string;
-  /**
-   * An explicit manifest file to load instead of the default `app.manifest(.*)?` lookup, or a
-   * manifest function (same shape as `defineAppManifest`'s argument) applied directly.
-   */
-  manifest?: string | AppManifestFn;
-  /**
-   * An explicit config file to load instead of the default `app.config(.*)?` lookup, or a
-   * config function (same shape as `defineAppConfig`'s argument) applied directly.
-   */
-  config?: string | AppConfigFn;
-};
-
-/**
- * Resolves an application's manifest and config using the same pipeline `ffc app build`/
- * `ffc app dev` use: a base manifest generated from `package.json`, merged with a local
- * `app.manifest.ts` if one exists; and `app.config.ts` for endpoints/environment, falling
- * back to an empty config if none exists.
- *
- * @remarks
- * 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('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.
- * @throws If no `package.json` can be found from `entrypoint` upward, or an explicitly requested
- * `manifest`/`config` file does not exist.
- * @example
- * ```ts
- * import { resolveAppTestEnv } from '@equinor/fusion-framework-vitest-plugin-react-app';
- * import { testApp } from '@equinor/fusion-framework-vitest-plugin-react-app/test';
- * import { configure } from '../config';
- *
- * const test = testApp
- *   .extend('appEnv', { injected: true }, () => resolveAppTestEnv())
- *   .extend('configureApp', { injected: true }, () => configure);
- * ```
- */
-export const resolveAppTestEnv = async (
-  options?: ResolveAppTestEnvOptions,
-): Promise<AppTestEnv> => {
-  const pkg = await resolvePackage({ cwd: options?.entrypoint });
-  const env: RuntimeEnv = { command: 'build', mode: 'test', root: pkg.root, environment: 'test' };
-
-  const baseManifest = createAppManifestFromPackage(env, pkg.packageJson);
-  const [manifest, config] = await Promise.all([
-    resolveManifest(env, baseManifest, options?.manifest),
-    resolveConfig(env, options?.config),
-  ]);
-
-  return { manifest, config };
-};
-
-/**
- * Loads `app.manifest(.*)?` (or applies an inline {@link AppManifestFn}), falling back to the
- * package-derived manifest when none exists — mirrors `ffc app build`'s own fallback so a test
- * env matches a real build with zero manifest file.
- */
-const resolveManifest = async (
-  env: RuntimeEnv,
-  base: AppManifest,
-  manifest?: string | AppManifestFn,
-): Promise<AppManifest> => {
-  // an inline function is applied directly, the same way a loaded `app.manifest.ts`'s default export would be
-  if (typeof manifest === 'function') {
-    const result = await manifest(env, { base });
-    return mergeAppManifests(base, result ?? {});
-  }
-  try {
-    return (await loadAppManifest(env, { base, file: manifest })).manifest;
-  } catch (err) {
-    // an explicitly requested manifest that's missing is a real error; only the default lookup falls back
-    if (err instanceof FileNotFoundError && !manifest) return base;
-    throw err;
-  }
-};
-
-/**
- * Loads `app.config(.*)?` (or applies an inline {@link AppConfigFn}), falling back to an empty
- * config when none exists — mirrors `ffc app build`'s own fallback so a test env matches a real
- * build with zero config file.
- */
-const resolveConfig = async (
-  env: RuntimeEnv,
-  config?: string | AppConfigFn,
-): Promise<ApiAppConfig> => {
-  // an inline function is applied directly, the same way a loaded `app.config.ts`'s default export would be
-  if (typeof config === 'function') {
-    const result = await config(env, { base: { environment: {} } });
-    return ApiAppConfigSchema.parse(result ?? { environment: {} });
-  }
-  try {
-    return (await loadAppConfig(env, { file: config })).config;
-  } catch (err) {
-    // an explicitly requested config that's missing is a real error; only the default lookup falls back
-    if (err instanceof FileNotFoundError && !config) return { environment: {} };
-    throw err;
-  }
-};
-
-export default resolveAppTestEnv;

package/src/scope/create-app-scope-wrapper.tsx

@@ -1,26 +0,0 @@
-import type { ReactElement, ReactNode } from 'react';
-
-import { FrameworkProvider } from '@equinor/fusion-framework-react';
-import { ModuleProvider } from '@equinor/fusion-framework-react-module';
-import type { AnyModule } from '@equinor/fusion-framework-module';
-
-import type { AppScope } from './resolve-app-scope';
-
-/**
- * The provider nesting `createComponent` uses in production, for wrapping a component or
- * hook under test in its resolved {@link AppScope}.
- *
- * @template TModules - Module descriptors beyond the default set.
- * @param scope - The resolved parent Fusion instance and application module scope.
- * @returns A wrapper component nesting a `FrameworkProvider` around a `ModuleProvider`.
- */
-export function createAppScopeWrapper<TModules extends Array<AnyModule> | unknown = unknown>({
-  framework,
-  app,
-}: AppScope<TModules>): (props: { children: ReactNode }) => ReactElement {
-  return ({ children }: { children: ReactNode }) => (
-    <FrameworkProvider value={framework}>
-      <ModuleProvider value={app}>{children}</ModuleProvider>
-    </FrameworkProvider>
-  );
-}

package/src/scope/default-app-env.ts

@@ -1,13 +0,0 @@
-import type { AppEnv } from '@equinor/fusion-framework-app';
-
-/**
- * The application environment used when a test does not care about its own app identity.
- */
-export const defaultAppEnv: AppEnv = {
-  manifest: {
-    appKey: 'test-app',
-    displayName: 'Test App',
-    description: 'A test application',
-    type: 'standalone',
-  },
-};

package/src/scope/index.ts

@@ -1,4 +0,0 @@
-export { defaultAppEnv } from './default-app-env';
-export { resolveFusion } from './resolve-fusion';
-export { resolveAppScope, type AppScope } from './resolve-app-scope';
-export { createAppScopeWrapper } from './create-app-scope-wrapper';

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

@@ -1,46 +0,0 @@
-import { mockAppModules } from '@equinor/fusion-framework-app/mock';
-import type { AppMockConfigureFn } from '@equinor/fusion-framework-app/mock';
-import type { AppEnv, AppModulesInstance } from '@equinor/fusion-framework-app';
-import type { Fusion } from '@equinor/fusion-framework';
-import type { AnyModule } from '@equinor/fusion-framework-module';
-
-import { resolveFusion } from './resolve-fusion';
-import { defaultAppEnv } from './default-app-env';
-
-/**
- * The parent Fusion instance and resolved application module scope shared by every
- * `packages/react/app` testing helper.
- *
- * @template TModules - Module descriptors beyond the default set.
- */
-export interface AppScope<TModules extends Array<AnyModule> | unknown = unknown> {
-  /** The parent Fusion instance the application scope was resolved against. */
-  framework: Fusion;
-  /** The resolved application module instance. */
-  app: AppModulesInstance<TModules>;
-}
-
-/**
- * Resolves the parent Fusion instance and application module scope shared by every
- * `packages/react/app` testing helper.
- *
- * @template TModules - Module descriptors beyond the default set.
- * @template TEnv - The application environment descriptor.
- * @param options - A `configure` callback and `env` for {@link mockAppModules}, plus an
- *   already-built `fusion` instance to reuse instead of a fresh one.
- * @returns The resolved {@link AppScope}.
- */
-export async function resolveAppScope<
-  TModules extends Array<AnyModule> | unknown = unknown,
-  TEnv extends AppEnv = AppEnv,
->(options?: {
-  configure?: AppMockConfigureFn<TModules, TEnv>;
-  env?: TEnv;
-  fusion?: Fusion;
-}): Promise<AppScope<TModules>> {
-  const { configure, env, fusion: providedFusion } = options ?? {};
-  const resolvedEnv = env ?? (defaultAppEnv as TEnv);
-  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,74 +0,0 @@
-import type { AppEnv } from '@equinor/fusion-framework-app';
-import type { Fusion } from '@equinor/fusion-framework';
-import {
-  mockFramework,
-  type FrameworkMockConfigureFn,
-  type FrameworkMockConfigurator,
-} 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';
-
-/**
- * Enables the feature-flag mock only when `@equinor/fusion-framework-module-feature-flag` — an
- * optional peer dependency — is actually installed, so apps that don't use feature flags aren't
- * forced to install a module they never reference.
- */
-async function enableFeatureFlagMockIfAvailable(
-  configurator: FrameworkMockConfigurator<[AppModule, NavigationModule]>,
-): Promise<void> {
-  try {
-    const { enableFeatureFlagMock } = await import(
-      '@equinor/fusion-framework-module-feature-flag/mock'
-    );
-    enableFeatureFlagMock(configurator);
-  } catch (error) {
-    // re-throw anything other than the optional peer being missing, so a real
-    // registration failure isn't silently swallowed
-    if (
-      error instanceof Error &&
-      (error.message.includes('Cannot find module') || error.message.includes('MODULE_NOT_FOUND'))
-    ) {
-      return;
-    }
-    throw error;
-  }
-}
-
-/**
- * Resolves the parent Fusion instance backing an application module scope, building a
- * fresh {@link mockFramework} instance with this app's own manifest served when none is
- * given.
- *
- * @template TEnv - The application environment descriptor.
- * @param options - `env` seeds the built-in app manifest mock; navigation defaults to in-memory
- *   history, so tests don't leak URL/history state between runs. Feature flags default to the
- *   in-memory feature-flag mock, with none enabled, when the optional
- *   `@equinor/fusion-framework-module-feature-flag` peer dependency is installed. `configure`
- *   runs afterwards on the same configurator — e.g. call `enableNavigation` or
- *   `enableFeatureFlagMock` again to override either, 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>(options?: {
-  env?: TEnv;
-  fusion?: Fusion;
-  configure?: FrameworkMockConfigureFn<[AppModule, NavigationModule]>;
-}): Promise<Fusion> {
-  const { env, fusion, configure } = options ?? {};
-  return (
-    fusion ??
-    mockFramework<[AppModule, NavigationModule]>(async (configurator) => {
-      enableAppManifestMock(configurator, env ?? (defaultAppEnv as TEnv));
-      enableNavigation(configurator, {
-        configure: (config) => config.setHistory(createHistory('memory')),
-      });
-      await enableFeatureFlagMockIfAvailable(configurator);
-      await configure?.(configurator);
-    })
-  );
-}

package/src/test-app.tsx

@@ -1,148 +0,0 @@
-import type { ReactElement } from 'react';
-import { test as baseTest } from 'vitest';
-import { render, renderHook } from 'vitest-browser-react';
-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';
-
-/**
- * `vitest`'s `test`, extended with an application module scope fixture.
- *
- * @remarks
- * An alternative to {@link renderAppComponent}/{@link renderAppHook} for a test file whose
- * 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
- * lazily: a test that only destructures `app` never pays for rendering anything, and one
- * that only destructures `render`/`renderHook` gets the same fixture wiring automatically.
- *
- * Both entry points stay supported: reach for `renderAppComponent`/`renderAppHook` for a
- * 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 }) => {
- *   const screen = await render(<App />);
- *   expect(app.context).toBeDefined();
- * });
- * ```
- *
- * @example Seed a module for every test in a suite
- * ```tsx
- * describe('with a seeded context module', () => {
- *   const test = testApp.extend(
- *     'configureApp',
- *     { injected: true },
- *     (): AppMockConfigureFn =>
- *       (configurator) =>
- *         enableContextMock(configurator, (mock) => mock.setCurrentContext(projectA)),
- *   );
- *
- *   test('starts on the seeded context', async ({ render }) => {
- *     const screen = await render(<App />);
- *     await expect.element(screen.getByText(projectA.title)).toBeVisible();
- *   });
- * });
- * ```
- *
- * @example Type `app`'s registered modules for consumers
- * ```tsx
- * // `configureApp`'s `TModules` generic only types that callback's own `configurator` parameter.
- * // `app`'s type was already fixed (to `unknown`) when the base `testApp` chain defined it, so a
- * // later `configureApp` override does not retroactively change what `app` is typed as. Re-extend
- * // `app` too, with the same `TModules`, to get a typed `app.navigation` in tests.
- * const test = testApp
- *   .extend(
- *     'configureApp',
- *     { injected: true },
- *     ({ configureApp }): AppMockConfigureFn<[NavigationModule]> =>
- *       async (configurator, args) => {
- *         await configureApp?.(configurator, args);
- *         enableNavigation(configurator, '/app');
- *       },
- *   )
- *   .extend('app', ({ configureApp, appEnv, fusion }) =>
- *     mockAppModules<[NavigationModule], AppEnv>(configureApp, appEnv as AppEnv, fusion),
- *   );
- *
- * test('exposes the navigation module', async ({ app }) => {
- *   expect(app.navigation).toBeDefined();
- * });
- * ```
- *
- * @example Extend the parent framework mock with an application module
- * ```tsx
- * const test = testApp.extend(
- *   'configureFusion',
- *   { injected: true },
- *   (): FrameworkMockConfigureFn<[AppModule, NavigationModule]> =>
- *     (configurator) => {
- *       // seed a specific flag rather than merely enabling the mock — that's already the
- *       // default when the optional feature-flag peer dependency is installed
- *       enableFeatureFlagMock(configurator, (mock) => mock.addFeature({ key: 'new-search', enabled: true }));
- *       configurator.serviceDiscovery.addServices([
- *         { key: 'people', uri: baseUrl('people') },
- *         { key: 'context', uri: baseUrl('context') },
- *       ]);
- *     },
- * );
- * ```
- */
-export const testApp = baseTest
-  .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('configureApp', { injected: true }, () => undefined as AppMockConfigureFn | undefined)
-  // Runs after the built-in app manifest/navigation/feature-flag setup, so a test can register
-  // extra framework modules, service discovery entries, or call `enableNavigation`/
-  // `enableFeatureFlagMock` again to override either, 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 });
-    return (ui: ReactElement, options?: Omit<RenderOptions, 'wrapper'>) =>
-      render(ui, { ...options, wrapper });
-  })
-  .extend('renderHook', ({ fusion, app }) => {
-    const wrapper = createAppScopeWrapper({ framework: fusion, app });
-    return <Result, Props = undefined>(
-      cb: (initialProps?: Props) => Result,
-      options?: Omit<RenderHookOptions<Props>, 'wrapper'>,
-    ) => renderHook(cb, { ...options, wrapper });
-  });
-
-export default testApp;

package/src/test.tsx

@@ -1,42 +0,0 @@
-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 as configureApp } from 'virtual:fusion-app-test-configure';
-
-/**
- * `vitest`'s `test`, pre-seeded with the application's own manifest, config, and
- * module-configurator, resolved the same way `ffc app build`/`ffc app dev` resolve them.
- *
- * @remarks
- * Requires `appTestVitePlugin` (`@equinor/fusion-framework-vitest-plugin-react-app`) registered in
- * 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('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
- * import { test } from '@equinor/fusion-framework-vitest-plugin-react-app/test';
- * import { App } from '../App';
- *
- * test('renders the app', async ({ render }) => {
- *   const screen = await render(<App />);
- *   await expect.element(screen.getByRole('heading')).toBeVisible();
- * });
- * ```
- */
-export const test = baseTestApp
-  .extend('appEnv', { injected: true }, { manifest, config })
-  .extend('configureApp', { injected: true }, () => configureApp);
-
-export default test;

package/src/version.ts

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

package/src/virtual-modules.d.ts

@@ -1,12 +0,0 @@
-declare module 'virtual:fusion-app-test-env' {
-  import type { AppEnv } from '@equinor/fusion-framework-app';
-
-  export const manifest: AppEnv['manifest'];
-  export const config: AppEnv['config'];
-}
-
-declare module 'virtual:fusion-app-test-configure' {
-  import type { AppMockConfigureFn } from '@equinor/fusion-framework-app/mock';
-
-  export const configure: AppMockConfigureFn | undefined;
-}

package/tsconfig.json

@@ -1,26 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "jsx": "react-jsx",
-    "outDir": "dist/esm",
-    "rootDir": "src",
-    "declarationDir": "./dist/types",
-    "paths": {
-      "*": ["./*"]
-    }
-  },
-  "references": [
-    { "path": "../../cli" },
-    { "path": "../../framework" },
-    { "path": "../../app" },
-    { "path": "../../modules/module" },
-    { "path": "../../modules/app" },
-    { "path": "../../modules/navigation" },
-    { "path": "../../modules/feature-flag" },
-    { "path": "../../react/framework" },
-    { "path": "../../react/modules/module" },
-    { "path": "../../utils/imports" }
-  ],
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "src/__tests__/**/*"]
-}

package/vitest.config.ts

@@ -1,10 +0,0 @@
-import { defineProject } from 'vitest/config';
-
-import { name, version } from './package.json' with { type: 'json' };
-
-export default defineProject({
-  test: {
-    include: ['src/__tests__/**/*.test.ts'],
-    name: `${name}@${version}`,
-  },
-});