How to Build a Playwright BDD Test Framework from Scratch: Step-by-Step Setup Guide

Setting up a fresh test automation framework can feel overwhelming without a clear blueprint. Having a structured setup process ensures that directory layouts, configuration files, and execution scripts are aligned right from day one.

Here is a quick setup guide for initializing a hybrid BDD framework powered by Playwright, Cucumber, and JavaScript.

Installation & Directory Setup

Start by installing project dependencies and creating the core folder hierarchy for feature files, step definitions, page objects, and utilities:

# Install dependencies
npm install

# Create required folder structure
mkdir features features/API features/UI
mkdir step-definitions step-definitions/API step-definitions/UI
mkdir page-objects utils setup setup/fixtures
mkdir test-data test-data/json test-data/excel
mkdir reports logs test-results

Key Framework Files

Ensure your framework repository includes the following core files:

• Configuration: package.json, playwright.config.js, cucumber.config.js
• Page Models & Drivers: page-objects/PageManager.js, utils/ApiHelper.js
• Hooks & Fixtures: setup/hooks.js
• Step Definitions: step-definitions/API/PlaywrightAPISteps.js, step-definitions/API/JsonTestDataSteps.js

Test Data Strategy & Execution

• Test Data Management: Primary test data is managed via JSON (test-data/json/testData.json, test-data/json/apiTestData.json), with optional Excel support for tabular data inputs.

• Environment Setup: Store key environment variables (e.g., BASE_URL, API_BASE_URL) inside your local .env configuration file.

Execution Commands:

# Run API test suite
npm run test:api

# Run UI test suite
npm run test:ui

# Run full execution suite
npm run test