Katalon Step Renumber

katalon-step-renumber

Fixes "Step N:" labels in Katalon / Groovy test scripts.

⚠️ Critical: ALWAYS use the bundled script

Never renumber steps by reading the file and editing manually. The bundled script is the single source of truth for the numbering rules and brace-tracking logic. Manual edits are error-prone (especially around if (true) sub-numbering and duplicate detection) and silently produce the wrong output.

If the first command fails (e.g. python3: command not found), do not give up and edit by hand — try the next command in the fallback list below. PowerShell is built into every Windows install since Windows 7, so the PowerShell command will always work on Windows.

When this applies

The file contains step labels written as bare string statements, e.g.:

"Step 1: Login to the system"
doLogin()

"Step 2: Verify the order"
verifyOrder()

Numbers drift out of sync when steps are added, removed, or duplicated during editing (e.g. two consecutive "Step 7:" lines, or a jump from "Step 11" to "Step 27").

Numbering rules (what the script does)

1. Top-level steps are renumbered sequentially from 1: every "Step N:" that is not inside an if (true) { ... } block becomes "Step 1:", "Step 2:", "Step 3:", … in the order they appear in the file.
2. Steps inside an if (true) { ... } block become "Step N.M:", where:
   • N is the most recent top-level step number (the one just above the if (true))
   • M starts at 1 and increments for each step inside the block
3. Only if (true) { ... } triggers sub-numbering. Other blocks (Page.As(...).with { ... }, plain {} blocks, etc.) do not — steps inside them are still treated as top-level.
4. The script overwrites the file in place by default.

How to run it

The skill ships with three equivalent scripts. Pick the one that matches the user's OS. All three implement the same logic — output is byte-identical.

Windows (PowerShell) — preferred on Windows, no extra install required

powershell -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\renumber_steps.ps1" -Path "<file.groovy>"

Optional flags:

• -DryRun — print result to stdout without writing
• -Output "<other.groovy>" — write to a different file

macOS / Linux (Bash + Perl) — preferred on Mac, no extra install required

Perl ships with every macOS version and virtually every Linux distro, so no setup is needed.

bash "<SKILL_DIR>/scripts/renumber_steps.sh" "<file.groovy>"

Or, if the script has execute permission:

"<SKILL_DIR>/scripts/renumber_steps.sh" "<file.groovy>"

Optional flags: --dry-run, -o <other.groovy>.

Any OS with Python 3 (cross-platform fallback)

python3 "<SKILL_DIR>/scripts/renumber_steps.py" "<file.groovy>"

Optional flags: --dry-run, -o <other.groovy>.

Fallback order if a command errors out

On Windows:

1. powershell -ExecutionPolicy Bypass -File "...renumber_steps.ps1" -Path "..."
2. pwsh -File "...renumber_steps.ps1" -Path "..." (PowerShell 7+ if available)
3. python "...renumber_steps.py" "..." (Windows Python alias)
4. py -3 "...renumber_steps.py" "..." (Python launcher on Windows)

On macOS / Linux:

1. bash "...renumber_steps.sh" "..."
2. python3 "...renumber_steps.py" "..."
3. perl "...renumber_steps.sh" "..." won't work — the .sh is a bash script wrapping perl; if bash isn't available (unlikely), fall back to the .py script.

If none of the above works, stop and tell the user: "I can't run the renumber script in this shell. Please run this command yourself: <the appropriate command for their OS>." Do NOT renumber by hand.

Typical workflow

1. User shares a .groovy test file (or points to one in the repo) and asks to fix step numbering.
2. Run the PowerShell command with -DryRun first to preview the changes.
3. Show the user a short before/after comparison of just the "Step lines (e.g. via Select-String '"Step').
4. Run again without -DryRun to overwrite in place.
5. Confirm by printing the script's summary line (Renumbered N top-level step(s) and M sub-step(s).).

Quick before/after check

After running, verify with:

Select-String -Path "<file.groovy>" -Pattern '"Step'

Or on Linux/Mac:

grep -n '"Step' "<file.groovy>"

The output should show a clean sequential run: Step 1, Step 2, Step 3, … with Step N.M only inside if (true) blocks.

Known limitations to mention if they matter

• Brace counting is naive — braces inside string literals or comments are still counted. Katalon test scripts in practice don't put { or } inside strings/comments, so this is fine. If the file looks unusual, warn the user.
• Only if (true) is special-cased. Other always-true wrappers (e.g. if (1 == 1)) are not.
• The regex matches "Step <digits>(.<digits>)?: — labels with letters (e.g. "Step 5a:") or other prefixes (e.g. "VP: ...") are ignored, which is intentional.