@webship-js/diffy-steps

Diffy-specific Cucumber step definitions for webship-js — a Playwright + Cucumber BDD testing framework. @webship-js/diffy-steps adds a diffy.steps.js step-pack that captures full-page Playwright screenshots at multiple breakpoints and drives Diffy visual-regression comparisons through the Diffy REST API, so you can express visual checks as readable Gherkin instead of hand-rolling API calls.

It is a plugin for webship-js — it does not run standalone. It ships one file of step definitions; you drop it into an existing (or new) webship-js test project.

What's covered

• Viewport resizing and full-page screenshot capture, buffered in the World
• Breakpoint loops driven by DIFFY_BREAKPOINTS
• Custom snapshot upload (create-custom-snapshot, multipart)
• Diff creation, named and unnamed
• Server-side environment screenshots and env-to-env comparison
• Folder upload of pre-existing PNGs
• Diff polling until the comparison completes

See tests/step-definitions/diffy.steps.js for the full list of steps with Gherkin examples, and tests/step-definitions/README.md for the adoption guide, the environment-variable table, and the Diffy API reference.

Requirements

• Node.js >= 20
• An existing webship-js 2.x test project (or run npx init-webship-js to create one)
• A Diffy account, project id, and API key — for real comparisons. The bundled mock server covers local development without one.

Installation

npm install --save-dev webship-js @webship-js/diffy-steps

Add both step-definition paths to your project's cucumber.js:

module.exports = {
  default: {
    require: [
      'node_modules/webship-js/tests/step-definitions/**/*.js', // webship-js core steps
      'node_modules/@webship-js/diffy-steps/tests/step-definitions/**/*.js', // this plugin
      'tests/step-definitions/**/*.js', // your own custom steps, if any
    ],
    paths: ['tests/features/**/*.feature'],
    worldParameters: {
      launchUrl: process.env.LAUNCH_URL || 'https://your-site.example',
      diffy: {
        apiKey: '',                                 // prefer DIFFY_API_KEY
        projectId: 0,                               // DIFFY_PROJECT_ID
        breakpoints: '640,1200',                    // DIFFY_BREAKPOINTS
        baseUrl: 'https://app.diffy.website/api/',  // DIFFY_API_BASE_URL
      },
    },
  },
};

Configuration resolves in this order, highest first:

1. process.env.DIFFY_*
2. cucumber.js worldParameters.diffy.*
3. built-in defaults

Never commit an API key. Put it in CI secrets or a git-ignored .env.local and export DIFFY_API_KEY.

Quick example

Feature: Visual regression

  @diffy
  Scenario: Compare two pages across breakpoints
    Given I am on "/"
    Then I take screenshots for all breakpoints
    And send screenshots to diffy with name "baseline"

    Given I am on "/about-us"
    Then I take screenshots for all breakpoints
    And send screenshots to diffy with name "feature-branch"

    Then create diffy comparison with name "PR-42"
    And wait for diffy comparison to complete

More runnable examples: tests/features/.

Steps

Step	Diffy API call
When I resize window to "<px>"	— (Playwright viewport)
Then I take screenshot	— (buffered in World)
Then I take screenshots for all breakpoints	— (loops DIFFY_BREAKPOINTS)
Then send screenshots to diffy with name "<name>"	POST projects/{id}/create-custom-snapshot
Then create diffy comparison	POST projects/{id}/diffs
Then create diffy comparison with name "<name>"	POST projects/{id}/diffs
Then create diffy screenshot from "<env>" environment	POST projects/{id}/screenshots
Then compare diffy "<env1>" with "<env2>"	POST projects/{id}/compare
Then upload folder "<path>" to diffy as "<name>"	POST projects/{id}/create-custom-snapshot
Then wait for diffy comparison to complete	GET diffs/{id} (polling)

Per-step documentation: docs/.

Environment variables

Variable	Purpose	Default
DIFFY_API_KEY	Diffy API key (keys page)	required for real runs
DIFFY_PROJECT_ID	Diffy project id	required for real runs
DIFFY_BREAKPOINTS	Comma list of breakpoints, e.g. "640,1200"	1200
DIFFY_WINDOW_HEIGHT	Default viewport height	2000
DIFFY_SCREENSHOTS_DIR	On-disk copy of screenshots (debugging)	unset
DIFFY_API_BASE_URL	Override the API base URL (used for mocking)	https://app.diffy.website/api/
DIFFY_MAX_WAIT	Seconds to poll diffs/{id} before failing	1200
DIFFY_ENV1_URL	Custom env1 URL for compare diffy "custom" with ...	unset
DIFFY_ENV2_URL	Custom env2 URL for compare diffy ... with "custom"	unset

Running this repo's own test suite

This repository is itself a working webship-js project. Its features run against the bundled example pages in examples/diffy/ and a local mock Diffy API (tests/support/mock-diffy-api/), so the default run needs no Diffy account and no network access.

npm install
npx playwright install --with-deps chromium
npm start &          # serves examples/ on http://localhost:8080
npm test             # mock Diffy API, @real-api scenarios excluded

Against the real Diffy API:

export DIFFY_API_KEY="your-key"
export DIFFY_PROJECT_ID="30542"
export DIFFY_API_BASE_URL="https://app.diffy.website/api/"
export DIFFY_BREAKPOINTS="640,1200"
npx cucumber-js --tags "@real-api"

The project's allowed URLs must cover LAUNCH_URL — expose the local examples/ through a tunnel, or point LAUNCH_URL at a hosted copy.

Other scripts:

Script	Effect
npm test	Full suite, pretty output, mock Diffy API
npm run test:dry	--dry-run — checks for undefined/ambiguous steps only
npm run test:headed	Headed browser
npm run test:chromium / test:firefox / test:webkit	Pick a browser
npm start	Serve examples/ on :8080

Example pages

examples/diffy/baseline.html and examples/diffy/changed.html are a deliberate before/after pair — the changed page shifts the palette, adds a badge and a section, and alters pricing, so Diffy has real differences to report. examples/diffy/index.html links both.

Contributing

Issues and pull requests are tracked on GitHub. 2.0.x is the repository's single active branch, tracking the webship-js 2.0.x line.

Credits

Extracted from webship-js, where these steps first shipped as the opt-in tests/step-definitions-diffy/ layer.

License

MIT © Webship.co — see LICENSE.