Simulate a path through a form
simulate_pathRun a headless Formhaus form to test branching, routes, skips, and conditional fields by stepping through it like a user. Returns the active path, action trace, validation errors, and submit payload.
Instructions
Call this after validate_definition passes, to check branching, routes, skip and conditional fields by stepping through the form like a user; validate_definition checks only the structure. Runs a headless FormEngine. answers are applied as initial values; a group answer is an array of item objects, such as { "participants": [{ "name": "Ada" }] }. Then actions are pressed in order like a user would: next is refused while its disabled conditions match and on next: false steps until an autoAdvance radio is answered, skip only works on steps with a skip action and submits on the last step. Without actions it presses Next until the last step or a blocking error. Custom validators, onStepValidate and lifecycle hooks are not run. When the definition has errors, returns ok: false and the same validation issues as validate_definition. Otherwise returns the active step path (visited, skipped, visible fields, with item fields as paths such as participants.0.email), a trace of each action with errors or a reason when it did not move, validation errors for visited steps only, wouldSubmit (false while submit is disabled) and the submit payload. Pass overlay to run the form in a translated language; overlayIssues lists overlay entries that were ignored or do not match the source.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| actions | No | Buttons to press in order, each "next", "back" or "skip". Omit to press Next until the last step or the first blocking error. | |
| answers | No | Field values keyed by field key, applied as initial values before the actions, such as {"email": "ann@example.com", "plan": "pro"}. select, radio and multiselect take option values, not labels. Omit to start with an empty form. | |
| overlay | No | Translation overlay for one language: the overlay from translation_template with its values translated. Applied before the run, so labels and errors come out in that language. Omit to run in the source language. | |
| definition | Yes | Formhaus form definition as a JSON object or a JSON string. JSON Schema: https://formhaus.dev/schema/form-definition.json. Top level: id, title, submit { label }, and fields (one step) or steps [{ id, title, fields }]. Field: { key, type, label, validation?, options?, show?, showAny? }. Rules go inside "validation": { required, minLength, maxLength, min, max, pattern, matchField }. Condition: { field, eq | neq | in | notIn | notEmpty | gt | gte | lt | lte } with exactly one operator, on a field of the same or an earlier step. Optional: lang, messages and labels catalogs, and i18n objects that map texts to translation keys. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | ||
| path | No | ||
| trace | No | ||
| errors | No | Errors by field key, or by item path such as participants.0.email. | |
| multiStep | No | ||
| isLastStep | No | ||
| validation | Yes | ||
| currentStep | No | ||
| wouldSubmit | No | ||
| submitValues | No | ||
| overlayIssues | No | Overlay entries that were ignored or do not match the source. |