npm package: @progalaxyelabs/stonescriptphp-e2e-test-helpers
Description: Shared Playwright E2E test helpers for StoneScriptPHP platforms
Author: Progalaxy E-Labs
Latest version: 1.0.0

# @progalaxyelabs/stonescriptphp-e2e-test-helpers

Shared Playwright E2E test helpers for StoneScriptPHP platforms. Provides authentication, API testing, and page validation utilities for all 7 StoneScriptPHP platforms.

## Installation

```bash
npm install --save-dev @progalaxyelabs/stonescriptphp-e2e-test-helpers
```

## Features

- **AuthHelper**: User registration, login/logout, JWT token management
- **ApiHelper**: StoneScriptPHP API envelope handling, CRUD testing, health checks
- **PageHelper**: Page load verification, console error checking, Angular bootstrap detection
- **Platform Configs**: Pre-configured URLs for all 7 platforms
- **Playwright Fixtures**: Ready-to-use test fixtures with authenticated users

## Quick Start

```typescript
import { test, expect } from '@playwright/test';
import { PLATFORMS, createPlatformTest } from '@progalaxyelabs/stonescriptphp-e2e-test-helpers';

// Create platform-specific test with fixtures
const platformTest = createPlatformTest(PLATFORMS.progalaxyelabs);

platformTest('should authenticate and access API', async ({ authenticatedUser, apiHelper, request }) => {
  // authenticatedUser fixture provides: { accessToken, refreshToken, user, testUser }

  // Test API with authenticated token
  const data = await apiHelper.get(request, '/api/some-endpoint', authenticatedUser.accessToken);
  expect(data).toBeDefined();
});
```

## Usage Examples

### AuthHelper

```typescript
import { test } from '@playwright/test';
import { AuthHelper } from '@progalaxyelabs/stonescriptphp-e2e-test-helpers';

test('register and login user', async ({ request }) => {
  const authHelper = new AuthHelper({
    authUrl: 'http://localhost:3139',
    platform: 'progalaxyelabs',
    isSingleTenant: true,
  });

  // Register and login in one step
  const { accessToken, refreshToken, user, testUser } = await authHelper.registerAndLogin(request);

  console.log(`Logged in as ${user.email}`);

  // Cleanup
  await authHelper.logout(request, refreshToken);
});
```

### ApiHelper

```typescript
import { test } from '@playwright/test';
import { ApiHelper } from '@progalaxyelabs/stonescriptphp-e2e-test-helpers';

test('run CRUD test cycle', async ({ request }) => {
  const apiHelper = new ApiHelper({
    apiUrl: 'http://localhost:3130',
  });

  const token = 'your-jwt-token';

  const result = await apiHelper.crudTest(request, token, {
    basePath: '/api/items',
    createPayload: { name: 'Test Item', description: 'Test' },
    updatePayload: { name: 'Updated Item' },
    idField: 'id',
  });

  console.log('CRUD test passed:', result);
});
```

### PageHelper

```typescript
import { test } from '@playwright/test';
import { PageHelper } from '@progalaxyelabs/stonescriptphp-e2e-test-helpers';

test('verify Angular bootstrap', async ({ page }) => {
  await PageHelper.checkAngularBootstrap(page, 'http://localhost:3132');
});

test('check console errors', async ({ page }) => {
  const result = await PageHelper.checkConsoleErrors(page, 'http://localhost:3132', {
    failOnCritical: true,
    ignorePatterns: [/favicon/],
  });

  console.log(`Found ${result.errors.length} console messages`);
});
```

## Platform Configurations

Pre-configured platforms available via `PLATFORMS` export:

- **progalaxyelabs**: API (3130), Accounts (3132), Admin (3133), Marketing (3134), CRM (3136), Pay (3138)
- **progalaxy**: API (3040), WWW (3042), Admin (3045), HR (3046)
- **btechrecruiter**: API (3051), ATS (3052), Exam (3053), Admin (3054), Chat (3055)
- **instituteapp**: API (3030), Portal (3032), Student (3034), Partner (3036)
- **restrantapp**: API (3041), WWW (3040), Business (3042), Alert (3043)
- **medstoreapp**: API (3011), Portal (3010), Admin (3015), Alert (3013), File Server (3014) - Multi-tenant
- **logisticsapp**: API (3120), Portal (3122), Admin (3123) - Multi-tenant

All platforms use auth service at `http://localhost:3139`.

## API Reference

### AuthHelper

- `generateTestUser(prefix?)`: Generate unique test user credentials
- `register(request, user)`: Register a new user
- `login(request, user)`: Login and get JWT tokens
- `logout(request, refreshToken)`: Logout user
- `registerAndLogin(request, user?)`: Register and login in one step
- `healthCheck(request)`: Check auth service health

### ApiHelper

- `healthCheck(request)`: Check API health
- `get<T>(request, path, token)`: GET with envelope unwrapping
- `post<T>(request, path, token, body?)`: POST with envelope unwrapping
- `put<T>(request, path, token, body?)`: PUT with envelope unwrapping
- `delete<T>(request, path, token)`: DELETE with envelope unwrapping
- `crudTest(request, token, config)`: Full create-read-update-delete cycle
- `responseTimeCheck(request, maxMs?)`: Verify response time

### PageHelper (static methods)

- `loadAndVerify(page, options)`: Load page and verify title
- `checkConsoleErrors(page, url, options?)`: Collect console errors
- `checkAngularBootstrap(page, url)`: Verify Angular bootstrapped
- `checkNavigation(page, url, options?)`: Test link navigation
- `verifyAuthenticatedPage(page, url, token, options?)`: Verify authenticated state

## Test Fixtures

Using `createPlatformTest()` provides three fixtures:

- **authHelper**: AuthHelper instance for the platform
- **apiHelper**: ApiHelper instance for the platform's API service
- **authenticatedUser**: Auto-registered and logged-in user with cleanup

## License

MIT

## Author

Progalaxy E-Labs