XPath text - Stabilne selektory w testach automatycznych

Jak XPath widzi tekst w elemencie

XPath nie patrzy na element jak człowiek, tylko jak na drzewo węzłów. text() wybiera bezpośrednie węzły tekstowe potomne, a string-value elementu to po prostu złączony tekst wszystkich jego potomków w kolejności dokumentu. To brzmi technicznie, ale w testach ma bardzo praktyczny skutek: //button[text()='Zapisz'] może nie znaleźć przycisku, jeśli napis siedzi wewnątrz , a //button[.='Zapisz'] już go zobaczy.

//button[text()='Zapisz']
//button[.='Zapisz']
//button[normalize-space(.)='Zapisz']

Ja zwykle zaczynam od sprawdzenia, czy tekst jest jednym prostym węzłem, czy UI rozbija go na kilka fragmentów. Jeśli w środku są ikony, badge albo wrappery, text() często przestaje być wystarczające i wtedy lepiej od razu przejść na kropkę oraz normalizację białych znaków. To prowadzi prosto do wyboru właściwego wariantu selektora.

Który wariant wybrać w testach automatycznych

W praktyce nie ma jednego uniwersalnego XPath-a. Ja rozróżniam je według tego, czy potrzebuję dokładnego trafienia, tolerancji na odstępy, czy częściowego dopasowania tekstu.

Najkrócej: exact match daję tam, gdzie tekst ma być niezmienny, a contains() zostawiam dla przypadków, w których UI naturalnie się rozrasta. Jeśli selektor ma wybaczać odstępy, normalize-space() praktycznie zawsze poprawia czytelność i stabilność. I właśnie ten wybór decyduje, czy test będzie czytelny, czy tylko pozornie działający.

Przykłady, które najczęściej ratują testy

Najlepiej to widać na realnych elementach interfejsu. Poniżej pokazuję wzorce, które sam stosuję najczęściej w testach E2E i smoke testach.

//button[normalize-space(.)='Zaloguj się']
//a[contains(normalize-space(.), 'Regulamin')]
//div[@role='alert' and contains(normalize-space(.), 'Zapisano')]
//section[@data-section='checkout']//button[normalize-space(.)='Kup teraz']
//label[.//span[normalize-space()='E-mail']]

• Przycisk akcji - pierwsza linia łapie prosty napis, bezpieczna dla zwykłych buttonów.
• Link w nawigacji - contains() działa, gdy link ma dłuższy tekst, ale wciąż rozpoznawalny fragment.
• Komunikat statusu - warto dodać @role='alert', żeby nie łapać przypadkowego tekstu z innej części strony.
• Sekcja zamówienia - zawężenie do konkretnego bloku jest często ważniejsze niż sam tekst, bo ten sam napis może pojawić się kilka razy.
• Etykieta zagnieżdżona w spanie - to klasyczny przypadek, w którym text() bywa zawodny, a . działa lepiej.

Takie selektory są czytelne, ale nie powinny żyć w próżni. Jeśli masz powtarzalny napis typu „Zobacz więcej”, bez kontekstu dostaniesz kilka trafień i test zacznie wybierać pierwszy lepszy element. Wtedy sam tekst nie rozwiązuje problemu, tylko odsłania brak zawężenia.

Najczęstsze pułapki przy selektorach tekstowych

Najwięcej błędów widzę nie w samym XPath, tylko w założeniu, że tekst w DOM zawsze wygląda tak samo jak na ekranie. W praktyce tak nie jest.

• Spacje i łamania linii - dokładne porównanie bez normalize-space() potrafi się wysypać przez niewidoczne odstępy albo nową linię w markupie.
• Zagnieżdżone elementy - ikona, badge albo osobny mogą sprawić, że text() przestanie widzieć cały napis.
• contains(text(), '...') wygląda dobrze, ale bywa zdradliwe - przy kilku węzłach tekstowych porównujesz tylko fragment, więc lepiej użyć contains(normalize-space(.), '...') albo zawęzić selektor.
• Zbyt szerokie contains() - jeśli dopasowujesz tylko fragment, łatwo złapać element z innego modułu albo ukrytego panelu.
• Zmienne treści - liczby, daty, statusy i copy marketingowe zmieniają się częściej niż nazwy atrybutów, a przy aplikacjach wielojęzycznych tekst bywa dodatkowo zależny od lokalizacji.
• Brak kontekstu - globalne //button[...] jest wygodne na początku, ale w większym UI szybko robi się nieczytelne i kruche.
• Brak regexów w typowym browser XPath - jeśli tekst ma złożony wzorzec, sam XPath zwykle nie wystarcza i lepiej oprzeć się na atrybucie albo rozbić sprawdzenie na prostsze kroki.

Jeśli muszę naprawić taki selektor, zwykle nie zaczynam od kombinowania z funkcją, tylko od zawężenia obszaru: formularza, sekcji, karty produktu albo konkretnego komponentu. To daje więcej niż kolejne warstwy contains(), które tylko maskują zbyt szeroki wybór.

Jak pisać selektory, które przetrwają zmiany w interfejsie

W praktyce traktuję tekstowe XPath-y jako narzędzie drugiego wyboru: bardzo skuteczne tam, gdzie tekst niesie znaczenie biznesowe, ale nie jako domyślną odpowiedź na każdy element. Jeśli masz stabilne id albo sensowne data-testid, zwykle wygrywają z bardziej ekspresyjnym selektorem opartym na tekście.

1. Zacznij od najtańszego i najbardziej stabilnego identyfikatora - id, data-testid, name albo semantyczny role.
2. Używaj tekstu tam, gdzie to część zachowania - przyciski, etykiety, komunikaty, elementy nawigacji.
3. Zawężaj kontekst - zamiast globalnego //button[...] lepiej wskazać konkretną sekcję, formularz lub kartę.
4. Normalizuj odstępy - normalize-space(.) oszczędza czas przy debugowaniu drobnych różnic w markupie.
5. Rozróżniaj exact match i partial match - pełne dopasowanie jest bardziej precyzyjne, częściowe bardziej odporne na drobne zmiany copy.
6. Dodawaj jawne waity - tekst może pojawić się później niż sam kontener, więc locator i synchronizacja muszą iść razem.

To podejście dobrze współgra z Page Object Model: lokator siedzi w jednym miejscu, a test opisuje zachowanie. Dzięki temu, gdy UI się zmienia, poprawiasz selektor raz, a nie w kilkunastu scenariuszach.

Gdy tekst jest jedyną sensowną kotwicą

Najbardziej praktyczna zasada jest prosta: używaj tekstu wtedy, gdy to właśnie tekst jest dla użytkownika znaczący. Gdy interfejs jest złożony albo zbyt „sprytny”, tekstowy XPath staje się nie tyle złym narzędziem, ile narzędziem, które trzeba umieć ograniczyć.

• Exact match wybieram dla stałych etykiet i przycisków.
• Partial match zostawiam dla dłuższych komunikatów i nagłówków.
• Scoped locator stosuję, gdy ten sam napis występuje w kilku miejscach.
• Alternatywa w atrybucie wygrywa, jeśli tekst jest zależny od języka, kampanii albo testu A/B.

Dobrze napisany selektor po tekście skraca diagnostykę, poprawia czytelność testów i rzadziej psuje się przy kosmetycznych zmianach frontu. Jeśli mam wybrać jedną rzecz, którą warto zapamiętać, to tę: najpierw zawęź kontekst, potem dopasuj tekst, a dopiero na końcu kombinuj z bardziej złożonym XPath-em.