Debugging Tests
Use the interactive debugger to step through test cases, set breakpoints, inspect live variables, capture video, review AI agent steps, and modify steps mid-session in ContextQA.
Who is this for? SDETs, testers, and developers who need to diagnose failing test steps, inspect runtime state, or iterate on test logic without re-running the entire test case from scratch.
The interactive debugger lets you execute a test case step by step with full control over the flow. You can pause execution at any step, set breakpoints, inspect live variable values, capture video clips, review AI-generated steps, and add, edit, or delete steps during the session. Changes you make can be saved back to the test case when the session ends.
Prerequisites
You have at least one test case with one or more steps.
Your workspace license includes the Debug feature.
You have an environment configured with a valid base URL.
Starting a debug session
You launch a debug session from the test case details screen.
Open the test case from Test Development -> Test Cases.
Click the More menu (three-dot icon) in the test case header.
Select Debug.
The debug screen opens with a Debug Mode badge in the toolbar. Your test case steps load in the left panel and a live browser view appears in the right panel.
Click Start Debugging in the debug toolbar to begin execution.
The debugger connects to a live browser session via VNC. Execution pauses automatically at the first step so you can set breakpoints or review the step list before proceeding.
Debug is available for web test cases. For mobile test cases, VNC is disabled and a live screenshot stream is shown instead.
Debug screen layout
The debug screen is a split-pane view with three main areas:
Header
Displays the test case name, a status badge (Running, Paused, Completed, Failed, or Aborted), a step progress bar (X / Y Steps), and platform metadata (browser, device, build name).
Debug toolbar
Appears below the header when debug mode is active. Contains the Debug Mode badge, the current pause status (for example, "Paused at Step 5"), a session timer, and the execution control buttons described in the next section.
Left panel tabs
Steps
Displays all test steps grouped by prerequisite and main test case. Each step shows its number, action, status, and duration.
Console
Shows browser console log entries (info, warning, error) with timestamps.
Network
Displays captured HTTP requests and responses in a table.
Live Variables
Shows a searchable, sortable table of all runtime variables and their current values.
AI Prompt
Displays an archive of AI prompts used during the session. Each entry shows the step number, step name, timestamp, prompt text, and the operation that triggered the archive (created, edited, duplicated, deleted, or converted).
Right panel
Shows a live VNC browser stream during execution, or a screenshot preview when the session is paused or complete. During a live debug session, the simulator header includes a Live / Captured toggle. The Live view shows the real-time VNC stream, while the Captured view shows video clips captured on demand during the session. After execution completes, the right panel switches to a video library containing the full session recording.
Execution controls
The debug toolbar provides the following controls:
Start Debugging
Before the session starts
Begins step-by-step execution. Sends any pre-configured breakpoints and skipped steps to the execution engine.
Step Over
When paused at a step (not the last step)
Executes the current step and pauses at the next one.
Continue
When paused at any step
Resumes execution until the next breakpoint or the end of the test case.
Pause
While execution is running
Requests a pause after the current step completes. A spinner indicates the pause is pending.
Stop
While the debug session is active
Stops execution immediately and ends the debug session.
Re Run
After execution completes or is stopped
Resets the session and starts a fresh debug run.
More options menu
Click the More menu (vertical three-dot icon) in the debug toolbar for additional actions:
Jump to step -- opens a dialog where you can select any step and restart execution from that point.
Restart from first step -- restarts execution from the beginning of the test case.
View breakpoints -- opens a dialog listing all breakpoints you have set.
Review session changes -- opens a summary of all steps you added, edited, or deleted during the session (available after execution completes).
Setting breakpoints
Breakpoints tell the debugger to pause execution before a specific step runs. You can set breakpoints before starting execution or while the session is paused.
Adding a breakpoint
In the Steps tab, click the breakpoint indicator on the left edge of a step row to toggle a breakpoint on or off.
Alternatively, use the step's context menu and select Toggle breakpoint.
A breakpoint marker appears next to the step number. When execution reaches a step with a breakpoint, the debugger pauses and the toolbar shows "Paused at Step N".
Viewing and removing breakpoints
Click the More menu in the debug toolbar and select View breakpoints.
The Breakpoints dialog lists every breakpoint with the step number and description.
To remove a single breakpoint, toggle it off from the step row in the Steps tab.
To remove all breakpoints at once, click Remove all breakpoints in the dialog.
Skipping steps
You can mark steps to be skipped during the debug run. Skipped steps are excluded from execution but remain visible in the step list with a "skipped" status indicator.
In the Steps tab, use the step's context menu and select Skip step.
To restore a skipped step, use the context menu again and select Unskip step.
Inspecting live variables
The Live Variables tab displays all runtime variables in a searchable table. Variables update as each step executes, so you can see the current value of any variable at the point where execution is paused.
Name
The variable name (for example, username, ENV.BASE_URL).
Value
The current runtime value.
Use the search bar to filter variables by name.
Click the Refresh button to reload variable values manually.
When the debug session is active, you can edit variable values inline by clicking on a value cell.
AI Prompt Archive
The AI Prompt tab records a history of every AI prompt used during the debug session. When you add, edit, duplicate, delete, or convert an AI agent step, the prompt text is archived automatically.
Each archive entry shows:
Step number
The position of the step in the test case (for example, 6.2).
Step name
The display name of the AI agent step.
Timestamp
When the operation occurred (for example, "Today, 12:04 PM").
Prompt text
The full AI prompt that was sent to the agent.
Operation
The action that triggered the archive entry: created, edited, duplicated, deleted, or converted.
Status
A failed indicator appears if the step failed during execution.
A sub-header displays the test case name and the total number of AI prompts used in the current run.
When no AI agent steps have been used in the session, the tab shows an empty state with the message "No AI prompts yet."
The AI Prompt Archive is cleared when a new debug run starts. It tracks prompts for the current session only.
Modifying steps during a debug session
You can add, edit, or delete steps while the debug session is paused. Step edit controls (the edit icon, Add step button, and step context menu) are visible only when execution is paused at a step. While execution is actively running, these controls are hidden to prevent conflicts.
Step editing controls (add, edit, delete, and context menu options) are only available when execution is paused at a breakpoint or step. While execution is actively running, these controls are disabled to prevent conflicts with the running test.
Adding a step
While paused, click the Add step button that appears between steps in the step list.
The Add Step dialog opens with the standard step builder.
Configure the step and click Save.
The new step appears in the step list at the insertion point.
Editing a step
While paused, click the edit icon on the step row.
The Edit Step dialog opens with the step's current configuration.
Make your changes and click Save.
Deleting a step
Use the step's context menu and select Delete step.
The step is removed from the current session's step list.
Session changes banner
When you modify steps, a Changes detected since last run banner appears at the top of the Steps tab. It shows the count of added, edited, and removed steps. Click View Details to open the full session changes summary.
AI agent step approval
When an AI agent step executes during a debug session, it can generate sub-steps based on its prompt. Before these steps are applied, the debugger opens an approval dialog so you can review them.
The AI agent step executes and generates a set of proposed sub-steps.
The approval dialog opens, showing each proposed step with its action and details.
Review the proposed steps. You can select or deselect individual steps.
Click Create to approve the selected steps, or Discard to reject them all.
The debugger inserts approved steps into the step list directly after the AI agent step and tracks them as session changes. It marks the original AI agent step as deleted in the session. You can review all changes in the Session Changes dialog before saving.
The approval dialog has a 5-minute timeout. If you do not respond within 5 minutes, the proposed steps are automatically discarded. A notification confirms the discard.
AI agent steps approval
When an AI agent step executes during a debug session, ContextQA generates sub-steps based on the AI agent's actions. Before these steps are added to the test case, 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 proposed steps. The dialog shows the step count, action type, and a preview of each generated step.
Select one of the two options:
Create Steps — stages the generated steps as session changes. The original AI agent step is marked as deleted, and the new steps are inserted after it. You can review all changes in the session changes summary before saving to the test case.
Discard Changes — drops the generated steps without saving. 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 within that time, the generated steps are automatically discarded.
While the approval dialog is open, the Step Over, Continue, Pause, and Jump to Step controls are disabled. Review the generated steps before continuing execution.
AI Prompt Archive
The AI Prompt tab in the left panel keeps a running history 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 archived here.
Each archive entry shows:
Step number
The hierarchical step number (for example, 3 or 6.2).
Prompt text
The AI agent prompt as written in the step action.
Timestamp
When the prompt was archived (for example, "Today, 2:04 PM").
Operation
What triggered the archive entry: created, edited, duplicated, deleted, or converted.
Status
Whether the step passed or failed during execution.
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 across iterations.
The archive resets when the debug session ends.
On-demand video capture
During a debug session, you can capture a video clip of the current execution segment while paused at a breakpoint.
Pause execution at a breakpoint or step.
Click the Capture Video button in the live browser view panel header.
A progress dialog appears showing the capture status:
Starting — the capture request is being processed.
Capturing — the video segment is being recorded.
Ready — the clip is available for playback.
When the clip is ready, click Watch Now to switch to the Captured view, or click Close to dismiss the dialog.
The live browser view panel header includes a Live / Captured toggle. Use it to switch between the live VNC stream and any video clips captured during the session.
Captured video clips are stored for the duration of the debug session. When execution completes, the full session video replaces the individual clips in the execution report.
Session restoration
If the browser session becomes invalid during a debug session (for example, due to a session timeout or authentication expiration), a Session Restoration dialog appears instead of a simple error notification.
The dialog shows the restoration state and available actions:
Restoring
ContextQA is attempting to restore the browser state.
Wait for completion.
Session expired
Session validation failed. The dialog may show specific validation failures (page URL verification, authentication token, login redirect check).
Restart from Beginning, Stop Debug, or Override & Continue anyway.
Restoration failed
The browser state could not be restored.
Restart from Beginning or Stop Debug.
Restart from Beginning restarts execution from the first step of the test case.
Stop Debug ends the debug session.
Override & Continue anyway (available only on session expiry) forces execution to continue from the target step despite the validation failure. Use this when you are confident the browser state is still usable.
When restoration succeeds, the debugger scrolls to the restored step and displays a success notification.
Reviewing and saving session changes
After the debug session ends, you can review all modifications you made and optionally save them back to the original test case.
Click the More menu in the debug toolbar and select Review session changes.
The Session Changes dialog displays three sections: Added, Edited, and Deleted steps.
Review each change. You can remove individual changes before saving.
Click Save to test case to commit the changes to the test case, or click Cancel to discard them.
Saving session changes modifies the original test case. Review all changes carefully before saving.
Capturing video during a debug session
You can capture video clips on demand while a debug session is paused. This is useful for recording specific interactions or reproducing a visual issue without waiting for the full post-execution recording.
Starting a capture
Pause execution at the step you want to record (using a breakpoint or the Pause button).
Click the Capture Video button in the simulator header. The button is available only when execution is paused during a debug session.
A progress dialog opens, showing the capture state:
Starting -- the capture is initializing.
Capturing -- the video is being recorded. The dialog updates as the capture progresses.
When the capture completes, the dialog shows a Ready state with two options:
Watch Now -- switches the simulator to the Captured view and plays the clip.
Close -- dismisses the dialog without switching views.
Viewing captured clips
During a live session, the simulator header shows a Live / Captured toggle:
Live -- displays the real-time VNC browser stream.
Captured -- displays video clips captured during the session. Clips are listed in the order they were captured.
You can switch between Live and Captured at any time during the session.
After execution completes
When the debug execution finishes, mid-session captured clips are replaced by the canonical session recording (the full WebM video produced by the execution engine). The post-execution video is available in the video library on the right panel, the same as for standard test executions.
Video capture during debug is separate from the automatic session recording. The session recording captures the entire execution, while on-demand captures record only the segment you request.
Session restoration
If you resume a debug session after a period of inactivity, the debugger attempts to restore the browser state to where you left off. A Session Restoration dialog appears to show the progress and any issues.
Restoration states
Restoring
The debugger is re-navigating the browser to the checkpoint page and re-applying state.
Wait for restoration to complete. No action is required.
Session expired
The browser session could not be fully validated. The page URL or DOM state does not match the expected checkpoint.
Choose Restart from Beginning, Stop Debug, or Override & Continue anyway.
Restoration failed
The restoration attempt failed entirely (for example, the server could not reconnect to the browser).
Choose Restart from Beginning or Stop Debug.
Restoration actions
Restart from Beginning
Starts a fresh debug run from step 1, discarding the previous session state.
Stop Debug
Ends the debug session and returns to the test case details screen.
Override & Continue anyway
Dismisses the warning and resumes execution at the checkpoint step, even though validation failed. Use this when you are confident the page state is acceptable despite the mismatch.
Override & Continue anyway skips session validation. If the browser state does not match expectations, subsequent steps may fail or produce unexpected results.
Inactivity timeout
If the debug session remains idle for an extended period, an inactivity warning banner appears below the debug toolbar. The banner displays a countdown timer showing how much time remains before the session is automatically terminated.
To keep the session active, perform any action (step over, continue, add a step, or interact with the browser view).
Tips and best practices
Set breakpoints before starting -- if you know which steps are likely to fail, set breakpoints on them before clicking Start Debugging to avoid stepping through every preceding step manually.
Use Jump to step for fast iteration -- when debugging a step deep in the test case, use Jump to step to restart execution from a point close to the problem area instead of re-running from the beginning.
Inspect variables at pause points -- switch to the Live Variables tab each time the debugger pauses to verify that variables hold expected values before continuing.
Save session changes only when confident -- make sure edits work correctly within the debug session before committing them to the test case.
Capture video at key moments -- use on-demand video capture when paused at a step to record a specific interaction, rather than relying only on the full session recording.
Review AI agent steps before approving -- the approval dialog lets you select individual steps. Deselect any steps that look incorrect before clicking Create.
Troubleshooting
The Debug option does not appear in the test case menu
Your workspace license may not include the Debug feature. Contact your ContextQA administrator to verify your license includes Debug support. The test case must also have at least one step.
VNC connection fails and no browser view is displayed
An error message appears in the debug toolbar when the VNC connection fails. Verify that your network allows WebSocket connections to the ContextQA execution servers. Try stopping the session and starting a new one.
The session was terminated due to inactivity
The debugger automatically terminates idle sessions to free execution resources. Start a new debug session and interact with the controls regularly to prevent timeout.
Step Over or Continue buttons are disabled
These controls require an active WebSocket connection. If the connection is interrupted, the buttons become disabled. Wait a moment for the connection to reconnect, or stop and restart the debug session.
A "Session expired" dialog appears when resuming a debug session
The debugger detected that the browser state no longer matches the checkpoint where you left off. This can happen after a long period of inactivity or a network interruption. Choose Restart from Beginning to start a fresh run, or Override & Continue anyway if you believe the current browser state is acceptable.
AI agent steps were discarded automatically
The approval dialog has a 5-minute timeout. If you did not respond in time, the proposed steps were discarded. Edit the AI agent step and re-run it to generate new steps.
The Capture Video button is not visible
The Capture Video button appears only when execution is paused during a debug session. If execution is actively running or the session has not started, the button is hidden. Pause execution at a step first, then look for the button in the simulator header.
Related pages
Running Tests -- standard (non-debug) test execution
Test Steps Editor -- creating and editing test steps
Video & Screenshots -- execution evidence and artifacts
Environments -- configuring execution environments
Debug smarter, not harder. ContextQA's interactive debugger gives you full control over test execution — set breakpoints, inspect variables, and fix tests in real time. Book a Demo -> — See how the interactive debugger accelerates test development and failure diagnosis.
Last updated
Was this helpful?