# Katalon Step Renumber

> Renumber "Step N:" labels in Katalon Groovy test scripts so they run sequentially from 1, with sub-numbering N.M for steps nested inside `if (true) { ... }` blocks. Use whenever the user asks to fix, correct, renumber, reorder, resequence, or clean up step numbers in a test script — including phrasings like "step numbers are off", "Step 7 is duplicated", "shift the steps", "the numbering is wrong after I added a step", "fix the test step numbering", or any time a Groovy/Katalon test file is shared and the step labels look wrong. Also use proactively when reviewing such a file and noticing duplicate or out-of-order `"Step N:"` labels.

- Skill: `nghiabui-kms/katalon-step-renumber` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add nghiabui-kms/katalon-step-renumber`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nghiabui-kms/katalon-step-renumber/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nghiabui-kms (https://skillmd.com/u/nghiabui-kms)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/nghiabui-kms/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.:

```groovy
"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
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
bash "<SKILL_DIR>/scripts/renumber_steps.sh" "<file.groovy>"
```

Or, if the script has execute permission:

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

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

### Any OS with Python 3 (cross-platform fallback)

```bash
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:

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

Or on Linux/Mac:

```bash
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.