Test journeys through MCP and the API

Use testJourney to check service routes, validation, actions, task lists and completion with disposable User view scenarios. Describe the expected inputs, run cases with assertions, and inspect the returned evidence before making a change ready for review.

Endpoints and access

Use your Builder host, such as https://app.govform.com, rather than a QA or Production service host. Discover testJourney through the connection's tool catalogue before calling it; availability depends on the connected release.

Channel	Endpoint	Access
Interactive OAuth MCP	`POST /builder/mcp` Early access: `POST /builder/early-access/mcp`	Current form-design read access to the selected library and `mcp:read`. Send the connection's Bearer token.
Library API-key MCP	`POST /builder/libraries/{libraryId}/mcp`	`apiDarcyToolRead` or `apiDarcyToolWrite`.
REST direct tool	`POST /builder/libraries/{libraryId}/api/darcy/tools/testJourney`	The same Darcy tool-read or tool-write API-key permission.

Interactive MCP uses JSON-RPC tools/call with name: "testJourney" and arguments containing org and formId. API-key MCP selects the library in the URL and requires formId in the arguments. REST accepts the arguments directly, or wrapped in { "input": { ... } }. API-key requests use Authorization: GovformsApiKey <key-id>:<key-secret> or GovformsApiHmac; send JSON with Content-Type: application/json.

This is a read-only tool. It needs no respondent-data permission, mutation approval or expectedSsId. Each successful call uses 1 API unit through the existing shared capacity limits.

Which service version is tested

MCP and REST test the latest saved Builder service in the selected library. They do not inherit an open browser journey or Darcy's unsaved edits. Darcy in the Builder can test its current session draft separately.

The result identifies tested.source: "saved", org, formId, ssId, versionNum and definitionFingerprint. Compare the returned ssId with the saved version under review and rerun after edits. The tool creates no saved respondent journey, sends no real integration request or message, and does not audit simulated events. Normal API accounting still applies.

Describe inputs and mocks

Start with mode: "describe". Use exact page, field or action IDs discovered from the service; the following IDs are illustrative.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "testJourney",
    "arguments": {
      "org": "example",
      "formId": "apply",
      "mode": "describe",
      "pageIds": [
        "aboutYou"
      ]
    }
  }
}

describe returns answer shapes, choice IDs, repeat membership, action fixture kinds, PDF mappings and valid examples. With no selectors it gives a page overview. Optional pageIds, fieldIds and actionIds accept up to 100 IDs each. These selectors apply only to describe; scenarios, defaults, output and limits apply only to run.

Run scenarios with assertions

mode: "run" is the default. Every scenario needs an id. Derive a complete positive case, alternative branches and relevant blank, invalid or boundary cases from the service requirements. Include assertions: a run without them cannot verify a journey.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "testJourney",
    "arguments": {
      "org": "example",
      "formId": "apply",
      "scenarios": [
        {
          "id": "positive",
          "answers": {
            "fullName": "Alex Example"
          },
          "assertions": [
            {
              "kind": "completed",
              "value": true
            }
          ]
        },
        {
          "id": "required-name",
          "answers": {
            "fullName": ""
          },
          "assertions": [
            {
              "kind": "validationFailure",
              "fieldId": "fullName"
            }
          ]
        }
      ]
    }
  }
}

Input	Use
`answers`	Field ID to respondent value, entered when first shown on a submitted page. Omit to keep the shown value; use an empty string or array to submit blank. Use actual choice IDs and the compound value shapes returned by describe.
`repeatRows`	Repeating group ID to row objects, as an alternative to per-field arrays. Include differing rows when checking repeated questions.
`steps`	Ordered page interventions for validation retries, changed answers, back links, task selection and supported controls. Repeat indexes are zero-based; page visits and action invocations are one-based.
`mocks.actions`	Action fixtures or per-invocation sequences: HTTP responses, transport errors, Connector scenarios, result objects, feed rows, document or email outcomes. Use describe for the action's actual shape. A skipped action consumes no sequence entry.
`defaults`	Shared batch inputs/settings, replaced by scenario overrides. Each scenario has fresh state and mock counters.
`output`	`detail: "trace"` adds bounded runtime events; `values` selects context paths. Honour truncation notices and request targeted evidence.

Configured service mocks are used by default. Set mocks.missing: "needsMock" to require explicit external fixtures. Supply the step or fixture requested by a needsInput or needsMock result, then rerun.

Interpret the result

The direct-tool response keeps its ordinary envelope:

{
  "success": true,
  "toolName": "testJourney",
  "mutatesForm": false,
  "form": null,
  "result": {
    "mode": "run",
    "tested": {
      "source": "saved",
      "org": "example",
      "formId": "apply",
      "ssId": "saved-snapshot-id",
      "versionNum": 7,
      "definitionFingerprint": "example-fingerprint"
    },
    "summary": {
      "scenarios": 2,
      "passed": 2,
      "failed": 0,
      "incomplete": 0,
      "notAsserted": 0
    },
    "scenarios": []
  },
  "validationErrors": []
}

The example above abbreviates the scenario evidence. MCP wraps the same envelope in its tool content. Each returned scenario separates execution.status (what happened, such as completed, validationStopped or needsMock) from verdict (what the assertions established).

Verdict	Meaning
`passed`	The supplied assertions passed for the supported scenario. Inspect route, validation and action/mock evidence before reporting coverage.
`failed`	An assertion did not match. Investigate the service behaviour and the expectation.
`incomplete`	The requested evidence could not be fully established. Resolve missing inputs, mocks, unsupported behaviour or limits.
`notAsserted`	No assertions were supplied. The run is observation, not verification.

A successful tool call is not automatically a passed journey. Read every scenario, not just the batch success flag.

Limits and separate checks

A batch accepts at most 20 scenarios, 100 steps and 100 assertions per scenario, and 50 repeated rows. Services support up to 200 pages and 2,000 fields. Transitions default to 200 per scenario, with a maximum of 500. The whole-request timeout defaults to 20 seconds, with a maximum of 25 seconds. Reduce a batch or its scope when a limit is reached.

A pass covers only the supplied cases and supported User view server behaviour. Browser rendering, visual PDF placement, real integrations, payments, reviewer decisions and background workflow actions need separate browser or authorised QA checks. Calculated Flow does not execute a respondent journey. Report missing evidence when a tool is unavailable or a case is unsupported.