Debugging Test Cases
Debug test cases interactively with breakpoints, live variable inspection, step-by-step execution, and real-time browser or device viewing.
Who is this for? QA engineers, SDETs, and developers who need to troubleshoot failing test cases by stepping through execution, inspecting variables, and editing steps in real time.
Overview
The debug screen provides an interactive environment for diagnosing and fixing test case failures. Instead of running a test end-to-end and reviewing results afterward, debug mode lets you pause execution at any step, inspect the live browser or device state, view variable values, and make changes on the fly — all without leaving the execution screen.
Key capabilities:
Set breakpoints on specific steps to pause execution automatically
Step through execution one step at a time with Step Over
Inspect live variable values at each pause point
Add, edit, skip, delete, and restore steps during a debug session
Jump to any step in the test case
Review all session changes before saving
View the live browser or device via VNC streaming
Starting a debug session
Select Debug
Click Debug from the menu. The debug screen opens with a three-panel layout:
Header
Top
Test case name, execution status, debug controls
Steps panel
Left
Step list, console, network, live variables, and AI conversation tabs
Live view
Right
Real-time browser or device screen via VNC
Debug controls
The header bar provides the following controls during an active debug session:
Start
Begin debug execution from the first step.
Step Over
Execute the current step and pause at the next step.
Continue
Resume execution until the next breakpoint or the end of the test.
Pause
Pause execution at the current step.
Stop
Stop the debug execution. Changes made during the session are preserved.
Restart
Restart execution from the first step.
Jump to Step
Open a dialog to select a specific step to jump to and continue execution from that point.
When execution is paused, the header displays a Paused at Step N indicator with the current step number and a timer showing how long the session has been paused.
Setting breakpoints
Breakpoints pause execution automatically when the test reaches a specific step. You can set breakpoints before or during a debug session.
To set a breakpoint:
Hover over a step in the steps panel.
Click the breakpoint indicator (circle) in the left gutter of the step, or use the step context menu and select Toggle Breakpoint.
To view all breakpoints:
Click View Breakpoints in the header. A modal lists all active breakpoints with options to:
Remove individual breakpoints
Remove all breakpoints at once
To remove a breakpoint:
Click the active breakpoint indicator on the step, or remove it from the breakpoints modal.
Steps panel
The left panel contains tabbed views for different aspects of the debug session.
Steps tab
Displays the full step list for the test case (including prerequisite steps). Each step shows:
Step number and description
Execution status (pending, running, passed, failed, skipped)
Breakpoint indicator
Context menu with debug actions
Step context menu actions:
Edit Step
Open the step editor to modify the step action, locators, or settings.
Add Step
Insert a new step before or after the current step.
Skip Step
Mark the step to be skipped during execution.
Unskip Step
Remove the skip flag from a previously skipped step.
Delete Step
Remove the step from the test case.
Restore Step
Undo a deletion and restore the step.
Duplicate Step
Create a copy of the step.
Toggle Breakpoint
Add or remove a breakpoint on the step.
Start from Step
Begin execution from this specific step.
Steps inside loops and conditions display their nested structure. You can add steps inside loop bodies and add else/else-if branches to condition steps directly from the debug screen.
Console tab
Displays console log output from the browser during execution, with timestamps for each entry.
Network tab
Shows network requests made during execution in a table format, useful for diagnosing API-related failures.
Live variables tab
Displays the current values of all variables at the paused step. Variables are shown in a flat table with:
Key
Variable name
Value
Current value
Type
Data type (string, number, object, etc.)
You can refresh variables to get the latest values. Nested object values are flattened for readability.
AI conversation tab
When debugging with AI assistance, this tab shows the AI agent conversation. You can send messages to the AI agent to help diagnose issues or perform actions.
AI Prompt tab
The AI Prompt tab displays an archive of all AI agent prompts used during the debug session. Every time you create, edit, duplicate, or delete an AI agent step, its prompt text is recorded here with a timestamp and operation label (created, edited, duplicated, deleted, or converted).
Each entry shows the step number, the prompt text, and whether the step passed or failed. When you edit an AI agent step, the archive records the previous prompt text (before the edit) so you can trace how a prompt evolved.
The archive resets when the debug session ends.
Editing steps during debugging
You can modify the test case while debugging without leaving the debug screen.
Step editing controls (add, edit, delete, and context menu options) are only available when execution is paused. While execution is actively running, these controls are disabled to prevent conflicts.
Editing an existing step:
Click the step context menu and select Edit Step.
The step edit modal opens with the step's current configuration.
Modify the action, locators, or settings.
Click Save to apply changes.
Adding a new step:
Click the step context menu on an adjacent step and select Add Step.
The step builder modal opens with all available step types (Actions, Loops, Conditions, Database, API, AI Agent, Custom Code, Document, Step Group).
Configure the new step and click Create.
Note: On mobile debug sessions, the Custom Code step type is not available in the step builder.
AI agent steps approval
When an AI agent step executes during a debug session, ContextQA generates sub-steps from the agent's actions. Before the steps are added, you review and approve them.
The AI agent step executes and ContextQA analyzes the actions performed.
A Review AI-generated steps dialog appears with a preview of the generated steps.
Review the steps and select an option:
Create Steps — stages the steps as session changes. The original AI agent step is marked as deleted, and the new steps appear after it.
Discard Changes — drops the steps. You can edit the AI agent step and re-run it, or continue past it.
The approval dialog has a 5-minute timeout. If no action is taken, the steps are automatically discarded.
While the approval dialog is open, execution controls (Step Over, Continue, Pause, Jump to Step) are disabled.
On-demand video capture
You can capture a video clip during a debug session while paused at a breakpoint.
Pause execution at a breakpoint or step.
Click the Capture Video button in the live view panel header.
A progress dialog tracks the capture: Starting → Capturing → Ready.
Click Watch Now to switch to the captured view, or Close to dismiss.
Use the Live / Captured toggle in the panel header to switch between the live browser stream and captured clips. When the debug execution completes, the full session video replaces individual clips.
Session restoration
If the browser session becomes invalid (session timeout, authentication expiration), a Session Restoration dialog appears:
Restoring
ContextQA is restoring browser state.
Wait for completion.
Session expired
Session validation failed. Shows specific failures (URL verification, authentication token).
Restart from Beginning, Stop Debug, or Override & Continue anyway.
Restoration failed
Browser state could not be restored.
Restart from Beginning or Stop Debug.
Override & Continue anyway forces execution to continue despite validation failure. Use this when you are confident the browser state is still usable.
Reviewing session changes
During a debug session, every modification you make (adding, editing, deleting, or skipping steps) is tracked. Before closing the debug session, you can review all changes.
Click Review Session Changes in the header or steps panel to open a summary of all modifications made during the session.
Execution results
When the debug execution completes (or is stopped), an execution result modal displays:
Status — Passed, Failed, Aborted, or Timed Out
Step summary — Total steps, completed steps, and failed steps
Timing — Total time, application time, and tool time
Available actions after execution:
View Run Results
Navigate to the full run results screen.
Re Run
Start a new debug execution.
Back to Debug
Return to the debug screen to continue working.
Save & Close Debug Mode
Save all session changes and exit the debug screen.
Copy Run Link
Copy a link to the run results (available on passed executions).
Best practices
Set breakpoints before the failing step — Place breakpoints one or two steps before the suspected failure point. This gives you context on the application state leading up to the failure.
Use live variables to diagnose data issues — Check variable values at each pause point to verify that API responses, environment parameters, and test data are what you expect.
Review session changes before saving — Click Review Session Changes before closing the debug session to verify that all modifications are intentional. Changes are applied to the test case when you save.
Related documentation
Test Steps Editor — Reference for all step types and the step builder
Creating Test Cases — Test case creation methods
Version History — Track and restore test case versions
Running Tests — Standard (non-debug) test execution
Last updated
Was this helpful?