---
name: consolidating-test-setup
description: Consolidates repeated test setup and teardown into the narrowest shared lifecycle owner. Use when test files repeat initialization, cleanup, environment management, fixtures, or equivalent test doubles.
---

# Consolidating test setup

Move repeated test plumbing to the narrowest shared owner that can provide it
reliably. Keep test files focused on behavior. The isolation and readability
rules this skill applies are stated once in
`docs/guidance/testing-principles.md`. This skill is the procedure.

## Principles

### Prove the code is equivalent

Repetition is evidence, not proof. Similar code may use different defaults,
ordering, or lifetimes. Group candidates by behavior before treating them as
duplicates.

### Centralize invariants, not scenarios

Shared setup should establish conditions that hold for every test in its scope.
State that explains one scenario belongs with that scenario.

### Use the narrowest owner

Prefer the mechanism that already owns the lifecycle. Use runner configuration
before hooks, scoped fixtures before global setup, and local setup for local
requirements. Wider reuse is not better reuse.

### Treat setup and teardown as one contract

Define who creates state, how long it lives, and who releases it. Cleanup must
finish even when a test fails. Tests must not depend on execution order or on
another test's cleanup.

A shared default should be deterministic and easy to override. Local exceptions
must not weaken isolation elsewhere.

### Subtract before abstracting

Remove suspected cargo-cult setup and run the affected tests. A targeted pass
only marks it provisionally unnecessary. Delete it after the complete relevant
suite and runner-specific lifecycle checks pass. If a test fails, use the
failure to identify the contract before designing shared setup.

A helper must own a policy or lifecycle, or remove meaningful reader effort.
Moving the same lines behind a new name is not an improvement.

### Preserve test intent

Do not hide state that matters to the behavior under test. Check history before
removing synchronization or cleanup because it may guard a past regression.
Preserve that guarantee even if the implementation changes.

## Runner-specific guidance

Load only the reference for the runner in use:

- [`reference/vitest.md`](reference/vitest.md) for Vitest and similar
  in-process unit-test runners
- [`reference/playwright.md`](reference/playwright.md) for Playwright and
  similar browser-test runners

These references supplement the repository's testing guide. They do not replace
it. Load both only when the task spans both runners.

## Workflow

### 1. Discover

Read the runner configuration, setup files, fixtures, helpers, and test guidance.
Count repeated lifecycle behavior and note the suites that use it.

### 2. Classify

For each candidate, record:

- the state it owns
- its lifetime and scope
- whether it is an invariant or scenario detail
- intentional differences between suites
- behavior already supplied by the runner

### 3. Challenge

Remove the candidate and run every affected suite. Classify it as unnecessary,
universal, common with exceptions, or suite-specific.

Subagents may evaluate disjoint groups of suites. Require evidence and exception
reports from each. Keep the design and integration decision in the parent task.

### 4. Place

Choose the required lifetime and scope first. Then use the simplest owner at
that exact boundary:

- native runner behavior that supports the required scope
- existing shared setup, fixture, or hook
- a focused helper or test double
- the individual suite

Do not move state to a broader owner because its mechanism appears earlier in
the list.

### 5. Migrate

Move one responsibility at a time. Add the shared owner, then remove only the
local code it replaces. Keep intentional exceptions and scenario setup visible.
Avoid unrelated test rewrites.

### 6. Prove

Run affected tests, tests of the shared lifecycle, repository static checks, and
the complete relevant suite. Measure before and after when the new behavior runs
for every test. Use enough comparable samples to separate a real change from
normal variance.

## Report

State the repeated contract, its new owner, retained exceptions, rejected
alternatives, duplication removed, and validation results. Include performance
evidence when shared setup could affect suite runtime.

## Guardrails

- Do not replace native runner behavior with a custom abstraction.
- Do not widen setup scope without evidence.
- Do not add a helper merely to move code.
- Do not hide global mutable state behind helper indirection.
- Do not trade visible test intent for shorter files.
- Do not trust targeted tests alone after changing shared lifecycle behavior.