Debugging

Debugging lets you pause a running Feature File, step through it one step at a time, and inspect the state of your test as it runs. The Cycle Testing VS Code Extension builds on the standard Visual Studio Code debugging tools, so the controls, breakpoints, and panels behave the way they do for any other language in VS Code. The difference is that you debug CycleScript rather than a general-purpose programming language.

First supported version

Debugging requires Cycle 2.29.0 or later and Cycle Testing VS Code Extension 1.18.0 or later.

Debugging is available for Feature Files only. You cannot debug playlists, group tests, or API requests.

Why debug a Feature File?

Running a test tells you whether it passed or failed. Debugging tells you why.

• Pause at a point of interest: Stop execution on a specific step instead of watching the whole test run through.
• Inspect state as it happens: See the current value of every variable at the moment execution pauses.
• Follow the flow across Scenarios: Trace how one Scenario calls another and how execution returns.

Launching a debug session

A debug session runs the entire Feature File.

Start debugging in any of these ways:

• Press F5 while the Feature File is the active editor tab.
• Run Debug Feature from the Command Palette.
• Click the Debug feature CodeLens that appears above the Feature line.

No launch configuration is required. You do not need to create or edit a launch.json file before debugging.

Debug sessions do not report results

A debug session does not stream output to the Test Results tab or to the Cycle Report Dashboard. Both are populated by normal execution only. See Executing Cycle Tests.

Controlling execution

When execution pauses on a breakpoint, the VS Code debug toolbar becomes active. Breakpoints and stepping operate on steps, so each action advances execution by whole steps.

The toolbar supports every control:

• Continue: Resume execution until the next breakpoint or the end of the test.
• Step Over: Run the current step and pause on the next step in the same Scenario.
• Step Into: Enter a called Scenario. In CycleScript, I execute scenario "..." behaves like a function call, so Step Into descends into the called Scenario and pauses on its first step.
• Step Out: Finish the current Scenario and return to the step that called it.
• Restart: Stop the current debug session, then start a fresh one from the beginning of the Feature File.
• Stop: End the debug session. Cycle closes the execution session and all supporting resources.

Setting breakpoints

A breakpoint marks a step where you want execution to pause.

1. Click the gutter to the left of a step, the same way you would in any VS Code editor.
2. Confirm that a red dot appears to indicate an active breakpoint.

You can set breakpoints on steps only. The gutter still accepts a breakpoint on a non-step line, such as the Feature line, a Scenario line, a comment, or a blank line. That breakpoint is ignored when the Feature File runs. Execution does not pause there, and the breakpoint does not move to the nearest step.

You can disable a breakpoint without removing it, then enable it again later. Manage all breakpoints in the current workspace from the Breakpoints section of the Run and Debug view.

Cycle does not support the following breakpoint types:

• Conditional breakpoints and logpoints
• Function breakpoints
• Hit count breakpoints

To pause when the value of a variable changes rather than when execution reaches a step, see Watching a variable for changes.

Inspecting variables and the call stack

While execution is paused, the Run and Debug view shows the current state of the test.

Variables

The Variables section lists every variable currently defined, along with its value. CycleScript uses a single, top-level Scenario scope, so all variables appear together in one Variables scope rather than being grouped into locals and globals.

Values are read-only. You can inspect a variable while execution is paused, but you cannot change its value from the Variables section.

Call stack

The Call Stack section shows the chain of Scenarios that led to the current step. Each frame corresponds to a Scenario. Cycle lists frames from deepest to shallowest:

• Top of the list: The Scenario that contains the current step.
• Bottom of the list: The top-level Scenario that started the test.
• Frames in between: Scenarios called through I execute scenario "...". See Reusing Scenarios.

Each frame shows the Scenario name, the Feature File, and a position in that file. For a calling Scenario, that position is the I execute scenario "..." step it is waiting on.

Select a frame to show the variables and source location for that Scenario.

Watching a variable for changes

A data breakpoint pauses execution when the value of a variable changes, wherever in the Feature File that change happens. Use one when a variable holds the wrong value by the end of a test and you do not know which step wrote it. A breakpoint in the gutter requires you to know which step to suspect. A data breakpoint finds the step for you.

First supported version

Data breakpoints require Cycle 2.30.0 or later.

Data breakpoints are set from the Variables section, so execution must already be paused.

1. Pause execution on a breakpoint or a failing step.
2. Right-click the variable you want to watch in the Variables section.
3. Select Break on Value Change.

The breakpoint appears in the Breakpoints section of the Run and Debug view, described as Break when $orderId changes (currently "12345").

You can only start watching a variable that already appears in the Variables section. To watch a variable before its first assignment, set the breakpoint in one session and leave it in place for the next one. See Managing data breakpoints.

Where execution pauses

A data breakpoint pauses execution after the step that changed the value, not before it. The step that made the change is highlighted in the editor, and the Variables section already shows the new value.

The Call Stack section reports the pause as Paused on data breakpoint. Hover over that label to see the variable with its old and new values.

Every debug toolbar control behaves at a data breakpoint pause as it does at any other pause.

CycleScript uses a single variable scope, so a watched variable is watched everywhere in the run:

• In a called Scenario: Execution pauses on the step inside the called Scenario that made the change, not on the I execute scenario "..." step that called it.
• In an imported Feature File: VS Code opens the imported Feature File and pauses on the step there. The Call Stack section shows the calling Scenario below it.

What counts as a change

Cycle compares the value of each watched variable before and after every step. Execution pauses when the two differ:

• A new value: A step assigns a different value to the variable.
• A first assignment: A step assigns the variable for the first time in the run.
• An unassignment: A step removes the variable, such as I unassign variable "orderId".

A step that assigns the value the variable already holds is not a change, so execution does not pause. When one step changes several watched variables, execution pauses once.

A step that carries a breakpoint in the gutter and also changes a watched variable pauses execution twice. The first pause happens before the step runs, and the second happens after it.

A watched variable that is never assigned during the run does not pause execution at all.

Failing steps pause once

When a step fails, execution pauses at the failure only, even if the failure changes a variable you are watching. See Pausing on failing steps.

Managing data breakpoints

Data breakpoints are listed in the Breakpoints section alongside the breakpoints you set in the gutter. Clear the checkbox beside one to disable it without removing it, or use the remove button to delete it.

Data breakpoints persist after the debug session ends, and VS Code restores them at the start of the next session before the run begins. A variable watched in one session therefore pauses execution on its first assignment in the next one.

Cycle watches variables for value changes only. The Break on Value Read and Break on Value Access commands do not appear for CycleScript variables. Conditions and hit counts are also unsupported on data breakpoints. VS Code marks a data breakpoint that carries either one as unverified and shows the reason, and that breakpoint does not pause execution.

Pausing on failing steps

Execution pauses automatically when a step fails, without you having to set a breakpoint on that step in advance. In CycleScript, an error surfaces as a failing step, so this is the equivalent of breaking on an exception.

This behavior is always active. The Breakpoints section of the Run and Debug view does not offer exception breakpoint options to configure.

When execution pauses on a failing step, you see the failing step highlighted in the editor, with a red panel open directly beneath it. The panel is headed Exception has occurred: CycleScriptStepFailure and shows the error message reported by the step. Use the copy button to copy the failure details, or the X button to close the panel.