Playwright ile Ekran Görüntüsü Nasıl Alınır?

Açıkça belirtelim: Biz Geonode olarak proxy satıyoruz ve proxy aracılığıyla alınan ekran görüntüleri, ürünümüzün en temiz kullanım örneklerinden biridir — bir sayfanın başka bir ülkeden gerçekte nasıl göründüğünü doğrulamak, hiçbir API’nin size söyleyemeyeceği bir şeydir. Dürüstçe belirtmek gerekirse, sorun maliyettir: Tarayıcı her görüntüyü, yazı tipini, komut dosyasını ve videoyu önceden yükler; bu nedenle ekran görüntüsü almak, kotalı trafikte yapabileceğiniz en fazla bant genişliği tüketen işlemdir. Aşağıda bunu azaltmaya yönelik bir bölüm bulunmaktadır ve burada anlatılan teknik, daha ucuz bir sağlayıcı seçmekten çok daha fazla tasarruf etmenizi sağlayacaktır.

Üç Tür Ekran Görüntüsü

Görünüm Alanı — o anda görünür olan kısım, varsayılan ayar:

await page.screenshot({ path: 'viewport.png' });

Tam Sayfa — belgelerde bu, "sanki çok uzun bir ekranınız varmış ve sayfa bu ekrana tamamen sığıyormuş gibi, kaydırılabilir bir sayfanın tam ekran görüntüsü" olarak tanımlanmaktadır:

await page.screenshot({ path: 'full.png', fullPage: true });

Öğe — "Bazen tek bir öğenin ekran görüntüsünü almak yararlı olabilir":

await page.getByRole('article').screenshot({ path: 'element.png' });

Bunlar arasında seçim yapmak, çoğunlukla sonuçla ne yapacağınıza bağlıdır. Görüntü alanı ekran görüntüleri "kullanıcının ilk olarak ne gördüğü" sorusuna cevap verir. Tam sayfa ekran görüntüleri ise "bu sayfada neler var" sorusuna cevap verir. Öğe ekran görüntüleri ise "bu bileşen doğru görünüyor mu" sorusuna cevap verir ve sormadığınız her şeyi hariç tuttukları için karşılaştırma açısından bu üçü arasında en istikrarlı olanıdır.

Tam Sayfa Ekran Görüntüleri ve Sorun Yaşanan Noktalar

fullPage: true, kullanıcıların sıklıkla tercih ettiği ancak en fazla dikkat edilmesi gereken hususları barındıran seçenektir.

Gecikmeli yüklenen içerik görüntülenmeyebilir. Playwright, ekran görüntüsünü almak için sayfayı kaydırır; ancak kesişme noktasında yüklenen resimler ve bileşenler, ekran görüntüsü alma işlemi tamamlandığında henüz yüklenmemiş olabilir. Bunu güvenilir bir şekilde düzeltmenin yolu, kasıtlı olarak kaydırma yapmak ve beklediğiniz içeriğin gelmesini beklemektir:

await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
await expect(page.getByRole('img').last()).toBeVisible();
await page.evaluate(() => window.scrollTo(0, 0));
await page.screenshot({ path: 'full.png', fullPage: true });

Sabit başlıklar tekrarlanır veya garip bir şekilde kayar. position: fixed veya sticky özelliklerine sahip öğeler, birleştirilmiş bir ekran görüntüsünde öngörülemez şekilde davranır. style seçeneği — "ekran görüntüsü alınırken stil uygulamak için sayfaya eklenecek bir CSS dizesi" — bu sorunu temiz bir şekilde çözer:

await page.screenshot({
  path: 'full.png',
  fullPage: true,
  style: '.sticky-header { position: absolute !important; }',
});

Çok uzun sayfalar çok büyük dosyalar oluşturur. Sonsuz kaydırmalı bir akışın doğal bir sonu yoktur. Bunun yerine, "sonuçtaki görüntünün kırpılmasını belirten bir nesne" alan clip seçeneğini kullanarak tanımlanmış bir bölgeyi yakalamayı düşünün.

Üst katmanlar da yakalanır. Çerez bildirimleri, sohbet widget'ları ve modal pencereler, ekran görüntüsünde tam olarak kullanıcıya göründüğü gibi görünür. Bunları istemiyorsanız, önce kapatın — bunu yapamıyorsanız, mask adresindeki araç işinize yarayacaktır.

Öğe Ekran Görüntüleri ve Tamponlar

Öğe ekran görüntüleri, öğeyi görüntü alanına kaydırır ve yalnızca sınır kutusunu yakalar; bu da onları bileşen düzeyinde kontroller için doğru varsayılan seçenek haline getirir.

const card = page.getByTestId('product-card').first();
await card.screenshot({ path: 'card.png' });

Yapmadıkları iki şey vardır: overflow: hidden

tarafından kırpılan içeriği yakalamak ve görsel olarak üst üste binse bile öğenin kutusunun dışındaki hiçbir şeyi yakalamak.

Dosya yerine tamponlar. Belgelerde, "bir dosyaya yazmak yerine, görüntüyü içeren bir tampon alabilir ve bunu sonradan işleyebilir veya üçüncü taraf bir piksel farkı analiz aracına aktarabilirsiniz" denilmektedir. path

'i atlarsanız baytları geri alırsınız:

const buffer = await page.screenshot();
const base64 = buffer.toString('base64');

Ekran görüntüsü yerel disk dışında bir yere (nesne deposu, API, rapor, fark bulma hizmeti) gönderilecekse istediğiniz biçim budur. Ayrıca dosya sisteminden tamamen uzak durur; bu, diskin geçici olduğu konteyner tabanlı çalıştırıcılarda önemlidir.

Ekran Görüntülerinin Tekrarlanabilir Olmasını Sağlayan Seçenekler

Ekran görüntülerini birbirleriyle karşılaştırıyorsanız, bunlar isteğe bağlı değildir. Sadece bir tanesine göz atıyorsanız, bunları göz ardı edin.

| disabled

, allow

| "'disabled' olarak ayarlandığında, yakalama sırasında CSS animasyonlarını durdurur" | | caret

| hide

, initial

| "'hide' olarak ayarlandığında, ekran görüntüsü alınırken metin imlecini gizler" | | mask

| Locator[]

| "Ekran görüntüsü alınırken maskelenmesi gereken konum belirleyicileri belirtin" | | maskColor

| CSS rengi, varsayılan #F0F

| "Maskelenen bölgeler için kullanılacak rengi belirtin" | | scale

| css

, device

| "Web sayfasının görüntülenme ölçeği" | | omitBackground

| boolean, varsayılan false

| "Varsayılan beyaz arka planı gizler ve şeffaf ekran görüntüleri alınmasına izin verir" | | type

| png

, jpeg

, varsayılan png

| "Ekran görüntüsü dosya biçimini belirtir" | | quality

| 0–100 | "JPEG biçimi için görüntü kalitesi" — Yalnızca JPEG | | style

| CSS dizesi | Yakalama süresince sayfaya eklenir |

Tekrarlanabilirlik sorunlarının çoğunu çözen dört unsur:

**animations: 'disabled'

**, aynı sayfanın iki yakalaması arasındaki en büyük fark kaynağını ortadan kaldırır. İşlem sırasında gerçekleşen herhangi bir CSS geçişi, her çalıştırmada farklı bir piksel sonucu üretir.

**mask

** bölgeleri düz bir renkle değiştirir; bu sayede, karşılaştırmayı tamamen bir kenara bırakmadan, zaman damgaları, oturum tanımlayıcıları, kişiselleştirilmiş öneriler ve reklamlar gibi gerçekten değişken içeriği hariç tutabilirsiniz:

await page.screenshot({
  path: 'page.png',
  mask: [page.getByTestId('timestamp'), page.locator('.ad-slot')],
  maskColor: '#000000',
});

**scale: 'css'

**, cihaz piksel oranından ziyade CSS piksel boyutlarında yakalama yapar; böylece yüksek DPI'lı bir makine ile CI çalıştırıcısı, benzer boyutlarda görüntüler üretir. Varsayılana güvenmek yerine bunu açıkça ayarlayın, çünkü bu seçenek dizüstü bilgisayarınız ile derleme sunucusu arasında en çok farklılık gösterebilecek seçenektir.

**caret: 'hide'

**, odaklanmış bir giriş alanı bulunan herhangi bir sayfanın yakalamalarının yaklaşık yarısında görünen yanıp sönen metin imlecini kaldırır.

Tekrarlanabilirlik için belirlemeniz gereken üç husus daha vardır; bunların hiçbiri ekran görüntüsü seçeneği değildir: yapılandırmanızda görüntü alanı boyutunu, yerel ayarları ve saat dilimini sabitleyin; ayrıca yazı tiplerini de sabitleyin — yazı tipi kullanılabilirliği, geliştirici makinesi ile konteyner arasında farklılık gösterir ve farklı yazı tipleri, farklı mizanpaj anlamına gelir.

Test Hatası Durumunda Otomatik Ekran Görüntüsü Alma

Playwright’ta en kullanışlı ekran görüntüsü yapılandırması budur ve tek bir satırla gerçekleştirilir:

export default defineConfig({
  use: {
    screenshot: 'only-on-failure',
    trace: 'retain-on-failure',
    video: 'retain-on-failure',
  },
});

screenshot: 'only-on-failure' , testin başarısız olduğu anda sayfanın ekran görüntüsünü alır ve bunu rapora ekler. Diğer seçenekler şunlardır: off , on ve only-on-failure ; on ise her test için ekran görüntüsü alır ve çok sayıda dosya üretir.

Bunu trace ile birleştirmek özellikle önem arz eder, çünkü bir izleme kaydı DOM anlık görüntülerini, ağ etkinliğini ve zamanlamalarıyla birlikte her eylemi içerir. Bir ekran görüntüsü, sayfanın yanlış göründüğünü gösterir; bir izleme kaydı ise bunun nedenini açıklar. Gözetimsiz çalışan her şey için her ikisi de etkinleştirilmelidir.

Bu yapılandırma, sayfanın görüntülendiği ancak beklediğiniz sayfa olmadığı gibi kafa karıştırıcı hata türlerini teşhis etmenin de en hızlı yoludur. Bir kimlik doğrulama sayfası, oturum açma yönlendirmesi veya bölgesel bir varyant, ekran görüntüsünü görene kadar öğe sorunları gibi görünen zaman aşımlarına neden olur.

toHaveScreenshot

ile Görsel Karşılaştırma Geçici ekran yakalama yerine gerçek görsel regresyon testi için:

await expect(page).toHaveScreenshot('homepage.png');
await expect(page.getByRole('navigation')).toHaveScreenshot('nav.png');

İlk çalıştırmada bir referans çizgisi oluşturur; sonraki çalıştırmalarda karşılaştırma yapar ve farklılık tespit edildiğinde hata verir. Referans çizgilerini --update-snapshots ile bilinçli bir şekilde güncelleyin.

Üç pratik not.

Temel değerler platforma özeldir. Yazı tipi görüntüleme, işletim sistemleri arasında farklılık gösterir; bu nedenle macOS'ta oluşturulan bir temel değer, Linux konteynerinde oluşturulanla eşleşmez. Temel değerleri, testlerinizin çalıştığı ortamda oluşturun — genellikle CI'da, genellikle yerel olarak da çalıştırabileceğiniz bir konteyner aracılığıyla.

Bir tolerans belirleyin. Piksellerin tam olarak eşleşmesi, hiçbir insanın fark edemeyeceği antialiasing farklılıkları nedeniyle hatalara neden olur. Yapılandırmanızda maxDiffPixels veya maxDiffPixelRatio ayarını kullanmanız, test paketini kullanışlı hale getirir.

Başlamadan önce tüm değişkenleri maskeleme. Zaman damgası her değiştiğinde başarısız olan bir görsel test, bir hafta içinde devre dışı bırakılır; bu da testin hiç olmaması durumundan daha kötüdür.

Proxy Üzerinden Ekran Görüntüleri

Bu durum tam anlamıyla bizim uzmanlık alanımızdır ve oldukça iyi bir örnektir.

Playwright kurulumunuzda proxy'yi yapılandırın:

const context = await browser.newContext({
  proxy: { server: 'http://proxy.example.com:9000', username: 'u', password: 'p' },
  locale: 'de-DE',
  timezoneId: 'Europe/Berlin',
});

Proxy'nin yanındaki locale

ve timezoneId

adreslerine dikkat edin. en-US

yerel ayarına ve Londra saat dilimine sahip bir Alman çıkış adresi, gerçek bir ziyaretçinin oluşturmayacağı bir kombinasyondur ve birçok site, ne sunacağına karar vermek için adresten bağımsız olarak yerel ayarı kullanır. Üçünü de birlikte ayarlayın, aksi takdirde amaçladığınızdan farklı bir şeyi test edersiniz.

Bunun gerçekten cevapladığı şey: o ülkedeki gerçek bir ziyaretçinin ne gördüğü. Bölgesel fiyatlandırma, para birimi gösterimi, stok durumu, promosyon afişleri, reklamlarınızın ödeme yaptığınız yerde gösterilip gösterilmediği ve içeriğinizin yanında neyin göründüğü. Hiçbir API size bunu vermez, çünkü cevap, görüntülenen sayfadır.

Maliyeti nedir ve nasıl azaltılır? Bir tarayıcı her şeyi alır. Kademeli ücretlendirilen ev trafiğinde — bizimki 0,79 $/GB'den başlar, Eylül 2026'da fiyatlandırma sayfamız üzerinden kontrol edilmiştir — yirmi pazarda yapılan bir ekran görüntüsü alımı, maliyetin hızla artmasına neden olur. İhtiyacınız olmayan kaynak türlerini engellemek en etkili yöntemdir:

await page.route('**/*.{woff,woff2,mp4,webm}', route => route.abort());

Bu listede bulunmayan öğelere dikkat edin. Ekran görüntüsü teslim edilecek sonuçsa, resimleri engelleyemezsiniz — bu, amacınıza ters düşer. Yazı tiplerini ve medyayı engelleyin, görselleri koruyun ve görsel doğrulamanın doğası gereği pahalı bir proxy işi olduğunu kabul edin. Görünümden ziyade yalnızca metin içeriğini doğrulamanız gereken durumlarda, görselleri de engelleyin ve ekran görüntüsünü tamamen atlayın.

Ve coğrafi konumun gerçekten ulaştığını doğrulayın. Ekran görüntüsünü alın ve inceleyin. Brezilya çıkış noktası üzerinden yakalanan bir sayfada, sizin ofisinizdekiyle aynı fiyatlar gösteriliyorsa, IP sorgusu ne sonuç verirse versin hedefleme çalışmıyor demektir. Bu, proxy testlerinin neden önemli olduğu başlıklı yazımızda anlattığımız sessiz hatanın tam da kendisidir — ve ekran görüntüleri bunu tespit etmede olağanüstü etkilidir, çünkü bir insan bunu bir bakışta görebilir.

Büyük Ölçekli Ekran Görüntüleri

Birkaç taneden fazlasını çekmeye başladığınızda, işin yönetilemez hale gelmesini önleyen birkaç yöntem vardır.

Bağlamı değil, tarayıcıyı yeniden kullanın. Bir tarayıcıyı başlatmak maliyetlidir; bir bağlam oluşturmak ise ucuzdur. Birçok sayfayı veya bölgeyi tarayacaksanız, tarayıcıyı bir kez başlatın ve her iş birimi için yeni bir bağlam oluşturun — bu sayede, başlangıç maliyetini tekrar tekrar ödemeden izole edilmiş çerezlere ve depolama alanına sahip olursunuz:

const browser = await chromium.launch();
for (const country of countries) {
  const ctx = await browser.newContext({ proxy: { server: proxyFor(country) } });
  const page = await ctx.newPage();
  await page.goto(url, { waitUntil: 'domcontentloaded' });
  await page.screenshot({ path: `shots/${country}.png`, fullPage: true });
  await ctx.close();
}
await browser.close();

Bekleme koşulu olarak networkidle adresini kullanmayın. Analitik işaretçileri, web soketleri veya sorgulama içeren sayfalar asla boşta kalmaz ve bekleme süresi dolmuş olur. Sayfanın hazır olduğunu belirten öğeyi bekleyin:

await page.goto(url);
await expect(page.getByRole('heading', { level: 1 })).toBeVisible();
await page.screenshot({ path: 'shot.png' });

Eşzamanlılığı kasıtlı olarak sınırlayın. Her tarayıcı bağlamı gerçek bellek tüketir — bir sayfa yüklendikten sonra birkaç yüz megabayt tüketimi normaldir. Küçük bir çalıştırıcıda otuz tanesini paralel olarak çalıştırmak, zaman aşımı gibi görünen ancak aslında makinenin bellek yetersizliğinden kaynaklanan hatalara yol açar. Dört veya beş ile başlayın ve belleği izlerken sayıyı artırın.

Dosyaları bulabilmeniz için uygun şekilde adlandırın. screenshot-1.png ile screenshot-400.png arasında değişen bir dizin kullanılamaz. Dosya adına hedefi, bölgeyi ve zaman damgasını ekleyin ve URL'yi görüntünün yanında saklayın.

Arşivlemeden önce sıkıştırın. PNG kayıpsızdır ve boyut olarak büyüktür. Görüntüler piksel karşılaştırması yerine insan tarafından incelenmek üzereyse, quality: 80 adresindeki JPEG formatı genellikle boyut olarak çok daha küçüktür ve görsel olarak ayırt edilemez — ve yirmi pazarda zamanlanmış bir çalışma için bu fark, depolama maliyetine yansır.

Çalıştırmayı durdurmadan hataları yönetin. Yüklenmeyen tek bir sayfa, diğer on dokuz sayfanın da işin dışına kalmasına neden olmamalıdır. Her bir yakalamayı sonlandırın, hatayı kaydedin ve devam edin — ardından işin üçüncü hedefte tamamen durduğunu fark etmek yerine, hangi hedeflerin başarısız olduğunu raporlayın.

Ekran Görüntüsü Yanlış Araç Olduğunda

Veriyi istediğinizde. Fiyata ihtiyacınız varsa, fiyatı ayıklayın. Bir sayının ekran görüntüsü, daha sonra resimden okumanız gereken bir sayıdır. Ekran görüntüleri görünüş içindir; seçiciler ise içerik içindir.

Bir testin neden başarısız olduğunu bilmek istediğinizde. Bir izleme raporu kesinlikle daha bilgilendiricidir ve zaten ekran görüntüsünü de içerir.

Sayfa çok büyük olduğunda. Sonsuz kaydırmalı sayfaların tam sayfa ekran görüntüleri, kimsenin açmayacağı devasa dosyalar oluşturur. Önemli olan bölgeyi kesip alın.

Metni kontrol ederken. Metni doğrulayın. expect(locator).toHaveText() okunabilir bir hata mesajı verir; piksel farkı ise size bir resim sunar.

Büyük ölçekte arşivlemeniz gerektiğinde. Ekran görüntüleri büyüktür ve birçok pazarda binlerce ekran görüntüsü, hem depolama alanında hem de bant genişliğinde yük oluşturur. Hash değerlerini veya farkları saklayın ve yalnızca bir değişiklik olduğunda tam görüntüleri saklayın.

Sık Sorulan Sorular

Playwright'ta ekran görüntüsü nasıl alınır? Görünüm alanı için

await page.screenshot({ path: 'shot.png' }), kaydırılabilir sayfanın tamamı için { fullPage: true } ve tek bir öğe için locator.screenshot() komutlarını kullanın. Dosya kaydetmek yerine arabelleğe almak istiyorsanız path ifadesini atlayın.

Tam sayfa ekran görüntüsünü nasıl alabilirim?

fullPage: true parametresini kullanın. Gecikmeli yüklenen içeriğin henüz gelmemiş olabileceğini ve sabitlenmiş öğelerin birleştirilmiş sonuçta garip davranabileceğini unutmayın — önce kasıtlı olarak kaydırın ve yakalama sırasında sabit konumlandırmayı etkisiz hale getirmek için style seçeneğini kullanın.

Tek bir öğenin ekran görüntüsünü nasıl alabilirim?

Sayfa yerine bir konum belirleyicide screenshot() işlevini çağırın: await page.getByTestId('card').screenshot({ path: 'card.png' }). Playwright, öğeyi görüş alanına getirir ve sınır kutusunu yakalar. overflow: hidden ile kırpılan içerik dahil edilmez.

Playwright ekran görüntülerinin çalıştırmalar arasında tutarlı olmasını nasıl sağlarım?

animations: 'disabled' ve caret: 'hide' ayarlarını yapın, değişken bölgeleri mask ile maskeleyin ve scale ayarını açıkça belirtin. Ardından, dört unsurun tümü mizanpajı etkilediği ve hiçbiri ekran görüntüsü seçeneği olmadığı için, görüntü alanı boyutunu, yerel ayarları, saat dilimini ve kullanılabilir yazı tiplerini sabitleyin.

Bir test başarısız olduğunda otomatik olarak ekran görüntüsü nasıl yakalayabilirim?

Playwright yapılandırmanızın use bloğunda screenshot: 'only-on-failure' ayarını yapın. Bunu trace: 'retain-on-failure' ile birleştirin — bir izleme, sadece hatayı göstermekle kalmayıp, hatanın nedenini açıklayan DOM anlık görüntülerini, ağ etkinliğini ve eylem zamanlamalarını içerir.

Ekran görüntüsünü dosya yerine base64 olarak alabilir miyim?

Evet. path seçeneğini atlayın; screenshot() bir tampon döndürür ve bunu buffer.toString('base64') ile dönüştürebilirsiniz. Belgelerde bu yöntem, sonradan işleme veya bir piksel farkı hizmetine aktarım için önerilmektedir; ayrıca geçici CI çalıştırıcılarında dosya sistemini kullanmayı önler.

Ekran görüntüsünden dinamik içeriği nasıl gizleyebilirim?

mask seçeneğini bir konum belirleyiciler dizisiyle kullanın; bu, söz konusu bölgeleri düz bir renkle değiştirir — maskColor varsayılan olarak #F0F değerine ayarlıdır ve değiştirilebilir. Zaman damgaları, oturum verileri veya reklamlar içeren sayfalarda görsel karşılaştırmayı bu şekilde kullanışlı hale getirebilirsiniz.

Bölgesel sayfaları görmek için bir proxy üzerinden ekran görüntüsü alabilir miyim?

Evet, bu da proxy'nin en iyi kullanım alanlarından biridir. Proxy'yi tarayıcı bağlamında ayarlayın ve locale ile timezoneId adreslerini ilgili ülkeye uygun şekilde ayarlayın — birçok site, adresten bağımsız olarak yerel ayarları kullanır. Ardından, IP sorgusuna güvenmek yerine, elde ettiğiniz görüntüyü inceleyerek bölgesel içeriğin gerçekten farklı olduğunu doğrulayın.

Sonuç

Playwright’ta ekran görüntüsü almak tek satırlık bir işlemdir. Ancak anlamlı bir ekran görüntüsü almak biraz daha fazla zaman alır.

Ekran görüntüsü bir kişinin bir kez bakması içinse — bir hata örneği, bir hata raporu, Brezilya'dan bir sayfanın nasıl göründüğünün kontrolü gibi — varsayılan ayarlar yeterlidir ve yapılandırmanızda screenshot: 'only-on-failure' satırı ekleyebileceğiniz en değerli satırdır. Bunu bir izleme ile birleştirin, çünkü izleme, ekran görüntüsünün sadece gösterdiği şeyi açıklar.

Ekran görüntüsü başka bir ekran görüntüsüyle karşılaştırılacaksa, her şey değişir. Animasyonları devre dışı bırakın, imleci gizleyin, değişken bölgeleri maskelemeyi unutmayın, ölçeği sabitleyin ve görüntüleme alanını, yerel ayarları, saat dilimini ve yazı tiplerini sabitleyin. Ardından, testlerin yürütüldüğü ortamda referans değerler oluşturun; çünkü yazı tipi görüntüleme platformlar arasında farklılık gösterir ve dizüstü bilgisayarınızdan alınan bir referans değer, bir konteynerle asla eşleşmez.

Coğrafi doğrulama içinse — ki bu, işlenmiş bir sayfanın yapılandırılmış verileri gerçekten geride bıraktığı noktadır — proxy'yi, yerel ayarları ve saat dilimini birlikte ayarlayın, ardından resme bakarak hedeflemenin işe yaradığını doğrulayın. Bant genişliği bir maliyettir, resimler ise engelleyemeyeceğiniz tek kaynak türüdür ve görsel doğrulamanın maliyeti de tam olarak budur.