test

# Test Workflow Skill

Guides a maker through debugging a Power Automate cloud flow (workflow) behind their agent — exercising it, reading its per-action run history, localizing a fault to a specific action, and fixing the flow (or the template config it reads).

**You do not drive a flow directly from this skill.** An ESS flow is triggered by Copilot Studio — a topic calls it — so you exercise it one of two ways (below) and then read the decisive surface: the **run history**, action by action. The bot reply tells you what the user saw; the flow source tells you what was authored; only the run-action view tells you what actually happened.

## The debug-and-validate loop

Debugging a flow is one loop, repeated until the run is clean:

1. **Identify the flow** — the workflow folder and its `workflowId` (the flow GUID).
2. **Exercise it** — in **isolation** (Power Automate manual Test with direct inputs) or **in context** (drive the topic that calls it). Isolation tells you if the fault is in the flow itself; in-context tells you if the fault is in how the topic calls it.
3. **Read the run history** — `flow_run_inspect.py` dumps the per-action cascade. This is read-only and the decisive "why" surface.
4. **Localize the fault** — the first `Failed` action + its statusCode, the scope-vs-handler trap, the skipped branch — then map the action name back to `workflow.json`.
5. **Fix the flow** — through the `workflows/update` skill (edit the local working copy **and** push), or fix the **template config** the orchestrator reads. Never hand-patch the deployed flow.
6. **Re-exercise** until the cascade is clean.

**The one invariant:** inspection is read-only; every fix lands in the **flow definition or its template config**, applied through `workflows/update` so the local working copy and the live environment stay in sync. A flow's output shape is a contract the calling topic consumes — don't change `Respond_to_Copilot` outputs or `workflowId` without checking the topic that depends on them.

## Rules

- **Read-only inspection.** `flow_run_inspect.py` only GETs run history — it never invokes, patches, or deletes a flow. The only mutation path is a fix applied via `workflows/update`.
- **Exercise before you inspect.** Run history only exists after the flow has run. If there is no recent run, exercise the flow first (isolated or in-context), then inspect — and allow a few seconds for eventual consistency.
- **A `Succeeded` handler is not a `Succeeded` flow.** Read scope status, not just handler status (see the interpretation reference). This is the trap that masks a connector 400 as a generic 500.
- **TRACK PROGRESS.** Use the todo list tool to track the loop so the maker can see where you are.

## Identify the flow

Record anonymous usage telemetry (best-effort, non-blocking — no user-facing
message, and it never fails the step): `python scripts/emit_capability.py workflow_test`

Read `.local/config.json` for `agent.folder` and `agent.slug`. List the workflow folders under `{agent.folder}/workflows/` — each holds a `metadata.yml` (with `workflowId`, `name`) and a `workflow.json`. Match the user's request to a folder by name or `metadata.yml` display name; if ambiguous, list them and ask. The **flow GUID** you pass to the inspector is `workflowId` from that `metadata.yml`.

## Exercise the flow

Pick the mode by the question you're answering:

- **Isolated — is the fault in the flow itself?** Have the maker open the flow in Power Automate (make.powerautomate.com → the agent's environment → Solutions → the solution containing the flow), open it, and click **Test → Manually**, supplying the inputs the flow's trigger expects. This removes the topic from the picture — a failure here is purely the flow (or the backend it calls).
- **In context — is the fault in how the topic calls it?** Drive the topic that invokes the flow with the `topics/test` skill (`scripts/drive_topic.py`). This exercises the real request the topic builds and passes in. Use this when the flow tests clean in isolation but the topic still misbehaves.

Either way, the flow produces a run you then inspect.

**Exercise the failure inputs, not just the happy path.** By default, drive the flow with a **set** of inputs that includes its error conditions — a **missing record** (an id/key that doesn't exist), an **unauthorized / needs-consent** call, and a **malformed / out-of-range** input the connector rejects — alongside the valid request. These are the runs where the scope-vs-handler trap below actually bites, and they are the ones skipped when testing by hand. Derive them from the flow's trigger inputs and the scenario's template config; run the failure inputs first.

## Read the run history (the decisive surface)

Dump the latest run's action cascade:

```
python scripts/flow_run_inspect.py --flow <workflowId>
```

The **environment id** is resolved automatically from the active agent's Dataverse org URL — pass `--environment <env-guid>` only to override. The tool acquires a Flow-scoped token automatically via the kit's sign-in (set `FLOW_API_TOKEN` only to bring your own). Add `--run <run-guid>` to inspect a specific earlier run instead of the latest.

Interpret the cascade with **`src/reference/ess-docs/operations/flow-run-inspection.md`** — read it before drawing a conclusion. The essentials:

- **The first `Failed` action is usually the real fault**; everything after it is fallout. Its **statusCode** localizes why — `400` bad request body, `401`/`403` auth/consent, `404` wrong table or missing record, `429`/`5xx` throttling or transient backend.
- **A `Failed` scope with a `Succeeded` catch handler** commonly routes to a catch-all Response that returns a generic 500 and discards the handler's error body — so the user's "something went wrong (500)" is often a masked 400. Look at scope status, not just handler status.
- **`Skipped` actions show the path not taken** — a skipped success branch alongside a run error branch confirms the flow took its failure path.

## Localize and fix

Map the failing action's `name` back to `workflow.json` and compare the intended path to the actual path — the gap is the bug. Then fix at the right layer:

- **Bad request body (a `400` from the orchestrator's connector call)** — for the ESS common-orchestrator flows, the request is built from a **template config** read by `scenarioName`, not hardcoded in the flow. A missing or mis-mapped field is usually a template-config fault, not a `workflow.json` fault. Check the scenario's template config mappings first.
- **Auth (`401`/`403`)** — the connection reference isn't consented, is stale, or lacks entitlement; re-check the agent's `connectionreferences.mcs.yml` and re-consent in the environment. This is a connection fix, not a flow-logic fix.
- **Flow logic (wrong branch, wrong mapping, missing action)** — apply the edit through the `workflows/update` skill so the local working copy and Copilot Studio stay in sync, then re-exercise.

## Report

Summarize for the maker:

- How the flow was exercised (isolated / in-context) and whether a run was produced.
- The **first failing action + statusCode**, and whether the fault is in the flow, its template config, the connection, or the calling topic.
- The concrete fix and where it belongs (`workflow.json`, template config, connection reference), and a reminder to **publish** after pushing.