debuggerViews

Adds a section to the debugger under your extension's steps, built from that step's trace data.

Details #

When a macro runs, Switchboard records a trace: for each step, what went in, what came out, how long it took and any error. The debugger shows it. The debuggerViews point adds a section under a step of your extension that explains that trace in your own words, for example "the page returned 404" or "nothing matched the separator".

Where an inspector looks at a step before it runs, a debugger view looks at it after.

Declare it in switchboard.json under adds.debuggerViews:

{
  "adds": {
    "debuggerViews": [
      { "id": "request", "title": "Request details", "appliesTo": "fetch-page" }
    ]
  }
}

And implement it:

import { defineExtension, debuggerView } from '@switchboard/sdk';

export default defineExtension({
  debuggerViews: [
    debuggerView('request', ({ step }) => ({ title: 'Request', rows: [{ label: 'Status', value: step.status }] })),
  ],
});

Gotchas #

The handler must answer within 5 seconds. A view that fails or times out is skipped.
A dry run or a skipped step may have no output. Check before you read it.
The trace is what the engine recorded. Do not use a view to run anything; it only reads.
Unknown keys in an entry are refused.

A complete extension using this point can be downloaded from the Full example section and edited: a step that cuts text, and a debugger view that explains the result.

Manifest fields #

Field	Required	What it is
`id`	yes	Lowercase letters, digits and `.` `_` `-`, up to 64 characters, starting with a letter. Unique in the list.
`title`	yes	1 to 80 characters. Used as the panel title when the handler gives none.
`description`	no	Up to 1000 characters.
`appliesTo`	no	Which steps get the view: a step type in full (`com.example.thing.make`) or short for your own (`make`). Left out, all of your extension's steps.

What the handler gets and returns #

The handler gets { run, step }:

run: the run (id, status, and more).
step: the step's trace record. It always has id, type and status. It has input, output, note, error and ms when there are any.

It returns a panel, or null to show nothing:

title: a heading (defaults to the manifest title).
rows: up to 50 { label, value } pairs. A value can be text, a number, a switch or null.
text: a paragraph, up to 20000 characters.
status: ok, warning or error.

A panel with no rows and no text is not shown.