@pdnsyamkumar/playwright-base

Reusable Playwright test utilities. Includes BaseTestData, BaseApi, and WaitUtils.

Supports both ES6 Modules (import) and CommonJS (require).

Installation

npm install @pdnsyamkumar/playwright-base

🛠️ Components

1. BaseTestData

💡 Note: BaseTestData has been extracted into @pdnsyamkumar/test-utils for framework-agnostic usage. It is re-exported here for backward compatibility.

Helper for building test data objects with override, exclude, and only options.

import {
  BaseTestData,
  GetTestDataOptions,
} from "@pdnsyamkumar/test-utils";

const testData = new BaseTestData();

const defaults = {
  firstName: "Syam Kumar",
  lastName: "Pdn",
  email: "[email protected]",
  preferences: {
    notifications: {
      email: true,
      sms: false,
    },
  },
};

// Override specific fields
const updated = testData.getTestData(defaults, {
  override: { lastName: "PDN" },
});

// Exclude specific fields
const minimal = testData.getTestData(defaults, {
  exclude: ["email", "preferences.notifications.sms"],
});

// Keep only selected fields
const whiteListed = testData.getTestData(defaults, {
  only: ["firstName", "preferences.notifications.email"],
});

Usage Examples

| Option | Description | Example Usage | Resulting Object | | -------------- | ----------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------- | | override | Overrides specific fields | { override: { lastName: "PDN" } } | { firstName: "Syam Kumar", lastName: "PDN", email: "[email protected]" } | | exclude | Removes top-level fields or nested dot paths | { exclude: ["email", "preferences.notifications.sms"] } | User object without email and nested sms | | only | Keeps only top-level fields or nested dot paths | { only: ["firstName", "preferences.notifications.email"] } | User object with only firstName and nested notification email setting | | Array Paths| Works seamlessly with dot notation for arrays | { exclude: ["documents.0.fileName"] } | Target specific items inside nested arrays |

Extending BaseTestData in Feature Test Data Classes

import {
  BaseTestData,
  GetTestDataOptions,
} from "@pdnsyamkumar/test-utils";

export interface NewLeadTestData {
  leadName: string;
  country: string;
  channel: string;
  clientEmail: string;
}

export class SalesTrackerTestData extends BaseTestData {
  createNewLeadTestData(
    options: GetTestDataOptions<NewLeadTestData> = {}
  ): Partial<NewLeadTestData> {
    const defaultLeadData: NewLeadTestData = {
      leadName: "Lead_991823",
      country: "INDIA",
      channel: "ONLINE",
      clientEmail: "[email protected]",
    };

    return this.getTestData(defaultLeadData, options);
  }
}

2. BaseApi

Robust base wrapper around Playwright's APIRequestContext providing automatic HTTP & GraphQL response validation, clean console table logging with sensitive data masking (🔐 ********), duration tracking, pagination handling, and caller stack trace resolution.

import { BaseApi, HttpMethod } from "@pdnsyamkumar/playwright-base";

export class UserApiService extends BaseApi {
  async getUser(userId: string) {
    return this.get({
      url: `https://api.example.com/users/${userId}`,
      options: {
        headers: { Authorization: "Bearer token" },
      },
    });
  }

  async fetchAllUsers() {
    return this.handlePagination({
      url: "https://api.example.com/users",
      options: { headers: { Authorization: "Bearer token" } },
      pageSize: 25,
      dataExtractor: (body: any) => body.data,
    });
  }
}

3. WaitUtils

WaitUtils is a centralized utility for advanced waiting scenarios in Playwright.

The standalone waitForApiResponse() export remains fully supported for existing users. New projects are encouraged to use WaitUtils.forApiResponse().

API Response Wait

Waits for an API response with matching URL (supporting single * wildcard matching) and method, then validates expected status codes.

import { WaitUtils } from "@pdnsyamkumar/playwright-base";

const response = await WaitUtils.forApiResponse(page, {
  url: "/api/products/*",
  method: "POST",
  status: 201,
  alternateStatus: 200,
  timeout: 5000,
});

Loader Wait

Waits for loading indicators to disappear completely from the DOM.

import { WaitUtils } from "@pdnsyamkumar/playwright-base";

// Default Usage (waits for page.getByTestId("icon-loading"))
await WaitUtils.forLoaderToDisappear(page);

// Custom Loader
await WaitUtils.forLoaderToDisappear(page, {
  loader: page.locator(".spinner"),
});

// Custom Timeout
await WaitUtils.forLoaderToDisappear(page, {
  timeout: 60000,
});

Migration Guide

Existing Projects

No changes are required.

Continue using

import { waitForApiResponse } from "@pdnsyamkumar/playwright-base";

await waitForApiResponse(...);

if desired. Everything will continue working exactly as before.

Recommended for New Projects

Use

import { WaitUtils } from "@pdnsyamkumar/playwright-base";

await WaitUtils.forApiResponse(...);
await WaitUtils.forLoaderToDisappear(page);

This keeps all waiting-related utilities under a single, consistent API.

License

MIT