Playwright Locators Rehberi: getByRole, getByText, getByLabel, CSS ve XPath ile Güçlü Seçiciler

Playwright Locators Rehberi: getByRole, getByText, getByLabel, CSS ve XPath ile Güçlü Seçiciler

Web otomasyonu ve uçtan uca test süreçlerinde elementleri doğru, stabil ve verimli bir şekilde bulmak, testlerin başarısı için kritik öneme sahiptir. Playwright, modern web uygulamalarını test etmek için güçlü ve esnek bir araç seti sunarken, element seçicileri (locators) bu sürecin temelini oluşturur. Bu makale, Playwright’ın sunduğu başlıca locator stratejilerini – getByRole, getByText, getByLabel, CSS seçiciler ve XPath – derinlemesine inceleyecek, her birinin avantajlarını, dezavantajlarını ve en iyi kullanım senaryolarını detaylı kod örnekleriyle açıklayacaktır. Amacımız, Playwright ile daha sağlam, okunabilir ve bakımı kolay otomasyon testleri yazmanız için size kapsamlı bir rehber sunmaktır.

Playwright Locators’a Giriş: Neden Önemliler?

Playwright’ın test otomasyonundaki gücü, elementleri bulma ve onlarla etkileşim kurma yeteneğinden gelir. Bir web sayfasındaki bir butona tıklamak, bir metin alanına veri girmek veya bir elementin görünürlüğünü doğrulamak için öncelikle o elementi doğru bir şekilde hedeflememiz gerekir. İşte tam bu noktada Playwright locators devreye girer. Doğru locator seçimi, testlerinizin kararlılığını artırır, uygulamanın UI değişikliklerinden daha az etkilenmesini sağlar ve test kodunuzun okunabilirliğini yükseltir.

Stabil ve Güvenilir Testler İçin Temel

Elementlerin dinamik ID’leri veya sık değişen CSS sınıfları olduğunda, geleneksel seçicilerle yazılan testler kırılgan hale gelebilir. Playwright locators, bu tür sorunları minimize etmek için daha akıllı ve anlamsal yaklaşımlar sunar. Örneğin, bir butonun metnine veya erişilebilirlik rolüne göre seçim yapmak, o butonun görsel stilinin veya konumunun değişmesinden etkilenme olasılığını azaltır.

Farklı Senaryolar İçin Esnek Yaklaşımlar

Her elementin benzersiz bir tanımı veya kolayca erişilebilir bir niteliği olmayabilir. Playwright, bu farklı senaryoları ele almak için geniş bir yelpazede locator stratejileri sunar. Bir elementin erişilebilirlik rolü yoksa metnine, metni yoksa ilişkili etiketine veya karmaşık bir yapıya sahipse CSS veya XPath’e başvurabilirsiniz. Bu esneklik, her türlü web uygulamasını test etme yeteneği sağlar.

Otomasyon Testlerinde Bakım Kolaylığı

Testlerin bakımı, yazılması kadar önemlidir. Anlamlı ve stabil locators kullanmak, bir UI değişikliği olduğunda test kodunuzda yapmanız gereken değişiklik miktarını önemli ölçüde azaltır. Örneğin, getByRole('button', { name: 'Gönder' }) ile bir butonu seçmek, geliştiricinin o butonun class adını değiştirmesi durumunda testin bozulmamasını sağlar. Bu da uzun vadede test otomasyonu maliyetlerini düşürür.

Anlamsal Seçiciler: getByRole ve Erişilebilirlik Odaklı Yaklaşım

getByRole, Playwright’ın en güçlü ve önerilen locator stratejilerinden biridir. Web elementlerini erişilebilirlik (ARIA) rolüne göre bulmayı sağlar. Bu yaklaşım, sadece testlerinizi daha sağlam hale getirmekle kalmaz, aynı zamanda uygulamanızın erişilebilirlik standartlarına uygunluğunu da dolaylı olarak kontrol etmenize yardımcı olur.

getByRole Nedir ve Nasıl Kullanılır?

getByRole, HTML elementlerinin sahip olduğu standart ARIA rollerini (örneğin, button, textbox, link, checkbox, heading) kullanarak elementleri bulur. Bu yöntem, bir elementin görsel özelliklerinden ziyade anlamsal anlamına odaklanır. Kullanımı oldukça basittir:

await page.getByRole('button', { name: 'Gönder' }).click();
await page.getByRole('textbox', { name: 'Kullanıcı Adı' }).fill('testuser');
await page.getByRole('link', { name: 'Daha Fazla Bilgi' }).click();
await page.getByRole('checkbox', { name: 'Beni Hatırla' }).check();
await page.getByRole('heading', { name: 'Ürün Detayları', level: 2 }).isVisible();

name seçeneği, genellikle elementin erişilebilir adını (örneğin, butonun metni, input'un etiketi) belirtir. level seçeneği başlıklar için (h1, h2 vb.), checked, selected, expanded gibi durumlar ise ilgili elementin anlık durumunu kontrol etmek için kullanılır.

Erişilebilirlik ve Test Kalitesi İlişkisi

getByRole kullanmak, uygulamanızın erişilebilirlik açısından daha iyi olmasını teşvik eder. Çünkü bu locator, bir elementin erişilebilir adını veya rolünü bulmaya çalışır. Eğer bir geliştirici, bir element için erişilebilir bir rol veya isim tanımlamamışsa, getByRole o elementi bulamayabilir. Bu durum, geliştiricileri erişilebilirlik standartlarına uygun kod yazmaya yönlendirir ve sonuç olarak hem kullanıcılar hem de otomasyon testleri için daha iyi bir deneyim sunar.

Yaygın getByRole Kullanım Senaryoları ve Parametreleri

• Butonlar: getByRole('button', { name: 'Kaydet' })
• Metin Kutuları: getByRole('textbox', { name: 'Email' })
• Linkler: getByRole('link', { name: 'Hakkımızda' })
• Başlıklar: getByRole('heading', { name: 'Ana Sayfa', level: 1 })
• Onay Kutuları: getByRole('checkbox', { name: 'Şartları Kabul Ediyorum' })
• Radyo Butonları: getByRole('radio', { name: 'Erkek' })
• Listeler: getByRole('list', { name: 'Menü Öğeleri' })

Parametreler, elementleri daha spesifik olarak hedeflemek için kullanılır. Örneğin, aynı metne sahip birden fazla buton varsa, diğer nitelikleri (örneğin, pressed: true) kullanarak ayırt edebilirsiniz.

Metin Tabanlı Seçiciler: getByText ile Kullanıcı Odaklı Yaklaşım

getByText, bir elementin görünür metin içeriğine göre seçim yapmanızı sağlar. Bu, özellikle kullanıcıların etkileşimde bulunduğu metin etiketli elementleri hedeflemek için oldukça sezgisel ve kullanışlı bir yöntemdir. Kullanıcılar bir butona "Gönder" yazısı yüzünden tıklıyorsa, testlerinizin de aynı mantıkla o butonu bulması mantıklıdır.

getByText Nedir ve Avantajları Nelerdir?

getByText, bir elementin içindeki veya altındaki metin içeriğini arar. En büyük avantajı, kullanıcı arayüzündeki metin değişikliklerine karşı daha dirençli olmasıdır. Bir elementin ID'si veya class'ı değişse bile, metni aynı kaldığı sürece testiniz çalışmaya devam eder.

await page.getByText('Hoş Geldiniz!').isVisible();
await page.getByText('Sepete Ekle').click();
await page.getByText('Toplam: 150 TL').textContent();

Tam Eşleşme ve Kısmi Eşleşme (exact: true)

Varsayılan olarak, getByText kısmi eşleşme yapar ve büyük/küçük harf duyarlı değildir. Yani "Sepete Ekle" aradığınızda, "sepete ekle" veya "Sepete ekle" gibi metinleri de bulabilir. Tam eşleşme istiyorsanız exact: true seçeneğini kullanmalısınız:

// Kısmi eşleşme (varsayılan)
await page.getByText('Sepete Ekle').click(); // "Sepete Ekle" veya "sepete ekle" bulur

// Tam eşleşme
await page.getByText('Sepete Ekle', { exact: true }).click(); // Sadece "Sepete Ekle" bulur

Dikkat Edilmesi Gerekenler ve En İyi Uygulamalar

getByText kullanırken dikkatli olunması gereken bazı noktalar vardır:

• Benzersizlik: Sayfada aynı metne sahip birden fazla element varsa, getByText ilk eşleşeni döndürebilir veya belirsizlik hatası verebilir. Bu durumda, daha spesifik bir locator (örneğin, üst elementiyle zincirleme) kullanmanız gerekebilir.
• Görünür Metin: Sadece kullanıcıya görünen metinleri hedefler. Gizli metinleri bulmaz.
• Performans: Çok büyük ve karmaşık sayfalarda, metin tabanlı arama diğer seçicilere göre biraz daha yavaş olabilir, ancak çoğu senaryoda farkedilir bir performans düşüşü yaşanmaz.

Etiket Tabanlı Seçiciler: getByLabel ile Form Elementlerini Hedefleme

getByLabel, özellikle form elementleri (input, textarea, select) için tasarlanmış bir locator'dır. Bir etiketi ile ilişkili olan input elementini bulmayı sağlar. Bu, kullanıcıların bir formu doldururken gördükleri etiketi kullanarak elementleri hedeflemenin doğal bir yoludur.

getByLabel Nedir ve Neden Kullanılır?

HTML'de etiketi, bir form kontrolü (genellikle ) ile ilişkilendirilir. Bu ilişki ya for niteliği ile input'un id'sine bağlanarak ya da input'u label'ın içine alarak kurulur. getByLabel, bu ilişkiyi kullanarak etiketin metni aracılığıyla ilgili input elementini bulur.

// HTML: Kullanıcı Adı
await page.getByLabel('Kullanıcı Adı').fill('testuser');

// HTML: Email: 
await page.getByLabel('Email').fill('test@example.com');

label Etiketinin Rolü ve İlişkili Inputlar

etiketi, erişilebilirlik açısından hayati öneme sahiptir. Ekran okuyucular, label metnini ilgili input ile ilişkilendirerek görme engelli kullanıcılara formları daha iyi anlamalarını sağlar. getByLabel bu erişilebilirlik özelliğinden faydalanarak testlerinizi daha sağlam ve erişilebilir yapar.

Bir etiketi iki şekilde bir form kontrolü ile ilişkilendirilebilir:

1. for niteliği ile: Email
2. İç içe yerleştirme: Adınız:

Her iki durumda da getByLabel('Email') veya getByLabel('Adınız') ilgili input elementini bulacaktır.

Yaygın Kullanım Alanları ve Sınırlamalar

getByLabel, özellikle kullanıcı adı, şifre, email, adres gibi form alanlarını doldurmak için idealdir. Ancak, bir elementin ilişkili bir etiketi yoksa veya label metni benzersiz değilse bu locator kullanılamaz. Bu durumda getByRole('textbox', { name: 'Placeholder Metni' }) veya CSS/XPath gibi diğer seçicilere başvurmak gerekebilir.

Geleneksel ve Güçlü Seçiciler: CSS Seçiciler

CSS seçiciler, web otomasyonunda en yaygın kullanılan ve en esnek locator stratejilerinden biridir. HTML elementlerini niteliklerine, konumlarına ve ilişkilerine göre hedeflemek için güçlü bir sözdizimi sunarlar. Playwright, tarayıcının yerleşik CSS seçici motorunu kullanarak hızlı ve güvenilir element bulma yeteneği sağlar.

CSS Seçicilerin Temelleri ve Playwright Entegrasyonu

CSS seçiciler, web geliştiricileri tarafından elementleri stilize etmek için kullanılır. Playwright bu seçicileri elementleri bulmak için kullanır. Temel sözdizimi şöyledir:

• Etiket Adı: button, input, div
• ID: #myId (benzersiz olmalıdır)
• Class: .myClass (birden fazla elementte olabilir)
• Nitelik: [name="username"], [type="text"], [data-test-id="login-button"]

await page.locator('#loginButton').click(); // ID ile
await page.locator('.product-card').first().click(); // Class ile
await page.locator('input[name="password"]').fill('secret'); // Nitelik ile

Kombinatörler ve Pseudo-Class'lar

CSS seçiciler, elementler arasındaki ilişkileri (ebeveyn-çocuk, kardeş vb.) tanımlamak için kombinatörler kullanır:

• Çocuk Seçici: .parent > .child (doğrudan çocuk)
• Torun Seçici: .ancestor .descendant (herhangi bir derinlikteki torun)
• Bitişik Kardeş Seçici: h2 + p (hemen sonra gelen kardeş)
• Genel Kardeş Seçici: h2 ~ p (herhangi bir sonra gelen kardeş)

Pseudo-class'lar, elementlerin durumlarına veya konumlarına göre seçim yapmayı sağlar:

• :hover, :focus, :active (durumlar)
• :nth-child(n), :first-child, :last-child (konum)
• :not(.class) (hariç tutma)

await page.locator('div.card > button.add-to-cart').click();
await page.locator('ul li:nth-child(2)').click(); // İkinci liste öğesi

En İyi Uygulamalar ve Performans İpuçları

• Benzersiz Nitelikler: Mümkünse id veya data-test-id gibi benzersiz nitelikleri kullanın. Bu, testlerinizi daha sağlam yapar.
• Kısa ve Net: Seçicilerinizi olabildiğince kısa ve okunabilir tutun. Gereksiz yere karmaşık seçicilerden kaçının.
• Değişkenlere Atama: Sık kullanılan veya karmaşık seçicileri bir değişkene atayarak kodu daha düzenli hale getirebilirsiniz.
• Performans: ID seçiciler en hızlısıdır. Genel etiket seçiciler ve çok karmaşık kombinatörler performansı bir miktar etkileyebilir, ancak çoğu durumda bu fark göz ardı edilebilir.

Gelişmiş Seçiciler: XPath ile Esneklik ve Karmaşıklık

XPath (XML Path Language), XML ve HTML belgelerindeki elementleri seçmek için kullanılan güçlü bir sorgu dilidir. CSS seçicilerin yetersiz kaldığı, özellikle elementlerin metin içeriğine veya karmaşık ebeveyn-çocuk ilişkilerine göre seçilmesi gereken durumlarda XPath devreye girer. Playwright, XPath'i destekleyerek en karmaşık senaryolar için bile bir çözüm sunar.

XPath Nedir ve Ne Zaman Kullanılmalı?

XPath, bir HTML belgesinin DOM ağacında gezinerek elementleri bulmanızı sağlar. En büyük avantajı, CSS seçicilerle yapılamayan bazı şeyleri yapabilmesidir:

• Elementleri metin içeriğine göre seçme (text() fonksiyonu).
• Geriye doğru gezinme (ebeveyn elementleri seçme).
• Kardeş elementler arasında daha esnek gezinme.

XPath, genellikle CSS seçicilerin yetersiz kaldığı durumlarda (örneğin, "Bu metni içeren div'in ebeveynindeki butona tıkla" gibi senaryolar) tercih edilir.

Temel XPath Sözdizimi ve Yollar

XPath yolları, bir dosya sistemindeki yollara benzer:

• /html/body/div[1]/p: Mutlak yol (genellikle önerilmez, kırılgan).
• //div: Belgedeki tüm
  elementleri.
• //button[text()='Kaydet']: Metni "Kaydet" olan tüm butonlar.
• //*[@id='loginForm']: ID'si 'loginForm' olan herhangi bir element.

await page.locator('xpath=//button[text()="Giriş Yap"]').click();
await page.locator('xpath=//input[@name="kullaniciAdi" and @type="text"]').fill('testuser');

Playwright'ta XPath kullanırken, seçicinin başına xpath= eklemeniz gerekir.

Nitelik Tabanlı Seçim ve İlişkisel Yollar

XPath, niteliklere göre seçim yapmak için @ sembolünü kullanır:

• //input[@id='username']
• //a[@href='/profile']
• //div[contains(@class, 'card')] (class'ı 'card' içeren div'ler)

İlişkisel yollar, elementler arasındaki bağlantıları kullanır:

• //div[@class='parent']/button (.parent class'ına sahip div'in doğrudan altındaki buton)
• //input[@id='username']/following-sibling::button (username input'undan sonra gelen kardeş buton)
• //span[text()='Ürün Adı']/ancestor::div[@class='product-card'] (Metni 'Ürün Adı' olan span'in .product-card class'ına sahip ebeveyni)

Avantajları ve Dezavantajları

Avantajları:

• CSS seçicilerden daha esnektir, özellikle metin içeriği ve ebeveyn-çocuk ilişkileri söz konusu olduğunda.
• Geriye doğru gezinme yeteneği.
• Dinamik elementleri bulmak için güçlü fonksiyonlar (contains(), starts-with()).

Dezavantajları:

• Sözdizimi daha karmaşık ve okunması zor olabilir.
• Mutlak XPath yolları çok kırılgan olabilir.
• Performans, özellikle çok karmaşık sorgularda, CSS seçicilere göre biraz daha yavaş olabilir.
• Geliştirici araçlarında hata ayıklaması CSS seçicilere göre daha zor olabilir.

Locator Stratejileri Karşılaştırması ve En İyi Uygulamalar

Playwright'ın sunduğu zengin locator seçenekleri, her senaryo için en uygun aracı seçme özgürlüğü tanır. Ancak bu çeşitlilik, doğru seçimi yapma konusunda bazen kafa karışıklığına yol açabilir. İşte farklı locator stratejilerinin karşılaştırması ve genel en iyi uygulamalar:

Hangi Locator Ne Zaman Kullanılmalı?

Birden Fazla Locator Kullanımı ve Zincirleme

Playwright, birden fazla locator'ı birleştirerek daha spesifik hedefler oluşturmanıza olanak tanır. Buna "locator zincirleme" denir. Bu, özellikle aynı tipte birden fazla element olduğunda veya belirli bir konteyner içindeki elementleri hedeflemek istediğinizde kullanışlıdır.

// Bir kart içindeki butonu bulma
await page.locator('.product-card').filter({ hasText: 'Ürün Adı X' }).getByRole('button', { name: 'Sepete Ekle' }).click();

// Belirli bir form içindeki inputu bulma
await page.locator('form#loginForm').getByLabel('Kullanıcı Adı').fill('testuser');

Zincirleme, testlerinizin okunabilirliğini artırır ve elementleri daha kesin bir şekilde hedeflemenizi sağlar.

Bakım Kolaylığı ve Test Sağlamlığı İçin İpuçları

• Anlamsal Seçicilere Öncelik Verin: Her zaman getByRole, getByText, getByLabel gibi anlamsal seçicileri tercih edin. Bunlar, uygulamanın UI değişikliklerinden en az etkilenen ve erişilebilirlik standartlarını destekleyen seçicilerdir.
• Veri Test Nitelikleri Kullanın: Geliştiricilerinizden elementlere data-test-id veya data-qa gibi özel nitelikler eklemelerini isteyin. Bu nitelikler, UI veya stil değişikliklerinden etkilenmez ve testleriniz için sağlam bir temel oluşturur. Örneğin: page.locator('[data-test-id="login-button"]').
• Aşırı Spesifik Olmaktan Kaçının: Gereksiz yere uzun ve karmaşık CSS veya XPath seçiciler kullanmayın. Bu tür seçiciler, DOM yapısındaki küçük değişikliklerde bile kolayca kırılabilir.
• Görsel Doğrulama: Bazı durumlarda, bir elementin varlığını veya metnini doğrulamak yeterli olmayabilir. Playwright'ın görsel karşılaştırma özelliklerini kullanarak UI'ın doğru göründüğünden emin olun.
• Hata Ayıklama Araçlarını Kullanın: Playwright'ın yerleşik test runner'ı ve tarayıcı geliştirici araçları (örneğin, "Elements" sekmesi ve "Console" sekmesindeki $$() ve $x() fonksiyonları) locator'larınızı test etmek ve hata ayıklamak için çok faydalıdır.

Sonuç

Playwright, modern web uygulamalarının test otomasyonu için güçlü ve çok yönlü bir platform sunar. Bu makalede ele aldığımız getByRole, getByText, getByLabel, CSS ve XPath gibi locator stratejileri, testlerinizi daha sağlam, okunabilir ve bakımı kolay hale getirmeniz için size zengin bir araç seti sunar. Anlamsal seçicilere öncelik vermek, veri test niteliklerini kullanmak ve doğru locator'ı doğru senaryoda uygulamak, başarılı bir test otomasyon stratejisinin temel taşlarıdır. Playwright'ın esnekliği sayesinde, her türlü web uygulamasını güvenle test edebilir ve geliştirme sürecinizin kalitesini artırabilirsiniz.

SSS (Sık Sorulan Sorular)

getByRole ve getByText arasındaki temel fark nedir?

getByRole, elementleri erişilebilirlik rolüne (örneğin, buton, metin kutusu) ve erişilebilir adına göre bulur. Bu, elementin anlamsal anlamına odaklanır ve UI değişikliklerine karşı daha dirençlidir. getByText ise elementin görünür metin içeriğine göre seçim yapar. Kullanıcıların doğrudan gördüğü metinleri hedeflemek için idealdir.

XPath ne zaman CSS'e tercih edilmeli?

XPath, CSS seçicilerin yapamadığı belirli senaryolarda tercih edilir. Bunlar arasında elementleri metin içeriğine göre seçme (text() fonksiyonu), bir elementin ebeveynini bulma (geri gezinme) veya daha karmaşık kardeş ilişkilerini hedefleme bulunur. Genellikle, daha basit bir CSS seçici veya anlamsal locator yeterliyse CSS tercih edilmelidir.

Performans açısından hangi locator daha iyidir?

Genel olarak, ID seçiciler (#myId) en hızlısıdır. Ardından basit CSS seçiciler gelir. Anlamsal seçiciler (getByRole, getByText) ve XPath, tarayıcının DOM üzerinde daha fazla işlem yapmasını gerektirebilir, ancak modern tarayı