Form steps are the everyday workhorses: fill inputs, select dropdown options, check boxes, and pick radio buttons the way a user describes them - by visible label, placeholder, or name - rather than by brittle CSS paths. Every phrasing accepts I or we as the subject, and most exist in both directions (fill in "Username" with "John" and fill in "John" for "Username") so scenarios read naturally either way.
Each step has an attribute-addressed twin ending in by attr / by attribute. Without an explicit attribute name, the value is matched against a broad set - id, class, name, data-testid, data-test-id, data-test, data-cy, aria-label, value, placeholder, and title - so fill in "uname" with "John Smith" by attr finds the input however the front-end team tagged it. Name a specific attribute with by its "placeholder" attribute when you need precision. Registered names from the selector registry also resolve through the by attr path.
After every fill, select, check, uncheck, and radio step, webship-js silently runs a BBR smart-settle pass, so AJAX-driven forms (Drupal states, conditional fields, autocomplete) are typically ready for the next step without an explicit wait. Failures raise friendly errors with hints - for example, the select step reminds you that option text is case-sensitive and that multi-selects need additionally select.
Quick reference
| Step | What it does |
|---|---|
When I fill in "Username" with "John Smith" | Fill a field located by label, placeholder, or name. |
When I fill in "#uname" with "John Smith" by attr | Fill a field located by attribute. |
When I fill in "Username" with: | Clear a field located by label. |
When I fill in "#uname" with: by attr | Clear a field located by attribute. |
When I fill in "jon-smith" for "Username" | Fill by label - reverse (value-first) syntax. |
When I fill in "John Smith" for "#uname" by attr | Fill by attribute - reverse syntax. |
When I fill in the following: | Fill multiple fields from a table, located by labels. |
When I fill in the following: by attr | Fill multiple fields from a table, located by attribute. |
When I select "Mercedes" from "Cars" | Select a dropdown option by label, id, class, or name. |
When I additionally select "Red" from "Colors" | Add an option to a <select multiple> without clearing the current selection. |
When I check "Remember me" | Check a checkbox by label, id, class, or name. |
When I uncheck "Remember me" | Uncheck a checkbox by label, id, class, or name. |
When I select radio button "Male" | Select a radio by label, value, id, or class. |
Steps in detail
When I fill in "..." with "..." and When I fill in "..." for "..."
The standard fill. The field resolves via <label for=...>, placeholder, or [name] - whichever matches first. The reverse syntax swaps value and field for scenarios written value-first; both call the same fill logic.
When I fill in "Username" with "John Smith"
And I fill in "1234" for "Password"
When I press "Login"
Then I should see "You enter Username: John Smith and Password: 1234"When I fill in "..." with "..." by attr
Attribute-addressed fill. Pass a raw selector (#uname), a bare token matched against the common attribute set, or name the attribute explicitly. The reverse for ... by attr form also exists.
When I fill in "#uname" with "John Smith" by attr
And I fill in "pwordcss" with "1234" by "class" attr
And I fill in "Your full name" with "John Smith" by its "placeholder" attributeWhen I fill in "..." with: (clear a field)
The colon-terminated form with no value clears the field. Both the label and the attribute (with: by attr) variants exist. Handy before re-typing into a pre-populated edit form.
When I fill in "Username" with:
And I fill in "Password" with:
When I press "Login"
Then I should see "You enter Username: and Password:"When I fill in the following: (table fill)
Fills many fields in one step from a two-column table of | label | value | rows, resolving each label through the same label / placeholder / name chain. The by attr variant takes | attribute-value | value | rows instead, optionally pinned to a named attribute.
When I fill in the following:
| Username | webshipco |
| Password | s3cret |
When I fill in the following: by its "placeholder" attribute
| Your full name | John Smith |
| Your Password | s3cret |When I select "..." from "..."
Selects a dropdown option. The list resolves by #id / .class selector, single-token [name] or id, or exact label text. The option is matched by visible label first, then by value attribute as a fallback - so select "mercedes" from "cars" (value) and select "Mercedes" from "Choose a car:" (label) both work. On failure you get hints about case-sensitivity and value-based selection.
When I select "Saab" from "#cars"
When I select "mercedes" from "cars"
When I select "Saab" from "Choose a car:"When I additionally select "..." from "..."
For <select multiple>: reads the currently selected values, adds the new option (matched by label or text, with a clear error if it does not exist), and re-applies the combined set - so previous choices survive. Build multi-selections as a select followed by additionally select chains.
When I select "Red" from "Colors"
And I additionally select "Blue" from "Colors"
And I additionally select "Green" from "Colors"When I check "..." / When I uncheck "..."
Check or uncheck a checkbox. #id and .class values are used as selectors; anything else is tried as an exact label, then as a checkbox id, name, or value. Errors include the underlying cause plus hints about visibility and disabled state.
When I check "Remember me"
And I check "#newsletter"
And I uncheck ".terms-and-conditions"When I select radio button "..."
Selects a radio by #id / .class selector, by value attribute, or by exact label - tried in that order. For asserting the resulting state, see the radio assertions in the field steps group.
When I select radio button "Male"
When I select radio button "female"
When I select radio button "#gender-male"Complete example
From tests/features/test--when--i-fill-in.feature, against the bundled fixture examples/test--when--i-fill-in.html:
Feature: An example of filling an input textbox with a value using its label.
Scenario: Check filling an input field with a value using its label.
Given I am on "/test--when--i-fill-in.html"
When I fill in "Username" with "John Smith"
When I fill in "Password" with "1234"
When I press "Login"
Then I should see "You enter Username: John Smith and Password: 1234"
Scenario: Check filling a table of input fields using their labels.
Given I am on "/test--when--i-fill-in.html"
When I fill in the following:
| Username | John Smith |
| Password | 1234 |
When I press "Login"
Then I should see "You enter Username: John Smith and Password: 1234"Tips
- Reach for labels first; fall back to
by attronly when a field has no label or placeholder. Label-based steps survive theme and markup churn. - For select lists, remember: quoted values matching the option's visible text win; if that fails the step retries with the
valueattribute. Multi-selects needadditionally selectto build up a selection. - State assertions live elsewhere: field emptiness, checkbox and radio state, and option-selected checks are in field steps; CSS-selector fill/check/choose variants are there too.