npm package: @moizkhan/playwright-automation-framework
Description: A comprehensive, configurable, and scalable Playwright test automation framework for merchant onboarding workflows
Author: Muhammad Moiz Khan
Latest version: 1.0.1

# Generic Data-Driven Test Framework

A comprehensive, configurable, and scalable test automation framework for merchant onboarding workflows. This framework provides maximum flexibility to run different test scenarios with minimal configuration changes.

## 🚀 Quick Start

### Run Different Test Suites

```bash
# Quick smoke test (5-10 minutes)
npm run test:smoke

# Complete regression test (30-45 minutes)
npm run test:regression

# Field validation focused test (20-30 minutes)
npm run test:validation

# MDR and payment channel test (15-20 minutes)
npm run test:mdr

# Performance test
npm run test:performance
```

### Run with Browser Visible (Headed Mode)

```bash
npm run test:smoke:headed
npm run test:regression:headed
npm run test:validation:headed
```

### Run on Different Environments

```bash
# Test on staging environment (default)
npm run test:staging

# Test on production environment
npm run test:production

# Test on local environment
npm run test:local
```

### Test Different Business Scenarios

```bash
# Test individual small business scenario
npm run test:individual

# Test company medium business scenario (default)
npm run test:company

# Test enterprise large business scenario
npm run test:enterprise
```

## 🎯 Test Suite Options

| Suite | Description | Duration | Use Case |
|-------|-------------|----------|----------|
| `smoke` | Basic functionality validation | 5-10 min | Quick verification, CI/CD |
| `regression` | Complete end-to-end testing | 30-45 min | Full regression testing |
| `validation` | Field validation focus | 20-30 min | Input validation testing |
| `mdr_focused` | MDR and payment channels | 15-20 min | Payment feature testing |
| `performance` | Performance and load testing | 20-30 min | Performance validation |
| `custom` | Configurable test suite | Variable | Custom scenarios |

## 🛠️ Advanced Usage

### Command Line Interface

```bash
# Basic usage
node run-tests.js [test-suite] [options]

# Examples
node run-tests.js smoke
node run-tests.js regression --headed
node run-tests.js validation --env staging --data company
node run-tests.js mdr_focused --project chromium --workers 1
```

### Available Options

| Option | Description | Values |
|--------|-------------|--------|
| `--env` | Set environment | staging, production, local |
| `--data` | Set data scenario | individual, company, enterprise |
| `--headed` | Show browser window | - |
| `--debug` | Enable debug mode | - |
| `--project` | Browser selection | chromium, firefox, webkit |
| `--workers` | Parallel workers | number |

### Direct Playwright Commands

```bash
# Run specific test files
npx playwright test Universal-TestRunner.spec.js
npx playwright test Generic-DataDriven.spec.js
npx playwright test Sequential-Complete.spec.js

# Run with specific configuration
TEST_SUITE=smoke npx playwright test Universal-TestRunner.spec.js --headed
TEST_SUITE=regression DATA_SCENARIO=enterprise npx playwright test Universal-TestRunner.spec.js
```

## 📊 Configuration

### Test Suite Configuration

Edit `config/testConfig.json` to customize test behavior:

```json
{
  "testSuites": {
    "your_custom_suite": {
      "description": "Your custom test description",
      "execution": {
        "mode": "sequential",
        "timeout": 300000,
        "continueOnError": true
      },
      "scenarios": {
        "validDataFlow": true,
        "invalidDataValidation": true,
        "mdrSplitTesting": true
      },
      "pages": {
        "basicInfo": true,
        "businessDetails": true,
        "mdrDetails": true
      }
    }
  }
}
```

### Field Configuration

Edit `config/testData.json` to add new fields or validation rules:

```json
{
  "pages": {
    "basicInfo": {
      "fields": [
        {
          "fieldName": "newField",
          "selector": "#newField",
          "type": "input",
          "validInputs": [
            {
              "value": "valid data",
              "description": "Valid input description"
            }
          ],
          "invalidInputs": [
            {
              "value": "",
              "expectedError": "Required field error",
              "description": "Empty field test"
            }
          ]
        }
      ]
    }
  }
}
```

## 🔧 Test Configuration Options

### Execution Modes

- **Sequential**: Tests run one after another (default)
- **Parallel**: Tests run simultaneously (faster but requires more resources)
- **Single Page**: Test only one page at a time

### Scenario Types

- **validDataFlow**: Test with valid data only
- **invalidDataValidation**: Test field validation with invalid data
- **fieldByFieldTesting**: Test each field individually
- **comprehensiveValidation**: Complete validation testing
- **mdrSplitTesting**: Test MDR split functionality
- **duplicateMerchantTesting**: Test duplicate merchant handling
- **paymentChannelTesting**: Test payment channel configuration

### Page Selection

Enable/disable specific pages in your test run:

- `basicInfo`: Basic merchant information
- `businessDetails`: Business details and coordinates
- `proprietorDetails`: Proprietor and contact information
- `bankingDetails`: Banking and payment information
- `posSpecificDetails`: POS-specific configurations
- `mdrDetails`: MDR rates and configurations

## 📈 Test Data Scenarios

### Business Type Scenarios

| Scenario | Business Type | Scale | Use Case |
|----------|---------------|-------|----------|
| `individual` | Individual | Small | Single person business |
| `company` | Private Limited | Medium | Company business (default) |
| `enterprise` | Public Limited | Large | Enterprise level business |

### Custom Test Data

Generate custom test data by modifying `utils/TestDataHelper.js`:

```javascript
export function generateCustomTestData(scenario) {
    const baseData = generateUniqueTestData();
    
    switch (scenario) {
        case 'high_volume':
            return {
                ...baseData,
                dailyTurnover: '1000000',
                mdrRates: { default: '1.5' }
            };
        case 'special_category':
            return {
                ...baseData,
                businessCategory: 'Custom Category'
            };
    }
}
```

## 📊 Reporting

### Allure Reports

```bash
# Generate and view Allure report
npm run allure:serve

# Generate static report
npm run allure:generate
npm run allure:open
```

### HTML Reports

```bash
# View Playwright HTML report
npx playwright show-report
```

### Custom Reports

Test results are saved in multiple formats:

- **Allure**: `./allure-results/` → Interactive reports
- **HTML**: `./test-reports/report.html` → Static HTML report
- **JSON**: `./test-reports/results.json` → Raw test data
- **Screenshots**: `./screenshots/` → Error screenshots

## 🔍 Debugging

### Debug Mode

```bash
# Run in debug mode with browser visible
node run-tests.js smoke --debug --headed

# Debug specific test
npx playwright test Universal-TestRunner.spec.js --debug
```

### Error Investigation

1. **Check Screenshots**: Error screenshots are automatically saved in `./screenshots/`
2. **Review Logs**: Detailed console output shows test progress
3. **Allure Report**: Interactive reports with step-by-step execution
4. **Test Configuration**: Verify `config/testConfig.json` settings

### Common Issues

| Issue | Solution |
|-------|----------|
| Login fails | Check credentials in `config/testConfig.json` |
| Field not found | Update selector in `config/testData.json` |
| Timeout errors | Increase timeout in test configuration |
| Validation fails | Check expected error messages |

## 🚀 CI/CD Integration

### GitHub Actions

```yaml
name: Test Automation
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm install
      - run: npx playwright install
      - run: npm run test:smoke
      - run: npm run allure:generate
```

### Jenkins

```groovy
pipeline {
    agent any
    stages {
        stage('Test') {
            steps {
                sh 'npm install'
                sh 'npx playwright install'
                sh 'npm run test:regression'
            }
        }
        stage('Report') {
            steps {
                sh 'npm run allure:generate'
                publishHTML([
                    allowMissing: false,
                    alwaysLinkToLastBuild: true,
                    keepAll: true,
                    reportDir: 'allure-report',
                    reportFiles: 'index.html',
                    reportName: 'Test Report'
                ])
            }
        }
    }
}
```

## 🛡️ Best Practices

### Test Organization

1. **Use appropriate test suite** for your needs (smoke for quick validation, regression for comprehensive testing)
2. **Configure environments** properly in `config/testConfig.json`
3. **Customize test data** scenarios for different business types
4. **Enable error handling** with `continueOnError: true` for comprehensive test runs

### Performance

1. **Use parallel execution** for faster test runs when possible
2. **Optimize selectors** for better reliability
3. **Reduce timeouts** for faster feedback in development
4. **Disable screenshots** in performance tests

### Maintenance

1. **Update selectors** in `config/testData.json` when UI changes
2. **Add new validation rules** as business rules evolve
3. **Keep test data fresh** with unique generation
4. **Monitor test execution times** and optimize slow tests

## 📚 Examples

### Custom Test Suite

```bash
# Create a custom test for specific scenario
TEST_SUITE=custom DATA_SCENARIO=individual npx playwright test Universal-TestRunner.spec.js --headed
```

### Environment-Specific Testing

```bash
# Test on staging with enterprise data
node run-tests.js regression --env staging --data enterprise --headed
```

### Quick Validation

```bash
# Quick field validation test
npm run test:validation:headed
```

### Performance Testing

```bash
# Run performance tests without screenshots
node run-tests.js performance --workers 3
```

## 🤝 Contributing

1. **Add new test scenarios** by extending `config/testConfig.json`
2. **Add new field configurations** in `config/testData.json`
3. **Create new test data scenarios** in `utils/GenericTestHelper.js`
4. **Document new features** in this README

## 📞 Support

For issues and questions:

1. Check the **Common Issues** section above
2. Review **test logs** and **screenshots**
3. Verify **configuration files**
4. Check **Allure reports** for detailed execution information

---

*This framework provides maximum flexibility for testing merchant onboarding workflows with minimal configuration changes. Choose the appropriate test suite for your needs and customize as required.*