Unverified Commit f08c4536 authored by Joseph's avatar Joseph Committed by GitHub

Fix Activity testing guide claim about label and placeholder locators (#100445)

## Summary

The Testing section of the Preserving UI state guide said Playwright
`getByLabel` and `getByPlaceholder` filter by visibility. They do not:
with Activity keeping a hidden page in the DOM, both locators match the
hidden copy and `.fill()` fails with a strict mode violation. Only
`getByRole` excludes hidden elements by default.

- Lead with the tool-agnostic rule: query the accessibility tree, or
filter matches by visibility before acting
- Keep `getByRole` as the default Playwright example
- Move `getByLabel` / `getByPlaceholder` into the explicit `.filter({
visible: true })` examples
- Note that waiting for visibility does not narrow a query that matches
multiple elements
- Drop the Cypress example, which mixed a visibility assertion with a
non-existent `cy.get()` option, and point readers to their testing
tool's locator and helper docs, since this behavior varies between tools
and versions

## Verification

- Playwright 1.61 against a visible form plus a `display: none` copy:
`getByLabel` matched 3, `getByPlaceholder` matched 2 (both strict mode
violations on `.fill()`); `getByRole` and the `.filter({ visible: true
})` variants each matched 1

<!-- NEXT_JS_LLM -->
parent 57b708a7
...@@ -355,27 +355,28 @@ This isn't only a React data-flow or Next.js concern. Broad `:has()` selectors a ...@@ -355,27 +355,28 @@ This isn't only a React data-flow or Next.js concern. Broad `:has()` selectors a
Hidden Activity content has `display: none` but remains in the document. This applies both to routes preserved by Cache Components and to content you hide with `<Activity>` directly. It affects end-to-end testing with tools like Playwright, Cypress, or Puppeteer: Hidden Activity content has `display: none` but remains in the document. This applies both to routes preserved by Cache Components and to content you hide with `<Activity>` directly. It affects end-to-end testing with tools like Playwright, Cypress, or Puppeteer:
- **DOM queries can find hidden elements.** Selectors may match elements regardless of visibility. - **DOM queries can find hidden elements.** Selectors may match elements regardless of visibility.
- **Interactions with hidden elements fail or timeout.** Most tools wait for elements to become visible before interacting. - **Interactions with hidden elements fail or time out.** Most tools wait for an element to become visible before interacting, but waiting doesn't narrow a query that matches both a visible and a hidden element. Playwright reports this as a strict mode violation.
- **Assertions may match hidden content.** Be explicit about visibility when asserting element presence. - **Assertions may match hidden content.** Be explicit about visibility when asserting element presence.
### Use visibility-aware selectors ### Use visibility-aware selectors
In Playwright, `getByRole` queries automatically filter by visibility: Prefer locators that query the accessibility tree, which leaves out hidden elements, or filter matches by visibility before acting on them. In Playwright, `getByRole` queries exclude hidden elements by default:
```ts ```ts
// Good - getByRole filters by visibility automatically // Good - getByRole excludes hidden elements by default
await page.getByRole('button', { name: 'Submit' }).click() await page.getByRole('button', { name: 'Submit' }).click()
await page.getByRole('textbox', { name: 'Email' }).fill('test@example.com') await page.getByRole('textbox', { name: 'Email' }).fill('test@example.com')
// Also good - getByLabel, getByPlaceholder filter by visibility
await page.getByLabel('Email').fill('test@example.com')
await page.getByPlaceholder('Search...').fill('query')
``` ```
When `getByRole` isn't suitable, use `.locator()` with visibility filtering: Other locators, including `getByLabel`, `getByPlaceholder`, and `.locator()`, can match hidden elements. Filter them by visibility explicitly:
```ts ```ts
// Fallback - filter by visibility explicitly // Filter by visibility explicitly
await page
.getByLabel('Email')
.filter({ visible: true })
.fill('test@example.com')
await page.getByPlaceholder('Search...').filter({ visible: true }).fill('query')
await page.locator('.product-card').filter({ visible: true }).first().click() await page.locator('.product-card').filter({ visible: true }).first().click()
await page await page
.locator('[data-testid="timer"]') .locator('[data-testid="timer"]')
...@@ -383,10 +384,11 @@ await page ...@@ -383,10 +384,11 @@ await page
.textContent() .textContent()
// Avoid - may match hidden elements in Activity boundaries // Avoid - may match hidden elements in Activity boundaries
await page.getByLabel('Email').fill('test@example.com')
await page.locator('.product-card').first().click() await page.locator('.product-card').first().click()
``` ```
`getByRole` is robust to Activity, tabbed navigation, accordions, and any other pattern that keeps hidden content in the DOM. It queries the accessibility tree, which excludes hidden elements. For other testing tools, check their documentation for visibility-aware selectors. For example, Cypress uses `.should('be.visible')` or `{ visible: true }` options. `getByRole` is robust to Activity, tabbed navigation, accordions, and any other pattern that keeps hidden content in the DOM. It queries the accessibility tree, which excludes hidden elements. Which locators match hidden elements varies between testing tools and their versions, so check your tool's documentation for its locators and test helpers to confirm.
## Using Activity in your components ## Using Activity in your components
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment