Install Webship JS

Webship-js is an automated functional acceptance testing tool built on Playwright and Cucumber-js. You write feature files in plain Gherkin; webship-js provides the browser automation, smart waits, screenshots, HTML reports, and a large library of ready-made step definitions. Installing it into a project takes one command, and the bundled scaffolder gives you a complete, runnable test skeleton.

Requirements

  • Node.js 20 or later (the package declares "engines": { "node": ">= 20.0" }).
  • npm (or a compatible package manager) in an existing project with a package.json.
  • A browser binary for Playwright - the scaffolder runs playwright install chromium for you unless you pass --skip-browsers.

Install

Install Webship-js on your project. Simply execute the following command:

npm install webship-js --save-dev

The post-install script copies a starter cucumber.js, playwright.config.ts, and tests/ skeleton into your project on first install. You can also (re)scaffold explicitly at any time - it is idempotent and never overwrites your files unless you ask it to:

npx init-webship-js

Usage: init-webship-js [options]
  -f, --force          Overwrite existing files
      --skip-browsers  Skip `playwright install chromium`
      --cwd <dir>      Target directory (default: $INIT_CWD or cwd)
  -h, --help           Show this help

Project layout

After install, your project contains:

your-project/
├── cucumber.js                      # Profiles + worldParameters (launchUrl, selectors, screenshots, …)
├── playwright.config.ts             # Browser launch + context options
├── tsconfig.json                    # Lets TypeScript step definitions run with no build step
└── tests/
    ├── features/                    # *.feature files (Gherkin)
    │   └── check-homepage.feature   # Sample feature added by the scaffolder
    ├── reports/                     # cucumber_report.json / .html output
    ├── selectors/                   # CMS / framework selector JSON (optional)
    └── step-definitions/
        └── custom.js                # Your custom step definitions

The generated cucumber.js loads the webship-js core step definitions from node_modules/webship-js/tests/step-definitions/ plus anything you add under tests/step-definitions/. A commented-out line enables the optional Diffy visual-regression steps, and a commented diffy: block in worldParameters holds their configuration. All tunables - launchUrl, wait times, selector files, responsive breakpoints, screenshot behavior - live in worldParameters and are documented on the Global Settings page. Step definitions can be plain JavaScript or TypeScript, mixed freely in the same project.

Automated Functional Acceptance Testing

Write your first scenario in tests/features/smoke.feature - plain English, no JavaScript required:

Feature: Sign in

  Scenario: Successful login
    Given I am on "/login"
    When I fill in "Email" with "alice@example.com"
     And I fill in "Password" with "s3cret"
     And I press "Sign in"
    Then I should see "Welcome, Alice"

Make sure your site is running on http://localhost:8080 (or set LAUNCH_URL to point elsewhere), then run:

npm test

Useful variants generated into your package.json scripts:

# Pick a browser
npm run test:chromium
npm run test:firefox
npm run test:webkit

# Watch the browser interactively
npm run test:headed

# Environment overrides
LAUNCH_URL=https://staging.example.com npm test
HEADLESS=false SLOW_MO=0 npm test

Every run auto-generates an HTML report at tests/reports/cucumber_report.html, and failing steps save a screenshot to screenshots/ for instant debugging. Actions use automatic smart waits - no sleep needed in the happy path.

Boost your site's success with automated testing

For Commercial Professional Support

Contact Us

Documentation Structure

The page is part of the Webship JS 2.0.x documentation section, which includes:

There is also a subsection on "DDEV Webship-JS" available under the installation guide, for teams running sites in DDEV.