This template repository helps you automate testing of web applications using Serenity/JS, Cucumber, and Playwright, and comes pre-configured with TypeScript, linting, reporting, and example test scenarios.
Use this template to accelerate your test automation setup and generate Serenity BDD living documentation.
View live reports generated by this template:
- Pre-configured Serenity/JS + Cucumber + Playwright + TypeScript setup
- Example BDD scenarios demonstrating web application testing
- Screenplay Pattern implementation showcasing reusable tasks and interactions
- Integrated reporting with Serenity BDD living documentation
- ESLint configuration for code quality and consistency
- CI-ready scripts and development environment support
- Ready-to-use GitHub Codespaces environment using the official Serenity/JS Docker image
Launch this project in an online development environment:
Follow the Serenity/JS installation guide to set up your development environment with the following prerequisites:
- Node.js (LTS version recommended)
- Java JRE 17+
Create a new GitHub repository from this template and clone it to your machine:
git clone <your-repo-url>
cd <your-project>Install the project dependencies and Playwright browsers:
npm ci
npx playwright installIf your environment requires proxy configuration or an internal registry like Artifactory or Nexus, add an .npmrc file
with the appropriate configuration 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/
Run the example tests:
npm test
View the Serenity BDD report generated under the following path:
- Serenity BDD:
./target/site/serenity/index.html
Alternatively, serve the Serenity BDD report using the built-in HTTP server, accessible at http://localhost:8080:
npm run start
The project provides several NPM scripts defined in package.json:
npm run lint # runs code linter
npm run lint:fix # attempts to automatically fix linting issues
npm run clean # removes reports from any previous test run
npm test # executes the example test suite
# and generates the report under ./target/site/serenity
npm start # starts a mini HTTP server and serves the test reports
# at http://localhost:8080
# Run all tests
npm test
# Run specific feature file
npm test -- features/authentication/form-based_authentication.feature
# Run tests with specific tags
npm test -- --tags "@smoke"
# Run tests in headed mode (see the browser)
HEADLESS=false npm test
# Run tests with different configuration
npm test -- --profile <profile-name>The template follows a clear structure to help you organize your tests:
features/
├── authentication/
│ ├── form-based_authentication.feature # Cucumber feature files
│ └── readme.md # Feature narrative
├── step-definitions/ # Cucumber step definitions
│ ├── parameter.steps.ts # Custom parameter types
│ └── the-internet.steps.ts # Step definitions for test scenarios
└── support/
└── serenity.config.ts # Serenity/JS configuration
test/ # Screenplay Pattern implementations
├── Actors.ts # Actor configuration with abilities
├── authentication/ # Example authentication-related tasks
│ ├── Authenticate.ts
│ └── VerifyAuthentication.ts
└── examples/
└── PickExample.ts # Example navigation tasks
cucumber.js # Cucumber profile configuration
target/site/serenity/ # Generated Serenity BDD reports
Key files:
features/*.feature- Cucumber scenarios written in Gherkin (Given/When/Then)features/step-definitions/- Cucumber step definitions connecting Gherkin to implementationtest/- Tasks and questions following the Screenplay Pattern
- Replace the example tests with your own
- Add new tasks, interactions, and assertions using Serenity/JS
- Extend the test suite or integrate it into CI/CD pipelines
- Use the sample reports to understand expected testing and reporting workflows
If you see errors about browsers not being installed, run:
npx playwright installIf the report server fails to start because port 8080 is in use, you can specify a different port:
npx http-server -p 3000 target/site/serenity -s -oSerenity BDD reports require Java 17 or higher. Verify your installation:
java -versionIf Java is not installed, download it from Oracle or use a package manager:
- macOS:
brew install openjdk@17 - Linux:
sudo apt-get install openjdk-17-jre - Windows: Download from Oracle or use Chocolatey:
choco install openjdk17
- Using Serenity/JS with Cucumber
- API Reference
- Screenplay Pattern Guide
- Serenity/JS Project Templates
- More examples and reference implementations
- Tutorial: First Web Scenario
- Tutorial: First API Scenario
Contributions of all kinds are welcome! Get started with the Contributing Guide.
Join a thriving community of developers using Serenity/JS to deliver high-quality software!
- 📰 Get the latest updates on LinkedIn - Product announcements, tutorials, and best practices
- 📺 Watch tutorials on YouTube - Video guides and conference talks
- 💬 Join the Community Chat - Real-time help and discussions
- 💡 Browse the Discussions Forum - Q&A and feature discussions
- Check out How to...? for answers to common questions
Love Serenity/JS? Help others discover the framework:
⭐ Star the Serenity/JS repository on GitHub
Starring the repository helps increase visibility and shows your support for the project!
The Serenity/JS code base is licensed under the Apache-2.0 license, while its documentation and the Serenity/JS Handbook are licensed under the Creative Commons BY-NC-SA 4.0 International.
See the Serenity/JS License.
Support the ongoing development of Serenity/JS and the open-source community:
Sponsor benefits:
- 🎓 Access to Serenity/JS Playbooks - Advanced patterns and best practices
- 🏆 Priority support in the Community Discussions Forum
- 💚 Support open-source development and help keep Serenity/JS free for everyone
Need dedicated support, training, or consulting for your team?
Contact Jan Molak for:
- 🎯 Consulting & Training - Custom workshops and team training sessions
- 🤝 Corporate Support - Dedicated technical support and SLA-backed assistance
- 🏗️ Architecture Reviews - Expert guidance on test automation strategy and implementation
- 📊 Corporate Sponsorship - Tailored partnership opportunities for organizations