📝 Spec & Step Basics

Spec & Step Basics: The relationship between a spec file and a step implementation is that of sheet music to a pianist: the sheet (.spec) says WHAT to play line by line, the pian

The relationship between a spec file and a step implementation is that of sheet music to a pianist: the sheet (.spec) says WHAT to play line by line, the pianist (the @Step method) knows HOW to strike each note. The critical mechanism is matching: every symbol on the sheet must have an exact counterpart in the pianist's repertoire — Gauge matches the spec's step sentence to the @Step("...") annotation text CHARACTER BY CHARACTER; "User signs in" and "User sign in" are two different steps. Why doesn't Gauge do fuzzy matching — wouldn't accepting "roughly the same" sentence be more practical? No: in test automation, ambiguity is the most expensive thing; if "which method runs" were based on a guess, the wrong implementation could run silently. The Java parallel is method overload resolution: the compiler decides which method a call binds to with exact rules — it never says "I'll call the closest-named method". In QA this rigidity works for you: when a word changes in the spec, the test breaks with "Step implementation not found" instead of silently running the wrong method — protecting you from a false PASS, the most dangerous test outcome.

📄 Anatomy of a Spec File

A .spec file has three levels: a single Specification heading starting with # (one per file), Scenario headings starting with ## (each an independent test), and step lines starting with *. Steps placed right under the Specification heading become "context steps": they run before EVERY scenario in that file — the in-spec equivalent of Java's @BeforeMethod. Values in double quotes (like "admin") automatically become parameters.

Step by Step: Context Step vs Scenario Step

Directly under the # heading

A * line placed right under the Specification heading becomes a "context step".

A context step runs before EVERY scenario

The in-spec equivalent of Java's @BeforeMethod — it runs automatically for every scenario in that file.

A * line under a Scenario heading is scoped to THAT scenario only and runs independently.

If you keep copy-pasting a shared step into every scenario (like "open the page"), move it to a context step.

Micro Lab: Gauge spec-step binding practice

Replace the TODO line with the critical line from the expected solution. This is not a real runtime; the goal is to reinforce writing the correct structure in a controlled way.

☕ Step Implementation: the @Step Annotation

Every * line in the spec binds to a Java method annotated with @Step. A double-quoted value in the spec maps to a placeholder in the annotation text and flows into the method as an argument. Java comparison: in TestNG the @Test method name is free-form and data comes from a @DataProvider; in Gauge the method name is still free-form but the BINDING is through the annotation text — you can rename the method without breaking the spec; change the annotation text and the spec breaks.