# Test

> Trigger a deployed BorgIQ flow with a sample payload, wait for it to complete, and report pass/fail with the final actor output. Does NOT deploy.

- Skill: `borgiq/test` (Agent Skill)
- Install (CLI): `npx skillmds@latest add borgiq/test`
- Raw SKILL.md: https://api.skillmd.com/api/skills/borgiq/test/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: BorgIQ (https://skillmd.com/u/borgiq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/borgiq/test

---


# /test — trigger a flow and assert on the result

Run a flow end-to-end against a deployed canvas, poll until completion, and report whether it produced the expected output. This is for verifying that a deployed flow actually works — not for deploying. Use `/borgiq-builder:deploy` first.

> **On a deployed workspace, every run — `borgiq triggers run` and editor test runs alike — executes
> the canvas's active runtime build, not its current code.** If the flow was edited since the last
> build, this tests the OLD code and the result will not reflect your changes; a canvas with no fully
> successful build fails with "No built runtime available". Build the canvas first
> (`borgiq canvases runtime-build <canvas>` — it waits for the build). Check with
> `borgiq workspaces deployment --json`; a canvas showing `outdated: true` is exactly this situation.

## Parse arguments

Accepted forms:

- `/borgiq-builder:test <canvasId> <triggerActorId> '{"key": "value"}'`
- `/borgiq-builder:test <canvasId> <triggerActorId> --fixture <path-to-payload.json>`
- `/borgiq-builder:test` (no args) — ask which canvas and trigger to use; default the payload to `{}`

If only the canvasId is given, list triggers in that canvas and ask the user which to fire:

```bash
borgiq canvases get <canvasSlugOrId> --json   # inspect triggers
```

## Trigger the flow

```bash
borgiq triggers run --canvas <canvasId> --actor-id <triggerActorId> --payload '<json>' --json
```

Capture the `flowrunId` from the response.

## Wait for completion

Poll until the flowrun reaches a terminal state. Don't loop in a `sleep` block — use `borgiq flowruns watch` if available, otherwise poll with reasonable backoff (3s, 5s, 10s):

```bash
borgiq flowruns status <flowrunId> --json
```

Terminal states are `Completed`, `Failed`, `Cancelled`. See `${CLAUDE_SKILL_DIR}/../borgiq-builder/references/flowrun-job-states.md` for the full state machine.

## Report the result

Once terminal, pull the summary:

```bash
borgiq flowruns summary <flowrunId> --json
```

Then assert based on the user's intent:

- If the user supplied an expected output shape, compare against it.
- If not, report what the final actor emitted and let the user judge.
- For `Failed` flowruns, surface the failing actor's `runtime-data` and the error message:
  ```bash
  borgiq flowrun-jobs runtime-data <jobId> --root-path inputs --json
  borgiq flowrun-results summaries --job-id <jobId> --json
  ```

## Exit summary

End with a clear PASS / FAIL line, plus:

- The flowrunId (so the user can re-inspect later)
- A one-line summary of what each actor emitted (or where it failed)
- If FAIL, suggest `/borgiq-builder:debug-flow <flowrunId>` for deeper inspection