🇺🇸English

Writing Playwright Tests for Hyvä + Alpine.js

Overview

Hyvä replaces Luma's KnockoutJS/RequireJS/jQuery with Alpine.js + Tailwind CSS. Playwright's strict mode (rejects locators matching multiple elements) conflicts with Alpine.js DOM patterns where hidden elements exist throughout the page. This skill documents pitfalls and solutions discovered while writing Playwright tests for Hyvä storefronts.

The #1 Rule: Hidden Alpine Elements

Hyvä templates scatter elements like <div x-show="displayErrorMessage" class="message error"> throughout the DOM. These are invisible but present , so a bare selector like .message.error matches both hidden and visible instances, causing Playwright strict mode violations.

Always scope page-level messages to the#messages container:

// WRONG — matches hidden Alpine x-show elements throughout DOM
await expect(page.locator('.message.success')).toContainText('Added to cart');
await expect(page.locator('.message-error')).toContainText('Error');

// RIGHT — scoped to the visible messages container
await expect(page.locator('#messages .message.success')).toContainText('Added to cart');
await expect(page.locator('#messages .message-error, #messages .message.error')).toContainText('Error');

Never use: bare .message, .message.error, .message.success, or div.message as selectors.

Exception — inline page messages: Not all .message elements are flash messages. The search results "no results" notice (.message.notice) renders as static inline content inside #maincontent, not inside the #messages container. For these inline messages, the bare class selector is correct.

Selector Strategy

Follow Playwright's recommended locator priority:

1. getByRole() — always prefer — closest to how users perceive the page. Avoids text ambiguity where the same text appears in headings, links, breadcrumbs, and sr-only spans.
2. getByLabel() — for form controls (checkboxes, inputs with associated labels).
3. getByText() — for non-interactive elements, scoped to a container (e.g., page.locator('#maincontent').getByText(...)).
4. getByPlaceholder() , getByAltText() — for inputs and images respectively.
5. getByTestId() — when Hyvä provides attributes or when adding custom test IDs.

Avoid: :visible pseudo-selector — per Playwright docs, "it's usually better to find a more reliable way to uniquely identify the element." Scope to a container or use role/attribute selectors instead. Only use :visible as an absolute last resort when the DOM provides no other way to distinguish elements.

Alpine.js Interaction Patterns

Assertions

Always use web-first assertions that auto-wait and retry:

// DO — auto-retries             // DON'T — no retry
await expect(loc).toBeVisible(); // expect(await loc.isVisible()).toBe(true);
await expect(loc).toContainText('X'); // expect(await loc.textContent()).toContain('X');

For async Alpine.js updates (cart counts, prices), use extended timeouts on the assertion — never waitForTimeout():

// Cart count updates asynchronously via Alpine x-text
await expect(page.locator('#menu-cart-icon span[x-text="summaryCount"]'))
  .not.toHaveText('0', { timeout: 15_000 });

Hyvä vs Luma Selector Differences

References

See references/ for code examples. Load files relevant to the current task:

Always useful:

• page-object-patterns.md — Page object structure, navigation, form submits, redirects
• selector-patterns.md — Before/after selector fixes (messages, text ambiguity, forms)

Page-specific (load when testing that page):

• cart-patterns.md — Cart spinner wait, quantity changes, mini cart
• product-patterns.md — Bundle quantities, gallery images
• account-patterns.md — Password change (Alpine checkbox reveal)
• category-patterns.md — Filters (x-defer scroll), pagination (ARIA)

Weekly Installs

159

Repository

hyva-themes/hyv…ai-tools

GitHub Stars

59

First Seen

Feb 16, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

github-copilot158

opencode149

codex149

gemini-cli148

amp148

kimi-cli148