Serenity/JS + Cucumber + WebdriverIO + Percy + Eyes template

Kickstart your web application acceptance testing with Serenity/JS, Cucumber, WebdriverIO and Percy using this template repository.

Learn more about Serenity/JS: Serenity/JS and WebdriverIO guide

🚀 Quick Start

1. Create a Project

This repository is a GitHub template. Use it to create a new GitHub repository for your project.

2. Set Up Your Environment

Install the required tools:

• Node.js (LTS version 18.12 or later)

• Java (JRE or JDK version 11 or later)

Follow the installation guide to verify your setup.

If using Percy:
Follow their docs to create an account, create a project, and get your token to use.
Pass your token as an environment variable PERCY_TOKEN.

If using Applitools Eyes:
Follow their docs to create an account, create an app, and get your API key to use.
Pass your API key as an environment variable APPLITOOLS_API_KEY.

Also, consider these environment variables in you .env file:

EXEC_MODE=
EYES_ULTRAFAST_GRID=
EYES_EXECUTION_CLOUD=

To decide which visual regression tool to use and, in case of Applitools Eyes, how to run the tests (i.e. Ultrafast Grid takes several screenshots emulating different devices).
EXEC_MODE can be set to:

• everything (runs all tests).
• percy (runs only Percy visual tests).
• eyes (runs only Eyes visual tests).

3. Install Dependencies

Clone the project and run:

npm ci

This installs dependencies, including the Serenity BDD CLI.

4. Run Tests

Use the predefined NPM scripts defined in package.json to run your tests and related tasks:

npm test                # Run non visual tests and generate reports
npm test:visual:percy   # Run visual tests with Percy and generate reports
npm test:visual:eyes    # Run visual tests with Eyes and generate reports
npm start               # Serve test reports at http://localhost:8080

npm run lint            # Run code linter
npm run lint:fix        # Try to automatically fix linting issues
npm run clean           # Remove test reports from any previous test run

5. Write your tests

Test scenarios are located in the ./test/specs directory. Modify the examples or write your own scenarios using the Serenity/JS Screenplay Pattern.

🌟 Features

• All automation tools ready to go: Start testing immediately with WebdriverIO, Serenity/JS and Cucumber already integrated and configured.
• Ready for Percy: Percy is integrated in this SerenityJS template thanks to the TakePercyScreenshot ability and the PercySnapshot interaction.
• Serenity BDD Reports: Serenity BDD reporter pre-configured with reports available at ./target/site/serenity
  • Published Reports: Reports for this repository are published to GitHub Pages and available at https://serenity-js.github.io/serenity-js-cucumber-webdriverio-template/.
• Screenplay Pattern: Out-of-the-box integration with the Serenity/JS actors and Screenplay Pattern APIs
• GitHub Actions: Continuous Integration setup included
• VS Code: Pre-configured for a seamless developer experience

🔧 Configuration for Corporate Networks

If you're behind a proxy or use an internal registry, configure an .npmrc file in your home directory:

proxy=http://user:password@host.mycompany.com:8080/
https-proxy=http://user:password@host.mycompany.com:8080/
strict-ssl=false
registry=https://artifactory.mycompany.com/artifactory/

💡️ Learn Serenity/JS

• Serenity/JS WebdriverIO integration guide - Integrate Serenity/JS with your WebdriverIO test suite, enable Serenity BDD reports, and start using the Screenplay Pattern
• Serenity/JS Handbook - Write high-quality automated acceptance tests with Serenity/JS
• Serenity/JS API documentation - Explore Serenity/JS modules and features
• Serenity/JS Project Templates - Kickstart your projects with best practices built right in

👋 Join the Serenity/JS Community

• Serenity/JS Community chat channel - Meet Serenity/JS developers and maintainers
• Serenity/JS Forum - Find answers to your Serenity/JS questions
• Contribute to Serenity/JS - Learn how to propose features, report bugs, and contribute to the Serenity/JS codebase

📣 Stay up to date

• Serenity/JS on YouTube - Subscribe for tutorials, demos, conference talks, and more
• Serenity/JS on LinkedIn - Follow for release and community event announcements
• Serenity/JS on GitHub - Star Serenity/JS to help others discover the framework!

💛 Support Serenity/JS

Support our mission to make test automation collaborative and easier to scale. Become a Serenity/JS GitHub Sponsor today!