Mercure 1.0 alpha is available. Check out the new docs
Sponsored by Les-Tilleuls.coop
DocumentationSpecificationCloudDemos
Contribute!

Conformance tests

The Mercure repository ships a Playwright-based conformance test suite. It exercises the protocol against a running hub and checks that the responses match the spec.

Use it to:

  • Validate a third-party Mercure implementation.

  • Catch regressions when modifying the reference hub.

  • Understand the protocol by reading concrete examples.

Run the Mercure conformance test suite

# Run the Mercure Conformance Test Suite
git clone https://github.com/dunglas/mercure
cd mercure/conformance-tests
npm ci
npx playwright install --with-deps
npx playwright test

By default the suite hits a hub on https://localhost. Start one before running tests, or override BASE_URL:

# Run the Mercure Conformance Test Suite
BASE_URL=https://hub.example.com npx playwright test

Mercure conformance test configuration

VariableDescription
BASE_URLURL of the hub to test.
CUSTOM_IDToggle tests that depend on the hub honoring publisher-supplied event IDs.

Set CUSTOM_ID=0 for transports that don't support custom IDs (e.g. Pulsar, see High availability for transport feature matrices).

What the Mercure conformance suite covers

Tests are organized by spec section:

  • Subscribe semantics (match and match_urlpattern).

  • Publish semantics (form fields, single topic, custom IDs).

  • Authorization (OAuth 2.0 access token validation, authorization_details, RFC 6750 errors).

  • Reconnection (Last-Event-ID, last_event_id, earliest).

  • Active subscriptions (events + API).

Run with --ui for the interactive Playwright explorer; useful when debugging a specific assertion failure.

  • Load test: measures throughput, not correctness.

  • Protocol: the spec the tests are validating against.