Validate and Test

Validation should happen before every deployment and, ideally, before every commit. WOML validates more than XML shape: it checks the workflow graph, references, modules, workflow-call targets, provider contracts, and the compiled model Rust will execute.

Validate without running anything

woml check workflow.woml
woml check workflows/ --json

check performs the safe authoring pipeline:

1. Parse the WOML document while preserving source locations and raw scripts.
2. Validate elements, attributes, IDs, references, schemas, and graph structure.
3. Resolve imported modules and reusable definitions.
4. Lower workflows into the versioned compiled model.
5. Validate known synchronous workflow-call targets across the supplied deployment.
6. Refresh the default woml-env.d.ts declarations for editor support.

It does not execute scripts, connect providers, open trigger ports, send notifications, or create runs. That makes it safe for editor tasks and CI.

Validate the complete deployment

If workflows call one another, validate them together:

woml check workflows/
woml check order-api.woml calculate-risk.woml

Directories load their direct .woml files non-recursively. A deployment-level check can catch a missing services.workflows.call() target that checking one file alone cannot.

Use production configuration during preflight:

woml check workflows/ --config woml.runtime.json

This adds listener, storage, configuration, and referenced-secret checks without opening the runtime.

Execute one occurrence and exit

woml test workflow.woml

test executes one manual trigger occurrence and exits after it reaches a terminal outcome. Use it when a test runner or CI job needs a finite command. It uses the real engine, so it is an integration test rather than a lightweight syntax check.

For everyday automation, use woml run: triggers such as webhook, schedule, Slack, and event need a living host. Use test only when one manual occurrence is the intended unit.

Understand failures

A good diagnostic tells you the stable code, the file, and the exact line and column:

WOML validation error [WOML_UNKNOWN_ELEMENT] at workflow.woml:18:5:
Unknown WOML element <on-finish>.

Fix the first structural error first; later errors can be consequences. In CI, use --json and preserve diagnostic codes rather than matching human messages.

Refresh declarations

woml types workflows/ --output woml-env.d.ts

check and run already generate the default file; use types only for explicit refresh or a custom path.

You do not need to run types before every .js module edit. The normal workflow is:

woml check workflows/

That validates the files and keeps editor declarations synchronized in one command.