From lisa-expo
Best practices for writing reliable Playwright E2E tests and adding testID/aria-label selectors in Expo web applications using GlueStack UI and NativeWind. Use this skill when creating, debugging, or modifying Playwright tests, adding E2E test coverage, creating components that need test selectors, reviewing code for testability, or troubleshooting testID/data-testid issues. Trigger on any mention of Playwright, E2E tests, end-to-end tests, testID, data-testid, or GlueStack testing in an Expo web context.
npx claudepluginhub codyswanngt/lisa --plugin lisa-expoThis skill uses the workspace's default tool permissions.
Before writing ANY Playwright test, open the target page in a browser and manually walk through the flow. Never write tests blind from code reading alone.
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
Before writing ANY Playwright test, open the target page in a browser and manually walk through the flow. Never write tests blind from code reading alone.
Expo/GlueStack apps have complex rendering pipelines — what you see in source code is not always what renders in the DOM. Components may have state-dependent behavior (a button that opens an actionsheet OR a confirm dialog depending on data), elements may live on different tabs than you expect, and testIDs may or may not forward to the web DOM depending on the component type.
document.querySelectorAll('[data-testid]') to see which testIDs are actually in the DOMBefore writing a batch of tests that depend on testIDs, verify ONE testID end-to-end:
// Run this in the browser console or via Playwright MCP evaluate
document.querySelectorAll('[data-testid]').length
// Should return > 0 after page fully loads
Accessibility snapshots from Playwright MCP may NOT show data-testid attributes. Always use document.querySelectorAll for ground truth. Pages may show very few testIDs before full render (e.g., 3 elements on initial load vs 80+ after data loads) — wait for the page to settle before checking.
getByTestId — most stable, survives copy changes and redesignsgetByRole — good for interactive elements (button, tab, switch, heading)getByLabel — form elements with labelsgetByPlaceholder — inputs with placeholder textgetByText — fragile, use only when no testID or role is availableThe generic web testing advice to prefer getByRole over getByTestId doesn't fully apply to React Native Web apps because ARIA role mapping is inconsistent across GlueStack components. testIDs are more reliable when properly set up.
// 1. Preferred — testID
await expect(page.getByTestId("settings:dark-mode-toggle")).toBeVisible();
// 2. Good — role + accessible name
await page.getByRole("button", { name: "Close dialog" }).click();
// 3. Good — placeholder
await page.getByPlaceholder("Search players...").fill("Messi");
// 4. Fallback — text (fragile)
await expect(page.getByText("Settings").first()).toBeVisible();
When adding testIDs to components that are deployed separately from tests, use .or() to fall back gracefully:
// Works before AND after testID is deployed
const heading = page
.getByTestId("feature:heading")
.or(page.getByText("Feature Title").first());
await expect(heading.first()).toBeVisible();
Remove the .or() fallback once the testID is confirmed deployed and working.
Use a namespaced pattern with colons as separators: screen:element
{screen}:{element}
home, profile, settings)container, title, submit-button)| testID | Description |
|---|---|
home:container | Main container on home screen |
home:title | Title text on home screen |
profile:avatar | User avatar on profile screen |
settings:dark-mode-toggle | Dark mode toggle in settings |
auth:login-button | Login button on auth screen |
:) to separate screen from element-) for multi-word elementshome:home-title should be home:title)This is the most critical technical knowledge for this stack. GlueStack UI components have different testID behavior depending on their render pipeline.
React Native Web converts testID → data-testid through its createDOMProps function. But this only happens for components that go through RN Web's createElement path. GlueStack wraps many components with NativeWind utilities (withStyleContext, tva) that bypass this path.
| Component | testID approach | Why |
|---|---|---|
Pressable (GlueStack) | testID={value} | Wraps RN Pressable → View → createDOMProps ✅ |
View (react-native) | testID={value} | Goes through createDOMProps ✅ |
Text (react-native) | testID={value} | Goes through createDOMProps ✅ |
Text (GlueStack @/components/ui/text) | {...{"data-testid": value}} | NativeWind wrapper renders <span>, bypasses createDOMProps |
HStack / VStack / Box (GlueStack) | {...{"data-testid": value}} | Same — NativeWind wrapper bypasses pipeline |
Heading (GlueStack) | data-testid={value} | Renders raw <h1>–<h6> HTML elements |
Button (GlueStack) | Unreliable — verify first | May or may not forward depending on version |
| Third-party (e.g., BouncyCheckbox) | Usually not possible | Use text/role selectors instead |
Trace the component's render chain:
GlueStack Pressable → createPressable({ Root: withStyleContext(RNPressable) })
→ withStyleContext passes {...props} to RNPressable
→ RN Web Pressable renders <View {...rest}>
→ View goes through createElement → createDOMProps
→ createDOMProps converts testID → data-testid ✅
vs:
GlueStack Text → tva-styled component
→ Renders <span> or <p> directly
→ Never hits createDOMProps
→ testID prop is silently ignored ❌
Pressable or RN View/Text, use testID={value} directlyText, HStack, VStack, Box, use {...{"data-testid": value}}Heading, use data-testid={value} as a JSX attribute// Pressable — testID prop works
<Pressable testID="feature:action-button" onPress={handlePress}>
<Text>Click me</Text>
</Pressable>
// GlueStack Text — use data-testid spread
<Text {...{"data-testid": "feature:section-heading"}}>
Section Title
</Text>
// GlueStack HStack — use data-testid spread
<HStack {...{"data-testid": "feature:row"}} className="items-center">
<Icon as={Star} />
<Text>Rating</Text>
</HStack>
// GlueStack Heading — use data-testid attribute
<Heading data-testid="feature:page-title" size="lg">
Page Title
</Heading>
Prefer semantic selectors and aria-labels over testID when possible. This benefits both testing and screen reader users.
// Correct — benefits both testing and accessibility
<Pressable
accessibilityLabel="Close dialog"
onPress={handleClose}
>
<XIcon />
</Pressable>
// E2E test uses accessible name
await page.getByRole("button", { name: "Close dialog" }).click();
// Correct — semantic role for assistive technology
<Box accessibilityRole="banner" testID="header:container">
<Text accessibilityRole="heading">Welcome</Text>
</Box>
// E2E test can use role
await expect(page.getByRole("banner")).toBeVisible();
await expect(page.getByRole("heading", { name: "Welcome" })).toBeVisible();
Playwright must test against the code in the PR, not a remote deployed environment. If CI tests against a deployed app, new testIDs and component changes are invisible until deployed — creating a frustrating push-wait-fail cycle.
The CI pipeline should:
npx expo export --platform web (creates dist/)npx serve dist -l 8081 -shttp://localhost:8081/import { defineConfig } from "@playwright/test";
export default defineConfig({
// In CI, serve the static web build locally
...(process.env.CI
? {
webServer: {
command: "npx serve dist -l 8081 -s",
port: 8081,
reuseExistingServer: false,
},
}
: {}),
use: {
baseURL: process.env.CI
? "http://localhost:8081/"
: "https://dev.example.com/",
},
});
Never assert on data-dependent elements as required. The CI test user may have different data than your local environment.
// BAD — fails if test user has no data
const tableRows = page.locator("table tr");
await expect(tableRows.first()).toBeVisible();
expect(await tableRows.count()).toBeGreaterThan(1);
// GOOD — handles empty state gracefully
const tableRows = page.locator("table tbody tr");
const rowCount = await tableRows.count();
if (rowCount === 0) {
await expect(page.getByPlaceholder("Search...")).toBeVisible();
return;
}
await tableRows.first().click();
Use environment-aware timeouts from a shared constants file. CI runners are slower than local machines.
export const TIMEOUT = {
test: isCI ? 90_000 : 60_000,
expect: isCI ? 30_000 : 15_000,
navigation: isCI ? 45_000 : 30_000,
};
// In tests — never hardcode
await expect(element).toBeVisible({ timeout: TIMEOUT.navigation });
Use serial mode for tests that mutate shared backend state. Read-only tests can run in parallel.
test.describe("Feature with mutations", () => {
test.describe.configure({ mode: "serial" });
});
Some UI elements behave differently depending on application state. Discover this during the browser-first step, then handle both cases:
const addButton = page.getByTestId("feature:add-button").first();
await expect(addButton).toBeVisible();
const modal = page.getByText("Add to List");
const isModalVisible = await modal.isVisible();
if (isModalVisible) {
await page.getByText("Done").click();
} else {
await expect(addButton).toBeVisible();
}
These patterns trigger SonarCloud security hotspot warnings that block PR merges:
// BAD — triggers security hotspot
page.on("dialog", dialog => dialog.dismiss());
const result = await element.waitFor().catch(() => false);
// GOOD — use explicit checks instead
const isVisible = await element.isVisible();
const count = await elements.count();
Always wait for a content-dependent element before asserting on testIDs:
// BAD — may run before page renders
const count = await page.evaluate(() =>
document.querySelectorAll('[data-testid]').length
);
// GOOD — wait for known element first
await page.waitForLoadState("domcontentloaded");
const item = page.getByTestId("feature:item").first();
await item.waitFor({ state: "visible", timeout: 15000 });
Components from third-party libraries (e.g., react-native-bouncy-checkbox, react-native-gifted-chat) generally do NOT forward testID to the web DOM. Use text, role, or structural selectors for these.
When adding E2E test coverage to a component:
document.querySelectorAll('[data-testid]') to see existing testIDsscreen:element) for elements without semanticsdata-testid on web before writing tests/**
* Profile screen component.
*
* Test IDs for E2E testing:
* - `profile:container` - Main container
* - `profile:avatar` - User avatar image
*
* @module features/profile/screens/Main
*/
export const ProfileScreen = () => (
<Box testID="profile:container" className="flex-1 p-4">
<Image
testID="profile:avatar"
source={{ uri: user.avatarUrl }}
accessibilityLabel={`${user.name}'s profile photo`}
/>
<Text accessibilityRole="heading">
{user.name}
</Text>
<Pressable
accessibilityLabel="Edit profile"
onPress={handleEdit}
>
<Text>Edit</Text>
</Pressable>
</Box>
);
test.describe("Profile Screen", () => {
test.use({ viewport: VIEWPORT.desktop });
test.beforeEach(async ({ auth }) => {
await auth.login();
});
test("displays user information", async ({ page }) => {
await page.goto("/profile");
await page.waitForLoadState("domcontentloaded");
// Verify structural container
await expect(page.getByTestId("profile:container")).toBeVisible();
// Prefer accessible queries when available
await expect(page.getByRole("heading")).toHaveText("John Doe");
await expect(
page.getByRole("button", { name: "Edit profile" })
).toBeVisible();
// Use testID for elements without semantic roles
await expect(page.getByTestId("profile:avatar")).toBeVisible();
});
});