moizkhan-data-driven-test/README.md

A comprehensive data-driven test automation framework for Playwright with universal field detection, intelligent error validation, and bundled source code protection

# Data-Driven Test Framework for Playwright

A comprehensive data-driven test automation framework for Playwright with universal field detection, intelligent error validation, and clean architectural separation.

## � Version 1.3.1 - Clean Architecture + Webpack Bundle

This version introduces a clean separation of concerns and webpack bundling:
- **BaseTestPage**: Handles field validation logic only
- **Individual Page Classes**: Handle page-specific navigation
- **Zero Hardcoded Values**: Complete genericization with JSON-driven configuration
- **Webpack Bundle**: Minified and optimized for production use

## 📦 Installation

```bash
npm install moizkhan-data-driven-test
```

## 🎯 Key Features

### ✅ **Clean Architecture**
- **Separation of Concerns**: Validation logic separated from navigation logic
- **Page-Specific Navigation**: Each page handles its own next button selectors
- **Generic Framework**: Zero hardcoded selectors, completely JSON-driven

### ✅ **Advanced Field Detection**
- **Universal Field Detection**: Automatically detects input fields, dropdowns, textareas
- **Label-Based Approach**: Finds fields by their associated labels
- **Multiple Selector Strategies**: Handles various HTML structures and frameworks

### ✅ **Comprehensive Validation**
- **Field-by-Field Testing**: Invalid → Valid approach for each field individually
- **Enhanced Error Validation**: Intelligent error message matching and validation
- **Visual Test Indicators**: Clear pass/fail indicators with detailed logging

### ✅ **Flexible Testing Modes**
- **Full Validation Mode**: Complete invalid and valid input testing
- **Positive-Only Mode**: Quick valid data filling for flow testing
- **Custom Validation**: Targeted testing of specific fields or scenarios

## 📦 Installation

```bash
npm install moizkhan-data-driven-test
```

## 🚀 Quick Start

### 1. Import the Framework

```javascript
const { BaseTestPage, DataDrivenTestPage } = require('moizkhan-data-driven-test');
```

### 2. Create Test Data

```json
{
  "pageInfo": {
    "pageName": "Login",
    "url": "https://example.com/login"
  },
  "selectors": {
    "userIdInput": "input[name='userId']",
    "passwordInput": "input[name='password']",
    "loginButton": "button[type='submit']"
  },
  "credentials": {
    "admin": {
      "userId": "admin",
      "password": "password123",
      "description": "Admin account"
    }
  },
  "fieldData": [
    {
      "labelName": "User ID",
      "selector": "input[name='userId']",
      "validInputs": [
        {
          "value": "admin",
          "description": "Valid admin user"
        }
      ],
      "invalidInputs": [
        {
          "value": "",
          "description": "Empty user ID",
          "expectedError": "User ID is required"
        }
      ]
    }
  ]
}
```

### 3. Create Page Class

```javascript
const { BaseTestPage } = require('moizkhan-data-driven-test');

class LoginPage extends BaseTestPage {
  constructor(page, testData) {
    super(page, testData, testData.pageInfo.pageName);
    this.loginUrl = testData.pageInfo.url;
    this.selectors = testData.selectors;
    this.credentials = testData.credentials;
  }

  async navigate() {
    await this.page.goto(this.loginUrl);
  }

  getNextButtonSelector() {
    return this.selectors.loginButton;
  }

  getSubmitButtonSelector() {
    return this.selectors.loginButton;
  }
}
```

### 4. Write Tests

```javascript
const { test } = require('@playwright/test');
const loginTestData = require('./testData/loginTestData.json');

test('data-driven login test', async ({ page }) => {
  const loginPage = new LoginPage(page, loginTestData);
  
  // Run comprehensive validation tests
  await loginPage.runValidationTests();
  
  // Run positive tests only
  await loginPage.runPositiveTestsOnly();
});
```

## 📋 API Reference

### BaseTestPage

Main base class for page objects with data-driven capabilities.

**Constructor:**
- `constructor(page, testData, pageName)`

**Abstract Methods:**
- `getNextButtonSelector()` - Must return next button selector
- `getSubmitButtonSelector()` - Must return submit button selector

**Main Methods:**
- `runValidationTests()` - Run invalid then valid input tests
- `runPositiveTestsOnly()` - Fill all fields with valid data
- `clickNext()` - Click next button using generic approach

### DataDrivenTestPage

Core test execution engine with universal field handling.

**Constructor:**
- `constructor(page, testData)`

**Methods:**
- `testOneValidInput(field)` - Test single field with valid input
- `applyBlurAndValidate(field, invalidInput)` - Test field validation
- `clickNextButton(selector)` - Click button using provided selector
- `compareErrorMessages(expected, actual)` - Advanced error comparison

### Utils

Utility functions for the framework.

**Methods:**
- `validateTestData(testData)` - Validate test data structure
- `mergeTestData(...testData)` - Merge multiple test data objects
- `formatErrorMessage(error, context)` - Format error messages

## 🎯 Advanced Usage

### Generic Login Implementation

```javascript
class GenericLoginPage extends BaseTestPage {
  constructor(page, testData) {
    super(page, testData, testData.pageInfo.pageName);
    this.loginUrl = testData.pageInfo.url;
    this.selectors = testData.selectors;
    this.credentials = testData.credentials;
  }

  async loginWithCredentials(credentialKey = 'admin') {
    const credential = this.credentials[credentialKey];
    await this.page.goto(this.loginUrl);
    await this.page.fill(this.selectors.userIdInput, credential.userId);
    await this.page.fill(this.selectors.passwordInput, credential.password);
    await this.page.click(this.selectors.loginButton);
  }

  getNextButtonSelector() {
    return this.selectors.loginButton;
  }

  getSubmitButtonSelector() {
    return this.selectors.loginButton;
  }
}
```

### Multi-Page Flow Testing

```javascript
const { mergeTestData } = require('moizkhan-data-driven-test');

// Merge test data from multiple pages
const combinedTestData = mergeTestData(
  loginTestData,
  basicInfoTestData,
  businessDetailsTestData
);

// Use in comprehensive flow tests
test('complete user flow', async ({ page }) => {
  const flow = new UserFlow(page, combinedTestData);
  await flow.completeFullWorkflow();
});
```

## 🔧 Configuration

### Test Data Structure

The framework expects test data in a specific JSON structure:

```typescript
interface TestData {
  pageInfo?: {
    pageName?: string;
    url?: string;
    description?: string;
  };
  selectors?: {
    [key: string]: string;
  };
  credentials?: {
    [key: string]: {
      userId: string;
      password: string;
      description?: string;
      role?: string;
    };
  };
  fieldData: FieldData[];
}
```

## 🎨 Benefits

### ✅ **Bundled Source Protection**
- Source code is bundled and minified
- Intellectual property protection
- Clean distribution without exposing implementation

### ✅ **Complete Framework**
- No hardcoded values anywhere
- Fully configurable through JSON
- Works with any web application

### ✅ **Advanced Features**
- Intelligent error message comparison
- Universal field detection
- Visual pass/fail indicators
- Comprehensive validation testing

### ✅ **Easy Integration**
- Simple NPM installation
- Clear API and documentation
- TypeScript definitions included

## 📄 License

MIT

## 🔗 Repository

[GitHub Repository](https://github.com/moizkhan/data-driven-test)

## 🐛 Issues

[Report Issues](https://github.com/moizkhan/data-driven-test/issues)

---

**Note**: This is a bundled package with minified source code for intellectual property protection. The framework provides comprehensive testing capabilities while keeping the implementation details secure.