Project Setup and Configuration Guide

This guide covers setup, configuration, and development environment preparation for this Playwright-Cucumber project.

Project Dependencies

Core Testing Framework

• •@cucumber/cucumber: BDD testing framework
• •@playwright/test: Browser automation and testing
• •allure-cucumberjs: Test reporting and documentation
• •ts-node: TypeScript execution for Node.js

Development Tools

• •TypeScript: Type safety and modern JavaScript features
• •ESLint: Code linting and quality enforcement
• •Prettier: Code formatting
• •Lefthook: Git hooks for pre-commit checks

Environment Setup

1. Required Environment Variables

Create a .env file in the project root:

# Salesforce Credentials
SF_USERNAME=your-salesforce-username
SF_PASSWORD=your-salesforce-password

# Optional Configuration
SF_BASE_URL=https://your-org.my.salesforce.com
TEST_ENV=development
HEADLESS=true
DEBUG=false

2. Development Scripts

# Install dependencies
npm install

# Run all tests
npm run test

# Code quality checks
npm run lint          # ESLint with auto-fix
npm run prettier      # Code formatting

# Test reporting
npm run allure:generate  # Generate Allure report
npm run allure:open      # Open Allure report
npm run allure          # Generate and open report

3. Git Hooks Configuration

The project uses Lefthook for pre-commit checks. Configuration in lefthook.yml:

• •Runs ESLint on staged files
• •Runs Prettier formatting
• •Validates TypeScript compilation

Project Architecture

File Structure

playwright-cucumber/
├── .github/skills/          # Agent Skills for Copilot
├── tests/
│   ├── features/           # Cucumber feature files
│   │   └── [FeatureName]/
│   │       └── [FeatureName].feature
│   ├── pages/              # Page Object Model classes
│   │   └── [PageName].ts
│   ├── steps/              # Step definition files
│   │   └── [FeatureName].ts
│   └── support/            # Test support files
│       ├── hooks.ts        # Before/After hooks
│       └── world.ts        # Test context and fixtures
├── log/                    # Test execution logs
├── allure-results/         # Allure test results
├── allure-report/          # Generated Allure reports
└── config files           # Various configuration files

Configuration Files

• •cucumber.mjs: Cucumber test runner configuration
• •tsconfig.json: TypeScript compilation settings
• •eslint.config.mts: ESLint linting rules
• •package.json: Dependencies and scripts
• •lefthook.yml: Git hooks configuration

Development Workflow

1. Adding New Tests

# 1. Create feature file
mkdir -p tests/features/NewFeature
touch tests/features/NewFeature/NewFeature.feature

# 2. Create step definitions
touch tests/steps/NewFeature.ts

# 3. Create page object (if needed)
touch tests/pages/NewFeature.ts

# 4. Run tests to verify
npm run test -- tests/features/NewFeature/

2. Code Quality Workflow

# Before committing (automated via lefthook)
npm run lint
npm run prettier

# Manual verification
npm run test

3. Debugging Setup

# Run tests with debug output
DEBUG=pw:api npm run test

# Run with browser visible
HEADLESS=false npm run test

# Run specific scenario
npx cucumber-js tests/features/Login/Login.feature --name "Successful Login"

TypeScript Configuration

Compiler Options

• •Target: ES2022
• •Module: CommonJS
• •Strict type checking enabled
• •Path mapping for clean imports
• •Experimental decorators for Cucumber

Import Patterns

// Relative imports for test files
import { Fixture } from 'tests/support/world';
import LoginPage from 'tests/pages/Login';

// Package imports
import { Given, When, Then } from '@cucumber/cucumber';
import { expect } from '@playwright/test';

Browser Configuration

Default Settings

• •Browser: Chromium (configurable)
• •Headless: true (override with HEADLESS=false)
• •Viewport: Default Playwright viewport
• •Timeout: 10 seconds default

Custom Configuration

Modify browser settings in tests/support/world.ts:

const browserOptions = {
  headless: process.env.HEADLESS !== 'false',
  slowMo: process.env.DEBUG ? 1000 : 0,
  devtools: process.env.DEBUG === 'true'
};

Troubleshooting Setup Issues

Common Issues

1. •Missing Environment Variables: Ensure .env file is created with required variables
2. •TypeScript Compilation Errors: Check tsconfig.json path mappings
3. •Import Resolution: Verify relative paths and module resolution
4. •Browser Installation: Run npx playwright install if browsers are missing
5. •Permission Issues: Ensure proper file permissions for log directory

Verification Commands

# Check Node.js version (requires 18+)
node --version

# Verify TypeScript compilation
npx tsc --noEmit

# Test Playwright installation
npx playwright --version

# Verify Cucumber setup
npx cucumber-js --version

CI/CD Integration

Required Environment Variables for CI

• •SF_USERNAME: Salesforce test user
• •SF_PASSWORD: Salesforce test password
• •SF_BASE_URL: Target Salesforce org URL

Artifacts to Preserve

• •allure-results/: Test execution results
• •allure-report/: Generated test reports
• •log/: Test execution logs
• •Screenshots from failed tests

This setup provides a robust foundation for BDD testing with Playwright and Cucumber, with comprehensive tooling for development, debugging, and reporting.