This starter template helps you test React components using Serenity/JS and the Playwright Test runner in Component-Test mode, and comes pre-configured with TypeScript, linting, reporting, and example React components with test scenarios.
Component testing enables you to test React components in isolation, without the need for a full application setup. This approach provides faster feedback, better test isolation, and more focused test scenarios compared to full end-to-end tests.
Use this template to accelerate your component testing setup and generate enhanced Playwright Test reports and Serenity BDD living documentation.
View live reports generated by this template:
- Pre-configured Serenity/JS + Playwright Component Test + React + TypeScript setup
- Example React components (Dropdown) with corresponding test scenarios
- Screenplay Pattern implementation demonstrating reusable page elements and interactions
- Integrated reporting with Serenity BDD and Playwright Test HTML reports
- 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:[email protected]:8080/
https-proxy=http://user:[email protected]:8080/
strict-ssl=false
registry=https://artifactory.mycompany.com/artifactory/
Run the example tests:
npm test
View the test reports generated under the following paths:
- Serenity BDD:
./target/site/serenity/index.html - Playwright Test:
./playwright-report/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 tests in specific browser
npx playwright test -c playwright-ct.config.ts --project=chromium
# Run tests in headed mode (see the browser)
npx playwright test -c playwright-ct.config.ts --headed
# Run tests in debug mode
npx playwright test -c playwright-ct.config.ts --debug
# Run a specific test file
npx playwright test -c playwright-ct.config.ts src/components/Dropdown/Dropdown.spec.tsxThe template follows a clear structure to help you organize your components and tests:
src/
├── components/ # Your React components
│ ├── Dropdown/ # Example: Dropdown component
│ │ ├── Dropdown.tsx # React component implementation
│ │ ├── Dropdown.spec.tsx # Component test scenarios
│ │ ├── Dropdown.serenity.ts # Serenity/JS page objects (Screenplay Pattern)
│ │ └── index.tsx # Component exports
│ ├── index.ts # Components barrel export
│ └── serenity.ts # Serenity/JS barrel export
├── index.ts # Main entry point
├── serenity.ts # Main Serenity/JS entry point
└── style.css # Global styles
playwright/ # Playwright CT configuration
├── index.html # Test runner HTML template
└── index.tsx # Test runner setup
playwright-ct.config.ts # Playwright Component Test configuration
target/site/serenity/ # Generated Serenity BDD reports
playwright-report/ # Generated Playwright Test reports
Key files:
*.tsx- React component implementations*.spec.tsx- Test scenarios using Serenity/JS and Playwright CT*.serenity.ts- Reusable page objects following the Screenplay Pattern
- Replace sample components: Remove the
Dropdownexample and add your own React components insrc/components/ - Create Serenity/JS page objects: Define reusable test code following the Screenplay Pattern (see
Dropdown.serenity.tsfor examples) - Write test scenarios: Add
*.spec.tsxfiles alongside your components to test them in isolation - Customize reporting: Configure test metadata and tags in your test scenarios for better living documentation
- Integrate into CI/CD: Use the provided npm scripts in your continuous integration pipeline
- Explore the reports: Review the generated Serenity BDD and Playwright reports to understand test results and living documentation
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 -oEnsure your component exports are correct in the index.tsx files and that you're importing from the right path in your test files.
Serenity 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
- 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