Skip to main content

@atomic-testing/component-driver-astryx

Component drivers for Astryx, Meta's open-source, StyleX-based design system. Component drivers expose simple APIs for unit tests or end-to-end tests to interact with Astryx components—reading state and driving actions—so test engineers focus on test flows instead of the component internals.

The problem​

Astryx styles components with StyleX, whose class names are build-time hashed and therefore are not stable test anchors. Astryx is ARIA-role-first: widgets expose a semantic role plus an accessible name (visible text or aria-label). The stable anchors are data-testid, role, and accessible name—never StyleX classes.

The solution​

The drivers in this package locate Astryx components by those stable anchors and expose high-level interactions. Combined with a React adapter, the same scene definitions run across DOM (jsdom) and end-to-end (Playwright) tests.

Target package & version pin​

This driver targets the published Astryx package @astryxdesign/core (the components live here; theme packages such as @astryxdesign/theme-neutral are separate). It is declared as a peer dependency pinned to ^0.1.1: consumers bring their own Astryx, and the caret on a 0.x release locks the 0.1 minor (>=0.1.1 <0.2.0)—the closest analogue to "pin a major" while Astryx is pre-1.0. Astryx peer-requires React ≥19.

Astryx forks (-vN) are deferred: a single package tracks one 0.x minor until a breaking Astryx release warrants a versioned fork.

Installation​

npm install @atomic-testing/core @atomic-testing/react-19 \
  @atomic-testing/component-driver-html @atomic-testing/component-driver-astryx \
  @astryxdesign/core --save-dev

Refer to the documentation for usage patterns and examples.

Drivers​

Wave 1 — buttons, inputs, toggles and the structural/feedback primitives around them. Each driver locates its component by data-testid, role, or accessible name (never a StyleX class) and exposes high-level reads and interactions. Method details are in the API docs; anchoring rationale and any E2E-only behaviour live in each driver's source doc comment.

Buttons & actions​

DriverAstryx componentNotes
ButtonDriverButtongetLabel/isDisabled/isLoading; inherited click.
IconButtonDriverIconButtonIcon-only Button; getLabel reads the always-present aria-label.
ToggleButtonDriverToggleButtonisSelected/setSelected via aria-pressed.
ButtonGroupDriverButtonGroupList of buttons; clickButton(name), getButtonCount, getOrientation.
ToggleButtonGroupDriverToggleButtonGroupselect/deselect/isSelected by aria-label; getSelectedLabels.
LinkDriverLinkgetHref/getTarget/getRel; isButtonFallback (no-href <button>).

Text inputs​

DriverAstryx componentNotes
TextInputDriverTextInputValue, clear, getLabel/getStatusMessage (a11y links), isRequired/isInvalid.
TextAreaDriverTextAreaValue, getRows, getCharCount.
NumberInputDriverNumberInputValue, getMin/getMax/getStep/getUnits; stepUp/stepDown (E2E).
TimeInputDriverTimeInputgetValue returns the display string (not ISO); increment/decrement (E2E).
AstryxFieldInputDriver—Shared base for the field inputs above (linked label/status resolution).

Selection controls​

DriverAstryx componentNotes
CheckboxInputDriverCheckboxInputisChecked/toggle; isIndeterminate (aria-checked="mixed").
RadioListDriverRadioListgetSelectedValue/selectByValue by radio value; isItemChecked.
CheckboxListDriverCheckboxListLabel/index addressed (item value is not in the DOM); getCheckedLabels.
CheckboxListItemDriver—A single CheckboxList row: getLabel/isChecked/toggle.
SwitchDriverSwitchisOn/turnOn/turnOff via the role="switch" input.
SegmentedControlDriverSegmentedControlSingle-select radiogroup; value via data-value.
SelectableCardDriverSelectableCardisSelected/toggle via the card's hidden checkbox; clicks the card.
SliderDriverSliderSingle-thumb; getValue (aria-valuenow), keyboard setValue (no drag).

Structure & feedback​

DriverAstryx componentNotes
FieldDriverFieldgetLabel/getDescription/getStatusMessage, isRequired/isOptional.
InputGroupDriverInputGroupgetLabel, getAddonTexts.
FieldStatusDriverFieldStatusgetStatus/getMessage/isError via stable data-type (role is conditional).
BannerDriverBannergetTitle/getDescription/getStatus, dismiss, toggleExpand.
PaginationDriverPaginationgetCurrentPage, goToPage/next/previous, getCountText.
CollapsibleDriverCollapsibleisExpanded/expand/collapse via the trigger's aria-expanded.

Wave 2 — overlays & menus. Astryx renders these in-tree (no portal): menus and popovers mount their panel as a sibling of the trigger via the native Popover API, and dialogs are native <dialog> elements. Each driver anchors on the trigger (or the <dialog>) and reads open state from aria-expanded or the <dialog> open attribute; panel visibility and Escape/backdrop dismissal are native behaviours covered only by the Playwright run (and skipped on WebKit, which cannot drive native-popover interactions). Anchoring rationale lives in each driver's source doc comment.

Menus & navigation​

DriverAstryx componentNotes
NavMenuDriverNavHeadingMenuFlat link/action menu; getItemLabels/getItemCount/clickItem/getItemHref.
DropdownMenuDriverDropdownMenuTrigger-anchored; open/close/isOpen, selectByLabel, getTriggerLabel.
MoreMenuDriverMoreMenuIcon-only DropdownMenu; getTriggerLabel reads the aria-label.
TabListDriverTabListgetItemLabels/getActiveLabel/selectTab/isActive/getTabHref.
TabDriverTabA single tab: getLabel/isActive (aria-current="page")/getHref.
ToolbarDriverToolbargetLabel/getOrientation/getSize/getItemCount.
AstryxMenuDriver—Shared menu base (positional role="menuitem" iteration).
MenuItemDriver—A single role="menuitem" (<a>/<div>): getLabel/isDisabled/getHref.

Overlays & feedback​

DriverAstryx componentNotes
PopoverDriverPopoverTrigger-anchored; open/close/isOpen, getLabel/getContent.
DialogDriverDialogNative <dialog>; isOpen/isModal/getTitle/closeByEscape; content parts.
AlertDialogDriverAlertDialogrole="alertdialog"; getTitle/getDescription, clickAction/clickCancel.
ToastDriverToastStable data-type: getType/isError/getRole/getMessage, dismiss.

Wave 3 — lists, tables, selectors & dates. The list/table/tree drivers read structure from native semantics (<li>, <table>, ul[role="tree"]) and per-row state from ARIA. The combobox family (Selector/MultiSelector/Typeahead/Tokenizer, plus the CommandPalette dialog and PowerSearch's field suggestions) shares one option-enumeration mechanism — options are addressed by their contiguous ${listboxId}-${item|option}-${i} ids — exposed through AstryxComboboxDriver (its trigger open/close layer) over an internal IndexedOptionListDriver base. Popup and calendar-popover visibility are native behaviours covered by the Playwright run; structure and ARIA render faithfully in jsdom. Anchoring rationale and the scroll/layout-only caveats (Carousel overflow, Outline scroll-spy) live in each driver's source doc comment.

Lists & display​

DriverAstryx componentNotes
ListDriverList<li>-addressed rows; getItemLabels/getSelectedLabels/clickItem/isOrdered.
ListItemDriver—A single row: getLabel (full text), isSelected/isDisabled (ARIA), isLink/getHref.
MetadataListDriverMetadataList<dl> pairs; getLabels/getValueByLabel/getEntryCount, showMore/showLess.
OutlineDriverOutlineTOC nav; getItemLabels/getActiveLabel (aria-current)/getHref/getLevel/clickItem.
OutlineItemDriver—A single entry: getLabel/getHref/getLevel (data-level)/isActive.
CarouselDriverCarouselgetLabel/getItemCount/hasNavButtons; scrollNext/scrollPrev are E2E-only.

Tables & trees​

DriverAstryx componentNotes
TableDriverTabledata-column-key/aria-sort/aria-selected; headers, data rows (empty-state row excluded), sort, row selection. TableSortDirection is re-exported.
TreeListDriverTreeListul[role="tree"] walked depth-first; getVisibleItemLabels/getItemDepth/expandItem/collapseItem/clickItem.

Selectors, typeaheads & search​

DriverAstryx componentNotes
AstryxComboboxDriver—Shared combobox base: trigger open/close/isExpanded over the option-enumeration surface.
SelectorDriverSelectorSingle-select; getOptionLabels/selectByLabel/getSelectedLabel/isOptionSelected.
MultiSelectorDriverMultiSelectorMulti-select; toggleByLabel/getSelectedLabels (excludes select-all)/selectAll/clearAll.
TypeaheadDriverTypeaheadSearch-as-you-type single-select; type/getResultLabels/selectByLabel/clear/isLoading.
TokenizerDriverTokenizerMulti-token; getTokenLabels/addByLabel/create/removeToken/clearAll/isLoading.
CommandPaletteDriverCommandPaletteHost-controlled <dialog>; search/getOptionLabels/getOptionValue/selectByLabel/getActiveValue.
PowerSearchDriverPowerSearchBest-effort v1: getFilterLabels/removeFilter/clearAll/getFieldSuggestionLabels/getResultCount (in-popover edit is E2E/follow-up).

Dates​

DriverAstryx componentNotes
CalendarDriverCalendarInline; [data-date] cells, getMode/getVisibleMonthLabel/selectDay/selectRange/previousMonth/nextMonth.
DateInputDriverDateInputInput value + calendar popover; open/pickDate (via aria-controls)/isInvalid/clear.
DateTimeInputDriverDateTimeInputExtends DateInputDriver with a paired time field (getTimeValue/setTime).
DateRangeInputDriverDateRangeInputBest-effort v1: popover <dialog> with presets + range pickRange (the end day is re-resolved after the start click).

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

Classes​

Type Aliases​