@tobiashochguertel/playwright-debug-helper

Comprehensive debugging utilities for Playwright tests

Features

✨ Comprehensive Debugging

• 📝 Console message capture (errors, warnings, logs)
• 🌐 Network error tracking (failed requests, HTTP errors)
• 🏷️ Test ID discovery and validation
• 🖱️ Interactive element inspection
• 📄 HTML structure logging
• 📸 Screenshot capture
• ⚡ Performance metrics
• 💾 Storage state inspection (localStorage, sessionStorage, cookies)
• ⏳ Wait helpers with automatic debug logging

🎯 Environment Control

• Enable/disable via PLAYWRIGHT_DEBUG environment variable
• Fine-grained control over individual features
• CI-friendly (can be disabled in production)

🧪 Well-Tested

• Comprehensive unit tests
• Integration tests with real Playwright
• 80%+ code coverage

📚 Well-Documented

• Full API documentation
• Usage examples
• TypeScript types included

Installation

npm install --save-dev @tobiashochguertel/playwright-debug-helper

pnpm add -D @tobiashochguertel/playwright-debug-helper

yarn add -D @tobiashochguertel/playwright-debug-helper

Quick Start

Basic Usage

import { test } from "@playwright/test";
import {
  setupTestDebug,
  debugTest,
} from "@tobiashochguertel/playwright-debug-helper";

test("my test", async ({ page }) => {
  // Setup debug logging for this test
  const debug = await setupTestDebug(page, {
    logConsole: true,
    logNetwork: true,
  });

  await page.goto("https://example.com");

  // Quick debug at any point
  await debugTest(page, "After navigation");

  // Access captured data
  console.log(debug.getConsoleMessages());
  console.log(debug.getNetworkErrors());

  // Print summary
  debug.printDebugSummary();
});

Output:

When you run this test, you'll see helpful debug information in your console:

🌐 [NETWORK FAILED] GET https://example.com/api/data: Connection refused

================================================================================
📊 DEBUG SUMMARY
================================================================================

📝 Console Messages (2):
  [ERROR] Failed to load resource
  [WARN] Deprecated API usage detected

🌐 Network Errors (1):
  [GET] https://example.com/api/data: Connection refused
================================================================================

Advanced Usage

import { TestDebugHelper } from "@tobiashochguertel/playwright-debug-helper";

test("advanced debugging", async ({ page }) => {
  const debug = new TestDebugHelper(page);

  // Enable all debug features
  await debug.enableDebugLogging({
    logConsole: true,
    logNetwork: true,
    logHtmlStructure: true,
    logScreenshot: true,
    logPerformance: true,
    logStorage: true,
  });

  await page.goto("https://example.com");

  // Log performance metrics
  const metrics = await debug.logPerformanceMetrics();
  console.log("Load time:", metrics.loadTime);

  // Log storage state
  const storage = await debug.logStorageState();
  console.log("LocalStorage:", storage.localStorage);

  // Take screenshot
  await debug.takeDebugScreenshot("debug-screenshot.png");

  // Wait with debug logging
  await debug.waitForElementWithDebug('[data-testid="submit"]', 10000);

  // Log available test IDs
  await debug.logTestIds();

  // Log interactive elements
  await debug.logInteractiveElements();
});

Output:

⚡ PERFORMANCE METRICS:
================================================================================
  Load Time: 1250ms
  DOM Ready: 850ms
  First Paint: 420ms
  First Contentful Paint: 580ms
================================================================================

💾 STORAGE STATE:
================================================================================
LocalStorage:
{
  "userId": "12345",
  "theme": "dark",
  "sessionToken": "abc..."
}

SessionStorage:
{
  "tempData": "value"
}

Cookies:
session_id=xyz789; auth_token=def456
================================================================================

📸 Screenshot saved: debug-screenshot.png

🏷️  AVAILABLE TEST IDS:
================================================================================
✅ [submit-button] <button> "Submit Form"
✅ [email-input] <input>
✅ [password-input] <input>
❌ [cancel-button] <button> "Cancel"
================================================================================

🖱️  INTERACTIVE ELEMENTS:
================================================================================
✅ <button type="submit"> submit-button
✅ <input type="email"> email-input
✅ <input type="password"> password-input
✅ <a href="/help"> help-link
================================================================================

Environment Control

Enable debug logging via environment variable:

# Enable debug logging
PLAYWRIGHT_DEBUG=true npm run test

# Disable debug logging (default)
npm run test

In your code:

// Debug will only run when PLAYWRIGHT_DEBUG=true
const debug = await setupTestDebug(page);

// Force debug even when PLAYWRIGHT_DEBUG is not set
const debug = await setupTestDebug(page, {
  logConsole: true, // Any option set to true will force enable
});

Examples

📁 Example Projects

The examples/ directory contains complete, runnable example projects demonstrating various use cases:

• basic-usage - Simple setup and usage
• network-debugging - Track failed requests and HTTP errors
• performance-testing - Monitor page performance metrics
• screenshot-capture - Automated screenshot debugging
• wait-helpers - Smart waiting with automatic debug logging

Each example includes:

• ✅ Complete project setup with package.json
• ✅ Runnable test files
• ✅ Expected output examples
• ✅ Step-by-step README

Run any example:

cd examples/basic-usage
npm install
npm test

See examples/README.md for detailed information.

📖 Documentation Examples

See EXAMPLES.md for more code snippets and usage patterns.

See API.md for detailed API documentation.

Main Exports

• TestDebugHelper - Main debug helper class
• setupTestDebug() - Factory function to create and enable debug helper
• debugTest() - Quick debug function for one-off debugging

Types

• DebugOptions - Configuration options
• ElementInfo - Test ID element information
• InteractiveElement - Interactive element information
• PerformanceMetrics - Performance metrics data
• StorageState - Storage state data
• NetworkError - Network error information
• ConsoleMessage - Console message information

Examples

See EXAMPLES.md for more usage examples.

Development

Setup

# Install dependencies
npm install

# Or use Task
task install

Build

# Build the package
npm run build

# Or use Task
task build

Test

# Run tests
npm run test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Or use Task
task test
task test:watch
task test:coverage

Type Checking

# Run TypeScript type checking
npm run typecheck

# Or use Task
task typecheck

Linting

# Run ESLint
npm run lint

# Fix linting issues
npm run lint:fix

# Or use Task
task lint
task lint:fix

Publishing

# Dry run
npm publish --dry-run

# Publish to npm
npm publish

# Or use Task
task publish:dry
task publish

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT © Tobias Hochgürtel

Changelog

See CHANGELOG.md for version history.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions