ui-omakase-framework/README.md

A comprehensive E2E testing framework library with pre-built Cucumber step definitions and utilities for web automation testing

# 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

```bash
npm install @your-org/e2e-framework
```

### Peer Dependencies

Make sure you have the following peer dependencies installed:

```bash
npm install @cucumber/cucumber playwright
```

## 🆕 Improved Imports (v1.0.20+)

This version introduces cleaner, more intuitive import patterns:

```typescript
// 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](./IMPORT_EXAMPLES.md) for comprehensive usage examples.

## 🛠️ Quick Start

### 1. Project Setup

Create a new project and install the framework:

```bash
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**:
```bash
# 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**:
```bash
NODE_ENV=localhost
BASE_URL=http://localhost:3000
```

### 4. Configuration Files

**config/hosts.json**:
```json
{
  "localhost": "http://localhost:3000",
  "staging": "https://staging.example.com",
  "production": "https://example.com"
}
```

**config/pages.json**:
```json
{
  "home": {
    "route": "/",
    "title": "Home Page"
  },
  "login": {
    "route": "/login",
    "title": "Login"
  }
}
```

**config/mappings/common.json**:
```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**:
```javascript
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**:
```gherkin
@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`:

```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**:
```typescript
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

```javascript
// 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**:
```json
{
  "users_api": "http://localhost:8080/api/users",
  "auth_api": "http://localhost:8080/api/auth"
}
```

**config/json_payloads/users.json**:
```json
{
  "single_user": {
    "id": 1,
    "name": "Test User",
    "email": "test@example.com"
  }
}
```

## 🧪 Running Tests

```bash
# 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:

```bash
# 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:

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

## 📄 License

ISC

## 🆘 Support

For issues and questions:
- GitHub Issues: [Repository Issues](https://github.com/your-org/e2e-framework/issues)
- Documentation: [Framework Docs](https://github.com/your-org/e2e-framework#readme)

## 📋 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.