Skip to main content

Capture debugging artifacts on Playwright test failures

Release Notes Downloads GitHub CI Status License: MIT

When your Playwright tests fail, you need to see what went wrong. This pytest plugin does a couple things to make it easier for you (and LLMs!) to debug and build Playwright tests:

  1. Automatically captures HTML, screenshots, console logs, and failure summaries the moment a test fails and dumps them into a per-test folder for easy debugging.
  2. Allows you to assert that no console errors were logged during a test.
  3. Automatically retry tests that fail due to Playwright flakiness

No more guessing what the page looked like, what JavaScript errors occurred, or what the actual DOM content was.

Installation

uv add --dev pytest-playwright-artifacts

The plugin activates automatically once installed. No configuration needed.

Usage

Artifacts on failure

def test_my_page(page):
    page.goto("https://example.com")
    assert page.title() == "Example"

When this test fails, you'll find artifacts in test-results/<test-name>/:

  • failure.html - Rendered DOM content at the moment of failure
  • screenshot.png - Full-page screenshot
  • failure.txt - Failure summary with traceback
  • console_logs.log - All captured console messages

Console messages are captured for every test but are only written to console_logs.log on failure. During a passing test they are emitted at DEBUG log level via structlog and are not visible in normal pytest output.

Fail tests on console errors

from pytest_playwright_artifacts import assert_no_console_errors


def test_no_console_errors(page, request):
    page.goto("https://example.com")
    assert_no_console_errors(request)

This fails the test if any console.error() messages were logged during the test. Use clear_console_errors() to exclude messages captured before a specific point from subsequent assertions without removing them from console log output:

from pytest_playwright_artifacts import (
    assert_no_console_errors,
    clear_console_errors,
)


def test_no_console_errors_after_login(page, request):
    page.goto("https://example.com/login")
    clear_console_errors(request)

    page.get_by_role("button", name="Log in").click()
    assert_no_console_errors(request)

Retry on Playwright timeouts

Playwright tests can flake due to network latency or slow animations. The plugin can retry a test automatically when it fails with a TimeoutError. Only playwright._impl._errors.TimeoutError triggers a retry — assertion failures and other errors fail immediately. Retried attempts show as R / RERUN in pytest output.

Per-test

@pytest.mark.playwright_timeout_retries(2)
def test_checkout(page):
    page.goto("https://example.com/checkout")
    page.click("#pay-button")
    expect(page.locator(".success")).to_be_visible()

Per-folder

Add a pytestmark to conftest.py in the folder you want to cover:

# tests/e2e/conftest.py
import pytest

pytestmark = [pytest.mark.playwright_timeout_retries(2)]

Global default

Set a default for the entire suite in pyproject.toml. A marker on an individual test or folder always takes precedence.

[tool.pytest.ini_options]
playwright_timeout_retries = 2

Configuration

Filter noisy console messages

Use regex patterns to ignore known noisy messages:

pyproject.toml:

[tool.pytest.ini_options]
playwright_console_ignore = [
  "Invalid Sentry Dsn:.*",
  "Radar SDK: initialized.*",
  # Ignore all messages from a specific file/URL
  { file = "third-party-tracker\\.js" },
  # Ignore all messages from a specific domain (and subdomains)
  { domain = "example.com" },
  # Ignore only specific messages from a file
  { file = "analytics\\.js", message = "deprecated.*" },
]

pytest.ini (plain strings only — TOML inline tables are not supported):

[pytest]
playwright_console_ignore =
  Invalid Sentry Dsn:.*
  Radar SDK: initialized.*
  # Plain strings match against the full JSON log, allowing simple domain filtering
  example.com

Plain string patterns

Plain string entries match against both the raw console text and the fully formatted log entry (which includes the type, text, arguments, and source location/URL). This allows you to filter by content OR origin.

For example, a console log like console.log("User:", {id: 1, name: "Alice"}) will be formatted as a JSON string:

{"type": "log", "text": "User: JSHandle@object", "args": ["User:", {"id": 1, "name": "Alice"}], "location": {"url": "...", "lineNumber": 1, "columnNumber": 0}}

You can match against any part of this JSON string, including expanded object arguments.

Structured dict patterns (pyproject.toml only)

Dict entries let you scope ignore rules precisely by URL and/or message.

Finding the source URL: the easiest way is to look at console_logs.log in a failed test's artifact directory. Each line includes the full location, e.g.:

{"type": "error", "text": "deprecated API", "args": [], "location": {"url": "https://cdn.example.com/analytics.js?v=2", "lineNumber": 1, "columnNumber": 0}}

Copy the relevant part of the URL and use it as the file regex (remember to escape . as \\.).

  • domain — regex-free way to ignore a hostname and its subdomains (e.g., example.com matches http://example.com, https://api.example.com, etc.). Must be a valid domain name.
  • file — regex matched against the console message's source URL
  • message — optional; regex matched against the raw console text

If only domain or file is given, all messages from matching URLs are ignored. If both are given with message, both must match (AND logic).

playwright_console_ignore = [
  # Ignore everything from a third-party bundle
  { file = "vendor/sentry\\.js" },
  # Ignore all errors from a specific domain
  { domain = "google-analytics.com" },
  # Ignore only deprecation warnings from analytics
  { file = "analytics\\.js", message = "deprecated.*" },
]

You can also pass dict patterns directly to assert_no_console_errors:

assert_no_console_errors(
    request,
    ignore=[
        {"domain": "example.com"},
        {"file": r"analytics\.js", "message": r"deprecated.*"},
    ],
)

Change artifact output directory

By default, artifacts are saved to test-results/. You can customize this:

Command line:

pytest --playwright-artifacts-output=my-artifacts

pyproject.toml:

[tool.pytest.ini_options]
playwright_artifacts_output = "my-artifacts"
  • pytest-playwright-visual-snapshot: Adds visual regression testing capabilities to your Playwright and pytest suite.
  • playwright-trace-analyzer: Provides a CLI for inspecting Playwright trace files without needing the full browser viewer.
  • pytest-plugin-utils: Offers reusable logic for managing artifacts and configurations when building other pytest plugins.
  • gh-clean-artifacts: Helps manage storage costs by pruning old or large GitHub Actions artifacts.
  • pytest-line-runner: Simplifies test execution by allowing you to run pytest tests using file line numbers.
  • pytest-celery-utils: Enables inspection of Celery task queues in Redis directly from your pytest environment.
  • python-package-prompts: Contains LLM instructions for maintaining Python standards across projects using pytest and other libraries.

MIT License


This project was created from iloveitaly/python-package-template

Metadata

Release files for pytest-playwright-artifacts 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pytest-playwright-artifacts 0.5.0
File Size Uploaded Provenance Actions
pytest_playwright_artifacts-0.5.0.tar.gz 11.7 kB Without provenance Details for pytest_playwright_artifacts-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pytest-playwright-artifacts 0.5.0
File Interpreter ABI Platform Actions
pytest_playwright_artifacts-0.5.0-py3-none-any.whl Python 3 none any Details for pytest_playwright_artifacts-0.5.0-py3-none-any.whl

Total release size: 24.7 kB

Release files / pytest_playwright_artifacts-0.5.0.tar.gz

Download URL pytest_playwright_artifacts-0.5.0.tar.gz
Size 11.7 kB
Tags Source
SHA-256 checksum
How to use checksums
5bb068f32ed75fd641ec81557f0db3cc1d63ff637d21a4bf47990efd0126fc86
BLAKE2b-256 checksum
How to use checksums
84fa51ac1ca183f1faee50e6302335aba5c45e2ecf0c9d2264020b055e37b524
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / pytest_playwright_artifacts-0.5.0-py3-none-any.whl

Download URL pytest_playwright_artifacts-0.5.0-py3-none-any.whl
Size 13.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e5cdf1da2525369388aac63833456479bc011d3a4942fd1c1ce9f49fabbd0eb2
BLAKE2b-256 checksum
How to use checksums
68d8bd71f2e953b2b7cda9fa487d3b6b779a5ec950b5a8d7f93a6d6600c9ea46
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for pytest-playwright-artifacts 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page