# Sparq:refactor

> Updating E2E test files after codebase refactoring. Bulk renaming selectors, imports, class names, and string references across test suites.

- Skill: `stukh/sparq-refactor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add stukh/sparq-refactor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stukh/sparq-refactor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: STUkh (https://skillmd.com/u/stukh)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/stukh/sparq-refactor

---


# Refactor Test References

Config, version check, pattern rules, and E2E code generation preamble per `claude/rules/skills.md`.

## Input Parsing

- `--from` (required): old name, selector, import path, or string to find
- `--to` (required): new name, selector, import path, or string to replace with
- Remaining args: file or directory paths to scope the search (default: full `e2e/` directory per `e2e.structure.*` config)
- Match types: component names, `data-testid` values, CSS selectors, import paths, route URLs, class names, variable names
- Error: `--from` and `--to` identical -> exit immediately

## Workflow

1. Parse `--from`, `--to`, and scope paths from user input. Validate both flags are present and differ.
2. Grep scoped directories for all occurrences of the `--from` value. Search across: spec files, page objects, step definitions, component objects, fixtures, barrel files. Do NOT search: `src/` (application code), `node_modules/`, config files.
3. Report partial matches and near-matches (e.g., `LoginForm` also matching `LoginFormModal`). Warn about import path changes that may break barrel re-exports.
4. **CHECKPOINT** -- Present grep results: N occurrences across M files. Show each occurrence with `file:line` context. Include near-matches in a separate section. **Wait for approval of which replacements to apply.**

> **Non-interactive mode**: When `preferences.interactiveMode` is `false`, checkpoints are auto-approved except when near-matches or barrel re-export warnings are present. See orchestrator Checkpoint Policy.

5. Apply approved replacements (deterministic find/replace -- no second checkpoint needed for the replacements themselves).
6. Run smoke verification: `npx playwright test --list` (when `e2e.framework` is `playwright`) or `npx tsc --noEmit`.
7. **CHECKPOINT** -- Present smoke verify results. If failures detected, show affected tests and offer rollback via `git checkout -- {files}`. **Wait for approval.**
8. **Optional lint check**: After smoke passes, offer `sparq lint {scope-directory}/` to verify renamed references follow code-quality rubrics (locator quality, naming conventions, flaky patterns). Confirms no structural regressions were introduced. Instant, CI-compatible.
9. Write refactor report to `.sparq/validation/refactor-report.md`.

**Delegation**: Routes to `sparq-test-validator` in refactor mode. The orchestrator adds `mode: "refactor"` and `refactorParams: { from, to, scope }` to the dispatch. This is an S4 variant, not a new scenario.

## Error Handling

- No matches found: report "No occurrences of `{from}` found in scoped files" and exit
- Smoke verify fails after replacement: offer rollback via `git checkout -- {files}`, list affected files
- Barrel re-export broken: include in smoke verify failures with specific barrel file paths

## Output

```
# Modified project files (in-place edits)
{e2e.structure.pages}/{affected}.page.ts
{e2e.structure.specs}/{affected}.spec.ts
{e2e.structure.steps}/{affected}.steps.ts

# Refactor report (metadata)
.sparq/validation/refactor-report.md
```

Files are edited directly in the project E2E directory. Git is the safety net for review (`git diff`) and revert (`git checkout`).

<done_criteria>
1. `sparq.config.json` read and `--from` / `--to` patterns parsed and validated as non-identical
2. All occurrences of `--from` value located across scoped E2E files (specs, pages, steps, components, fixtures, barrels) with near-matches flagged separately
3. Approved replacements applied to all matched files — no partial replacements left pending
4. Smoke verify per `e2e.framework` (`npx playwright test --list` for Playwright, `npx cypress run --spec {path}` or `npx tsc --noEmit` for Cypress) passed without errors
5. Refactor report written to `.sparq/validation/refactor-report.md` listing replacement count, affected files, and smoke verify result
</done_criteria>

## References

- `.claude/skills/sparq-shared/references/validation-checklist.md`
- `.claude/skills/sparq-shared/references/pattern-adherence.md`
- `.claude/skills/sparq-shared/references/degradation-strategy.md`

## Examples

```
/sparq:refactor --from "LoginForm" --to "AuthenticationForm" e2e/
-> greps e2e/ for "LoginForm": 14 occurrences across 5 files
-> near-matches: "LoginFormModal" (3 occurrences) -- flagged separately
-> CHECKPOINT: review 14 replacements + 3 near-matches
-> user approves 14 exact matches, skips near-matches
-> applies replacements in login.page.ts, login.spec.ts, auth.steps.ts, loginFixture.ts, pages/index.ts
-> smoke verify: npx playwright test --list -- PASSED
-> CHECKPOINT: all green
-> output: .sparq/validation/refactor-report.md (14 replacements across 5 files)
```

```
/sparq:refactor --from "data-testid='submit-btn'" --to "data-testid='form-submit'" e2e/specs/auth/
-> greps e2e/specs/auth/ for "submit-btn": 6 occurrences across 2 files -> user approves
-> applies, smoke verify FAILED: login.page.ts still references old testid
-> CHECKPOINT: 1 failure, offer rollback or expand scope to e2e/pages/
```