# Debugging Test Cases

{% hint style="info" %}
**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.
{% endhint %}

## 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

{% stepper %}
{% step %}

#### Open a test case

Navigate to **Test Development**, open a test case, and click the **More** menu (three dots) in the header bar.
{% endstep %}

{% step %}

#### Select Debug

Click **Debug** from the menu. The debug screen opens with a three-panel layout:

| Panel           | Location | Purpose                                                               |
| --------------- | -------- | --------------------------------------------------------------------- |
| **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                            |
| {% endstep %}   |          |                                                                       |

{% step %}

#### Start execution

Click the **Start** button in the header. ContextQA connects to a browser or device instance and begins executing from the first step. If breakpoints are set, execution pauses automatically when it reaches a breakpoint.
{% endstep %}
{% endstepper %}

***

## Debug controls

The header bar provides the following controls during an active debug session:

| Control          | Description                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------ |
| **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:**

1. Hover over a step in the steps panel.
2. 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:**

| Action                | Description                                                            |
| --------------------- | ---------------------------------------------------------------------- |
| **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:

| Column    | Description                              |
| --------- | ---------------------------------------- |
| **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.

{% hint style="info" %}
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.
{% endhint %}

**Editing an existing step:**

1. Click the step context menu and select **Edit Step**.
2. The step edit modal opens with the step's current configuration.
3. Modify the action, locators, or settings.
4. Click **Save** to apply changes.

**Adding a new step:**

1. Click the step context menu on an adjacent step and select **Add Step**.
2. The step builder modal opens with all available step types (Actions, Loops, Conditions, Database, API, AI Agent, Custom Code, Document, Step Group).
3. 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.

1. The AI agent step executes and ContextQA analyzes the actions performed.
2. A **Review AI-generated steps** dialog appears with a preview of the generated steps.
3. 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.

{% hint style="warning" %}
The approval dialog has a 5-minute timeout. If no action is taken, the steps are automatically discarded.
{% endhint %}

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.

1. Pause execution at a breakpoint or step.
2. Click the **Capture Video** button in the live view panel header.
3. A progress dialog tracks the capture: **Starting** → **Capturing** → **Ready**.
4. 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:

| State                  | Description                                                                                  | Actions                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| **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:**

| Action                      | Description                                                      |
| --------------------------- | ---------------------------------------------------------------- |
| **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

{% hint style="success" %}
**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.
{% endhint %}

{% hint style="info" %}
**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.
{% endhint %}

{% hint style="warning" %}
**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.
{% endhint %}

***

## Related documentation

* [Test Steps Editor](/web-testing/test-steps-editor.md) — Reference for all step types and the step builder
* [Creating Test Cases](/web-testing/creating-test-cases.md) — Test case creation methods
* [Version History](/web-testing/version-history.md) — Track and restore test case versions
* [Running Tests](/execution/running-tests.md) — Standard (non-debug) test execution


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learning.contextqa.com/web-testing/debugging-test-cases.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.