Lekcja 1: selektory proste w Selenium (id, name, className, tagName, linkText, partialLinkText)

Selektory proste w Selenium to sześć metod klasy By, które znajdują element strony po jednej cesze: By.id, By.name, By.className, By.tagName, By.linkText i By.partialLinkText. Od nich zaczyna się każdy test interfejsu, bo zanim klikniecie przycisk, musicie go znaleźć. W tej lekcji każdy selektor uruchomiliśmy na żywej stronie w Selenium 4.51.0 i Javie 25, a wynik wpisaliśmy w komentarze kodu.

To pierwsza lekcja cyklu o lokalizowaniu elementów, zaraz po tekście wprowadzającym. Jeśli nie znacie jeszcze pojęć DOM, lokator i WebElement, zacznijcie od wprowadzenia selektory w Selenium: lokalizowanie elementów. Selektory złożone, czyli CSS i XPath, to temat kolejnej lekcji. Ćwiczymy na naszej stronie treningowej selenium-shop.pl, na formularzu logowania w zakładce Moje konto.

Czym są selektory proste w Selenium?

Selektor prosty to sposób wskazania elementu przez jeden atrybut albo jedną właściwość HTML: identyfikator, nazwę, klasę, nazwę znacznika albo tekst linku. Przekazujecie go do driver.findElement(), które zwraca pierwszy pasujący element, albo do driver.findElements(), które zwraca listę wszystkich pasujących. Gdy nic nie pasuje, findElement rzuca NoSuchElementException, a findElements zwraca pustą listę.

Według dokumentacji Selenium biblioteka obsługuje 8 tradycyjnych strategii lokalizowania: sześć prostych z tej lekcji oraz selektor CSS i XPath. Lokalizowanie elementów to fundament każdego skryptu, bo na WebElementach wykonujecie większość akcji użytkownika: kliknięcie, wpisanie tekstu, zaznaczenie pola. Dobry selektor jest jednoznaczny, krótki i odporny na zmiany wyglądu strony.

Jak przygotować projekt w Selenium 4 i Javie 25?

Wystarczy jedna zależność Maven. Według Maven Central wersja selenium-java 4.51.0 ukazała się 9 października 2026 roku i to na niej uruchomiliśmy przykłady. Od Selenium 4.6 wbudowany Selenium Manager sam pobiera sterownik pasujący do zainstalowanej przeglądarki, więc nie pobieracie ręcznie pliku chromedriver i nie ustawiacie System.setProperty, co w starszych kursach było krokiem numer jeden.

pom.xml, fragment

<properties>
    <maven.compiler.release>25</maven.compiler.release>
</properties>
<dependencies>
    <dependency>
        <groupId>org.seleniumhq.selenium</groupId>
        <artifactId>selenium-java</artifactId>
        <version>4.51.0</version>
    </dependency>
</dependencies>

W kodzie poniżej używamy zwykłych cudzysłowów prostych ". Jeśli kopiujecie przykłady z edytora tekstu albo z prezentacji, sprawdźcie, czy nie zamieniły się w typograficzne ”: kompilator Javy odrzuci taki znak jako niedozwolony, a to jeden z najczęstszych powodów, dla których kod z internetu „nie działa” u początkujących.

Jak działa By.id i dlaczego to pierwszy wybór?

By.id szuka elementu po atrybucie id, który według specyfikacji HTML musi być unikalny w całym dokumencie. Dokumentacja Selenium zaleca go jako pierwszy wybór, jeśli identyfikatory są dostępne, unikalne i przewidywalne, bo wyszukiwanie po id jest szybkie i proste do czytania. Na stronie logowania selenium-shop.pl pole „Użytkownik lub e-mail” wygląda w DevTools tak:

HTML elementu, selenium-shop.pl/moje-konto

<input type="text" class="woocommerce-Input woocommerce-Input--text input-text"
       name="username" id="username" autocomplete="username" value="" />

Java, Selenium 4.51.0

WebElement poleLogin = driver.findElement(By.id("username"));
poleLogin.sendKeys("tester@example.com");

Uwaga na identyfikatory generowane przez frameworki front endowe, na przykład input-4821 albo mat-input-7. Zmieniają się po każdym przeładowaniu albo nowej wersji aplikacji. Jeśli w id widzicie liczbę, której nie rozumiecie, nie budujcie na nim testu.

Kiedy użyć By.name?

By.name szuka po atrybucie name, który mają przede wszystkim elementy formularzy: pola, przyciski, listy wyboru. To dobry drugi wybór, bo nazwa pola jest częścią kontraktu z serwerem i zmienia się rzadziej niż wygląd. Przycisk logowania na stronie treningowej:

HTML elementu

<button type="submit" class="woocommerce-button button woocommerce-form-login__submit"
        name="login" value="Log in">Zaloguj się</button>

Java

WebElement przyciskZaloguj = driver.findElement(By.name("login"));
przyciskZaloguj.click();

Pułapka: na stronie z dwoma formularzami, na przykład logowanie i rejestracja obok siebie, ta sama nazwa może się powtórzyć. findElement zwróci wtedy pierwszy element w kolejności dokumentu, niekoniecznie ten, o który Wam chodziło. Zawsze sprawdźcie w DevTools, ile elementów pasuje do selektora.

Dlaczego By.className nie przyjmuje kilku klas?

By.className przyjmuje dokładnie jedną klasę CSS. Element z atrybutem class="woocommerce-form__input woocommerce-form__input-checkbox" ma dwie klasy, a nie jedną długą nazwę ze spacją. Gdy przekażecie obie naraz, Selenium przerwie test wyjątkiem InvalidSelectorException z komunikatem Compound class names not permitted. Dokumentacja Selenium mówi to wprost przy opisie strategii class name.

HTML pola „Zapamiętaj mnie”

<input class="woocommerce-form__input woocommerce-form__input-checkbox"
       name="rememberme" type="checkbox" id="rememberme" value="forever" />

PulapkiSelektorow.java, uruchomione 10.10.2026

import org.openqa.selenium.By;
import org.openqa.selenium.InvalidSelectorException;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;

public class PulapkiSelektorow {
    public static void main(String[] args) {
        WebDriver driver = new ChromeDriver(new ChromeOptions().addArguments("--headless=new"));
        try {
            driver.get("http://www.selenium-shop.pl/moje-konto/");

            // 1. Kilka klas rozdzielonych spacją
            try {
                driver.findElement(By.className("woocommerce-form__input woocommerce-form__input-checkbox"));
            } catch (InvalidSelectorException e) {
                System.out.println("Błąd: " + e.getRawMessage()); // Compound class names not permitted
            }
            // Poprawnie: jedna klasa albo selektor CSS łączący obie
            System.out.println(driver.findElements(
                    By.cssSelector(".woocommerce-form__input.woocommerce-form__input-checkbox")).size()); // 1

            // 2. Klasa użyta przez wiele elementów: findElement zwraca pierwszy
            System.out.println(driver.findElements(By.className("input-text")).size()); // 3

            // 3. Tekst linku z CSS text-transform: uppercase
            System.out.println(driver.findElements(By.partialLinkText("Selenium")).size()); // 0
            System.out.println(driver.findElements(By.partialLinkText("SELENIUM")).size()); // 1
        } finally {
            driver.quit();
        }
    }
}

Program pokazuje trzy rzeczy. Kilka klas łączycie selektorem CSS z kropkami bez spacji, .klasa1.klasa2, o czym więcej w lekcji o CSS i XPath. Klasa input-text pasuje na tej stronie do 3 pól naraz: loginu, hasła i e-maila w rejestracji, więc findElement zwróci tylko pierwsze z nich. A trzecia pułapka dotyczy linków i omawiamy ją dwie sekcje niżej. Selenium nie zgaduje, którą z trzech klas mieliście na myśli. W tym jest bardziej konsekwentny niż niejeden code review.

Do czego służy By.tagName?

By.tagName szuka po nazwie znacznika, na przykład h1, table albo tr. Dokumentacja Selenium ostrzega, że to strategia ryzykowna, bo na stronie zwykle jest wiele elementów tego samego typu, i poleca ją głównie razem z findElements. Typowy przykład z testów: policzyć wiersze tabeli zamówień albo pobrać wszystkie nagłówki sekcji.

Java

WebElement naglowek = driver.findElement(By.tagName("h1"));
List<WebElement> wierszeZamowien = driver.findElements(By.tagName("tr"));

Na stronie treningowej trafiliśmy przy tym na lekcję gratis. W naszym przebiegu w Chrome 154 w trybie headless nagłówek h1 z tekstem „Moje konto” był w DOM, ale Selenium uznało go za niewidoczny, więc getText() zwróciło pusty tekst. Metoda getText zwraca tylko tekst widoczny dla użytkownika. Gdy potrzebujecie treści elementu niezależnie od widoczności, użyjcie getDomProperty("textContent"), a gdy test ma sprawdzać to, co widzi użytkownik, zostańcie przy getText i najpierw upewnijcie się, że element jest wyświetlony.

Dlaczego linkText i partialLinkText zależą od wielkości liter?

By.linkText znajduje link po jego pełnym tekście, a By.partialLinkText po fragmencie. Według specyfikacji W3C WebDriver porównywany jest tekst renderowany, czyli taki, jaki zwróciłoby getText, a nie tekst ze źródła HTML. Dlatego wielkość liter ma znaczenie, a style CSS potrafią ją zmienić.

HTML linku w nagłówku strony

<a href="http://www.selenium-shop.pl/" title="Selenium Shop Automatyzacja Testów" rel="home">Selenium Shop Automatyzacja Testów</a>

Druga wada selektorów tekstowych to wersje językowe. Test z By.linkText("Zaloguj się") przestaje działać na angielskiej wersji strony. Jeśli Wasza aplikacja ma kilka języków, trzymajcie teksty w plikach z danymi testowymi albo wybierzcie lokator niezależny od treści, na przykład id albo atrybut data-testid.

SelektoryProste.java, Selenium 4.51.0 i Java 25, wynik z 11.10.2026

import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;

public class SelektoryProste {
    public static void main(String[] args) {
        ChromeOptions opcje = new ChromeOptions();
        opcje.addArguments("--headless=new", "--window-size=1400,900");
        WebDriver driver = new ChromeDriver(opcje); // Selenium Manager sam dobiera chromedriver
        try {
            driver.get("http://www.selenium-shop.pl/moje-konto/");

            WebElement poleLogin = driver.findElement(By.id("username"));
            WebElement przyciskZaloguj = driver.findElement(By.name("login"));
            WebElement zapamietajMnie = driver.findElement(By.className("woocommerce-form__input-checkbox"));
            WebElement naglowek = driver.findElement(By.tagName("h1"));
            WebElement linkDoSklepu = driver.findElement(By.linkText("SELENIUM SHOP AUTOMATYZACJA TESTÓW"));
            WebElement linkCzesciowy = driver.findElement(By.partialLinkText("AUTOMATYZACJA"));

            System.out.println(poleLogin.getDomAttribute("autocomplete"));       // username
            System.out.println(przyciskZaloguj.getTagName());                 // button
            System.out.println(zapamietajMnie.getDomAttribute("type"));          // checkbox
            System.out.println(naglowek.getDomProperty("textContent"));       // Moje konto
            System.out.println(linkDoSklepu.getDomAttribute("href"));            // http://www.selenium-shop.pl/
            System.out.println(linkCzesciowy.getText());                      // SELENIUM SHOP AUTOMATYZACJA TESTÓW
        } finally {
            driver.quit();
        }
    }
}

Wartości atrybutów czytamy metodą getDomAttribute, a nie starszą getAttribute. Według dokumentacji Selenium getAttribute zwraca najpierw właściwość DOM o podanej nazwie, a dopiero gdy jej nie ma, atrybut z HTML, więc ten sam kod potrafi dać różne wyniki na różnych elementach. getDomAttribute zwraca dokładnie to, co zapisano w HTML, a getDomProperty aktualną właściwość elementu, tak jak przy nagłówku powyżej. Na tej stronie wynik obu podejść jest taki sam, co sprawdziliśmy 11.10.2026.

Który selektor wybrać w praktyce?

Dokumentacja Selenium podaje prostą kolejność: jeśli id jest dostępne, unikalne i przewidywalne, wybierzcie id, a gdy go brakuje, dobrze napisany selektor CSS. XPath działa, ale jest trudniejszy w czytaniu i debugowaniu, a linkText i partialLinkText działają wyłącznie na linkach. Z naszego doświadczenia przy ponad 450 000 testów automatycznych napisanych przez zespół Quality Island do tej listy warto dopisać jedną rzecz: umówcie się z programistami na stałe atrybuty testowe, na przykład data-testid, w kluczowych miejscach aplikacji.

Najwięcej czasu w utrzymaniu testów nie zjada pisanie selektora, tylko jego naprawianie po każdej zmianie wyglądu. W projektach automatyzacji, które prowadzimy dla klientów, kruche selektory oparte na klasach stylu i tekstach to jedna z pierwszych rzeczy, które porządkujemy razem ze stabilnymi oczekiwaniami w Selenium. Jeśli chcecie, żebyśmy spojrzeli na Wasz framework, robimy to w ramach usługi automatyzacji testów UI.

Gdy znajdziecie już element, kolejnym krokiem jest sprawdzenie wyniku, o czym piszemy w artykule o asercjach w Selenium. A jeśli wahacie się, czy Selenium to wciąż dobry wybór na start, porównanie z Playwright i Cypress znajdziecie w tekście Strefy QA o wyborze narzędzia w 2026 roku.

Całą ścieżkę od selektorów przez Page Object po uruchamianie testów w CI przerabiamy na szkoleniu automatyzacja testów z Selenium WebDriver, a kto woli od razu pracować na projekcie zbliżonym do komercyjnego, ma projekt stażowy tester automatyzujący. Zespołom, które zaczynają nowy framework, polecamy też szkolenie Playwright w Javie, bo zasady wyboru lokatorów są w obu narzędziach takie same. W Quality Island przeszkoliliśmy już ponad 2 500 specjalistów i selektory to temat, od którego zaczyna każdy z nich.

Selektor nie pomoże, gdy po kliknięciu zamiast elementu strony pojawi się okno przeglądarki z przyciskiem OK. Takie okna obsługuje się osobnym interfejsem, co pokazujemy w lekcji alerty w Selenium: alert, confirm i prompt.

Powiązane na blogu Quality Island

• Lokalizowanie elementów: selektory w Selenium, wprowadzenie
• Explicit Wait vs Implicit Wait: waity w Selenium WebDriver
• Asercja: co to jest i jak używać asercji w testach automatycznych
• Selenium: co to jest, jak działa i od czego zacząć
• Wzorce projektowe w Selenium WebDriver

Pełna lista źródeł

• Selenium, Locator strategies, dokumentacja WebDriver, 2026. Stąd 8 tradycyjnych strategii i zakaz złożonych nazw klas.
• Selenium, Tips on working with locators, 2022. Stąd kolejność id, CSS, XPath i ostrzeżenia dla tagName i linkText.
• Selenium, Selenium Manager, 2026. Stąd automatyczne pobieranie sterowników od wersji 4.6.
• W3C, WebDriver, Locator strategies. Stąd pięć strategii protokołu i porównywanie tekstu renderowanego dla link text.
• Maven Central, selenium-java 4.51.0, 2026. Wersja z 9 października 2026 roku użyta w przykładach.
• MDN Web Docs, atrybut id i text-transform.
• Quality Island, test selektorów na selenium-shop.pl/moje-konto, Chrome 154, Selenium 4.51.0, Java 25, 11.10.2026; dane własne 2026: ponad 450 000 testów automatycznych i ponad 2 500 przeszkolonych specjalistów.

Autor lekcji: Tomasz Stelmach.