2.11 Debugging a Case on Your Machine

How to find out why a case fails by stepping through it yourself, one step at a time.

Debugging runs on your computer

CertiQA does not host a debugger. When a case fails and the report is not enough, you run that one case on your own machine with the CertiQA CLI. It opens a real browser you can watch, pauses before each step, and shows a local debug panel where you can step, retry, skip and try selectors. This keeps the page, your test data and anything you type on your machine, and it works against environments that are only reachable from your network.

The command uses a debug ticket: it works for that one case, expires after 15 minutes, and cannot read your project’s Vault. Generate a new one when it expires. The ticket goes in an environment variable on purpose, because arguments appear in process listings. In PowerShell, set $env:CERTIQA_ENGINE_TOKEN first.

What the Debug Panel Lets You Do

The panel is served from your own machine (127.0.0.1, protected by a random token) and opens automatically. Each time the run pauses it shows the step as written and with its variables filled in, the variables and where each came from, the last API exchange, and the page (address and a screenshot).

Command	What it does
Next	Run this step, pause at the next one
Continue	Run to the end, pausing only on a failure
Retry	Run the failed step again (change a variable first if you like)
Skip	Move past a step
Run to	Run up to a chosen step
Evaluate	Try a selector against the live page and see how many elements it matches
Set variable	Change a value before the next step
Stop / Finish	End the case / end the session

For an agent or hybrid case, the debug run prints the whole conversation, every tool call (mocked or real) and the verdicts, so you can see what the agent was told and what it did. Browser steps inside a hybrid case pause in the same panel.

Secrets Stay Hidden

Values from your Vault, variables marked secret, and anything the run resolved as a credential are masked in the panel and in the terminal. Masked variables cannot be edited. A debug ticket is not allowed to read Vault secrets at all, so a step that needs one cannot resolve it in a debug run; use a stand-in value for debugging.

Useful Options

Option	Effect
`--headless`	No browser window (for a machine without a display)
`--no-debug-panel`	Use the terminal prompt instead of the panel
`CERTIQA_DEBUG_NO_OPEN=true`	Print the panel address instead of opening it
`CERTIQA_DEBUG_PANEL_PORT`	Use a fixed port for the panel