@sensigo/realm-testing

@sensigo/realm-testing — testing utilities for Realm workflows. Use this package to write unit and integration tests against your workflow definitions without making real service calls or writing to disk.

Installation

npm install --save-dev @sensigo/realm-testing

Requires @sensigo/realm at the same version to be installed in your project.

Usage — YAML Fixture Tests

Fixture tests are the fastest way to test a complete workflow. Each fixture file declares the initial params, mock service responses, agent step outputs, and the expected final state. The runFixtureTests runner loads your workflow, drives it to completion using the fixture data, and returns a result for each fixture.

// workflow-test.ts
import { describe, it, expect } from 'vitest';
import { runFixtureTests } from '@sensigo/realm-testing';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

describe('my-workflow fixtures', async () => {
  const results = await runFixtureTests({
    workflowPath: path.join(__dirname, '../my-workflow'), // accepts workflow.yaml path OR its containing directory
    fixturesPath: path.join(__dirname, '../my-workflow/fixtures'),
  });

  for (const result of results) {
    it(result.name, () => {
      expect(result.passed, result.error).toBe(true);
    });
  }
});

Usage — Programmatic Tests

Use programmatic tests when you need fine-grained control over a single step, a specific execution path, or assertions on individual evidence entries.

import { describe, it, expect } from 'vitest';
import { InMemoryStore, assertFinalState } from '@sensigo/realm-testing';
import { loadWorkflowFromFile } from '@sensigo/realm'; // NOTE: from @sensigo/realm, not @sensigo/realm-testing
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

describe('my-workflow programmatic', () => {
  it('run reaches expected final state', async () => {
    const store = new InMemoryStore();
    const definition = await loadWorkflowFromFile(
      path.join(__dirname, '../my-workflow/workflow.yaml'),
    );
    const run = await store.create({
      workflowId: definition.id,
      workflowVersion: definition.version,
      params: { input: 'hello' },
    });

    // drive the run to completion first — see examples/02-ticket-classifier/ for a full test
    assertFinalState(run, 'completed');
  });
});

API Reference

Store

| Symbol | Description | | --------------- | --------------------------------------------------------------------------------------- | | InMemoryStore | In-memory RunStore implementation. No I/O, no locking. Safe to use in parallel tests. |

Fixtures

| Symbol | Description | | ----------------------- | -------------------------------------------------- | | loadFixtureFromFile | Load a single fixture from a .yaml file path. | | loadFixtureFromString | Parse a fixture from a YAML string. | | loadFixturesFromDir | Load all *.yaml fixtures from a directory. | | TestFixture | Type — a parsed fixture object. | | MockOperations | Type — the mock service call map within a fixture. |

Mocks

| Symbol | Description | | ----------------------- | -------------------------------------------------------------------------------- | | MockServiceRecorder | Records adapter calls for later assertion. | | createAgentDispatcher | Creates a dispatcher that returns fixture-defined agent step outputs. | | createGateResponder | Creates a gate responder that auto-resolves gates using fixture-defined choices. |

Assertions

| Symbol | Description | | --------------------- | -------------------------------------------------------------- | | assertFinalState | Assert the run reached a specific terminal state. | | assertStepSucceeded | Assert a named step completed without error. | | assertStepFailed | Assert a named step is in the failed steps list. | | assertStepOutput | Assert the output of a completed step matches a value. | | assertEvidenceHash | Assert the evidence hash for a step matches an expected value. |

Unit test helpers

| Symbol | Description | | ----------------- | -------------------------------------------------------------------- | | testStepHandler | Run a single step handler in isolation and return its output. | | testProcessor | Run a processor function against a run record and return the result. | | testAdapter | Invoke an adapter operation and return the ServiceResponse. |

Runner

| Symbol | Description | | ------------------------ | --------------------------------------------------------------------------------------- | | runFixtureTests | Drive a workflow to completion for all fixtures in a directory. Returns TestResult[]. | | RunFixtureTestsOptions | Type — options for runFixtureTests (workflowPath, fixturesPath, registry?). | | TestResult | Type — result of a single fixture run (name, passed, error?). |

Servers

| Symbol | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | startGitHubMockServer | Integration testing helper for workflows that use the GitHub adapter. See the examples/08-pr-review/ example for usage. | | GitHubMockServerHandle | Type — handle returned by startGitHubMockServer (url, close()). |

Full documentation

Full documentation: https://github.com/sensigo-hq/realm