Skip to main content

@atomic-testing/component-driver-primevue-v4

Component drivers for PrimeVue 4 (Vue 3). Component drivers expose simple APIs for unit tests or end-to-end tests to interact with PrimeVue-based components—reading state and driving actions—so test engineers focus on test flows instead of the component internals.

The problem​

PrimeVue components are styled by swappable theme presets (Aura, Lara, Nora, …) and consumer design tokens, so theme class names are not stable test anchors. PrimeVue is accessibility-first: it publishes a per-component WCAG 2.1 AA accessibility contract (roles, aria-* states) and stamps its own structural pass-through markers on every part. The stable anchors, in priority order, are:

  1. role + ARIA state per PrimeVue's published per-component accessibility contract (role="combobox" + aria-expanded on Select, role="switch" + aria-checked on ToggleSwitch, …) — the a11y contract is the API these drivers test against.
  2. PrimeVue-owned structural attributes — data-pc-name / data-pc-section, the documented pass-through/theming markers naming each component and part (the analogue of Radix's data-state tier).
  3. Never theme/utility classes.

The solution​

The drivers in this package locate PrimeVue parts by those stable anchors and expose high-level interactions. Combined with the Vue 3 adapter (@atomic-testing/vue-3), the same scene definitions run across DOM (jsdom) and end-to-end (Playwright) tests.

Target package & version pin​

This driver targets PrimeVue 4 and is declared as a peer dependency pinned to ^4.0.0: consumers bring their own PrimeVue. PrimeVue 4 renamed several components this package covers (Dropdown → Select, InputSwitch → ToggleSwitch, TabView → Tabs), so the v4 pin is also a DOM-contract pin — PrimeVue 3 renders different roots and markers. PrimeVue requires Vue 3, so test with @atomic-testing/vue-3 to match your app.

Installation​

npm install @atomic-testing/core @atomic-testing/vue-3 \
  @atomic-testing/component-driver-html @atomic-testing/component-driver-primevue-v4 \
  primevue --save-dev

Refer to the documentation for usage patterns and examples.

Drivers​

Drivers land in waves (see the umbrella issue #1018); this table grows with each wave.

DriverPrimeVue componentNotes
ButtonDriverButtonNative <button>; getLabel reads the data-pc-section="label" span so add-ons (badge) don't leak into the label; native disabled.
InputTextDriverInputTextThe root IS a native <input> — full HTMLTextInputDriver surface, incl. isError via aria-invalid.
CheckboxDriverCheckboxReal (visually hidden) native input: isSelected/clicks/disabled/required ride it. Covers binary and array-value modes.
RadioButtonDriver, RadioButtonGroupDriverRadioButtonNative radio input per item; the group driver roots at a consumer container and selects by value (PrimeVue has no group component).
ToggleSwitchDriverToggleSwitch (v4 rename of InputSwitch)Hidden native checkbox with role="switch"; reads the native checked property, the ground truth behind the aria-checked mirror.
SliderDriverSliderNo native range input — aria reads on the role="slider" handle, keyboard-driven setValue, dragBy for E2E-only positional checks. Range (two-thumb, via data-pc-section="starthandler"/"endhandler") and vertical orientation covered — see getRangeValues/setRangeValues/getOrientation.
SelectDriverSelect (v4 rename of Dropdown)Label-based selection (PrimeVue renders no option value in the DOM); the teleported listbox is pinned via the combobox's aria-controls id link. appendTo="self" needs no option — see "Teleported overlays" below.
DialogDriverDialogInterior reached with within(parts); portal re-root on role="dialog"; title via aria-labelledby; close via header button or Escape. { selfAnchored: true } opts into appendTo="self" — see "Teleported overlays" below.
MenuDriverMenu (popup mode)Portal re-root on data-pc-name="menu"; items iterated with childListHelper (separators share the <li> tag); activation clicks the item link. { selfAnchored: true } opts into appendTo="self". Item iteration/selectByLabel live on the shared MenuContentDriverBase (#1036).
ContextMenuDriverContextMenuConstructed from the TRIGGER locator (the menu surface doesn't exist until opened); open() fires a real right-click, surface resolves document-rooted on data-pc-name="contextmenu". Top-level items only (role="menubar" list) — shares MenuContentDriverBase with MenuDriver (#1036).
TabsDriver, TabDriverTabs (v4 replacement for TabView)ARIA tabs pattern (role="tab", aria-selected, aria-controls → panel id); unselected panels stay mounted, hidden.
DataTableDriver, DataTableRowDriverDataTable + ColumnReal <table> with role semantics; full-count row/cell iteration via childListHelper. Covers sorting (sortBy/getSortDirection), row selection (checkbox column or row click, selectRow/isRowSelected/select-all), pagination (goToPage/nextPage/getCurrentPage), filterDisplay="menu" column filtering (setColumnFilter/getColumnFilterValue/clearColumnFilter, teleported overlay via the Select/Menu byAriaIdReference recipe), editMode="cell" cell editing (DataTableRowDriver.startCellEdit/setCellValue/commitCellEdit/cancelCellEdit) and a minimal E2E-only scrollRowIntoView/getRowByDataIndex for virtual scroll. filterDisplay="row" inline filtering and frozen columns remain deferred — see the class doc.

Teleported overlays (appendTo)​

PrimeVue overlays (Select panel, Dialog, Menu popup, …) Teleport to document.body by default via the uniform appendTo prop. The overlay drivers follow the MUI portal re-root recipe — the portalled surface is located document-rooted ('Root'-relative), not under the in-tree trigger. See the portals & overlays guide.

appendTo="self" (self-anchored overlays, #1033) is also covered. PrimeVue's shared Portal wrapper renders its slot in-tree — no <Teleport> at all — whenever appendTo === 'self', so a self-anchored overlay is a genuine DOM descendant of wherever the scene declares it:

  • SelectDriver needs no option: its dropdown part resolves through an aria-controls id link, which finds the listbox wherever it physically sits.
  • DialogDriver and MenuDriver take a selfAnchored: true driver option (default false) that switches their portal re-root off in favor of ordinary parent-chain-relative resolution — pass it in the scene's option for any instance rendered with appendTo="self".

For more in-depth information, visit https://atomic-testing.dev.

Classes​

Interfaces​

Type Aliases​

Variables​