Testing with the SDK

Getting Started

Automated tests need to put the mocked world into a known state before they run: this user exists, that feature is on, the next payment fails. @mocko/sdk does exactly that from TypeScript or JavaScript, by reading and writing the same flags your mock templates use.

Install

$npm install -D @mocko/sdk

Requires Node.js 20 or newer.

The SDK has zero runtime dependencies. Nothing else enters your lockfile, there is no transitive tree to audit, and no surprise findings in SAST, SBOM, or npm audit pipelines. In organizations where every new dependency needs a security review, that means one small package to approve, once.

Set up the client

Create one client for the Mocko instance your tests run against, typically in a shared test fixture module:

import { MockoClient } from '@mocko/sdk';

export const mocko = new MockoClient('http://localhost:8080');

The URL must point at the mock server (core, port 8080 by default), not at the control panel. The SDK talks to the same server your application requests hit.

Reading and writing flags

The raw flag methods cover ad-hoc state. Values are serialized as JSON, so strings, numbers, booleans, arrays, and objects all work:

await mocko.setFlag('users:123:status', 'active');

const status = await mocko.getFlag<string>('users:123:status');

await mocko.setFlag('users:123:profile', {
  status: 'active',
  roles: ['admin', 'reviewer'],
});

await mocko.deleteFlag('users:123:status');

getFlag returns undefined when the flag does not exist, which is also what your templates see as a missing value.

A complete test

The pattern that makes this useful: the test arranges state through the SDK, the mock template reacts to it, and the system under test never knows the difference. Given this mock:

mock "GET /users/{id}" {
  format = "json"
  body = <<-EOF
    {{= $statusKey (append 'users:' request.params.id ':status')}}
    {
      "id": {{request.params.id}},
      "status": "{{default (getFlag $statusKey) 'active'}}"
    }
  EOF
}

a test can drive both sides of the scenario:

import { mocko } from './fixtures/mocko';

it('locks out suspended users', async () => {
  await mocko.setFlag('users:123:status', 'suspended');

  const response = await app.login('123');

  expect(response.status).toBe(403);
});

Flags written by templates with setFlag are readable through the SDK too, so assertions can also inspect state your mocks accumulated during the test.

Behavior details

Flags written through the SDK get a default TTL of 300 seconds, so leftover test state expires on its own instead of leaking into later runs. TTLs are configurable per client, per definition, and per write; see Flag Definitions.
On shared instances, prefix keys per run (a worker id or a random suffix) to keep parallel test runs isolated, since flags are instance-wide.
The SDK talks to a small, stable HTTP API on the mock server, so it works against any run mode: CLI, containers, or a cluster deployment.