E2E Testing Framework Library

A comprehensive, reusable E2E testing framework built with Cucumber.js and Playwright. This library provides pre-built step definitions, utilities, and configuration management for web automation testing.

🚀 Features

• Pre-built Step Definitions: Over 50+ ready-to-use Cucumber step definitions for common web interactions
• Playwright Integration: Built on Playwright for reliable cross-browser automation
• Flexible Configuration: Configurable environments, page mappings, and test data
• Accessibility Testing: Built-in accessibility testing with axe-core
• Mock Support: Comprehensive mocking capabilities for API testing
• TypeScript Support: Full TypeScript support with type definitions
• Multi-browser Support: Chrome, Firefox, Safari support out of the box
• Parallel Execution: Built-in support for parallel test execution

📦 Installation

npm install @your-org/e2e-framework

Peer Dependencies

Make sure you have the following peer dependencies installed:

npm install @cucumber/cucumber playwright

🆕 Improved Imports (v1.0.20+)

This version introduces cleaner, more intuitive import patterns:

// Clean type imports
import type { GlobalConfig, ScenarioWorld } from 'ui-omakase-framework'

// Essential utilities
import { env, envNumber, setupUtils } from 'ui-omakase-framework'

// Specific support modules
import { waitFor, clickElement } from 'ui-omakase-framework/support/browser-behavior'

// Environment utilities with enhanced features
import { enhancedEnv, envBoolean } from 'ui-omakase-framework/env'

See IMPORT_EXAMPLES.md for comprehensive usage examples.

🛠️ Quick Start

1. Project Setup

Create a new project and install the framework:

mkdir my-e2e-tests
cd my-e2e-tests
npm init -y
npm install @your-org/e2e-framework @cucumber/cucumber playwright ts-node typescript

2. Basic Configuration

Create the following directory structure:

my-e2e-tests/
├── config/
│   ├── hosts.json
│   ├── pages.json
│   ├── emails.json
│   ├── errors.json
│   ├── mocks.json
│   ├── mappings/
│   │   ├── common.json
│   │   └── home.json
│   └── json_payloads/
│       └── users.json
├── env/
│   ├── common.env
│   └── localhost.env
├── src/
│   ├── features/
│   │   └── example.feature
│   └── step-definitions/
│       └── custom-steps.ts (optional)
├── cucumber.js
└── package.json

3. Environment Configuration

env/common.env:

# Browser settings
UI_AUTOMATION_BROWSER=chromium
HEADLESS=true
BROWSER_WIDTH=1920
BROWSER_HEIGHT=1080

# Test execution
PARALLEL=1
RETRY=0

# Config paths (optional - framework provides defaults)
HOSTS_URLS_PATH=/config/hosts.json
PAGE_URLS_PATH=/config/pages.json

env/localhost.env:

NODE_ENV=localhost
BASE_URL=http://localhost:3000

4. Configuration Files

config/hosts.json:

{
  "localhost": "http://localhost:3000",
  "staging": "https://staging.example.com",
  "production": "https://example.com"
}

config/pages.json:

{
  "home": {
    "route": "/",
    "title": "Home Page"
  },
  "login": {
    "route": "/login",
    "title": "Login"
  }
}

config/mappings/common.json:

{
  "login button": "button[data-testid='login-btn']",
  "username field": "input[name='username']",
  "password field": "input[name='password']",
  "error message": ".error-message"
}

5. Cucumber Configuration

cucumber.js:

const { createFrameworkConfig } = require('@your-org/e2e-framework');

// Initialize the framework configuration
const frameworkConfig = createFrameworkConfig({
  configPath: './config',
  envPath: './env/',
  featuresPath: './src/features/**/*.feature',
  customStepDefsPath: './src/step-definitions/**/*.ts'
});

module.exports = {
  default: frameworkConfig.cucumberConfig.dev
};

6. Write Your First Test

src/features/example.feature:

@dev
Feature: Login functionality

  Background:
    Given I am on the "home" page

  Scenario: Successful login
    When I click the "login button"
    And I fill the "username field" with "testuser"
    And I fill the "password field" with "password123"
    And I click the "login button"
    Then I should be on the "dashboard" page

7. Package.json Scripts

Add these scripts to your package.json:

{
  "scripts": {
    "test": "NODE_ENV=localhost COMMON_CONFIG_FILE=env/common.env cucumber-js",
    "test:dev": "NODE_ENV=localhost COMMON_CONFIG_FILE=env/common.env cucumber-js --tags @dev",
    "test:smoke": "NODE_ENV=localhost COMMON_CONFIG_FILE=env/common.env cucumber-js --tags @smoke",
    "test:headful": "HEADLESS=false npm run test"
  }
}

📚 Available Step Definitions

The framework provides numerous pre-built step definitions:

Navigation

• Given I am on the "{page}" page
• When I navigate to the "{page}" page
• Then I should be on the "{page}" page

Interactions

• When I click the "{element}" element
• When I fill the "{element}" with "{text}"
• When I select "{option}" from the "{element}" dropdown
• When I check the "{element}" checkbox

Assertions

• Then I should see the "{element}" element
• Then I should not see the "{element}" element
• Then the "{element}" should contain "{text}"
• Then the "{element}" should be enabled

Wait Conditions

• When I wait "{seconds}" seconds
• When I wait for the "{element}" to be visible
• When I wait for the "{element}" to be hidden

Forms

• When I submit the form
• Then the "{element}" should have the value "{value}"

And many more!

🔧 Advanced Configuration

Custom Step Definitions

Create custom step definitions in your project:

src/step-definitions/custom-steps.ts:

import { Given, When, Then } from '@cucumber/cucumber';
import { ScenarioWorld } from '@your-org/e2e-framework';

Given('I perform a custom action', async function(this: ScenarioWorld) {
  // Your custom logic here
  const { page } = this.screen;
  await page.locator('custom-selector').click();
});

Environment-Specific Configuration

// cucumber.js
const { createFrameworkConfig } = require('@your-org/e2e-framework');

const environment = process.env.NODE_ENV || 'localhost';

const frameworkConfig = createFrameworkConfig({
  configPath: `./config/${environment}`,
  envPath: './env/',
  environment: environment
});

module.exports = {
  default: frameworkConfig.cucumberConfig[process.env.TEST_TYPE || 'dev']
};

Mock Configuration

config/mocks.json:

{
  "users_api": "http://localhost:8080/api/users",
  "auth_api": "http://localhost:8080/api/auth"
}

config/json_payloads/users.json:

{
  "single_user": {
    "id": 1,
    "name": "Test User",
    "email": "[email protected]"
  }
}

🧪 Running Tests

# Run all tests
npm test

# Run development tests only
npm run test:dev

# Run smoke tests
npm run test:smoke

# Run in headed mode (browser visible)
npm run test:headful

# Run specific feature
npx cucumber-js src/features/login.feature

# Run with specific tags
npx cucumber-js --tags "@regression and not @skip"

🎯 Browser Configuration

Set browser via environment variables:

# Chrome
UI_AUTOMATION_BROWSER=chromium npm test

# Firefox
UI_AUTOMATION_BROWSER=firefox npm test

# Safari
UI_AUTOMATION_BROWSER=webkit npm test

📊 Reports

The framework generates detailed HTML reports in the reports/ directory after test execution.

🤝 Contributing

When developing the framework library itself:

git clone <repository>
cd e2e-framework
npm install
npm run build
npm test

📄 License

ISC

🆘 Support

For issues and questions:

• GitHub Issues: Repository Issues
• Documentation: Framework Docs

📋 Migration from Existing Projects

If you have an existing E2E project, follow these steps:

1. Install the framework: npm install @your-org/e2e-framework
2. Move your config/ and env/ directories to match the expected structure
3. Update your cucumber.js to use createFrameworkConfig()
4. Remove duplicate step definitions that are provided by the framework
5. Import the framework in your main test file or cucumber configuration
6. Update your package.json scripts to use the new configuration

The framework is designed to be backward-compatible with most existing Cucumber.js + Playwright setups.