pytest-playwright-softassert

A complete soft-assertion layer over Playwright's native expect() API.

Design

soft_expect(target, message) is a direct, thin wrapper around Playwright's own expect.soft(target, message). It returns Playwright's native LocatorAssertions, PageAssertions, or APIResponseAssertions object unchanged, so:

• Every current Playwright assertion method is available automatically.
• Every future Playwright assertion method will be available automatically.
• All assertion options (timeout, ignore_case, use_inner_text, regex, lists, …) pass through to Playwright without modification.
• Playwright's auto-retry, error messages, and call logs are fully preserved.
• No Playwright assertion logic is reimplemented.

Failure collection and per-test reporting are handled by Playwright's own _soft_scope() mechanism, activated by the pytest_runtest_call hook registered by this package.

Installation

pip install pytest-playwright-softassert

Usage

Sync

from pytest_playwright_softassert import soft_expect

def test_example(page):
    soft_expect(page.get_by_role("button", name="Save")).to_be_visible()
    soft_expect(page.get_by_text("Success")).to_have_text("Success")
    soft_expect(page).to_have_url("/dashboard")
    soft_expect(response).to_be_ok()

With custom message

soft_expect(
    page.get_by_role("heading"),
    "Dashboard heading must be visible"
).to_be_visible()

With assertion options

import re

soft_expect(locator).to_have_text("Hello", timeout=10_000, ignore_case=True)
soft_expect(locator).to_have_text(re.compile(r"Order\s+\d+"))
soft_expect(locator).to_have_text(["Item 1", "Item 2", "Item 3"])

Negative assertions

soft_expect(locator).not_to_be_visible()
soft_expect(locator).not_to_have_text("Error")
soft_expect(page).not_to_have_url(re.compile(r"/error"))

Async

from pytest_playwright_softassert import async_soft_expect

async def test_example(page):
    await async_soft_expect(locator).to_be_visible()
    await async_soft_expect(page).to_have_url("/dashboard")

Behaviour

Running the compatibility tests

pytest tests/test_compatibility.py -v

These tests verify that soft_expect exposes the same assertion method surface as Playwright's native expect() for LocatorAssertions, PageAssertions, and APIResponseAssertions. They run without a browser and should be included in CI.

Running the integration tests

playwright install chromium
pytest tests/test_integration.py --browser chromium -v