Oyun sayfası çoktan yazılmış ve tarayıcıda açılıyor: tahta çiziliyor, taşlar hareket ediyor, "Yeni Oyun" düğmesi yerinde. Ama ajan bu sayfayı henüz hiç görmedi. Dosyaların metniyle çalıştı; tarayıcıyı siz başlattınız, siz baktınız ve ne olduğunu yine siz anlattınız. Playwright tam da bu boşluğu kapatıyor: ajan aynı sayfayı açıyor, gereken öğeyi buluyor, tıklıyor ve ardından neyin değiştiğini okuyor.
Aşağıda bu döngüyü bir satranç sayfası üzerinden adım adım ele alacağız: aç, gözlemle, öğeyi seç, işlem yap, yeni durumu oku. Sunucunun kurulumunu ve bağlantısını burada tekrarlamıyoruz. Playwright'ı henüz bağlamadıysanız talimatlar projenin README dosyasında.
İstediğiniz Sayfayı Açın
Connected yazısı neyi kanıtlar?
Yalnızca şunu: Claude Code, Playwright sunucusuyla bağlantı kurdu ve araç listesini aldı. Henüz hiçbir sayfa açılmadı; tarayıcı çalışmıyor bile olabilir. Connected yalnızca bağlantıyla ilgilidir; oyununuzun çalıştığını ve ajanın onu gördüğünü göstermez.
Mevcut durumu /mcp komutuyla görebilirsiniz: bağlı sunucuları ve her birinin neler yapabildiğini listeler. Asıl iş bundan sonra başlıyor. İlk gereken de sayfanın adresi.
Yerel oyun ya diskteki bir dosyada ya da yerel bir sunucuda çalışır. Böyle bir sunucunun portu her durumda aynı olmaz. 5173, 8000, 3000 - oyunu neyle başlattığınıza bağlı. Adresi gerçekten yazdırıldığı yerden alın: başlatma komutunun çıktısından ya da oyuna az önce baktığınız tarayıcının adres çubuğundan. Portu tahmin ederseniz boş bir sayfa ya da bambaşka bir proje açılabilir; araç yanıtından bunu anlamak her zaman kolay değildir.
Sayfayı açmak ayrı bir çağrıdır: browser_navigate. Tek bir parametresi vardır: url. Ajana vereceğiniz görev de gündelik bir dille şöyle olabilir:
Playwright ile http://localhost:5173/ adresini aç
ve açılan sayfanın başlığını göster.Açtıktan sonra iki şeyi doğrulayın: ajanın gerçekten gittiği adresi ve sayfanın başlığını. Bir saniye sürer, yanlış yerde yapılan bir dizi işlemi önler. Özellikle aynı anda birkaç yerel projeniz çalışıyorsa ve onlardan biri de localhost adresinde yanıt veriyorsa.
Playwright kendi tarayıcısını başlatır. Sekmeleriniz, eklentileriniz ve daha önce giriş yaptığınız hesaplar oraya taşınmaz: varsayılan olarak normal tarayıcınızdan ayrı bir profil kullanılır. Yerel oyun için bu hiçbir şeyi değiştirmez; ama "zaten giriş yaptığım siteyi açacak" beklentisi kendiliğinden karşılanmaz.
Ajan Sayfada Neleri Görür
Açık sayfayı üç farklı şekilde gözlemleyebilirsiniz; her biri bambaşka türde bilgi verir:
| Ne istiyoruz? | Araç | Yanıtta ne gelir? |
|---|---|---|
| Nasıl göründüğünü görmek | browser_take_screenshot | sayfanın görüntüsü |
| Nelerden oluştuğunu öğrenmek | browser_snapshot | öğelerin metin ağacı: roller, adlar ve öğe referansları |
| Belirli bir değeri okumak | browser_evaluate | sayfada hesaplanan küçük bir ifadenin sonucu |
Üç yol da aynı sayfadan başlar ama farklı veriler döndürür. Snapshot düğmeyi bulmaya yardımcı olur; data-turn değerini ayrıca okumak gerekir. Tahta görüntüsü, HTML özniteliklerini tek başına göstermez.
Ekran görüntüsü bir resimdir. "nasıl görünüyor" ve "nerede ne var" sorularını yanıtlar, ama browser_click için öğe referansı sağlamaz. Playwright MCP'nin temel modunda işlemler için erişilebilirlik snapshot'ı kullanılır. Koordinatla tıklama, ilgili araçlar etkinleştirildiyse ayrıca kullanılabilir.
Erişilebilirlik snapshot'ı tam olarak öğelerin açıklamasıdır. Resim değil, metindir: sayfanın hangi parçalardan oluştuğunu, rollerini (düğme, bağlantı, giriş alanı), adlarını ve daha sonra öğeye başvurmanızı sağlayan referansları listeler. Ajan bir yere tıklarken buna dayanır. Örneğin bir düğme kabaca şöyle görünür:
- button "Yeni Oyun" [ref=e12]
- button "Hamleyi Geri Al" [ref=e13]Bu, biçimi anlatan bir taslaktır; aracın gerçek çıktısı değildir. Kesin biçim sunucu sürümüne göre değişir, bu yazı için sunucuyu çalıştırmayacağız. Burada önemli olan noktalama değil: düğme ajana metinli bir dikdörtgen olarak değil, rolü, adı ve referansı olan bir satır olarak gelir.
En sık takılınan yere gelelim. Oyunumuzda sıranın kimde olduğunu gösteren data-turn etiketi erişilebilirlik snapshot'ında yer almaz. Snapshot, sayfanın işaretlemesinden değil, rollerden, adlardan, durumlardan ve öğe referanslarından oluşturulur. Herhangi bir data özniteliği bu listeye girmez. Sayfa bu değeri görünür metin olarak da yazdırıyorsa etiketin değeri snapshot'ta ayrıca görünebilir. Ama bu, sayfadaki metindir; özniteliğin okunmuş olduğu anlamına gelmez. İkisini karıştırmayın.
Bu tür değerler browser_evaluate aracıyla ayrı bir işlemde okunur. Sayfa bağlamında kısa bir ifade çalıştırır ve sonucu döndürür. Bu, yalnızca okumak değil, sayfada kod çalıştırmaktır; bu yüzden ajan bazen önce izin ister. İfadeyi ajan kendisi oluşturur, kabaca şöyle görünür:
// sıra etiketine sahip öğeyi bulup değerini döndür
() => document.querySelector('[data-turn]')?.getAttribute('data-turn') ?? nullErişilebilirlik snapshot'ı, sayfa işaretlemesinin tam kopyası değil, özetidir. Bir öğeyi tanıyıp tıklamanıza yarayan bilgiler vardır, ama her şey yoktur. Bu yüzden "ajan snapshot aldı" ve "ajan tüm öznitelikleri okudu" farklı iddialardır; ikincisi birincisinden çıkmaz.
Ajan Öğeyi Nasıl Seçer
Koordinatla tıklama neden bazen düğmeyi ıskalar?
Çünkü koordinatlar düğmeyi değil, ekrandaki bir noktayı tarif eder. Pencere genişletildi, kenar çubuğu daraltıldı, yazı boyutu değişti ya da sayfanın üstüne bir satır eklendi: nokta yerinde kalır, düğme kayar. Tıklama yine gerçekleşir, ama bu kez boş bir yere.
Bu yüzden temel seçim yöntemi farklıdır. browser_click aracında burada önemli iki alan var: element, ajanın nereye tıklayacağını anlamanızı sağlayan "Yeni Oyun düğmesi" gibi okunabilir bir açıklama; target ise snapshot'tan alınan bir öğe referansı ya da benzersiz bir seçicidir. Burada snapshot referansıyla seçimi ele alacağız. Referans, alındığı snapshot'a bağlıdır ve tıklama tam o öğeye gider. Metin girişi de aynı şekilde işler; yalnızca aracın adı browser_type olur ve öğe açıklamasına metnin kendisi eklenir.
Burada kalıcı olan referansın kendisi değil, öğeyi bulma yöntemidir. Rol ve ad genellikle sabit bir ikilidir: tasarımcı düğmeyi ekranın öbür köşesine taşısa da "Yeni Oyun" düğmesi yine "Yeni Oyun" düğmesi olarak kalır. Ajan her yeni snapshot'ta bu ikiliyle öğeyi yeniden bulur ve güncel referansı alır. Yazıda "işlemden sonra yeniden bakın" kuralının tekrarlanma nedeni de bu.
Tahtadaki kareleri seçmek daha zordur: 64 kare var ve hepsinin rolü aynı. Uygulamanın verdiği etiket burada işe yarar. Karenin e2 veya e4 gibi kendi adı varsa doğru kareyi seçebilirsiniz. Snapshot'taki karelerin tümü isimsizse, yalnızca rol ve ada bakarak gerekeni seçemezsiniz. Karenin işaretlemesinde başka bir ayırt edici özellik olup olmadığını kontrol edin ya da kullanılabilen koordinat araçlarından yararlanın.
Playwright MCP'de koordinat araçları da var, ama standart yapılandırmada kapalıdır ve ayrıca açılmaları gerekir. Örneğin canvas üzerindeki bir öğeye başka türlü erişilemiyorsa kullanılabilirler. Standart yapılandırmada bu araçlar olmadığına göre, yalnızca görüntüye bakarak işlem yapmanın gerçekten bir yolu yok. Bölümün başındaki ekran görüntüsü uyarısı tam olarak bunu anlatıyordu.
İşlem ve Yeni Durum
Soldaki ok döngüyü tamamlar: ajan bir sonraki işlemden önce sayfanın güncel açıklamasını kullanır. Önceki işlemin yanıtında güncel bir snapshot varsa ona dayanabilirsiniz. Tıklamanın gerçekleşmiş olması, istenen değişikliğin yapıldığını henüz kanıtlamaz.
Hepsini ajana tek seferde verebileceğiniz bir akışta birleştirelim. Beş adım var ve her adımdan sonra ne görmeniz gerektiği belli. Akış, tahtadaki karelerin önceki bölümdeki e2 ve e4 gibi etiketlere sahip olduğunu varsayıyor. Etiket yoksa 4. adımda kareleri kesin olarak seçmek için başka bir yöntem gerekir.
| Adım | Ajan ne yapar? | Ne görünür? |
|---|---|---|
| 1 | oyunun adresini açar | sayfa başlığı, tahta yerinde |
| 2 | "Yeni Oyun" düğmesine tıklar | taşlar başlangıç konumunda |
| 3 | data-turn değerini okur | white |
| 4 | sayfanın arayüzünden e2-e4 hamlesini yapar | piyon iki kare ilerler |
| 5 | data-turn değerini ve e4 karesindeki taşı okur | black, e4'te beyaz piyon |
Solda başlangıç durumu, sağda hamleden sonra beklenen sonuç var. Alttaki kutu ikisini bir kontrolle bağlar: ajan sıra etiketini ve taşların konumunu yeniden okur, sonra değerleri karşılaştırır. Hareketi daha eksiksiz doğrulamak için başlangıç karesi e2'nin boşaldığını da kontrol edin. white değerinin black olması, piyonun gerçekten e4'e gittiğini tek başına kanıtlamaz.
data-turn hakkında açık konuşalım: bu, belirli bir uygulamanın kararıdır. Sayfanın yazarı bu etiketi eklemeyi seçtiği için onu okuyabiliyoruz. Playwright etiketi oluşturmaz, başka bir yerden de almaz; yalnızca sayfada zaten bulunan veriyi çıkarabilir. Böyle bir etiket eklenmemiş başka bir sayfada bu yöntem çalışmaz ve gözle görülebilen bilgilere dayanmanız gerekir.
Her işlemden sonra uyulacak temel kural şu: durumu yeniden okuyun. Tıklamadan önce alınan snapshot, ne kadar güncel görünürse görünsün, sayfanın tıklama öncesindeki hâlini anlatır. Tahta yeniden çizildikten sonra bu snapshot'taki öğe referansları geçersiz kalabilir; tıklamadan önce okunan data-turn değeri de değişmiş olabilir. İşlemi yapın, sonra tekrar bakın.
Uygulama gereken değeri vermediyse ajanın doğru yanıtı "Okuyamadım, sayfada böyle bir öznitelik yok" olmalıdır. Hamlenin yapılmış gibi görünmesinden çıkarılan makul bir black, gerçekten okunmuş bir değerle aynı görünür ama hiçbir şeyi kanıtlamaz. Özet yerine okunan değerlerin kendisini göstermesini isteyin.
İşlem Başarısız Olduğunda
En sık karşılaşılan sorun "öğe bulunamadı" mesajıdır. Şu kısa sırayla inceleyin:
- doğru sayfanın açık olduğunu kontrol edin. Adres ve başlık, en başta kontrol ettiğiniz iki şey;
- sayfanın hazır olduğundan emin olun. Oyun henüz yüklenmemiş, düğme de istekten bir saniye sonra belirmiş olabilir;
- güncel bir snapshot alın. Konuşmada zaten duran değil, yeni bir snapshot;
- bu snapshot'taki güncel açıklamaya göre öğeyi yeniden seçin ve işlemi tekrarlayın.
Olası nedenlerden biri üçüncü adımda ortaya çıkar: öğe hâlâ sayfadadır ama referansı eskimiştir.
İnceleme sırasında ekran görüntüsü de işe yarar, ama her sorunu çözen bir araç olarak değil. "Sayfa nasıl görünüyor, öğeler nerede?" sorularını yanıtlar. Örneğin tahtanın boş çizildiğini veya üstünde bir modal pencere açıldığını gösterebilir. Sıra bilgisi sayfada metin olarak gösteriliyorsa ekran görüntüsünde onu da görürsünüz. Ancak data-turn özniteliğinin kesin değerini yalnızca onu okuyarak doğrulayabilirsiniz. Bunlar iki ayrı soru ve iki ayrı araçtır; birbirine karıştırırsanız görüntüye bakıp veri hakkında tartışmaya başlarsınız.
Bu, Çalışma Şeklini Nasıl Değiştirir
Ajana verilen görev, tıklama listesinden kontrol noktaları olan bir akışa dönüşür. Ele aldığımız örnek tek bir metinde şöyle görünür:
Playwright ile http://localhost:5173/ adresini aç.
1) "Yeni Oyun" düğmesine tıkla;
2) data-turn değerini oku ve göster;
3) sayfanın arayüzünden e2-e4 hamlesini yap;
4) data-turn değerini ve e4 karesindeki taşı yeniden oku.
Bu değerlerden biri sayfada yoksa bunu söyle
ve kendin bir değer uydurma.Aklınızda tutmanız gerekenler:
- adres tahmini değil, başlatma çıktısından alınmış gerçek adres olmalı;
- görevde "oku ve göster" ifadeleri yer almalı. Yoksa elinizde yalnızca sonucun anlatımı kalır;
- durumlar işlemden önce ve sonra bir çift olarak gösterilir. Başlangıçta ne olduğu bilinmediğinden, sondaki tek değer bir şey kanıtlamaz;
- snapshot, ekran görüntüsü ve öznitelik okuma farklı soruları yanıtlar. Bunları alışkanlığa göre değil, soruya göre seçin;
- bir eğitim akışı yeterlidir. e2-e4 hamlesinin yapılmış olması, oyunun geri kalanının kurallara uygun süreceğini göstermez. Bu, ayrı ve çok daha kapsamlı bir kontroldür.
Şöyle akılda tutmak kolay: tarayıcı ajana el ve göz verir, ama hazır sonuçlar sunmaz. Ajan sayfayı kendisi açabilir, tıklayabilir ve değeri okuyabilir; o değerin ne anlama geldiğine ise yine siz karar verirsiniz.
Araç adları ve parametreleri 19 Eylül 2026'da Playwright MCP README dosyasına göre kontrol edildi; sürümler arasında değişebilir. Genel sıra aynı kalır: aç, gözlemle, öğeyi seç, işlem yap, yeniden oku.
GO TO FULL VERSION