@equinor/fusion-framework-cli-plugin-mock-server

Optional Fusion Framework CLI plugin for running local OpenAPI-backed services with ffc mock-server. Use it when development or browser tests need deterministic APIs, an unavailable backend, or a service that has not entered Fusion service discovery yet.

[!IMPORTANT] The command runs a standalone foreground HTTP server. It never fetches remote service discovery and never starts automatically with ffc app dev.

Quick start

Install the plugin:

pnpm add -D @equinor/fusion-framework-cli-plugin-mock-server

Create one executable module per service:

mocks/
  inventory.mock.ts
  inventory.openapi.json

import schema from './inventory.openapi.json' with { type: 'json' };
import { defineService } from '@equinor/fusion-openapi-mock-server/discovery';

export default defineService({
  key: 'inventory',
  serviceDiscovery: 'new',
  schema,
  components: {
    InventoryItem: { name: () => 'Local item' },
  },
});

This file is the service mock. Do not duplicate the service in dev-server.config.ts with api.routes or api.processServices; those low-level hooks are not required for the normal mock workflow.

'new' models a pre-production service and rejects collisions if the key becomes registered. See Choose a discovery mode for existing services, pre-production services, and direct-only app endpoints.

Start the server manually:

ffc mock-server

Installing the package makes the command available through the Fusion CLI. If the plugin is not installed, ffc mock-server prints an installation hint. Explicit mockServerPlugin() registration remains useful when fusion-cli.config.ts supplies command defaults.

Credentialed mock-auth requests from canonical loopback origins (localhost, 127.0.0.1, and [::1]) are allowed on every port. Use repeatable --allow-origin options only for non-loopback app or portal origins. Ordinary mock API responses remain available through non-credentialed CORS.

[!WARNING] This treats all local web servers as one development trust boundary. The mock server must issue unsigned test tokens only and must never be connected to real credentials or production services.

Connect an application

Keep the mock server running, then choose one app-development mode in another terminal:

# Keep real discovery and overlay selected local definitions
ffc app dev

# Use only bundled presets and local mock definitions
ffc app dev --mock http://localhost:4010

The standalone server uses only configured presets and local modules. --mock therefore gives an isolated environment with no remote discovery dependency.

[!WARNING] ffc app dev --mock does not fall back to real service discovery. Include every service the app needs through a preset or local mock module.

See Develop with mock services for discovery modes, direct-only endpoints, and the difference between normal and isolated development.

Configure defaults

The plugin augments DevServerOptions with a typed mockServer section. Import its types in dev-server.config.ts so TypeScript loads the augmentation:

import type {} from '@equinor/fusion-framework-cli-plugin-mock-server';
import { defineDevServerConfig } from '@equinor/fusion-framework-cli';

export default defineDevServerConfig(() => ({
  mockServer: {
    path: 'mocks',
    host: 'localhost',
    port: 4010,
    seed: 42,
    allowedOrigins: ['https://preview.example.test'],
    helpDocs: '../docs/my-app',
    analytics: { seed: ['recordings/analytics.jsonl'] },
  },
}));

Command-line arguments override config defaults. path, helpDocs, and analytics paths are relative to the project root.

[!TIP] Put shared team defaults in dev-server.config.ts; reserve command-line flags for temporary local or CI overrides.

Register the plugin explicitly when command defaults belong in fusion-cli.config.ts:

import { defineFusionCli } from '@equinor/fusion-framework-cli';
import mockServerPlugin from '@equinor/fusion-framework-cli-plugin-mock-server';

export default defineFusionCli(() => ({
  plugins: [
    mockServerPlugin({
      preset: ['fusion'],
      port: 4010,
      allowedOrigins: ['https://preview.example.test'],
    }),
  ],
}));

Serve local help articles

ffc mock-server serves help article and FAQ markdown files (the same frontmatter files fhelp syncs to the Fusion Help service) as a local help service. The dev portal then opens the article an app requests with useHelpCenter().openArticle(slug), so help wiring can be tested in Playwright.

Without configuration, the command auto-detects ./docs (or ./docs/articles) and docs/<appKey> in parent folders up to the repository root, and logs the folder it serves. When no articles are found, nothing changes. Set mockServer.helpDocs or --help-docs <dir> to choose a folder, or helpDocs: false / --no-help-docs to turn it off.

See Test help articles locally for article frontmatter, test ids, and troubleshooting.

Receive and check analytics

ffc mock-server receives the analytics a Fusion app sends, as a mock monitor service, and reads them the same way Fusion's analytics pipeline does. It also answers the Apps service's POST /apps/feature-events/query with those events, so analytics pages show your own local usage.

• Every batch is appended to .fusion-mock/analytics.jsonl, one entry per line. The folder gets a .gitignore so recordings are not committed by accident. Choose another file with analytics.record or --analytics-record <file>, or keep events in memory only with record: false or --no-analytics-record.
• Load earlier recordings, gzipped logs_*.json.gz landing-zone files, or folders of them at start with analytics.seed or --analytics-seed <path>. A recording from one run can be the seed for the next.
• Tests read, wait for, and clear events with createMockAnalytics() from @equinor/fusion-openapi-mock-server.
• analytics: false or --no-analytics turns it off. A local monitor.mock.ts that is not a merge layer replaces the analytics mock.

The startup log shows where analytics are recorded and how many seeded events were loaded. See Test analytics locally.

Command reference

ffc mock-server [dirs...] [options]

| Argument or option | Behavior | | --- | --- | | [dirs...] | Directories of <name>.mock.ts modules in ascending precedence. Later definitions are resolved by service key and discovery mode. | | --preset <name> | Bundled preset layered before local directories. Repeatable; defaults to fusion. The first explicit flag replaces the default. | | --port <port> | Listening port. Uses config, then plugin defaults, then 4010. | | --host <host> | Bind hostname. Uses config, then plugin defaults, then localhost. | | --seed <seed> | Deterministic seed for generated OpenAPI responses. Without a seed, generated values are random. | | --allow-origin <origin> | Additional exact non-loopback browser origin allowed to call credentialed mock-auth endpoints. Repeat for multiple app origins. | | --help-docs <dir> | Help docs folder served as the local help service. Overrides mockServer.helpDocs and auto-detection. | | --no-help-docs | Do not serve local help articles, even when a help docs folder is configured or detected. | | --analytics-record <file> | JSON Lines file received analytics are appended to. Overrides mockServer.analytics.record; defaults to .fusion-mock/analytics.jsonl. | | --no-analytics-record | Keep received analytics in memory only. | | --analytics-seed <path> | Recording, landing-zone file, or folder loaded at start. Repeatable; overrides mockServer.analytics.seed. | | --no-analytics | Do not receive analytics or answer the app-feature events query. |

The process shuts down on SIGINT and SIGTERM. Let Playwright webServer, concurrently, or a developer terminal own it instead of starting an unowned background process.

Related documentation

• OpenAPI mock-server getting started
• Testing with Playwright
• Test help articles locally
• Test analytics locally
• Mock API and Playwright cookbook

License

ISC