Mock Server Command

8/31/26Less than 1 minute

@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'],
  },
}));

Command-line arguments override config defaults. path is relative to the project root.

Tips

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

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'],
    }),
  ],
}));

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.

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.

License

ISC