pytest-playwright-artifacts 0.3.1

Capture screenshots, HTML, and console logs on Playwright test failures

Capture debugging artifacts on Playwright test failures

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.

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 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 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 \\.).

• file — required; regex matched against the console message's source URL
• message — optional; regex matched against the raw console text

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

playwright_console_ignore = [
  # Ignore everything from a third-party bundle
  { file = "vendor/sentry\\.js" },
  # 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=[
        {"file": r"third-party\.js"},
        {"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"

Related Projects

• 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