project-setup

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.