test-step-design-patterns

Overview

This skill is a pure reference - no execution steps. It is the catalog cited when auditing step granularity at the architecture tier - within an "Act" phase, what is one step? It complements test-code-conventions §1 (AAA structure at the file level).

When to use

• Designing a test framework - pick the abstraction layers up front (mechanical / page / business).
• Auditing existing tests where step count per test is high (>15 actions per test signals granularity problems).
• Refactoring codegen output where every UI mechanic became its own step.
• Onboarding engineers who are writing first tests - point them at the canonical citations.

How to use

1. Establish the three abstraction layers up front - mechanical / page / business - and fix the rule that the test body lives at the business layer (Pattern 3).
2. Read the target test top-down and count logical actions; >15 actions signals a granularity or abstraction problem (Pattern 2).
3. Check each step does exactly one of Arrange / Act / Assert / Annotate; split any step that mixes two (Pattern 2 single-purpose rule).
4. Apply the rule of three: any step in 3+ tests, or 5+ mechanical lines, extracts to a Page Object method / Task / fixture (Pattern 4).
5. Group steps into phases with one vocabulary (AAA or Given-When-Then) and keep the phases visually separable (references/step-grouping-and-phrasing.md, Pattern 5).
6. Rephrase surviving business-layer steps declaratively - would the wording change if the implementation changed? If yes, rewrite (Pattern 6).
7. Run the reader test: read the test body aloud; it should sound like a specification, and every step should still honor FIRST (Patterns 7 and 1).

Pattern 1 - FIRST principles

Canonical source: Robert C. "Uncle Bob" Martin - Clean Code (2008), chapter 9 "Unit Tests", reaffirmed in Clean Coder and across his blog. The FIRST mnemonic is the foundational quality bar for every test step.

FIRST is the underlying rationale for most of the patterns below. A step that violates FIRST is the smell; the patterns prescribe the fix.

Pattern 2 - Step granularity

A "step" is the minimal unit a test reader can name in business terms. One logical action per step - not one click, not one assertion, but one meaningful operation.

The single-purpose-step rule

Each step should do exactly one of: Arrange (setup), Act (the operation under test), Assert (verify outcome), or Annotate (logging / labelling). Steps that mix two are split.

Step count per test

Aim for 3-8 steps per test body (counting Arrange / Act / Assert phases as steps). >15 is the threshold flagged as a smell - the test is doing too much or operating at the wrong abstraction.

Anti-patterns

Pattern 3 - Abstraction layers

The dominant test-code smell at scale is mechanical steps in the test body. The fix is layered abstraction. Three layers, named consistently:

The test body lives at the business layer. The test never reaches into the mechanical layer directly. If it does, the team has either no abstraction or the abstraction leaks.

Bad vs good (cross-framework)

Bad (test body at the mechanical layer):

test('places an order', async ({ page }) => {
  await page.goto('/login');
  await page.fill('#email', '[email protected]');
  await page.fill('#password', 'pass');
  await page.click('#submit');
  await page.goto('/product/sku-001');
  await page.click('button.add-to-cart');
  await page.goto('/checkout');
  await page.fill('#shipping-address', '123 Main St');
  await page.click('#place-order');
  await expect(page.locator('.confirmation')).toBeVisible();
});

Good (test body at the business layer):

test('places an order', async ({ customer, cart, checkout }) => {
  await customer.signsIn();
  await cart.addsItem('sku-001');
  await checkout.placesOrderWithDefaultShipping();
  await expect(checkout.confirmation).toBeVisible();
});

The mechanics live in the Page Object / Task / fixture. The test body reads as the specification, not the implementation.

When to keep the test mechanical

Some tests legitimately operate at the mechanical layer - testing the mechanical surface itself:

• Accessibility tests asserting keyboard navigation order.
• Visual regression tests asserting pixel-level rendering.
• Selector-resilience tests asserting getByRole works across viewports.

For these, the test body at the mechanical layer is correct. Tag them (@a11y, @visual) so reviewers don't refactor them by mistake.

Pattern 4 - Step extraction rules

When should a step move out of the test body?

The "rule of three" for extraction

Per Refactoring (Fowler 1999, 2nd ed. 2018), duplicate code is acceptable at first occurrence (write it inline). At the second occurrence, note the duplication. At the third occurrence, extract.

This applies to test steps: don't pre-extract on the first test ("we might need this later" is YAGNI). Extract when the third test needs the same step.

Anti-patterns

Pattern 5 - AAA / Given-When-Then mapping

Two equivalent step-grouping vocabularies (Arrange/Act/Assert = Given/When/Then). The team picks one, uses it consistently, and keeps the phases visually separable (blank-line or comment separation). Full mapping table, when-AAA-vs-when-Given-When-Then guidance, and the phase-separation rule with code: references/step-grouping-and-phrasing.md.

Pattern 6 - Declarative vs imperative step phrasing

Even at the business layer, prefer declarative phrasing ("the customer signs in") over imperative ("enters email, enters password, clicks submit"). The test: would the wording need to change if the implementation changed? If yes, rewrite declaratively. Full table, when-imperative-is-correct cases, and anti-patterns: references/step-grouping-and-phrasing.md.

Pattern 7 - Step naming

Per Roy Osherove's The Art of Unit Testing (2013), test names follow the pattern <system_under_test>_<scenario>_<expected_outcome>. Step naming (within the test) follows similar discipline:

The reader test

A reviewer should be able to read the test body aloud and have it sound like a specification:

"A customer signs in. They add SKU-001 to their cart. They place an order with default shipping. The order is confirmed."

If reading aloud doesn't produce a specification - if it produces "click, type, click, click, navigate, click, expect-truthy" - the steps are at the wrong abstraction.

Worked example

A reviewer receives an E2E spec places an order written entirely at the mechanical layer (the "Bad" block under Pattern 3): goto login, fill email, fill password, click submit, goto product, click add-to-cart, goto checkout, fill address, click place-order, then assert the confirmation.

Applying the patterns:

1. Count (Pattern 2): nine mechanical actions in one test body, all at the mechanical layer - a granularity and abstraction smell (the >15 threshold isn't hit, but the abstraction is wrong).
2. Rule of three (Pattern 4): the four-line login block (goto / fill / fill / click) recurs in other order and checkout specs, so it extracts to a customer.signsIn() business step.
3. Layer the rest (Pattern 3): the add-to-cart and checkout mechanics move into cart.addsItem('sku-001') and checkout.placesOrderWithDefaultShipping() on their Page Objects / Tasks.
4. Phrase and separate (Patterns 6 and 5): the surviving steps read declaratively, and Arrange / Act / Assert stay visually separable.

Result - the test body now reads as a specification: it collapses to exactly the "Good" block under Pattern 3 (four business-layer steps, no mechanical leakage).

The reader test (Pattern 7) now passes: "A customer signs in, adds SKU-001 to the cart, places an order with default shipping, and the order is confirmed."

Pattern selection guide

Cross-cutting anti-patterns

Hand-off targets

• Translate manual test steps to Gherkin → manual-step-to-gherkin (qa-bdd).
• Object-model architecture patterns (where extracted steps live) → object-model-patterns (sister catalog).
• Test isolation / fixture lifecycle → test-isolation-patterns (sister catalog).
• Test data construction patterns → test-data-patterns (qa-test-data, sister catalog).
• Cross-file file-level conventions → test-code-conventions.

References

• Robert C. Martin - Clean Code: A Handbook of Agile Software Craftsmanship (2008), chapter 9 "Unit Tests" (the FIRST principles): ISBN 978-0132350884. The canonical reference for the FIRST mnemonic. https://www.oreilly.com/library/view/clean-code-a/9780136083238/
• Roy Osherove - The Art of Unit Testing (2nd ed. 2013) (the <sut>_<scenario>_<expected> naming pattern cited in test-code-conventions §3): ISBN 978-1617290893.
• Kent Beck - Test-Driven Development by Example (2002) - the canonical TDD reference for step / test design rhythm: ISBN 978-0321146533.
• Martin Fowler - Refactoring: Improving the Design of Existing Code (2nd ed. 2018) - the "rule of three" for extraction (Pattern 4): https://martinfowler.com/books/refactoring.html
• Martin Fowler - Eradicating Non-Determinism in Tests (cited for the Independent principle): https://martinfowler.com/articles/nonDeterminism.html
• Cucumber documentation - Better Gherkin (declarative vs imperative phrasing rule, Pattern 6): https://cucumber.io/docs/bdd/better-gherkin/
• Gerard Meszaros - xUnit Test Patterns (2007) - the named-pattern catalog for Test Method, Assertion Method, Custom Assertion, Inline Resource: ISBN 978-0131495050.
• ISTQB glossary - test step: https://glossary.istqb.org/en_US/term/test-step
• ISTQB glossary - test procedure (the imperative form, by ISTQB convention): https://glossary.istqb.org/en_US/term/test-procedure
• test-code-conventions, manual-step-to-gherkin (qa-bdd) - the related-tier components.
• object-model-patterns, test-isolation-patterns, test-data-patterns (qa-test-data) - sister architecture-tier pattern catalogs.