Step Definitions

A step definition is a piece of JavaScript that maps a plain English Gherkin phrase (for example When I press "Submit") to a Playwright action or assertion. Webship-js ships 411 built-in steps across 36 step files, so Product Owners, PMs, QA, CQ, DevOps, and automation engineers can author end-to-end tests without writing custom code.

How steps are organized

Each step group lives in its own file at tests/step-definitions/<group>.steps.js inside the webship-js package, and each group has its own documentation page below. Groups follow the test lifecycle: Given steps set the scene (navigate, restore auth, load fixtures), When steps act (click, fill, press, request), and Then steps verify outcomes (text, elements, headers, payloads). Every action step is backed by BBR smart waits - it waits for the page to settle before and after acting - and every phrasing accepts the pronoun prefix (I |we )* so scenarios read naturally in either voice. A typical scenario mixes steps from several groups:

Feature: Contact form

  Scenario: Visitor sends a message
    Given I am on "/contact-us.html"          # navigation
    When I fill in "Name" with "Alice"        # forms
     And I press "Send"                       # actions
    Then I should see "Thank you"             # assertions
     And there should be no JavaScript errors # javascript errors

The four sections below organize every step group by how teams use them. Follow any link to see the full step list with role-targeted explanations and examples.

User journeys

How the visitor moves through your site and interacts with the page.

  • Navigation - Anonymous user, homepage, arbitrary paths, back/forward history, reload, and URL assertions.
  • Actions - Press buttons, click links and elements, follow links, attach files. The fundamentals of every scenario.
  • Forms - Fill fields, select options, check/uncheck boxes, pick radios - targeted by label, placeholder, name, or id.
  • Field state - Assert what is currently in inputs, selects, checkboxes, and radios, including enabled/disabled state.
  • Pointer input - Hover, drag and drop, double-click, right-click, tap, and viewport sizing.
  • Keyboard - Single keys and combos (e.g. Control+A) with alias normalization for common key names.
  • Scrolling - Page and element scrolling: to top, to bottom, left/right, and into view.
  • Links - Assert link href, title, target, and rel attributes before your visitors click them.
  • Modals - HTML modal visibility and content assertions, clicks scoped inside the modal, and closing.
  • Browser dialogs - Native alert, confirm, and prompt handling: accept, dismiss, answer, and assert message text.

Outcome verification

What the page shows, how it is structured, what the server returned.

  • Assertions - Page-level text and element assertions, including text in a specific element, table row, or region scope.
  • Web-first matchers - Auto-retrying matchers with a within-N-seconds budget; they pass the moment the condition becomes true.
  • Element interactions - Focus, scroll-to, click-on-element, dispatch events, and position/CSS property checks.
  • Tables - Data table assertions by row and column, plus clicking text within a matching row.
  • Meta tags - Description, keywords, Open Graph, and Twitter card assertions for SEO and social sharing.
  • Response headers - Inspect status codes plus cache, security, and CDN headers on every release.

APIs and data formats

Drive REST endpoints, inspect JSON, XML, and YAML payloads directly from Gherkin - no browser required.

  • API steps (long form) - REST requests with headers and bodies, status and JSON Pointer assertions on the response.
  • REST steps (short form) - Same backend coverage as the API group with terser phrasings for quick smoke checks.
  • XML responses - XPath-style element, attribute, count, and namespace assertions on XML payloads (feeds, sitemaps, SOAP).
  • YAML responses - Path-based assertions, multi-document streams, type checks, JSON Schema validation, and golden-file diffs.
  • URL paths - Path, query parameter, and fragment assertions on the current URL.

Test resilience and instrumentation

Smart waits, mocked dependencies, accessibility audits, visual evidence, debug hooks.

  • Waits - Smart waits and edge waits: wait for text, elements, URLs, and network idle. Never sleep.
  • Clock - page.clock install, advance, pause, and set for deterministic time in date-dependent UIs.
  • Network - Route stubs and mocks, response delays, request blocking, and offline mode.
  • Storage - Set and assert localStorage and sessionStorage keys and values.
  • Cookies - Cookie existence, value, and attribute assertions; set and delete cookies.
  • Auth state - Save and restore Playwright storageState so logged-in sessions are reused across scenarios.
  • JavaScript errors - Track console and page errors during the scenario and assert a clean console.
  • Accessibility - POUR smoke checks: alt text, form labels, landmarks, heading order, focus, and page language.
  • Iframes - Switch into and out of frames and run frame-scoped interactions and assertions.
  • File downloads - Capture triggered downloads and assert filename, size, and content.
  • Selector registry - Named CSS and XPath selectors plus 22 CMS / framework presets (Drupal, WordPress, and more).
  • Responsive viewports - Named breakpoints (xs through xxxl) plus explicit width/height sizing.
  • Screenshots - Manual capture on demand, auto-on-failure, and per-step hooks with configurable filenames.
  • Video recording - Playwright recordVideo with start, stop, and save steps for shareable evidence.
  • Debug - Print the current URL or last response and pause the run for inspection.

Where the steps live

Source code: tests/step-definitions/<group>.steps.js. Every file carries a JSDoc block with at least five Gherkin examples per step, and every step phrasing supports the pronoun prefix (I |we )* so your scenarios read naturally in either voice. Visual-regression steps are documented separately under Diffy Step Definitions, and every configuration knob the steps honor is listed in Global Settings.