Cucumber Sentences

# cucumber-sentences

A Ruby gem that ships ~39 pre-built generic Cucumber step definitions on top of `page-object` + `watir` + `rspec-expectations`. The whole library is a single file; once required, every page in the host project speaks the same Gherkin DSL without re-implementing selenium boilerplate.

> Source: <https://github.com/donkeycode/cucumber-sentences> · gem name: `cucumber-sentences` · file: `lib/cucumber-sentences.rb` (~500 LOC).

---

## When to invoke this skill

Trigger on any of:

- A `.feature` file is being created or edited and you must decide whether to **reuse** an existing sentence or write a custom step.
- A new button, field, or element on a page must become referenceable from features (`I click on the button "..."`, `I fill "..." field with "..."`, …).
- A new page is being introduced — needs a `PageObject`-style class with the `get_button` / `get_field` / `get_element_by_name` lookups wired correctly.
- A `Cucumber::Undefined` error or "undefined step" feedback appears — the phrase is probably misspelled relative to the catalogue, or the page lacks a name in its lookup hash.
- A request to add a "kind" of object resolvable by name (`I am on the "OrderPage" of order "ABC-123"`) — needs a typed helper class under `support/helpers/`.
- A request to share state across steps in the same scenario (an extracted email link, a generated id, …) — needs a session-scoped state holder.

---

## The mental model: phrase → element in five hops

Cucumber-sentences is glue, not magic. Every browser-touching phrase follows the same chain. Internalise this before writing or debugging steps.

```
Gherkin string
    │  ① Cucumber regex match (captures the name)
    ▼
get_button("save profile")  ← method on @current_page (a PageObject)
    │  ② Hash lookup that you wrote on the page class
    ▼
save_element                ← page-object accessor
    │  ③ Synthesised by `button(:save, :xpath => "...")`
    ▼
Watir::Element              ← live DOM handle
    │  ④ Watir verb (when_visible, click, value=, text, …)
    ▼
Browser action              ← what actually happens
```

| Phrase family | Resolver method called on `@current_page` |
| --- | --- |
| `... button "<name>" ...` (click, see, not see, see disabled) | `get_button(name)` |
| `... field "<name>" ...`, `I fill "<name>" {field\|autocomplete\|datepicker\|contenteditable} with ...`, `I can see "..." in input "<name>"`, `I should not see the field "<name>"` | `get_field(name)` |
| `I should not see the element "<name>"`, `I can [not] see "..." in element "<name>"`, `I scroll to "<name>"`, `I hover over the element "<name>"`, `I should see the element "<name>"` | `get_element_by_name(name)` |
| `I fill "<name>" ckeditor field with "..."`, `I can see "..." in ckeditor "<name>"` | `get_ckeditor(name)` |
| `I fill "<name>" js field with "..."`, `I force scroll to "<name>"` | `get_js_selector(name)` |
| `I upload a file with the filename "..." in element "<name>"` | `get_field(name)` (Watir treats file inputs as fields) |

The **layered indirection** — Gherkin name → `get_X` hash → page-object accessor → Watir handle — is deliberate:

- Gherkin names track product copy, not markup.
- `get_X` hashes localise renames in a single file.
- Page-object declarations isolate locator strategy (xpath/id/css).
- Watir is the only stable thing the gem talks to.

**Adding a new button to a feature does not require a new step.** Extend the page's locator block + the `get_button` hash, and the existin