| name | sparq:refactor |
| description | Updating E2E test files after codebase refactoring. Bulk renaming selectors, imports, class names, and string references across test suites. |
| audience | internal |
| input_type | text |
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
- Parse
--from, --to, and scope paths from user input. Validate both flags are present and differ.
- 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.
- Report partial matches and near-matches (e.g.,
LoginForm also matching LoginFormModal). Warn about import path changes that may break barrel re-exports.
- 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.
- Apply approved replacements (deterministic find/replace -- no second checkpoint needed for the replacements themselves).
- Run smoke verification:
npx playwright test --list (when e2e.framework is playwright) or npx tsc --noEmit.
- CHECKPOINT -- Present smoke verify results. If failures detected, show affected tests and offer rollback via
git checkout -- {files}. Wait for approval.
- 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.
- 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>
sparq.config.json read and --from / --to patterns parsed and validated as non-identical- All occurrences of
--from value located across scoped E2E files (specs, pages, steps, components, fixtures, barrels) with near-matches flagged separately
- Approved replacements applied to all matched files — no partial replacements left pending
- 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
- 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/
