Playwright end-to-end tests (E2E)¶

End-to-end tests for this module use Playwright. Tests are under tests/src/Playwright.

This document provides a short Quickstart, examples for local/Docker usage and troubleshooting tips.

Prerequisites¶

• Composer dev dependencies (run from repository root):

composer require drush/drush --dev
composer require drupal/core-dev:^11.4 -W --dev

• Node and package manager (node >= 20, npm or Yarn). From the module folder install JS deps:

cd path/to/display_builder
npm install
# or: yarn install

• Install Playwright browsers (recommended with system deps):

npx playwright install --with-deps

See the Playwright installation docs for more details.

Notes:

• On some Linux distributions (e.g. Fedora support) you may need extra system packages before installing browsers. See the Playwright installation docs for distro-specific packages. As a workaround on Fedora, install the following packages:

dnf install \
    libicu \
    libjpeg-turbo \
    libwebp \
    flite \
    pcre \
    libffi

Playwright will throw an error on install but tests will work except for Webkit.

Quickstart¶

• Copy env and adjust if needed:

cd path/to/display_builder
cp .env.dist .env

• Run the base tests with firefox locally:

npx playwright test -c playwright.local.config.ts --project=firefox -g @base
# or use npm script
npm run test

The package.json scripts wrap the same commands:

If you need to run a single test file or grep-style selection:

npx playwright test -c playwright.local.config.ts --project=firefox page.spec.ts
npx playwright test -c playwright.local.config.ts --project=firefox -g 'Page Layout'

Use --headed or --ui while debugging:

npx playwright test -c playwright.local.config.ts --project=firefox -g 'Page Layout' --headed
npx playwright test -c playwright.local.config.ts --project=firefox -g 'Page Layout' --ui

More information on Playwright running and debugging tests.

Important env/settings notes:

• DRUPAL_TEST_BASE_URL must point to your site base: http://localhost:8000 with the PHP web server that playwright.local.config.ts launches automatically, or http://localhost:8000/web for a manual php -S localhost:8000 from the Drupal root.
• DRUPAL_TEST_SKIP_INSTALL allow a more specific behavior by having an installed Drupal with a running stack.
• Without it, DRUPAL_TEST_SETUP_FILE (path to tests/src/TestSite/DisplayBuilderTestSetup.php, relative to the web root) and DRUPAL_TEST_DB_URL set up the site to install.
• DRUPAL_TEST_DRUSH_PREFIX prefixes Drush calls (e.g. ddev), PLAYWRIGHT_DEBUG_LEVEL sets the test reporter verbosity.
• For tests run against an installed Drupal, enable in settings.php:

$settings['extension_discovery_scan_tests'] = TRUE;

• Modules that MUST be enabled for tests (as installed by tests/src/TestSite/DisplayBuilderTestSetup.php):
• breakpoint
• language, with a de language and path prefix negotiation
• ui_patterns
• ui_styles
• display_builder
• display_builder_ui
• display_builder_page_layout
• display_builder_test
• display_builder_page_layout_test

Specs needing more (entity view, Views, ui_skins) enable their modules themselves.

Theme MUST be display_builder_theme_test by default, unless test is specific for a theme.

Copy and adapt the .env.dist file as .env to set your environment.

There are different cases for running tests with a full installation or on a running Drupal instance to avoid the install step.

PHPUnit¶

PHPUnit tests live in tests/src/Unit, tests/src/Kernel and tests/src/FunctionalJavascript, and in each submodule's tests/src/Kernel and tests/src/Functional. Groups are declared with #[Group(...)] attributes, one per module: display_builder, display_builder_entity_view, display_builder_page_layout, display_builder_ui, display_builder_views. Run them with Drupal core's PHPUnit configuration, for example:

vendor/bin/phpunit -c web/core --group display_builder_views

Accessibility¶

tests/src/Playwright/Tests/accessibility.spec.ts runs axe (@axe-core/playwright, a devDependency) over the .display-builder element and fails on:

• any violation whose rule id is not listed in the spec's KNOWN_VIOLATIONS array;
• anything of critical impact, listed or not.

KNOWN_VIOLATIONS is currently empty — the builder has zero axe violations. Adding an id to it is admitting a regression: prefer fixing the violation, and never add an entry without a comment saying why.

Two Shoelace-specific traps, both handled centrally, worth knowing before adding UI:

• Icon-only buttons. sl-button's focusable element is the <button part="base"> inside its shadow root, which an aria-label on the host does not name. The accessible name has to come from the slotted <sl-icon label="…"> — see components/shoelace/button/button.twig.
• Inputs. A placeholder is not a name. Pass a label to display_builder:input so Shoelace renders a real <label for>; hide it visually if the design has no room for it (see components/library_panel/search.css).

Docker: remote Playwright server¶

When you cannot install native browsers, run a Playwright server in Docker and connect to it. See the Playwright remote browsers docs.

The image tag and the playwright@ version MUST match the @playwright/test version in package.json, otherwise the client refuses to connect. Read it first:

node -p "require('./package.json').devDependencies['@playwright/test']"

• Run Playwright server container, with PW set to that version:

PW=1.63.0
docker pull mcr.microsoft.com/playwright:v$PW-noble
docker run --add-host=hostmachine:host-gateway --rm -it -p 3000:3000 \
    --workdir /home/pwuser --user pwuser \
    mcr.microsoft.com/playwright:v$PW-noble \
    /bin/sh -c "npx -y playwright@$PW run-server --port 3000 --host 0.0.0.0"

• Run Webserver from Drupal root:

php -S 0.0.0.0:8000 -t web/

• Launch tests pointing to the remote WS endpoint:

PW_TEST_CONNECT_WS_ENDPOINT=ws://127.0.0.1:3000/ \
DRUPAL_TEST_BASE_URL='http://localhost:8000' \
    npx playwright test --project=firefox -g '@base'

Tips:

• Ensure ports and host mappings allow the test runner to reach the Docker container.
• If you use --add-host=hostmachine:host-gateway you may need to use that hostname in the container to reach the host.

Reporting and debugging¶

• The config already collects traces/screenshots/videos on failures per playwright.config.ts.
• To open the HTML report locally after a run, open playwright-report/index.html in the module folder.
• To collect a trace for a failing test, re-run with --trace on or rely on the config: trace: 'on-first-retry' in playwright.config.ts, trace: 'retain-on-first-failure' in playwright.local.config.ts. View traces with the Playwright trace viewer.

Troubleshooting (common issues)¶

• Playwright browser install fails: install system dependencies for your distro or use the Docker image.
• WebKit tests: WebKit is unreliable or unsupported on many Linux CI images — skip or use Chromium/Firefox in CI.
• Docker WS connection: ensure PW_TEST_CONNECT_WS_ENDPOINT points to the container and firewall rules allow the connection.
• Failing Drupal tests: verify required modules are enabled (see the list above), the test theme is active (display_builder_theme_test), and extension_discovery_scan_tests is enabled when running against an installed site.
• Timeouts: DRUPAL_TEST_SKIP_INSTALL toggles shorter timeouts in playwright.config.ts — unset it for full install flows. playwright.local.config.ts uses a fixed 180s test timeout.

Where to look in this repo¶

• package.json for test scripts
• Local Playwright config: playwright.local.config.ts
• DDEV Playwright config: playwright.ddev.config.ts (https://display-builder.ddev.site, no retries, no traces)
• Main Playwright config: playwright.config.ts

Fast debug checklist¶

• Run a single failing spec with --headed and --ui.
• Re-run with --trace or open the trace in the Playwright trace viewer.
• Check playwright-report for screenshots/videos.