feat: add Visual Trace Service for automatic screenshot capture during test execution

[bheemreddy-samsara]

Summary

This PR implements the Visual Trace Service functionality, adding automatic screenshot capture during test execution with smart defaults that only capture screenshots for failed tests.

Key Features

🎯 Smart Screenshot Capture

• Default behavior: Screenshots are only captured for failed tests (retain-on-failure mode)
• Respects Playwright's trace configuration modes
• Captures screenshots when steps throw errors (using try-finally pattern)
• Properly detects failures during test execution

📸 Advanced Screenshot Management

• Deduplication: Automatically skips duplicate screenshots using SHA-256 hashing
• Screenshot limits: Configurable maximum screenshots per test (default: 50)
• Smart naming: Screenshots include timestamps and step names
• State isolation: Maintains separate state for each test retry

🔧 Configuration Options

export type VisualTraceConfig = {
  enableScreenshots?: boolean | 'on' | 'off' | 'retain-on-failure';
  maxScreenshots?: number;
  dedupe?: boolean;
};

🏗️ Architecture Improvements

• Test-scoped device fixture support: Works with standard device fixture
• Worker-scoped persistentDevice support: Lazy initialization for worker-scoped fixtures
• Service reinitialization: Properly reinitializes between tests to prevent cross-test contamination
• Object trace config support: Handles both string and object Playwright trace configurations

Implementation Details

Core Components

1. Visual Trace Service (/src/visualTrace/service.ts)

   • Manages screenshot capture, deduplication, and limits
   • Integrates with Playwright's trace modes
   • Provides singleton instance management
   • Includes test isolation and reinitialization support

2. boxedStep Decorator Enhancement (/src/utils.ts)

   • Intercepts test steps to capture screenshots
   • Handles both Device and Locator contexts
   • Implements lazy initialization for persistentDevice
   • Ensures correct test context for screenshot attachment

3. Device Integration (/src/device/index.ts)

   • Exposes takeScreenshot method
   • Manages Visual Trace Service lifecycle
   • Provides initialization and cleanup methods

Test Coverage

Comprehensive unit tests covering:

• Configuration management
• Screenshot capture conditions
• Deduplication logic
• Screenshot limits
• State management and isolation
• Singleton instance management
• Runtime configuration updates

Usage

The Visual Trace Service works automatically with your existing tests:

// Screenshots are captured automatically for failed tests
test('my test', async ({ device }) => {
  await device.click(selector); // Screenshot captured if this step fails
  // ...
});

Configuration in playwright.config.ts

export default {
  use: {
    trace: 'retain-on-failure', // Default: only capture on failure
    visualTrace: {
      enableScreenshots: 'retain-on-failure',
      maxScreenshots: 50,
      dedupe: true
    }
  }
};

Changelog

Includes changeset for proper version management marking this as a minor version bump.

Testing

• ✅ All existing tests pass
• ✅ Added 25 new unit tests for Visual Trace Service
• ✅ CI/CD pipeline passes

Breaking Changes

None. The feature is fully backward compatible and works transparently with existing test suites.

Related

This is a clean PR containing only the Visual Trace Service implementation without any unrelated commits.

[changeset-bot]

🦋 Changeset detected

Latest commit: 688a3e3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
appwright	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR