Frontend BDD Testing Strategy With Gherkin And Playwright

Andi Lamprecht ·2026-05-11· 6 min read· Draft

Traceability:

This ADR is downstream of [Verification Strategy](confluence-title://UE/Verification Strategy)

Context

We use Gherkin scenarios with Cucumber for testing High-Level Requirements (HLR) and Low-Level Requirements (LLR) based requirements in our backend code. This approach provides excellent traceability from requirements to test cases, which is essential for DO-178C compliance and certification.

For the frontend, we need to extend this BDD approach to maintain consistency across our testing strategy while leveraging Playwright’s modern browser automation capabilities. Additionally, we require automated security scanning and vulnerability resolution using tools like Dependabot, followed by regression testing to verify system stability after security patches.

1.1 Problem Statement

We need to establish a unified testing approach that:

• Enables writing frontend tests in Gherkin syntax for stakeholder readability and DO-178C traceability
• Leverages Playwright’s advanced browser automation, tracing, and debugging capabilities
• Integrates with CI/CD pipelines for automated execution after security vulnerability fixes
• Provides comprehensive test artifacts (videos, screenshots, traces) for debugging and compliance evidence
• Maintains bidirectional traceability between requirements and test cases

1.2 Stakeholders

• Software Engineering Team: Primary implementers and maintainers
• QA/Test Engineers: Test scenario authors and executors
• Product Owners: Stakeholders who can read and validate Gherkin scenarios

Decision

We will adopt playwright-bdd (https://github.com/vitalets/playwright-bdd ) as our integration layer between Gherkin/BDD scenarios and Playwright test execution. This approach uses the Playwright test runner natively while supporting Gherkin feature files.

Rationale for playwright-bdd Over CucumberJS + Playwright

There are two primary approaches to integrate Gherkin with Playwright:

Option A: CucumberJS Runner with Playwright as Library

This approach uses CucumberJS as the test runner and Playwright purely as a browser automation library.

• Pros: Full Cucumber ecosystem compatibility, familiar to teams already using Cucumber
• Cons: Loses Playwright’s native test runner features (parallel execution, sharding, HTML reporter, trace viewer integration, UI mode debugging)

Option B: playwright-bdd with Playwright Runner (SELECTED)

This approach converts BDD scenarios into Playwright tests and runs them with the native Playwright runner.

• Pros: Full Playwright runner capabilities, excellent CI/CD integration, built-in tracing/video/screenshots, Cucumber reporter support, active development
• Cons: Additional build step (bddgen), newer tooling

Key Decision Factors

1. Native Playwright Features: playwright-bdd provides full access to Playwright’s trace viewer, video recording, screenshot capture, and HTML reporting—critical for debugging CI failures and providing compliance evidence.
2. CI/CD Integration: The Playwright runner offers superior parallel execution, test sharding, and retry mechanisms essential for regression testing after Dependabot security patches.
3. Independence from CucumberJS: As of 2024, playwright-bdd operates independently of the CucumberJS package, reducing dependency conflicts and improving stability.
4. Cucumber Reporter Support: playwright-bdd supports Cucumber message format and reporters, enabling integration with existing BDD reporting tools.

Implementation Architecture

Project Structure

project-root/
├── features/                    # Gherkin feature files
│   ├── login.feature
│   ├── dashboard.feature
│   └── *.feature
├── features/steps/              # Step definitions
│   ├── common.steps.ts
│   └── *.steps.ts
├── .features-gen/               # Generated Playwright specs (auto)
├── playwright.config.ts         # Playwright + BDD configuration
├── .github/
│   └── workflows/
│       ├── ci.yml               # Main CI pipeline
│       └── security-regression.yml
└── test-results/                # Artifacts (traces, videos)

Configuration Example

import { defineConfig } from '@playwright/test';
import { defineBddConfig } from 'playwright-bdd';

const testDir = defineBddConfig({
  paths: ['features/**/*.feature'],
  require: ['features/steps/**/*.ts'],
});

export default defineConfig({
  testDir,
  reporter: [['html'], ['playwright-bdd/reporter/cucumber']],
  use: {
    trace: 'on-first-retry',     // Capture traces on failures
    video: 'retain-on-failure',  // Record video for failed tests
    screenshot: 'only-on-failure',
  },
  retries: 2,  // Critical for CI stability
});

Feature File Example with Requirements Traceability

@HLR-UI-001 @LLR-LOGIN-001
Feature: User Authentication
  As a registered user
  I want to log into the application
  So that I can access protected features

  @smoke @regression
  Scenario: Successful login with valid credentials
    Given I navigate to the login page
    When I enter valid username and password
    And I click the login button
    Then I should be redirected to the dashboard
    And I should see my username in the header

Security Scanning & Regression Testing Workflow

Automated Security Pipeline

The following workflow ensures that security vulnerabilities are automatically detected, patched, and validated through regression testing:

1. Security Scan: Dependabot continuously monitors dependencies for known vulnerabilities (CVEs) and automatically creates pull requests with security patches. Additional automation will create deficiency reports using traceable bugs.
2. Pull Request Created: When a security update is available, Dependabot opens a PR with version bump and changelog details.
3. CI Pipeline Triggered: The PR triggers the full CI/CD pipeline including unit tests, integration tests, and BDD regression tests.
4. BDD Regression Suite Execution: All Gherkin scenarios tagged with @regression are executed using Playwright. Tests run in parallel with full tracing enabled.
5. Artifact Collection: Test results, traces, videos, and screenshots are collected and stored as CI artifacts for review and compliance evidence.
6. Auto-Merge or Review: If all tests pass and it’s a patch/minor update, the PR can be auto-merged. Major updates require manual review.
7. System Change Report: a formal system change report is generated and documented so we always have a full auditable trace of what changes were implemented across our code-base.

Consequences

Positive Consequences

• Unified Testing Language: Gherkin scenarios across frontend and backend maintain consistency and stakeholder readability
• Full Playwright Capabilities: Access to trace viewer, video recording, screenshots, and advanced debugging for CI failures
• Automated Security Assurance: Dependabot PRs automatically trigger regression tests, ensuring security patches don’t break functionality
• Compliance Evidence: Test artifacts, traces, and requirement tags provide auditable evidence for DO-178C certification
• Faster Feedback: Parallel test execution and sharding reduce regression test times

Negative Consequences

• Build Step Required: The bddgen command must run before tests to generate Playwright specs from features
• Learning Curve: Team members need to learn playwright-bdd configuration and Playwright-specific fixtures
• Generated Files: The .features-gen directory contains auto-generated files that must be managed (typically gitignored)

6.3 Risks and Mitigations

Alternatives Considered

Pure CucumberJS + Playwright as Library

This is the traditional approach where CucumberJS runs as the test framework and Playwright is used only for browser automation.

Rejected because: We lose access to Playwright’s native trace viewer, HTML reporter, UI mode debugging, and parallel execution optimizations. These features are critical for debugging CI failures and providing compliance evidence.

Native Playwright Tests (No BDD)

Writing tests directly in Playwright’s native TypeScript/JavaScript syntax without Gherkin.

Rejected because: This breaks our unified BDD approach and reduces test readability for non-technical stakeholders. It also complicates requirements traceability for DO-178C compliance.

Cypress with cucumber-preprocessor

Using Cypress framework with its BDD/Gherkin plugin.

Rejected because: Cypress has limitations with multi-tab/window scenarios, iframe handling, and cross-origin testing. Playwright’s architecture is more suitable for complex enterprise applications.

References

• playwright-bdd GitHub: https://github.com/vitalets/playwright-bdd
• playwright-bdd Documentation: https://vitalets.github.io/playwright-bdd/
• Playwright Documentation: https://playwright.dev/
• Cucumber Gherkin Reference: https://cucumber.io/docs/gherkin/reference/
• GitHub Dependabot Documentation: https://docs.github.com/en/code-security/dependabot
• DO-178C Standard: RTCA DO-178C / EUROCAE ED-12C
• Verification Strategy: [Verification Strategy](confluence-title://UE/Verification Strategy)
• ADR-0126: [ADR–0126-Automated Dependency Management and Security Scanning](confluence-title:///ADR–0126-Automated Dependency Management and Security Scanning)