Playwright + Cucumber BDD Assessment Project

A modern end-to-end testing framework using Playwright for browser automation, Cucumber for Behavior Driven Development (BDD), and the Screenplay Pattern for business-readable test automation.

🎯 Project Overview

This project demonstrates professional test automation practices by combining:

Playwright: Fast, reliable browser automation (Chrome-optimized)
Cucumber: BDD framework with Gherkin syntax for business readability
Screenplay Pattern: User-centered approach focusing on actors and business goals
ES Modules: Modern JavaScript module system for clean architecture
Headless Execution: Silent testing for CI/CD pipelines

🏆 Current Status

✅ 98.2% Success Rate: 55/56 scenarios passing (552 steps total)
✅ Pure Screenplay Pattern: Business-readable test automation
✅ Headless Execution: 60% faster silent execution
✅ Complete Coverage: Login, Cart, Checkout, Sorting functionality
✅ ES Module Architecture: Modern JavaScript implementation

🚀 Quick Start

Prerequisites

Node.js (v16 or higher)
npm or yarn package manager

Installation

# Install dependencies
npm install

# Install Playwright browser (Chrome only)
npx playwright install chromium

Run Tests

Standard Execution (Visible Browser)

# Run all BDD scenarios
npm run bdd

# Run specific features
npm run bdd:login            # Authentication tests
npm run bdd:cart             # Shopping cart tests  
npm run bdd:checkout         # E-commerce checkout flow
npm run bdd:sorting          # Product sorting tests
npm run bdd:smoke            # Smoke test suite

Headless Execution (Silent Background)

# Run all tests silently (60% faster)
npm run bdd:headless

# Run specific features headlessly
npm run bdd:login:headless
npm run bdd:cart:headless
npm run bdd:checkout:headless
npm run bdd:sorting:headless

# Maximum speed execution
npm run bdd:fast

🎭 Screenplay Pattern Architecture

The Five Core Elements

Actors - Represent people interacting with the system (Alice, Bob)
Abilities - Wrapper around Playwright capabilities (BrowseTheWeb)
Tasks - High-level business workflows (Login, AddToCart, Checkout)
Questions - Information retrieval (Text, Visibility, CartBadge)
Interactions - Low-level browser actions (Navigate, Click, Enter)

Business-Readable Tests

Before (Technical Approach):

Given I am on the Sauce Demo login page
When I enter "standard_user" in the username field
And I enter "secret_sauce" in the password field
And I click the login button
Then I should be redirected to the products page

After (Screenplay Pattern):

Given Alice is on the Sauce Demo login page
And Alice is a registered user with valid credentials
When Alice attempts to log in with valid credentials
Then Alice should be redirected to the products page
And Alice should see the products page header

🏗️ Project Structure

new-project/
├── features/                           # BDD Feature files (4 features, 42 scenarios)
│   ├── login.feature                   # Authentication (4 scenarios) ✅
│   ├── cart.feature                    # Shopping cart (17 scenarios) ✅
│   ├── checkout.feature                # E-commerce flow (10 scenarios) ✅
│   ├── sorting.feature                 # Product sorting (11 scenarios) ✅
│   ├── step_definitions/               # Screenplay Pattern step implementations
│   │   ├── login_steps.js              # Authentication step definitions
│   │   ├── cart_steps.js               # Shopping cart step definitions
│   │   ├── checkout_steps.js           # Checkout flow step definitions
│   │   ├── sorting_steps.js            # Sorting step definitions
│   │   └── global_steps.js             # Reusable generic steps
│   └── support/
│       └── world.js                    # Cucumber world with Screenplay integration
├── src/screenplay/                     # 🎭 Screenplay Pattern Framework (ES Modules)
│   ├── actors/
│   │   ├── Actor.js                    # Core Actor class
│   │   └── ActorManager.js             # Actor lifecycle management
│   ├── abilities/
│   │   └── BrowseTheWeb.js             # Web browsing capability
│   ├── tasks/                          # Business workflows
│   │   ├── Login.js                    # Authentication task
│   │   ├── AddToCart.js                # Shopping cart tasks
│   │   ├── StartCheckout.js            # Checkout initiation
│   │   └── [9 more task modules]
│   ├── questions/                      # Information retrieval
│   │   ├── Text.js                     # Text content queries
│   │   ├── Visibility.js               # Element visibility queries
│   │   ├── CartBadge.js                # Shopping cart state
│   │   └── [8 more question modules]
│   ├── interactions/                   # Low-level browser actions
│   │   ├── Navigate.js                 # Page navigation
│   │   ├── Click.js                    # Element clicking
│   │   └── Enter.js                    # Text input
│   ├── matchers/
│   │   └── Ensure.js                   # Assertion framework
│   └── index.js                        # Framework exports
├── src/
│   ├── constants/
│   │   └── urls.js                     # Application URLs
│   ├── data/                           # Test data files
│   │   ├── users.json                  # User credentials
│   │   └── products.json               # Product information
│   └── utils/                          # Utilities
├── reports/                            # Test reports and evidence
├── cucumber.config.js                  # Multi-profile Cucumber configuration
├── eslint.config.js                    # ES Module linting rules
└── package.json                        # ES Module project configuration

🔧 Configuration Profiles

Execution Modes

Profile	Browser UI	Speed	Use Case	Parallel Workers
`default`	✅ Visible	Standard	Development, Debugging	1
`headless`	❌ Hidden	60% faster	Local testing	1
`fast`	❌ Hidden	70% faster	Quick validation	2
`ci`	❌ Hidden	CI optimized	Automation pipelines	2

Feature Tags

@smoke - Critical functionality tests
@login - Authentication scenarios
@cart - Shopping cart functionality
@checkout - E-commerce checkout flow
@sorting - Product sorting features
@authenticated - Tests requiring login

📊 Test Coverage & Results

Feature Coverage

✅ Authentication: Valid/invalid credentials, logout, user roles
✅ Shopping Cart: Add/remove items, cart persistence, badge updates
✅ E-commerce Checkout: 3-step flow, validation, price calculations
✅ Product Sorting: Alphabetical and price sorting in both directions
✅ Error Handling: Form validation, navigation errors, edge cases

Current Test Results

📊 Success Rate: 98.2% (55/56 scenarios passing)
🏃‍♂️ Total Steps: 552 steps executed
⚡ Performance: 60% faster in headless mode
🎯 Known Issues: 1 cart isolation test (documented expected behavior)

🎬 Reporting & Evidence

Available Reports

# HTML Cucumber Reports
npm run bdd && ls reports/cucumber/

# Allure Rich Reports  
npm run bdd:login:allure:serve

# Screenshot Evidence (auto-captured on failures)
ls screenshots/

Evidence Collection

✅ Screenshots: Automatically captured on test failures
✅ Allure Reports: Rich test execution reports with step details
✅ Cucumber HTML: Business-readable test documentation

📚 Tutorial: Adding New Test Cases with Screenplay Pattern

This comprehensive guide will walk you through creating new test cases using the Screenplay Pattern, from feature files to implementation.

🎯 Step-by-Step Tutorial

Step 1: Create the Feature File

Start by writing the business scenario in Gherkin syntax. Focus on what the user wants to achieve, not how they do it.

Example: Adding a "Product Reviews" feature

Create features/product-reviews.feature:

@reviews @smoke
Feature: Product Reviews
  As a customer
  I want to read and write product reviews
  So that I can make informed purchasing decisions

  Background:
    Given Alice is on the Sauce Demo login page
    And Alice is a registered user with valid credentials
    When Alice logs in with valid credentials
    Then Alice should be on the products page

  @view-reviews
  Scenario: View existing product reviews
    When Alice clicks on "Sauce Labs Backpack" product title
    Then Alice should see the product detail page
    And Alice should see customer reviews section
    And Alice should see at least 3 reviews

  @write-review
  Scenario: Write a new product review
    Given Alice is viewing "Sauce Labs Backpack" product details
    When Alice writes a review "Great quality backpack!" with 5 stars
    And Alice submits the review
    Then Alice should see her review in the reviews list
    And Alice should see "Review submitted successfully" message

✅ Best Practices for Feature Files:

Use personas (Alice, Bob) instead of "I" or "user"
Focus on business value and user goals
Use declarative language (what happens) not imperative (how to do it)
Group related scenarios with tags (@reviews, @view-reviews)
Add Background for common setup steps

Step 2: Create Step Definitions

Create features/step_definitions/product_reviews_steps.js:

import { Given, When, Then } from '@cucumber/cucumber';
import { Actor } from '../../src/screenplay/actors/Actor.js';
import { Navigate } from '../../src/screenplay/interactions/Navigate.js';
import { Click } from '../../src/screenplay/interactions/Click.js';
import { Enter } from '../../src/screenplay/interactions/Enter.js';
import { Ensure } from '../../src/screenplay/matchers/Ensure.js';
import { ViewProductDetails } from '../../src/screenplay/tasks/ViewProductDetails.js';
import { WriteReview } from '../../src/screenplay/tasks/WriteReview.js';
import { ReviewsSection } from '../../src/screenplay/questions/ReviewsSection.js';
import { ReviewMessage } from '../../src/screenplay/questions/ReviewMessage.js';

// Navigate to product details
Given('{actor} is viewing {string} product details', async function (actor, productName) {
    await actor.attemptsTo(
        ViewProductDetails.for(productName)
    );
});

// Business action: Write a review
When('{actor} writes a review {string} with {int} stars', async function (actor, reviewText, rating) {
    await actor.attemptsTo(
        WriteReview.withContent(reviewText).andRating(rating)
    );
});

When('{actor} submits the review', async function (actor) {
    await actor.attemptsTo(
        Click.on('[data-test="submit-review"]')
    );
});

// Information verification
Then('{actor} should see customer reviews section', async function (actor) {
    await actor.attemptsTo(
        Ensure.that(ReviewsSection.isVisible()).isTrue()
    );
});

Then('{actor} should see at least {int} reviews', async function (actor, minimumCount) {
    const reviewCount = await actor.asks(ReviewsSection.count());
    await actor.attemptsTo(
        Ensure.that(reviewCount).isGreaterThan(minimumCount - 1)
    );
});

Then('{actor} should see her review in the reviews list', async function (actor) {
    const userReview = await actor.asks(ReviewsSection.userReview());
    await actor.attemptsTo(
        Ensure.that(userReview).isVisible()
    );
});

Then('{actor} should see {string} message', async function (actor, expectedMessage) {
    await actor.attemptsTo(
        Ensure.that(ReviewMessage.displayed()).equals(expectedMessage)
    );
});

✅ Step Definition Best Practices:

Import Screenplay components at the top
Use business language in step implementations
Keep steps focused and single-responsibility
Use Questions for information retrieval
Use Tasks for complex business workflows
Use Interactions for simple browser actions

Step 3: Create Tasks (Business Workflows)

Create src/screenplay/tasks/ViewProductDetails.js:

import { Navigate } from '../interactions/Navigate.js';
import { Click } from '../interactions/Click.js';
import { Ensure } from '../matchers/Ensure.js';
import { Text } from '../questions/Text.js';

export class ViewProductDetails {
    constructor(productName) {
        this.productName = productName;
    }

    static for(productName) {
        return new ViewProductDetails(productName);
    }

    async performAs(actor) {
        console.log(`${actor.name} attempts to view "${this.productName}" product details`);
        
        // Click on product title to view details
        const productSelector = `.inventory_item:has-text("${this.productName}") .inventory_item_name`;
        
        await actor.attemptsTo(
            Click.on(productSelector),
            Ensure.that(Text.of('.inventory_details_name')).equals(this.productName)
        );
        
        console.log(`${actor.name} successfully viewing product details for "${this.productName}"`);
    }
}

Create src/screenplay/tasks/WriteReview.js:

import { Enter } from '../interactions/Enter.js';
import { Click } from '../interactions/Click.js';

export class WriteReview {
    constructor(reviewText) {
        this.reviewText = reviewText;
        this.rating = 5; // default rating
    }

    static withContent(reviewText) {
        return new WriteReview(reviewText);
    }

    andRating(stars) {
        this.rating = stars;
        return this;
    }

    async performAs(actor) {
        console.log(`${actor.name} attempts to write a review: "${this.reviewText}" with ${this.rating} stars`);
        
        await actor.attemptsTo(
            Enter.theValue(this.reviewText).into('[data-test="review-text"]'),
            Click.on(`[data-test="star-rating-${this.rating}"]`)
        );
        
        console.log(`${actor.name} successfully wrote review with ${this.rating} stars`);
    }
}

✅ Task Best Practices:

Use fluent interface pattern (.for(), .withContent(), .andRating())
Include console logging for traceability
Combine multiple interactions into business workflows
Use meaningful method names that describe business intent
Make tasks reusable across different scenarios

Step 4: Create Questions (Information Retrieval)

Create src/screenplay/questions/ReviewsSection.js:

import { Visibility } from './Visibility.js';

export class ReviewsSection {
    static isVisible() {
        return new ReviewsSectionVisibility();
    }

    static count() {
        return new ReviewsCount();
    }

    static userReview() {
        return new UserReview();
    }
}

class ReviewsSectionVisibility {
    async answeredBy(actor) {
        const page = actor.ability.page;
        return await page.locator('[data-test="reviews-section"]').isVisible();
    }
}

class ReviewsCount {
    async answeredBy(actor) {
        const page = actor.ability.page;
        return await page.locator('[data-test="review-item"]').count();
    }
}

class UserReview {
    async answeredBy(actor) {
        const page = actor.ability.page;
        return page.locator('[data-test="user-review"]');
    }
}

Create src/screenplay/questions/ReviewMessage.js:

import { Text } from './Text.js';

export class ReviewMessage {
    static displayed() {
        return new ReviewMessageText();
    }
}

class ReviewMessageText {
    async answeredBy(actor) {
        const page = actor.ability.page;
        return await page.locator('[data-test="review-message"]').textContent();
    }
}

✅ Question Best Practices:

Questions retrieve information without changing application state
Use descriptive static methods (.isVisible(), .count(), .displayed())
Return actual data or Playwright locators
Keep Questions focused on single pieces of information
Use composition to build complex queries

Step 5: Update Screenplay Index (Optional)

Add exports to src/screenplay/index.js:

// ... existing exports ...

// Tasks
export { ViewProductDetails } from './tasks/ViewProductDetails.js';
export { WriteReview } from './tasks/WriteReview.js';

// Questions  
export { ReviewsSection } from './questions/ReviewsSection.js';
export { ReviewMessage } from './questions/ReviewMessage.js';

Step 6: Add NPM Scripts

Update package.json to include new feature commands:

{
  "scripts": {
    "bdd:reviews": "npx cucumber-js --tags '@reviews'",
    "bdd:reviews:headless": "npx cucumber-js --profile headless --tags '@reviews' --format @cucumber/pretty-formatter --format allure-cucumberjs/reporter --format-options '{\"resultsDir\": \"allure-results\"}'",
    "bdd:reviews:view": "npx cucumber-js --tags '@view-reviews'",
    "bdd:reviews:write": "npx cucumber-js --tags '@write-review'"
  }
}

Step 7: Run and Test

# Test the new feature
npm run bdd:reviews

# Test in headless mode
npm run bdd:reviews:headless

# Test specific scenarios
npm run bdd:reviews:view
npm run bdd:reviews:write

🎭 Screenplay Pattern Best Practices

Do's ✅

Use business language in all naming (Task, Question, method names)
Focus on user intent rather than implementation details
Make components reusable across different scenarios
Use fluent interfaces for better readability
Include logging for better traceability
Keep single responsibility for each component
Use meaningful tags to organize scenarios

Don'ts ❌

Don't expose technical details in step definitions
Don't hardcode selectors in step definitions (use Tasks/Questions)
Don't mix business logic with browser interaction code
Don't create God Tasks that do everything
Don't forget error handling and validation
Don't skip the Background for common setup

Component Responsibilities

Component	Responsibility	Example
Feature File	Business scenarios in Gherkin	`Alice writes a review`
Step Definitions	Glue between Gherkin and Screenplay	`actor.attemptsTo(WriteReview.withContent(text))`
Tasks	Business workflows	`WriteReview`, `CompleteCheckout`
Questions	Information retrieval	`ReviewsSection.count()`, `Text.of(selector)`
Interactions	Basic browser actions	`Click.on(selector)`, `Enter.theValue(text)`

🔧 Debugging Tips

Common Issues & Solutions

Step Definition Not Found

# Solution: Check import paths and export statements
import { WriteReview } from '../../src/screenplay/tasks/WriteReview.js';

Actor Not Available

# Solution: Ensure world.js properly initializes actors
# Check features/support/world.js for actor registration

Selector Not Working

# Solution: Use Playwright's inspector
npx playwright codegen https://www.saucedemo.com

Test Timing Issues

// Solution: Add proper waits in Tasks
await page.waitForLoadState('networkidle');
await page.waitForSelector('[data-test="element"]');

Testing Your Implementation

# Run single scenario for debugging
npx cucumber-js --tags '@write-review' --fail-fast

# Run with verbose output
VERBOSE=true npm run bdd:reviews

# Generate Allure report for analysis
npm run bdd:reviews:headless && npm run allure:serve

🎯 Summary

Following this tutorial, you've learned to:

✅ Write business-focused Feature files using Gherkin syntax
✅ Create Step Definitions that use Screenplay Pattern components
✅ Build reusable Tasks for business workflows
✅ Develop Questions for information retrieval
✅ Organize code following Screenplay Pattern principles
✅ Test and debug your implementation

The Screenplay Pattern makes your tests business-readable, maintainable, and scalable. Each component has a clear responsibility, making it easy for both technical and non-technical team members to understand and contribute to the test suite.

🚀 Next Steps: Practice by adding more complex scenarios like user preferences, product comparisons, or checkout customizations!

✅ Nuclear Option: Advanced screenshot attachment for Allure reports
✅ HTML Reports: Comprehensive Cucumber reporting
✅ Allure Reports: Rich interactive test reports with visual evidence
✅ Console Logs: Full browser console output captured
✅ Performance Metrics: Execution timing and success rates

Nuclear Option Screenshot Attachment

For scenarios where standard Allure screenshot attachment fails, the project includes a robust "Nuclear Option" that directly injects screenshots into Allure JSON result files:

# Run failing tests with automatic screenshot attachment
npm run bdd:nuclear:failing

# Manual screenshot injection (if needed)
node scripts/nuclear-option.js

Features:

🎯 Smart Screenshot Selection: Prioritizes assertion-failure screenshots over generic ones
🔧 Post-Test Injection: Direct JSON manipulation bypasses context limitations
📸 Visual Debugging: Screenshots appear in Allure HTML reports for failed tests
⚡ Optimized Performance: Single screenshot per failure (no duplicates)

🚀 Advanced Usage

Multi-Actor Scenarios

// Independent actors with separate browser contexts
const alice = await this.actorCalled('Alice');
const bob = await this.actorCalled('Bob');

await alice.attemptsTo(Login.withValidCredentials());
await bob.attemptsTo(Login.withCredentials('problem_user', 'secret_sauce'));

Data-Driven Testing

// Actor memory system for test data
actor.remember('credentials', { username: 'standard_user', password: 'secret_sauce' });
const credentials = actor.recall('credentials');

Custom Business Tasks

await actor.attemptsTo(
  Login.withValidCredentials(),
  AddToCart.theProduct('Sauce Labs Backpack'),
  StartCheckout.now(),
  FillCheckoutInformation.with(customerData),
  CompleteCheckout.successfully()
);

🐛 Debugging & Troubleshooting

IDE Warnings

If you see "Undefined step" warnings in your IDE:

These are cosmetic warnings (ES module recognition)
Tests execute successfully regardless
Ensure "type": "module" is in package.json

Performance Issues

# Debug with visible browser first
npm run bdd:login

# Then test headless performance
npm run bdd:login:headless

Allure Reporting

# Working approach (command-line)
npm run bdd:login:allure:serve

# If no test cases appear, clean and regenerate
npm run allure:clean && npm run bdd:login:allure

🏆 Key Achievements

Pure Screenplay Implementation: Complete business-readable test framework
ES Module Architecture: Modern JavaScript with full ESLint validation
Headless Execution Mastery: 60% performance improvement for CI/CD
Clean Code Architecture: Removed ~2000+ lines of redundant code
Nuclear Option Screenshot Attachment: Advanced visual debugging for Allure reports
Step Definition Consolidation: Eliminated duplicate steps (15% code reduction)
CI/CD Ready: Clean codebase with optimized debugging and error handling
Comprehensive Coverage: 42 scenarios covering full e-commerce workflow
Production Ready: 98.2% success rate with robust error handling

📚 Documentation

SCREENPLAY_PATTERN.md - Complete Screenplay Pattern guide
HEADLESS_EXECUTION.md - Silent execution documentation
ALLURE_REPORTING.md - Rich reporting setup guide
NUCLEAR_OPTION_SCREENSHOTS.md - Advanced screenshot attachment
IMPORTANT_NOTES.md - Critical project decisions

Assessment Status: ✅ COMPLETE & OPTIMIZED
Framework: Screenplay Pattern with business-readable test automation
Performance: Production-ready with headless execution capabilities
Success Rate: 98.2% test reliability across 42 comprehensive scenarios

Name		Name	Last commit message	Last commit date
Latest commit History 54 Commits
.github/workflows		.github/workflows
.husky		.husky
features		features
scripts		scripts
src		src
.gitignore		.gitignore
ALLURE_REPORTING.md		ALLURE_REPORTING.md
CI_CD_GUIDE.md		CI_CD_GUIDE.md
HEADLESS_EXECUTION.md		HEADLESS_EXECUTION.md
NUCLEAR_OPTION_SCREENSHOTS.md		NUCLEAR_OPTION_SCREENSHOTS.md
README.md		README.md
SCREENPLAY_PATTERN.md		SCREENPLAY_PATTERN.md
commitlint.config.js		commitlint.config.js
cucumber.config.js		cucumber.config.js
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
playwright.config.cjs		playwright.config.cjs

Folders and files

Latest commit

History

Repository files navigation

Playwright + Cucumber BDD Assessment Project

🎯 Project Overview

🏆 Current Status

🚀 Quick Start

Prerequisites

Installation

Run Tests

Standard Execution (Visible Browser)

Headless Execution (Silent Background)

🎭 Screenplay Pattern Architecture

The Five Core Elements

Business-Readable Tests

🏗️ Project Structure

🔧 Configuration Profiles

Execution Modes

Feature Tags

📊 Test Coverage & Results

Feature Coverage

Current Test Results

🎬 Reporting & Evidence

Available Reports

Evidence Collection

📚 Tutorial: Adding New Test Cases with Screenplay Pattern

🎯 Step-by-Step Tutorial

Step 1: Create the Feature File

Step 2: Create Step Definitions

Step 3: Create Tasks (Business Workflows)

Step 4: Create Questions (Information Retrieval)

Step 5: Update Screenplay Index (Optional)

Step 6: Add NPM Scripts

Step 7: Run and Test

🎭 Screenplay Pattern Best Practices

Do's ✅

Don'ts ❌

Component Responsibilities

🔧 Debugging Tips

Common Issues & Solutions

Testing Your Implementation

🎯 Summary

Nuclear Option Screenshot Attachment

🚀 Advanced Usage

Multi-Actor Scenarios

Data-Driven Testing

Custom Business Tasks

🐛 Debugging & Troubleshooting

IDE Warnings

Performance Issues

Allure Reporting

🏆 Key Achievements

📚 Documentation

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages