1# Locator Strategies
2 
3## Table of Contents
4 
51. [Priority Order](#priority-order)
62. [User-Facing Locators](#user-facing-locators)
73. [Filtering & Chaining](#filtering--chaining)
84. [Dynamic Content](#dynamic-content)
95. [Shadow DOM](#shadow-dom)
106. [Iframes](#iframes)
11 
12## Priority Order
13 
14Use locators in this order of preference:
15 
161. **Role-based** (most resilient): `getByRole`
172. **Label-based**: `getByLabel`, `getByPlaceholder`
183. **Text-based**: `getByText`, `getByTitle`
194. **Test IDs** (when semantic locators aren't possible): `getByTestId`
205. **CSS/XPath** (last resort): `locator('css=...')`, `locator('xpath=...')`
21 
22## User-Facing Locators
23 
24### getByRole
25 
26Most robust approach - matches how users and assistive technology perceive the page.
27 
28```typescript
29// Buttons
30page.getByRole("button", { name: "Submit", exact: true }); // exact accessible name
31page.getByRole("button", { name: /submit/i }); // flexible case-insensitive match
32 
33// Links
34page.getByRole("link", { name: "Home" });
35 
36// Form elements
37page.getByRole("textbox", { name: "Email" });
38page.getByRole("checkbox", { name: "Remember me" });
39page.getByRole("combobox", { name: "Country" });
40page.getByRole("radio", { name: "Option A" });
41 
42// Headings
43page.getByRole("heading", { name: "Welcome", level: 1 });
44 
45// Lists & items
46page.getByRole("list").getByRole("listitem");
47 
48// Navigation & regions
49page.getByRole("navigation");
50page.getByRole("main");
51page.getByRole("dialog");
52page.getByRole("alert");
53```
54 
55### getByLabel
56 
57For form elements with associated labels.
58 
59```typescript
60// Input with <label for="email">
61page.getByLabel("Email address");
62 
63// Input with aria-label
64page.getByLabel("Search");
65 
66// Exact match
67page.getByLabel("Email", { exact: true });
68```
69 
70### getByPlaceholder
71 
72```typescript
73page.getByPlaceholder("Enter your email");
74page.getByPlaceholder(/email/i);
75```
76 
77### getByText
78 
79```typescript
80// Partial match (default)
81page.getByText("Welcome");
82 
83// Exact match
84page.getByText("Welcome to our site", { exact: true });
85 
86// Regex
87page.getByText(/welcome/i);
88```
89 
90### getByTestId
91 
92Configure custom test ID attribute in `playwright.config.ts`:
93 
94```typescript
95use: {
96  testIdAttribute: "data-testid"; // default
97}
98```
99 
100Usage:
101 
102```typescript
103// HTML: <button data-testid="submit-btn">Submit</button>
104page.getByTestId("submit-btn");
105```
106 
107## Filtering & Chaining
108 
109### filter()
110 
111Narrow down locators:
112 
113```typescript
114// Filter by text
115page.getByRole("listitem").filter({ hasText: "Product" });
116 
117// Filter by NOT having text
118page.getByRole("listitem").filter({ hasNotText: "Out of stock" });
119 
120// Filter by child locator
121page.getByRole("listitem").filter({
122  has: page.getByRole("button", { name: "Buy" }),
123});
124 
125// Combine filters
126page
127  .getByRole("listitem")
128  .filter({ hasText: "Product" })
129  .filter({ has: page.getByText("$9.99") });
130```
131 
132### Chaining
133 
134```typescript
135// Navigate down the DOM tree
136page.getByRole("article").getByRole("heading");
137 
138// Get parent/ancestor
139page.getByText("Child").locator("..");
140page.getByText("Child").locator("xpath=ancestor::article");
141```
142 
143### nth() and first()/last()
144 
145```typescript
146page.getByRole("listitem").first();
147page.getByRole("listitem").last();
148page.getByRole("listitem").nth(2); // 0-indexed
149```
150 
151## Dynamic Content
152 
153### Waiting for Elements
154 
155Locators auto-wait for actionability by default. For explicit state waiting:
156 
157```typescript
158await page.getByRole("button").waitFor({ state: "visible" });
159await page.getByText("Loading").waitFor({ state: "hidden" });
160```
161 
162> **For comprehensive waiting strategies** (element state, navigation, network, polling with `toPass()`), see [assertions-waiting.md](assertions-waiting.md#waiting-strategies).
163 
164### Lists with Dynamic Items
165 
166```typescript
167// Wait for specific count
168await expect(page.getByRole("listitem")).toHaveCount(5);
169 
170// Get all matching elements
171const items = await page.getByRole("listitem").all();
172for (const item of items) {
173  await expect(item).toBeVisible();
174}
175```
176 
177## Shadow DOM
178 
179Playwright pierces shadow DOM by default:
180 
181```typescript
182// Automatically finds elements inside shadow roots
183page.getByRole("button", { name: "Shadow Button" });
184 
185// Explicit shadow DOM traversal (if needed)
186page.locator("my-component").locator("internal:shadow=button");
187```
188 
189## Iframes
190 
191```typescript
192// By frame name or URL
193const frame = page.frameLocator('iframe[name="content"]');
194await frame.getByRole("button").click();
195 
196// By index
197const frame = page.frameLocator("iframe").first();
198 
199// Nested iframes
200const nestedFrame = page.frameLocator("#outer").frameLocator("#inner");
201await nestedFrame.getByText("Content").click();
202```
203 
204## Debugging Locators
205 
206```typescript
207// Highlight element in headed mode
208await page.getByRole("button").highlight();
209 
210// Count matches
211const count = await page.getByRole("listitem").count();
212 
213// Check if exists without waiting
214const exists = (await page.getByRole("button").count()) > 0;
215 
216// Use Playwright Inspector
217// PWDEBUG=1 npx playwright test
218```
219 
220## Common Issues & Solutions
221 
222| Issue                   | Solution                                         |
223| ----------------------- | ------------------------------------------------ |
224| Multiple elements match | Add filters or use `nth()`, `first()`, `last()`  |
225| Element not found       | Check visibility, wait for load, verify selector |
226| Stale element           | Locators are lazy; re-query if DOM changes       |
227| Dynamic IDs             | Use stable attributes like role, text, test-id   |
228| Hidden elements         | Use `{ force: true }` only when necessary        |
229 
230## Anti-Patterns to Avoid
231 
232| Anti-Pattern                      | Problem                           | Solution                                          |
233| --------------------------------- | --------------------------------- | ------------------------------------------------- |
234| `page.locator('.btn-primary')`    | Brittle, implementation-dependent | `page.getByRole('button', { name: 'Submit' })`    |
235| `page.locator('#dynamic-id-123')` | Breaks when IDs change            | Use stable attributes like role, text, or test-id |
236| Testing implementation details    | Breaks on refactoring             | Test user-visible behavior                        |
237 
238## Related References
239 
240- **Debugging selector issues**: See [debugging.md](../debugging/debugging.md) for troubleshooting
241- **Waiting for elements**: See [assertions-waiting.md](assertions-waiting.md) for waiting strategies
242- **Using in Page Objects**: See [page-object-model.md](page-object-model.md) for organizing locators
243