Локатори: стратегія стабільних селекторів

Що таке локатор і чому кажуть, що він про стабільність, а не про пошук?

Локатор — це вираз, яким тест указує, який саме елемент сторінки йому потрібен: конкретну кнопку, поле, комірку таблиці. Знайти елемент технічно нескладно — способів десятки. Складність в іншому: щоб той самий рядок коду впізнавав той самий елемент і сьогодні, і через півроку сотні комітів у фронтенд. Тому на локатор дивляться як на неявний контракт із застосунком — «цей елемент існує, він один такий, і його впізнають ось за цією ознакою». Головне питання до будь-якого локатора не «чи знайду я його зараз», а «чи зміниться ознака, за яку я чіпляюся, поки поведінка застосунку та сама». Саме ця оптика й визначає, скільки живуть тести без ручного лагодження.

За яким пріоритетом обирати локатори?

Це головне питання теми, і сильна відповідь називає рекомендований порядок. Спершу — роль і доступне ім'я (getByRole), бо вони змінюються лише разом із призначенням елемента. Далі — видимий текст, мітка, placeholder (getByText, getByLabel): стабільні, поки не переписали копірайт чи не додали локалізацію. Потім спеціальний тест-ідентифікатор data-testid. І тільки в крайньому разі — CSS-селектор чи XPath. Логіка проста: цей порядок побудований на близькості до користувача, бо user-facing локатор заразом перевіряє доступність. Не плутай його з віссю стійкості: за нею нагорі стоїть саме data-testid — Playwright називає пошук за test id найстійкішим, а Cypress дає data-cy вердикт «Always» проти «Depends» для пошуку за текстом. Слабка відповідь звучить як «беру XPath, бо він завжди спрацьовує» — це видає людину, яка не підтримувала свої тести довше за спринт.

Чому getByRole вважають найнадійнішим варіантом?

Роль (button, link, textbox, row) плюс доступне ім'я описують призначення елемента, а не його оформлення чи місце в дереві. Розробник вільно міняє тег, класи, вкладеність, переносить кнопку в інший контейнер — доки це кнопка «Купити», getByRole('button', { name: 'Купити' }) її знаходить. Побічний бонус: такий локатор заразом опирається на дерево доступності (accessibility), тобто ще й побіжно перевіряє, що елемент коректно проговорюється скрінрідером. Тому пошук за роллю ближчий за все до того, як елемент сприймає жива людина, — і саме тому він перший у рекомендованому порядку.

Чому XPath виду /html/body/div[2]/div/div[3]/button — погана ідея?

Такий локатор кодує не сам елемент, а його випадкову позицію в дереві: «третій div усередині другого div…». Досить розробнику додати один обгортковий контейнер, поміняти місцями два блоки чи вставити банер — і весь ланцюжок індексів з'їжджає. Тест падає з element not found, хоча кнопка на місці й чудово клікається руками. Друга біда — нечитабельність: із такого рядка неможливо зрозуміти, що саме він шукає. Такі XPath найчастіше беруть із браузера через Copy → Copy selector, і саме тому вони й крихкі — інструмент генерує шлях за структурою, а не за змістом.

Що не так зі згенерованими класами на кшталт .button_a1b2c3 чи .sc-bdfBwQ?

Це деталі реалізації, не пов'язані з тим, що бачить користувач. CSS-модулі домішують до класу хеш, який змінюється щобілду; styled-components видають класи типу .sc-bdfBwQ; Angular додає атрибути _ngcontent-abc-c12. Прив'язатися до такого — це підписатися під тим, що тест червонітиме після кожного перебілду фронтенду, навіть якщо кнопка не змінилась ні на піксель. Проблема та сама, що з позиційним XPath: локатор чіпляється за те, що вільно міняється без зміни поведінки. Правило-протиотрута: описуй елемент так, як його описав би користувач, а не парсер HTML.

Що таке data-testid і навіщо він, якщо вже є class та id?

data-testid — атрибут, доданий у розмітку виключно заради автоматизації; поширені варіанти конвенції — data-test, data-qa, data-cy. Він працює краще за клас чи id, бо не має побічного життя: його не чіпає рефакторинг стилів, не переписує зміна тексту, не зачищає оптимізатор білда. Клас існує заради вигляду й тому міняється заради вигляду; тест-ідентифікатор існує заради тесту й міняється лише свідомо. А ще сам факт його наявності робить залежність явною — розробник, побачивши data-testid="checkout-submit", розуміє, що атрибут комусь потрібен і видаляти його не можна. Це і є контракт: команда домовляється, що такі атрибути — частина інтерфейсу застосунку, як публічний API.

data-testid — це завжди найкращий вибір?

Ні, хоч за стійкістю він і найвищий. Якщо елемент має роль і доступне ім'я, getByRole('button', { name: 'Оформити замовлення' }) кращий: він не потребує додаткової розмітки в продакшні й побіжно перевіряє доступність. Тест-ідентифікатор беруть тоді, коли семантичного зачепу немає або він нестабільний: іконка без підпису, службовий контейнер, віджет із динамічним локалізованим текстом. Тобто рекомендований порядок лишається — роль/ім'я → текст/мітка → data-testid, — а не «скрізь чіпляємось за testid, бо так простіше».

Як правильно іменувати тест-ідентифікатори?

Погана назва майже так само крихка, як клас. data-testid="button1" нічого не каже про елемент і легко дублюється по сторінці. Гарний тест-ідентифікатор описує роль елемента в сценарії: checkout-submit, login-email, cart-item-remove. Щоб уникати колізій, ім'я корисно префіксувати за компонентом — cart-item, cart-total, cart-checkout. Тоді локатор читається як намір, а не як випадковий ярлик, і два розробники не почеплять один і той самий testid на різні кнопки.

Хтось каже, що data-testid — це сміття в бойовій розмітці. Що відповісти?

Атрибути справді можна вирізати з продакшн-білда — це налаштовується конфігом бандлера, який лишає їх у тестових білдах і прибирає в бойовому. Але тут є пастка: вирізаний атрибут дорівнює мертвому локатору, тому рішення має бути спільним і узгодженим із QA, а не мовчазним рефакторингом одного розробника. Якщо команда домовилась вирізати testid у проді — тести мають ганятися на тому білді, де вони ще є. Отже, це не технічна дрібниця, а питання процесу: тест-ідентифікатори частина контракту, і поводитися з ними треба свідомо з обох боків.

Як знайти кнопку «Видалити» в потрібному рядку таблиці, коли таких кнопок багато?

Не через nth(3). Індекс кодує випадковий порядок: змінили сортування, додали запис, підвантажили нові дані — і третій рядок уже інший. Правильний хід — скоупінг (scoping): спершу знайти сам рядок за унікальним вмістом, потім шукати кнопку всередині нього. У Playwright це page.getByRole('row', { name: /Ноутбук/ }), а далі .getByRole('button', { name: 'Видалити' }); альтернатива — filter({ hasText: 'Ноутбук' }) на контейнері. Так локатор читається як намір («видали рядок з ноутбуком») і не залежить ні від кількості рядків, ні від їхнього порядку.

Коли наша практика допускає nth(), first() чи last()?

Дока Playwright не рекомендує ці методи взагалі: після зміни сторінки тест може клікнути не той елемент, тож замість індексу радять будувати локатор, який однозначно ідентифікує потрібний. Наша домовленість лишає для них один вузький випадок — коли позиція сама є частиною перевірки. «Перший результат пошуку», «останнє повідомлення в чаті», «верхній рядок відсортованого списку» — тут порядок несе бізнес-зміст, і прив'язка до нього виправдана й навіть необхідна. Крихкість починається там, де індексом підміняють ідентичність: nth(3) замість «рядок із товаром X» кодує не що це за елемент, а де він випадково опинився. Тобто питання не в самому nth, а в тому, чи позиція — це предмет тесту, чи випадковість верстки.

Тест упав з «element not found», хоча руками все клікається. Твої дії?

Спершу відрізнити два різні діагнози, бо лікуються вони по-різному. Перший — крихкий локатор: згенерований клас перебілдився, з'їхав позиційний індекс, зник testid; тут елемент на місці, а ознака протухла — рятує стабільніший локатор. Другий — синхронізація: елемент іще не з'явився на момент пошуку (запит до API не завершився, триває анімація, ліниве підвантаження); тут лікує автоочікування, а не зміна селектора. Головне — не «глушити» проблему через sleep: пауза замаскує обидва випадки й перетвориться на флак. Слабкий кандидат одразу додає waitForTimeout і йде далі; сильний спершу з'ясовує, який саме з двох діагнозів перед ним.

Чому waitForTimeout(3000) — антипатерн, і чим його замінити?

Бо це замаскований флак. Фіксована пауза підганяється під одну машину: на швидкій це змарновані секунди, на повільній чи під навантаженням у CI — все одно замало, і тест падає. Пошук елемента й очікування елемента — різні задачі, і змішувати їх через sleep не можна. У сучасних інструментів є автоочікування: getByRole(...) у Playwright сам дочекається, поки елемент з'явиться й стане готовим до дії, перш ніж клікнути. Тому правильний локатор плюс вбудоване очікування знімають потребу в жорсткому очікуванні, а waitForTimeout лишається хіба що для рідкісних діагностичних потреб, не для бойових тестів.

Навіщо тримати локатори в page object, а не в тілі тесту?

Заради дешевої підтримки при зміні верстки. Якщо кнопку «Оформити замовлення» шукають через getByTestId('checkout-submit') у п'ятнадцяти файлах копіпастом, зміна цього атрибута перетворюється на полювання по всьому репозиторію, і один пропущений файл дає червоний тест. Принцип одного джерела істини (single source of truth) каже: кожен локатор описаний рівно в одному місці, а тести звертаються до нього через ім'я. Канонічна форма — page object: клас тримає локатори й дії однієї сторінки, тест каже що робити, page object знає як знайти. Тоді зміна testid — це правка в одному рядку, і всі тести полагоджені разом.

Що спільного між локатором для UI і URL для API?

Обидва — технічна адреса, за якою тест звертається до системи, і обидва мають жити в одному місці, а не дублюватися по коду. Для UI це локатор у page object; для API — ендпоінт і заголовки в одному клієнті чи утиліті. Логіка ідентична: коли адреса змінюється, хочеться правити її в одному екземплярі, а не шукати двадцять копій по тестах. Тому «розмазаний по коду локатор» і «захардкоджений у кожному тесті URL» — це один і той самий борг, який вистрелить при першій же зміні.

Розробники не додають data-testid, доводиться чіплятися за випадкові класи. Це нормально?

Це не технічна проблема, а процесний борг, і крихкими локаторами його не лікують. Полювання за згенерованими класами — симптом того, що в команді немає домовленості про тест-ідентифікатори. Правильний хід — внести стабільні зачепи в Definition of Done: фіча не вважається готовою, поки її ключові елементи не мають надійних локаторів. Це командне рішення, а не таємна зброя QA, яку той нишком припасовує до чужого коду. Сильна відповідь тут показує, що кандидат бачить різницю між «поганий код» і «поганий процес» і не намагається закрити другу дірку першою.

Три кейси, де вибір локатора вирішує, переживе тест наступний редизайн чи посиплеться на рівному місці: перепис крихкого селектора з DevTools на стабільний, пошук потрібної кнопки серед десятків однакових і винесення локаторів у page object. Скрізь — що саме крихке і як його вилікувати.

Кейс 1. Той самий елемент, п'ять локаторів різної стійкості

Верстальник дав кнопку оформлення замовлення. Ось як її можна вхопити — від найкрихкішого до найстійкішого варіанта (це вісь стійкості; рекомендований порядок вибору — окрема вісь, і там getByRole іде першим). Розмітка:

<div class="checkout-footer sc-bdfBwQ">
  <button id="mui-4821" class="btn btn-primary sc-hKwDvalue" data-testid="checkout-submit">
    Оформити замовлення
  </button>
</div>

// Погано: скопійовано з DevTools через Copy selector — чіпляється за позицію й хеш
await page.locator('//div[2]/div/button').click();
await page.locator('.sc-hKwDvalue').click();

// Найживучіше: тест-атрибут, його не зрушить ні зміна тексту, ні зміна ролі
await page.getByTestId('checkout-submit').click();

// Перший вибір за рекомендованим порядком: роль + видиме ім'я, заразом перевіряє доступність
await page.getByRole('button', { name: 'Оформити замовлення' }).click();

Що дивитися і чому:

• Три верхні рядки таблиці «працюють зараз» і брешуть про стабільність. Позиційний XPath, згенерований клас і фреймворковий id живі рівно до наступної правки верстки чи перебілду — елемент лишиться на місці, а локатор перестане його знаходити.
• getByRole виграє, коли елемент має видиме ім'я. Він не потребує додаткової розмітки в продакшні й побіжно свідчить, що кнопка коректно проговорюється скрінрідером.
• data-testid — найстійкіший, але нижчий у рекомендованому порядку. Його беруть, коли ролі й імені немає чи вони нестабільні: іконка без підпису, службовий контейнер, динамічний локалізований текст. Нижчий він не через крихкість, а через те, що нічого не каже про користувацький досвід.

Кейс 2. Кнопка «Видалити» в потрібному рядку серед десятків однакових

Таблиця кошика: багато рядків, у кожному своя кнопка «Видалити». Спокуса взяти «третю кнопку» найсильніша — і найшкідливіша, бо порядок і кількість рядків змінюються від запуску до запуску.

<table>
  <tbody>
    <tr data-testid="cart-item"><td>Мишка</td><td>...</td><td><button>Видалити</button></td></tr>
    <tr data-testid="cart-item"><td>Ноутбук</td><td>...</td><td><button>Видалити</button></td></tr>
    <tr data-testid="cart-item"><td>Клавіатура</td><td>...</td><td><button>Видалити</button></td></tr>
  </tbody>
</table>

// Погано: прив'язка до позиції — зламається від сортування чи нових даних
await page.locator('table tbody tr').nth(1).getByRole('button', { name: 'Видалити' }).click();

// Добре: спершу звужуємо до рядка за унікальним вмістом, потім діємо всередині нього
const row = page.getByRole('row', { name: /Ноутбук/ });
await row.getByRole('button', { name: 'Видалити' }).click();

// Той самий підхід через filter — коли зачіп це data-testid контейнера
const item = page.getByTestId('cart-item').filter({ hasText: 'Ноутбук' });
await item.getByRole('button', { name: 'Видалити' }).click();

Що дивитися і чому:

• nth(1) кодує випадковий порядок, а не ідентичність. Змінили сортування чи сід тестових даних — і другий рядок уже інший товар; тест зелений, поки дані ті самі, і бреше, щойно вони змінюються.
• Скоупінг читається як намір. row.getByRole('button', ...) прямо каже «видали рядок з ноутбуком» і не залежить ні від кількості рядків, ні від їхнього порядку.
• Індекс наша практика лишає лише там, де позиція — предмет тесту. «Перший результат пошуку», «останнє повідомлення в чаті» — тут first()/last() несуть бізнес-зміст. Сама дока Playwright цих методів не рекомендує взагалі й радить будувати однозначний локатор.

Кейс 3. Page object: одна правка замість полювання по репозиторію

Локатор getByTestId('checkout-submit'), скопійований у п'ятнадцять тестів, — це п'ятнадцять точок відмови при одній зміні розмітки. Виносимо його в одне місце.

// checkout.page.ts — єдине місце, де живуть локатори сторінки
import { type Page } from '@playwright/test';

export class CheckoutPage {
  constructor(private readonly page: Page) {}

  readonly emailField = this.page.getByLabel('Email');
  readonly submitButton = this.page.getByRole('button', { name: 'Оформити замовлення' });

  async submit(email: string) {
    await this.emailField.fill(email);
    await this.submitButton.click();
  }
}

// checkout.spec.ts — у тесті жодного «сирого» селектора, лише наміри
import { test } from '@playwright/test';
import { CheckoutPage } from './checkout.page';

test('оформлення замовлення гостем', async ({ page }) => {
  const checkout = new CheckoutPage(page);
  await page.goto('/checkout');
  await checkout.submit('qa@example.com');
});

Що дивитися і чому:

• Зміна зачепу — правка в одному рядку. Якщо data-testid чи текст кнопки зміниться, чиниться один файл, а всі тести, що ходять через CheckoutPage, лагодяться разом.
• Тест читається як сценарій, а не як CSS. checkout.submit(...) описує намір; як знайти елементи — знає page object, і це деталь, якій не місце в тілі тесту.
• Той самий принцип працює й для API. Ендпоінти й заголовки теж тримають в одному клієнті: локатор для UI — це те саме, що URL для API, технічна адреса в одному сховищі, а не розмазана по коду.

Локатор як контракт стабільності

• Розумію, що локатор — це неявний контракт із застосунком, а не просто «спосіб намацати елемент зараз».
• Можу сформулювати головне питання до будь-якого локатора: чи зміниться ознака, за яку я чіпляюся, поки поведінка застосунку та сама.
• Знаю правило-протиотруту: локатор має описувати елемент так, як його описав би користувач, а не парсер HTML.

Пріоритет вибору локаторів

• Пам'ятаю рекомендований порядок: роль/ім'я → текст/мітка/placeholder → data-testid → CSS/XPath — і що це вісь близькості до користувача.
• Можу пояснити, чому getByRole — перший вибір: він описує призначення елемента й побіжно спирається на дерево доступності.
• Розумію, що пріоритет локаторів — це політика, а не смак, і не плутаю дві осі: за стійкістю нагорі data-testid, за близькістю до користувача — роль і доступне ім'я.

Чому крихкі локатори ламаються першими

• Знаю різницю між згенерованими ознаками (.button_a1b2c3, .sc-bdfBwQ, _ngcontent-abc) і осмисленими: перші міняються щобілду.
• Можу пояснити, чому позиційний XPath (div[2]/div[3]), nth-child і скопійований через Copy → Copy selector у DevTools локатор крихкі: кодують місце в дереві чи згенерований клас, а не сам елемент, хоч і «працюють зараз».
• Знаю, чому id виду mui-4821 ненадійний, а заданий руками id="login-form" — прийнятний.

data-testid як контракт із розробкою

• Можу пояснити, чому data-testid стабільніший за клас: у нього немає побічного життя (стилі, текст, оптимізатор його не чіпають); знаю синоніми конвенції — data-test, data-qa, data-cy.
• Розумію, що починають не з нього, хоч за стійкістю він і найвищий: за наявності ролі й імені getByRole кращий.
• Можу відрізнити гарне ім'я тест-ідентифікатора (checkout-submit, cart-item-remove) від крихкого (button1) і знаю про префікс за компонентом.
• Розумію, що тест-ідентифікатори — командна домовленість і частина Definition of Done (а не таємна зброя QA); їх можна вирізати з продакшн-збірки конфігом, але це спільне рішення, бо вирізаний testid = мертвий локатор.

Списки, таблиці, динаміка

• Можу пояснити скоупінг (scoping): спершу знайти рядок/картку за вмістом, потім шукати кнопку всередині нього.
• Знаю, як застосувати filter({ hasText }), щоб не чіплятися за позицію в списку.
• Розумію, що дока Playwright nth/first/last не рекомендує, а наша практика лишає їх лише там, де позиція сама є частиною перевірки.
• Розумію, що пошук елемента й очікування — різні задачі, які не змішують через sleep: waitForTimeout(3000) антипатерн, його замінює автоочікування.

Одне джерело істини: page object

• Розумію принцип single source of truth: кожен локатор описаний рівно в одному місці й не має жити в тілі тесту — інакше зміна верстки коштує полювання по репозиторію.
• Знаю, що page object тримає локатори й дії, а тест каже лише що робити, не як знайти.
• Розумію аналогію: локатор для UI — це те саме, що URL і заголовки для API, і жити вони мають в одному сховищі.