feat(cli): add zigflow test one-shot workflow runner - #595

Summary

• Add zigflow test to validate a workflow file, run it once against Temporal with JSON input, print the result, and exit with a non-zero code on failure (#304).
• Introduce pkg/testrunner and cmd/run/session.go for a short-lived in-process worker on the fixed zigflow-test task queue (separate from document.taskQueue used by zigflow run).
• Serialise concurrent test runs per Temporal address and namespace with a file lock so workers do not steal tasks for workflows they have not registered.
• On failure, print structured output when available (for example OWS errors from raise) plus an error line and Temporal UI inspect link.
• Document usage in the CLI and testing guides; add e2e coverage and manual concurrency fixtures under examples/test-concurrency.

Design decisions (discovered while implementing this feature, thus not present in #304)

These choices came out of implementation and e2e testing, not from the original issue text alone.

Fixed zigflow-test task queue (v1)

zigflow test always registers workers and starts workflows on zigflow-test, ignoring document.taskQueue in the YAML for this command. That keeps test runs off the same queue as long-lived zigflow run workers, so a dev server with zigflow run up does not need to be stopped to try a workflow once. v1 prioritises predictable local/CI behaviour over honouring the file’s queue name; overriding via registrationTaskQueue in runOptions is the internal hook if we extend this later.

Cross-process file lock on zigflow-test

Multiple zigflow test processes can connect to the same Temporal server and namespace. Each process registers only its own workflow type on the shared zigflow-test queue. Temporal does not guarantee that a poll goes to a worker that registered that workflow, so concurrent tests can fail with “workflow type not registered” style errors.

The lock is keyed by Temporal address + namespace (file under the user cache dir). It serialises who may poll zigflow-test at a time for that pair. Different namespaces or servers do not block each other. This is process-level coordination, not an in-memory mutex inside one binary.

Reuse zigflow run worker startup via StartSession

StartSession builds runOptions and calls the same prepareRegistrations, initTemporalClient, and startInitialWorkers path as zigflow run, without watch mode or signal handling. That avoids duplicating worker registration, codec, and external storage wiring. Test-specific behaviour is limited to flags on runOptions (below).

skipScheduleUpdates for test sessions

Schedule reconciliation (UpdateSchedules) is appropriate for long-lived zigflow run deployments. A one-shot test should not create or mutate Temporal schedules for the workflow under test. Test sessions set skipScheduleUpdates: true.

skipClientMetrics and Prometheus (Temporal client metrics only)

zigflow run enables Temporal SDK client metrics via temporal.WithPrometheusMetrics(..., nil). A nil registry uses Prometheus’s process-wide default registerer. Each call creates a new reporter that registers the same metric names again.

That is fine for one initTemporalClient per process (zigflow run). It breaks when several short-lived sessions run in the same process: central e2e (go test in one binary), multiple StartSession calls, or unit tests that invoke initTemporalClient without skipping metrics. The second registration collides on the default registry (helpers/Tally behaviour; see zigflow/helpers Prometheus tests).

Test sessions therefore set skipClientMetrics: true. Workers in Zigflow do not currently set worker.Options.MetricsHandler, so this is not a client-vs-worker double registration inside one session; it is repeated client setup in one process.

We did not adopt a process-wide shared PrometheusHandler or per-session prom.NewRegistry() in this PR: zigflow test does not expose a stable metrics scrape target, and sharing would need explicit refcount/Close() lifecycle. Skipping client metrics for test is the smallest correct fix. initTemporalClient unit tests also set skipClientMetrics: true so the cmd/run package’s go test does not hit the same collision.

zigflow run behaviour is unchanged (metrics still enabled once per process).

No “non-local Temporal” warning

Earlier feedback on #304: do not warn when the Temporal address does not look “local”. Cloud, in-cluster, and custom endpoints are all valid for zigflow test; guessing locality is misleading.

Failure output and e2e assertions

Failed runs print workflow output when the SDK returns it (useful for raise and OWS-shaped errors), plus the error and a Temporal UI history link. E2e assertions for the failure path were relaxed to match ApplicationError shape rather than assuming a specific string in the CLI error line alone.

Test plan

• go test ./pkg/testrunner/... ./cmd/...
• go test ./...
• task e2e (central e2e including TestE2EZigflowTest and TestE2EZigflowTestFailed)
• Manual: temporal server start-dev, go run . test examples/hello-world/workflow.yaml --input examples/hello-world/test-input.json
• Manual: failure path with go run . test examples/raise/workflow.yaml
• Manual: concurrent slow/fast fixtures under examples/test-concurrency/ to verify lock serialisation