Playwright Trace Viewer

Detailed explanation

The Playwright Trace Viewer is an invaluable tool for debugging and analyzing Playwright tests. It provides a comprehensive record of test executions, allowing developers and QA engineers to step through the test, inspect the DOM at various points, examine network requests, and review console logs. This level of detail significantly simplifies the process of identifying and resolving issues in automated tests.

How it Works

The Trace Viewer works by recording a trace of the test execution. This trace includes:

• Snapshots: Visual representations of the page at different stages of the test.
• Logs: Console output generated during the test.
• Network Requests: Details of all network requests made by the page.
• Source Code: The source code of the test itself.
• Actions: A chronological list of actions performed by Playwright.

When a test fails, or even when it passes but requires further investigation, the trace can be opened in the Trace Viewer. The viewer provides a timeline view of the test execution, allowing you to navigate through the different actions and inspect the state of the application at each step.

Enabling Tracing

Tracing is enabled through the tracing API in Playwright. You can configure tracing in your playwright.config.ts (or .js) file. Here's a basic example:

import { defineConfig } from '@playwright/test';
 
export default defineConfig({
  use: {
    trace: 'on-first-retry', // or 'on', 'off'
  },
});

• 'on': Always record a trace for every test. This is useful for debugging intermittent issues or for creating a comprehensive record of test executions. Be mindful of storage space when using this option in CI/CD.
• 'off': Disable tracing.
• 'on-first-retry': Record a trace only when a test fails and is retried. This is a good balance between capturing debugging information and minimizing storage overhead.
• 'on-all-retries': Record a trace for all retries.
• 'retain-on-failure': Keeps the trace available if the test fails.

You can also start and stop tracing programmatically within your tests:

import { test, expect } from '@playwright/test';
 
test('example test', async ({ page, context }) => {
  await context.tracing.start({ snapshots: true, screenshots: true, sources: true });
  await page.goto('https://example.com');
  await page.getByRole('link', { name: 'More information...' }).click();
  await context.tracing.stop({ path: 'trace.zip' });
});

This code snippet demonstrates how to start tracing before navigating to a page and stop it after performing an action. The path option specifies the location where the trace file will be saved. The snapshots, screenshots, and sources options control what data is included in the trace.

Opening the Trace Viewer

After a test run with tracing enabled, Playwright will generate a .trace file (or a .zip file containing the trace data). You can open this file using the Playwright Trace Viewer:

npx playwright show-trace trace.zip

Replace trace.zip with the actual path to your trace file. This command will launch the Trace Viewer in your browser.

Using the Trace Viewer

The Trace Viewer provides a rich interface for analyzing test executions. Key features include:

• Timeline: A chronological view of the test execution, showing each action performed by Playwright.
• Snapshot Viewer: Allows you to inspect the DOM at different points in the test. You can view the HTML, CSS, and JavaScript of the page.
• Network Inspector: Shows all network requests made by the page, including headers, payloads, and responses.
• Console Logs: Displays all console output generated during the test.
• Source Code: Shows the source code of the test, allowing you to easily correlate actions with the code that triggered them.
• Call Stack: Displays the call stack for each action, helping you understand the flow of execution.

Practical Implementation and Best Practices

• Selective Tracing: Avoid enabling tracing for all tests in production environments. Use it selectively for debugging specific issues or for monitoring critical workflows.
• Configure Trace Options: Carefully configure the snapshots, screenshots, and sources options to include the data you need for debugging without generating excessively large trace files.
• Integrate with CI/CD: Integrate tracing into your CI/CD pipeline to automatically capture traces for failed tests. This can significantly speed up the debugging process.
• Use Annotations: Use Playwright's annotation features to add custom messages and markers to the trace. This can help you highlight important events or sections of the test. For example:

import { test, expect } from '@playwright/test';
 
test('annotated test', async ({ page }) => {
  await page.goto('https://example.com');
  test.info().attach('My Custom Attachment', { body: 'Some data', contentType: 'text/plain' });
  await expect(page).toHaveTitle('Example Domain');
});

• Filter and Search: Use the Trace Viewer's filtering and search capabilities to quickly find specific actions, network requests, or console messages.
• Compare Traces: Playwright allows you to compare two traces side-by-side, highlighting the differences between them. This can be useful for identifying regressions or for understanding the impact of code changes.
• Redact Sensitive Information: Be mindful of sensitive information that may be captured in the trace, such as passwords or API keys. Use Playwright's redaction features to mask this information before sharing the trace with others.

Common Tools and Integrations

• Playwright CLI: The Playwright CLI provides commands for managing traces, including opening, comparing, and converting them.
• Playwright Test Runner: The Playwright test runner automatically captures traces for failed tests when tracing is enabled.
• CI/CD Integrations: Playwright integrates with popular CI/CD platforms such as GitHub Actions, GitLab CI, and Jenkins. These integrations allow you to automatically capture and store traces for failed tests in your CI/CD pipeline.

The Playwright Trace Viewer is a powerful tool that can significantly improve the efficiency and effectiveness of your testing efforts. By providing a detailed record of test executions, it simplifies the process of identifying and resolving issues, leading to more reliable and robust software.

Further reading

• Playwright Tracing Documentation
• Playwright Configuration
• Playwright CLI