Formatting
Formatting rewrites a Feature File so that its indentation, spacing, keyword casing, and blank lines follow one standard layout. Formatting changes only how the CycleScript code looks. It never changes what the code does when it runs.
Both the Desktop IDE and the Cycle Testing VS Code Extension format Feature Files on demand and automatically when you save them.
From the command line, run cycle-cli format <file.feature>.
Why use formatting
- Readable Feature Files: Consistent indentation shows at a glance which steps belong to which Scenario, conditional block, or loop.
- Less manual cleanup: You can write steps without lining them up by hand, and the editor fixes the layout when you save.
- Cleaner reviews: When everyone on a team formats the same way, file comparisons and pull requests show real changes instead of whitespace differences.
There is one set of formatting rules for all Cycle projects. The only option you can change is Preserve Step Indentation.
Formatting rules
| Element | Rule |
|---|---|
| Indentation | Tabs only. Lines indented with spaces are re-indented with tabs. Your editor controls how wide a tab appears. In the Desktop IDE, that width is Editor tab size (spaces). |
| Feature | Feature: starts at the left margin. Feature description lines are indented one tab. |
| Sections | Background:, Scenario:, Scenario Outline:, and After Scenario: lines are indented one tab. The steps inside them are indented two tabs. |
| Conditional blocks and loops | If, ElsIf, Else, and EndIf line up with each other, as do While and EndWhile. The steps inside each block are indented one more tab. |
| Tags | Tag lines are indented to match the Scenario they belong to. Tags are separated by a single space, and any tag missing its @ prefix gets one. Multiple tag lines stay on separate lines. |
| Comments | Comments are indented to match the section or block that contains them. Comments above the Feature: line stay at the left margin. |
| Keywords | Keywords use their capitalized forms, such as Given, ElsIf, EndWhile, and Scenario Outline. Multi-word keywords have a single space between words. |
| Colons | No space appears between a section keyword and its colon (Scenario:, not Scenario :). |
| Spacing | A single space separates a keyword from the title or step text that follows it. |
| Blank lines between sections | Exactly one blank line appears before each Background:, Scenario:, Scenario Outline:, and After Scenario: section, including any tags above it. |
| Other blank lines | Blank lines you add between steps are kept, and runs of several blank lines become one. Formatting does not add blank lines between steps. |
| Examples tables | Examples: is indented to match the steps, and its rows are indented one more tab. Cells are padded so that the | delimiters line up in every row. The table moves below the last step, with one blank line before it. |
| External examples | CSV Examples:, SQL Examples:, MOCA Examples:, Datastore Examples:, and Example Row: lines are indented to match the steps. They move directly below the Scenario Outline: line, followed by one blank line. |
| Line endings | The file keeps its existing line endings, ends with exactly one newline, and loses any trailing whitespace. |
To learn more about the elements in this table, see Tags, Comments, If-Else statements, While loops, and Scenario Outlines.
Seeing formatting in action
The following Feature File runs correctly but is hard to read. The examples on this page show each tab as four spaces so the indentation is easy to read. (In the Cycle Editor, each tab appears at the width set by Editor tab size (spaces).)
feature:My Order Tests
Background :
Given I assign "ORD-100" to variable "order_number"
@smoke regression
scenario: Check an order
given I echo $order_number
if I verify text $order_number is equal to "ORD-100"
then I echo "Order found"
endif
scenario outline: Check many orders
given I echo <order>
examples:
|order|status|
|"ORD-100"|"Shipped"|
|"ORD-20000"|"Open"|
After formatting, the same Feature File looks like this:
Feature: My Order Tests
Background:
Given I assign "ORD-100" to variable "order_number"
@smoke @regression
Scenario: Check an order
Given I echo $order_number
If I verify text $order_number is equal to "ORD-100"
Then I echo "Order found"
EndIf
Scenario Outline: Check many orders
Given I echo <order>
Examples:
| order | status |
| "ORD-100" | "Shipped" |
| "ORD-20000" | "Open" |
Preserving step indentation
Some testers add extra indentation between steps to show structure the language does not enforce. A common example is indenting the steps that follow an Activity step:
Scenario: Count inventory
Given I "log in to the app"
When I execute scenario "Boot up the app"
And I execute scenario "App Login"
When I "count the inventory"
Then I execute scenario "Perform LPN Count"
The Preserve Step Indentation setting controls what happens to that extra indentation. It is turned on by default.
| Setting | Result |
|---|---|
| On | Section and block indentation is still enforced, but any extra indentation you write between steps in the same block is kept. The Scenario above stays as written. |
| Off | Every step in a block is indented evenly. The steps under each Activity step move left to line up with the Activity step, as shown below. |
Scenario: Count inventory
Given I "log in to the app"
When I execute scenario "Boot up the app"
And I execute scenario "App Login"
When I "count the inventory"
Then I execute scenario "Perform LPN Count"
Formatting never adds this extra indentation on its own. Activity steps do not start a block, so the steps after them are indented only if you indent them yourself.
To change the setting, see the Desktop IDE formatting settings or the VS Code formatting settings.
Formatting files with syntax errors
Cycle does not format a Feature File that contains syntax errors. The file stays exactly as you wrote it, and when you save, it is saved unformatted. Fix the errors the editor marks with red underlines, and then format the file again. Warnings do not prevent formatting.