@playforge/core

Enterprise-grade Playwright framework with extended fixtures, annotations, and waiting utilities. Part of the PlayForge framework.

Installation

npm install @playforge/core

Requires @playwright/test >= 1.40.0 as a peer dependency.

Quick Start

Replace your Playwright imports with PlayForge:

// Before
import { test, expect } from '@playwright/test';

// After
import { test, expect } from '@playforge/core';

Your tests now have access to config and annotate fixtures:

test('login flow', async ({ page, config, annotate }) => {
  annotate.step('Navigate to login page');
  await page.goto(config.baseURL + '/login');

  await test.step('Enter credentials', async () => {
    await loginSteps.enterCredentials('[email protected]', 'password');
  });

  annotate.success('Login completed');
});

Modules

Timeout Presets

import { timeouts } from '@playforge/core/timeouts';

await page.waitForSelector('#loaded', { timeout: timeouts.medium });

| Preset | Value | Use case | |--------|-------|----------| | short | 5s | Quick element interactions | | medium | 15s | Form submissions, API calls | | long | 30s | Page loads, heavy operations | | navigation | 30s | Full page navigation | | fileUpload | 60s | File upload/download |

Annotations

import { annotations } from '@playforge/core/annotations';

test('checkout', async ({ page }, testInfo) => {
  annotations.step(testInfo, 'Add item to cart');
  // ... test code
  annotations.success(testInfo, 'Checkout completed');
});

Or use the built-in fixture (no import needed):

import { test } from '@playforge/core';

test('checkout', async ({ annotate }) => {
  annotate.step('Add item to cart');
  annotate.success('Checkout completed');
});

Available annotations: step, success, failure, warning.

Waiting Utilities

import { waitFor } from '@playforge/core/waiting';

// Retry a flaky locator action
await waitFor.elementWithRetry(
  page.getByRole('button', { name: 'Submit' }),
  (btn) => btn.click(),
  { retries: 3, delay: 500 },
);

// Wait for page to finish loading
await waitFor.loadingComplete(page, { timeout: 15_000 });

Environment Config

Configuration is loaded from environment variables:

| Variable | Default | Description | |----------|---------|-------------| | PLAYFORGE_BASE_URL | '' | Application base URL | | PLAYFORGE_ENV | 'local' | Environment name | | PLAYFORGE_TIMEOUT_MULTIPLIER | 1 | Timeout scaling factor | | PLAYFORGE_RETRY_COUNT | 2 | Default retry count |

Access via the config fixture:

import { test } from '@playforge/core';

test('example', async ({ config }) => {
  console.log(config.environment); // 'staging'
  console.log(config.baseURL);     // 'https://staging.example.com'
});

Or load directly:

import { loadConfig } from '@playforge/core';

const config = loadConfig({ baseURL: 'https://override.example.com' });

Requirements

• Node.js >= 20
• @playwright/test >= 1.40.0

License

MIT