npm package: @fimple/playwright-testing-utils
Description: Reusable Playwright testing components and utilities for Fimple applications
Author: Fimple Team
Latest version: 1.0.0

# @fimple/playwright-testing-utils

Reusable Playwright testing components and utilities for Fimple applications.

## Installation

```bash
npm install @fimple/playwright-testing-utils
```

## Usage

### Base Page Components

```typescript
import { BasePage, BrowsePage, FormPage, WebSuite } from '@fimple/playwright-testing-utils';

// Extend base components for your specific pages
class CustomersPage extends BrowsePage {
  constructor(page: Page) {
    super(page, "u101814fe92", "Customers");
  }
  
  async fillCustomerIdFilter(customerId: string) {
    return this.getComponent('CustomerId').fill(customerId);
  }
}

// Use WebSuite for high-level navigation
const webSuite = new WebSuite(page);
const customersPage = await webSuite.openCustomersPage();
```

### Authentication Fixtures

```typescript
import { createAuthFixture } from '@fimple/playwright-testing-utils';

// Define your authentication function
async function authenticateUser(page: Page, userType: 'entry' | 'approver') {
  // Your authentication logic here
  await page.goto('/login');
  // ... login implementation
}

// Create the test fixture
export const test = createAuthFixture(authenticateUser);

// Use in tests
test('customer search', async ({ authenticatedPage }) => {
  const webSuite = new WebSuite(authenticatedPage);
  // ... test implementation
});
```

### API Authentication

```typescript
import { getApiAuthTokens, setApiAuthInContext } from '@fimple/playwright-testing-utils';

const config = {
  baseUrl: 'https://identity.dev.fimple.co.uk/auth/realms/tenant/protocol/openid-connect/token',
  username: 'user@example.com',
  password: 'password123',
  clientId: 'fi-web-suite'
};

const tokens = await getApiAuthTokens(config);
await setApiAuthInContext(page, tokens);
```

## API Reference

### BasePage

Core page object with common UI interaction methods:

- `getComponent(componentName)` - Get element by data-testid pattern
- `selectAutocompleteByText(componentName, optionText)` - Select from dropdown by text
- `selectAutocompleteByIndex(componentName, index)` - Select from dropdown by index
- `fillTranslations(fieldName, translations)` - Fill multi-language fields
- `pressButtonTillFindElement(button, element)` - Retry button clicks until element appears

### BrowsePage

Extends BasePage for list/grid-based pages:

- `getGridRowActionByCellValue(gridName, rowAction, cellValue)` - Get row action by cell value
- `getGridCellByRowNumberAndColumn(gridName, rowNumber, columnName)` - Get specific grid cell
- `getGridFilterByColumnName(gridName, columnName)` - Get grid filter input

### FormPage

Extends BasePage for form-based pages:

- `saveAction` - Save button locator
- `cancelAction` - Cancel button locator
- `documentsAction` - Documents button locator

### WebSuite

High-level application navigation:

- `openCustomersPage()` - Navigate to customers page
- `openCustomer360PageByCustomerId(customerId)` - Open customer details
- `openInboxScreen()` - Navigate to approval inbox
- `approveInboxItem(businessKey, uiKey)` - Approve workflow item
- `rollback(businessKey)` - Rollback a process

## Configuration

### WebSuite Configuration

```typescript
const config = {
  customerMenuId: 'u9ab3193a96',
  customerSubMenuId: 'u101814fe92',
  inboxMenuId: 'uac2248dd39',
  inboxSubMenuId: 'u45518b4136',
  workflowMenuId: 'u441dbf7645'
};

const webSuite = new WebSuite(page, config);
```

## Development

```bash
# Install dependencies
npm install

# Build the package
npm run build

# Run linting
npm run lint

# Format code
npm run format
```

## License

MIT