Add browser interaction and accessibility tests with Playwright

[vitormattos]

pdf-elements currently uses Vitest and happy-dom for automated tests. These are useful for component logic, but some behaviors of a PDF editor depend on a real browser environment.

Before expanding the editor with more complex element and form-field interactions, add browser-level tests with Playwright for the most important user interactions and accessibility behavior.

pdf-elements is a generic Vue 3 library. The Playwright setup must run against the package demo or another lightweight local test page and must not require Nextcloud or LibreSign.

What should be done

Add Playwright

Add Playwright to the development dependencies and provide npm scripts for running the browser tests locally and in CI.

Use Chromium as the initial browser target.

The configuration should follow the existing patterns used in LibreSign and LibreCode projects where they make sense, including:

• fail CI when test.only is committed;
• retries on CI;
• trace collection on the first retry;
• screenshots on failure;
• predictable locale and viewport;
• clear reports for failed runs.

Test the real browser interactions

Add a small browser test suite covering the main editor interactions that are difficult to validate reliably with happy-dom.

Cover at least:

• loading a PDF;
• adding an element;
• selecting an element;
• moving an element;
• resizing an element;
• duplicating an element;
• deleting an element;
• changing zoom without losing the element position.

Tests should verify observable behavior through the public UI and API where practical, instead of depending on internal Vue component state.

Keep the initial suite focused. This issue does not need to reproduce all existing Vitest tests in Playwright.

Add accessibility checks

Add automated accessibility checks to the browser tests using axe-core, preferably through @axe-core/playwright.

At minimum, run accessibility validation on the main editor state used by the Playwright tests.

The tests should also protect basic keyboard interaction for controls introduced or exercised by the test scenarios, including visible focus and keyboard-accessible actions where applicable.

Do not treat automated accessibility checks as a replacement for manual accessibility review.

Add CI coverage

Add a Playwright workflow for pull requests and pushes to the main branch.

Use the current Node and npm versions declared by the package and install dependencies with npm ci.

The workflow should:

• build or start the local demo/test application;
• run Playwright against Chromium;
• upload the Playwright report when tests fail or complete;
• upload relevant test results, screenshots and traces for debugging;
• cancel older runs for the same branch when a newer run starts.

The Nextcloud Playwright workflow can be used as a reference for CI structure, but keep this workflow appropriate for a standalone Vue library. Do not add Nextcloud servers, PHP setup, Nextcloud-specific runners or application tooling.

References:

• LibreSign Playwright configuration
• LibreSign Playwright workflow
• profile_fields Playwright configuration
• profile_fields Playwright workflow
• Nextcloud Playwright workflow template

Keep responsibilities clear

Vitest should remain the main tool for fast unit and component tests.

Use Playwright for behavior that benefits from a real browser, such as pointer interaction, layout, zoom, focus and keyboard accessibility.

Avoid moving existing tests to Playwright only because the new framework is available.

Acceptance criteria

• Playwright is available through npm scripts.
• Chromium is the initial browser target.
• Tests run against a standalone pdf-elements demo or test page.
• No Nextcloud or LibreSign runtime is required.
• Browser tests cover loading, adding, selecting, moving, resizing, duplicating and deleting an element.
• A test verifies that zoom changes do not move an element away from its expected document position.
• Automated accessibility checks run in the browser test suite.
• Basic keyboard accessibility is covered for the tested editor controls.
• Playwright runs in GitHub Actions.
• Reports and debugging artifacts are available from CI.
• Existing Vitest tests remain in place and continue to pass.
• The setup remains generic for consumers of the Vue library.

Good first issue

This issue is suitable for contributors familiar with JavaScript testing or interested in learning Playwright. The work is mostly test infrastructure and should not require changing the public element model.

Keep the first implementation focused on the scenarios listed above. Additional browser tests can be added later as new editor behaviors are introduced.

Additional context

• If you have questions, feel free to ask in this issue.
• Give a ⭐️ to pdf-elements if you find the package useful.
• You can also support the project by giving a ⭐️ to LibreSign.

[nva138]

Hi @vitormattos, I'd like to take this one. I've worked with Playwright and axe-core before, so this is close to what I've done.

Since it covers a fair bit (setup, interaction tests, axe checks, CI), I'd start with a focused first PR — Playwright setup + the core editor interactions (load / add / select / move / resize / delete) - and follow up with axe and the CI workflow in separate PRs. Does that work for you, or would you rather have it all in one?

[vitormattos]

Nice @nva138 !

[vitormattos]

I assigned the issue to you.