🎭 playwright-tools

A comprehensive collection of utilities for Playwright testing that simplify common testing patterns and enhance your automation workflow.

---

✨ Features

• 🛡️ Safe Element Interactions - Built-in waits and error handling for reliable interactions
• 🔄 Retry Mechanisms - Exponential backoff retry logic for flaky operations
• 📸 Enhanced Screenshots - Timestamped screenshots with debugging annotations
• 🔍 Element Queries - Existence checks and bulk operations without throwing errors
• 🌐 Navigation Utilities - Safe navigation with loading state checks
• ⌨️ Advanced Interactions - File uploads, drag & drop, keyboard shortcuts
• 📊 Table Utilities - Extract and validate table data efficiently
• 🎯 Accessibility Helpers - Check ARIA attributes and accessibility properties
• 💾 Storage Management - Handle localStorage and sessionStorage operations
• 🌍 Network Helpers - Wait for specific requests and monitor network activity
• 🔧 Page Objects - Reusable page object patterns and utilities
• 📝 Test Data Factories - Generate consistent test data across tests
• 📋 Assertions - Enhanced assertion helpers for multiple elements
• ⚡ Test Utilities - Filter and dispatch tests with skip/runOnly flags
• 🧪 TypeScript Support - Full type safety with comprehensive TypeScript definitions
• 🪶 Zero Dependencies - No additional dependencies beyond Playwright

---

📦 Installation

npm install playwright-tools

Peer Dependency: This package requires @playwright/test to be installed in your project.

npm install @playwright/test

---

🚀 Quick Start

Basic Usage

import { safeClick, safeFill, elementExists } from "playwright-tools";

// Safe element interactions
await safeClick(page.locator("#submit-button"));
await safeFill(page.locator("#username"), "john.doe@example.com");

// Check element existence without throwing
const exists = await elementExists(page.locator("#optional-element"));

Modular Imports

Import specific modules for better tree-shaking:

// Import specific modules
import { safeClick, safeFill } from "playwright-tools/interactions";
import { waitForElements, elementExists } from "playwright-tools/element-queries";
import { takeTimestampedScreenshot } from "playwright-tools/screenshots";
import { retryAction } from "playwright-tools/retry";

// Or import everything
import * as pwUtils from "playwright-tools";

---

📚 Documentation

📖 Complete documentation is available in the docs directory:

• 📖 Main Documentation - Overview and navigation
• 🎯 Element Interactions - Safe clicks, fills, and form handling
• 🔍 Element Queries - Existence checks and bulk operations
• 🌐 Navigation - Safe navigation and page management
• ⌨️ Advanced Interactions - File uploads, drag & drop, keyboard shortcuts
• 🌐 Locator Decorator - Extend Playwright locators with custom methods
• 📸 Screenshots - Timestamped and debug screenshots
• 📋 Assertions - Enhanced assertion helpers
• ⏳ Waiting - Smart waiting strategies
• 🔄 Retry - Exponential backoff retry logic
• 🎯 Accessibility - ARIA and accessibility testing
• 💾 Storage - localStorage and sessionStorage management
• 🌍 Network - Network request monitoring and waiting
• 📊 Network Monitoring - Advanced network analysis
• 💬 Dialogs - Modal and popup handling
• 📊 Tables - Table data extraction and validation
• 🔧 Page Objects - Reusable page object patterns
• ⚡ Performance - Performance measurement utilities
• 🛠️ Error Handling - Error handling patterns
• ⚡ Test Utils - Test filtering and dispatching

Guides & Examples

• 📝 Examples - Practical usage examples
• 🚀 Migration Guide - From raw Playwright to playwright-tools
• 🛠️ Best Practices - Recommended patterns and configurations

---

💡 Quick Examples

Form Handling

import { fillForm, safeClick } from "playwright-tools";

await fillForm([
  { locator: page.locator("#username"), value: "john.doe" },
  { locator: page.locator("#password"), value: "secure123" },
  { locator: page.locator("#email"), value: "john@example.com" },
]);

await safeClick(page.locator("#submit"));

Element Queries

import { elementExists, waitForElements } from "playwright-tools";

// Check if element exists without throwing
const exists = await elementExists(page.locator("#optional-element"));

// Wait for multiple elements concurrently
await waitForElements([
  page.locator("#header"),
  page.locator("#navigation"),
  page.locator("#content"),
]);

Network Monitoring

import { waitForNetworkRequest } from "playwright-tools";

// Wait for specific API call
const response = await waitForNetworkRequest(page, "/api/users", {
  method: "GET",
  status: 200,
  timeout: 10000,
});

Retry Logic

import { retryAction } from "playwright-tools";

// Retry flaky operations with exponential backoff
const result = await retryAction(
  async () => {
    await page.click("#sometimes-slow-button");
    return await page.locator("#result").textContent();
  },
  { maxRetries: 3, baseDelay: 1000 }
);

Locator Decorator

The Locator Decorator lets you extend Playwright locators with custom methods, enhanced safe interactions, and even method overrides. This makes your locators more powerful, reusable, and tailored to your app.

Key Features

• Add your own methods to any locator
• Use enhanced methods like safeClick, safeFill, extractData, and more
• Override existing locator methods (e.g., custom click)
• Factory and page extension patterns for consistent usage

Quick Example

import { createEnhancedLocator, extendPage } from "playwright-tools";

// Enhance a single locator
const enhanced = createEnhancedLocator(page.locator("#my-btn"), {
  customMethods: {
    async highlight() {
      await this.evaluate(el => el.style.border = "2px solid red");
    }
  }
});
await enhanced.safeClick();
await enhanced.highlight();

// Or extend the whole page for consistent usage
const enhancedPage = extendPage(page, {
  customMethods: {
    async waitForAnimation() {
      await this.waitForFunction(() => !document.querySelector('[style*="animation"]'));
    }
  }
});
const btn = enhancedPage.locator("#my-btn");
await btn.safeClick();
await btn.waitForAnimation();

See the full documentation:
📖 Locator Decorator Guide

---

🔗 Quick Links

• 📖 Full Documentation
• 📝 Examples
• 🚀 Migration Guide
• 🛠️ Best Practices
• 🐛 Issues & Bug Reports
• 💬 Discord Community

---

📖 Resources & Learning Materials

🦎 Practice Application

• GAD (GUI API Demo) - Our free application designed specifically for automation practice

🇵🇱 Polish Resources

• Free Playwright Resources - Comprehensive Polish learning materials
• Playwright Basics - YouTube series (Polish)
• Playwright Elements - Advanced concepts (Polish)
• Playwright MCP - MCP course (Polish)
• Discord Community - First Polish Playwright community!
• Playwright Info - First and only Polish Playwright blog

🇬🇧 English Resources

• VS Code Extensions - Our free Playwright plugins
• Playwright Documentation - Official documentation
• Playwright GitHub - Source code and issues

---

📞 Contact & Support

Feel free to reach out to us:

• 🌐 Website: jaktestowac.pl
• 💼 LinkedIn: jaktestowac.pl
• 💬 Discord: Polish Playwright Community
• 📧 Support: Check our website for contact details
• 🐛 Issues: GitHub Issues

---

🌟 Show Your Support

If you found this package helpful:

• ⭐ Star this repository to show your support
• 🔄 Share with your team to help spread knowledge about advanced Playwright testing patterns
• 🗣️ Tell the community about your experience with playwright-tools
• 💝 Contribute by submitting issues or pull requests

---

Happy testing and automating tests! 🚀

jaktestowac.pl Team 💚❤️

PS. For more resources and updates, follow us on our website and GitHub.

---

Built with 💚❤️ for the Playwright and testing automation community