Stránka s hrou je hotová a otevírá se v prohlížeči: vykreslí se šachovnice, figurky se pohybují a tlačítko "Nová hra" je na svém místě. Jenže agent tu stránku ještě nikdy neviděl. Pracoval s textem souborů, zatímco prohlížeč jste spouštěli vy, dívali jste se do něj vy a také jste mu popisovali, co se stalo. Playwright právě tuhle mezeru zaplňuje: agent otevře stejnou stránku, najde na ní potřebný prvek, klikne na něj a přečte, co se změnilo.
Ukážeme si celý postup na příkladu šachové stránky: otevřít ji, prohlédnout, vybrat prvek, provést akci a přečíst nový stav. Instalaci ani připojení serveru tu neopakujeme. Pokud Playwright ještě nemáte připojený, návod najdete v README projektu.
Otevřete správnou stránku
Co dokazuje nápis Connected?
Jedinou věc: Claude Code se spojil se serverem Playwright a získal od něj seznam nástrojů. Žádná stránka přitom ještě není otevřená a prohlížeč možná ani neběží. Connected označuje připojení, nikoli to, že vaše hra funguje a agent ji vidí.
Aktuální stav můžete zobrazit příkazem /mcp: vypíše připojené servery a jejich možnosti. Pak začíná skutečná práce. Nejdřív potřebujete adresu stránky.
Lokální hra může být soubor na disku nebo stránka na lokálním serveru. Port takového serveru není vždy stejný. 5173, 8000 nebo 3000 - záleží na tom, jak jste hru spustili. Adresu vezměte z místa, kde se opravdu vypíše: z výstupu spouštěcího příkazu nebo z adresního řádku prohlížeče, ve kterém jste si hru právě prohlíželi. Když port jen odhadnete, může se otevřít prázdná stránka nebo úplně jiný projekt. Z odpovědi nástroje to přitom nemusí být hned zřejmé.
Otevření stránky je samostatné volání browser_navigate s jediným parametrem url. Zadání pro agenta může znít docela obyčejně:
Otevři přes Playwright http://localhost:5173/
a ukaž titulek stránky, která se otevřela.Po otevření zkontrolujte dvě věci: adresu, na kterou agent skutečně přešel, a titulek stránky. Zabere to vteřinu, ale ušetří celou řadu akcí na nesprávném místě. Zvlášť když vám vedle toho běží ještě několik lokálních projektů a jeden z nich také odpovídá na localhost.
Playwright spustí vlastní prohlížeč. Vaše panely, rozšíření ani přihlášení k účtům se do něj nepřenesou: ve výchozím nastavení používá samostatný profil oddělený od vašeho běžného prohlížeče. U lokální hry to nic nemění, ale samotné očekávání "otevře přece stránku, kde jsem přihlášený" se nenaplní automaticky.
Co agent na stránce vidí
Otevřenou stránku můžete prohlédnout třemi způsoby. Každý z nich vrací něco jiného:
| Co potřebujeme | Nástroj | Co vrátí |
|---|---|---|
| Vidět, jak stránka vypadá | browser_take_screenshot | obrázek stránky |
| Zjistit, z čeho se skládá | browser_snapshot | textový strom prvků: role, názvy a odkazy na prvky |
| Přečíst konkrétní hodnotu | browser_evaluate | výsledek krátkého výrazu vypočteného přímo na stránce |
Všechny tři možnosti začínají na stejné stránce, ale vracejí odlišné údaje. Snapshot pomůže najít tlačítko, hodnotu data-turn je ale třeba načíst zvlášť. Samotný obrázek šachovnice její HTML atributy neukáže.
Snímek obrazovky je obrázek. Skvěle odpoví na otázky "jak to vypadá" a "co je kde umístěné", ale sám o sobě neposkytne odkaz na prvek pro browser_click. V základním režimu Playwright MCP se k akcím používá snapshot přístupnosti. Klikání podle souřadnic je dostupné zvlášť, pokud zapnete příslušné nástroje.
Snapshot přístupnosti je právě popis prvků. Není to obrázek, ale textový seznam toho, z čeho se stránka skládá, včetně rolí (tlačítko, odkaz, vstupní pole), názvů a odkazů, přes které lze prvek později najít. Právě z něj agent vychází, když na něco kliká. Zjednodušeně může jedno tlačítko v něm vypadat třeba takto:
- button "Nová hra" [ref=e12]
- button "Vrátit tah" [ref=e13]Je to ukázka tvaru, ne skutečný výstup nástroje: přesný formát závisí na verzi serveru a kvůli článku ho spouštět nebudeme. Důležitá není interpunkce, ale to, že tlačítko agent dostane jako řádek s rolí, názvem a odkazem, ne jako obdélník s textem.
A teď místo, na kterém se lidé nejčastěji zarazí. Značka data-turn, podle které naše hra ukazuje, kdo je na tahu, se do snapshotu přístupnosti nedostane: ten se skládá z rolí, názvů, stavů a odkazů na prvky, nikoli z kódu stránky. Libovolný atribut data do něj nepatří. Hodnota značky se přesto může ve snapshotu objevit zvlášť, pokud ji stránka vypisuje jako viditelný text. To je ale text na stránce, ne přečtený atribut; jedno za druhé nezaměňujte.
Takové hodnoty se načítají zvlášť pomocí nástroje browser_evaluate. Spustí krátký výraz v kontextu stránky a vrátí výsledek. To už znamená spuštění kódu na stránce, nikoli pouhé čtení, takže agent si někdy předem vyžádá svolení. Výraz sestaví sám, může vypadat třeba takto:
// najít prvek se značkou tahu a vrátit její hodnotu
() => document.querySelector('[data-turn]')?.getAttribute('data-turn') ?? nullSnapshot přístupnosti je výběr informací, ne úplná kopie kódu stránky. Obsahuje údaje, podle kterých lze prvek rozpoznat a kliknout na něj, ale zdaleka ne všechno. Výroky "agent pořídil snapshot" a "agent přečetl všechny atributy" tedy znamenají různé věci. To druhé z prvního nevyplývá.
Jak agent vybírá prvek
Proč kliknutí podle souřadnic někdy mine tlačítko?
Souřadnice popisují bod na obrazovce, ne tlačítko. Roztáhnete okno, sbalíte postranní panel, změníte velikost písma nebo se nahoře na stránce objeví nový řádek. Bod zůstane na místě, ale tlačítko se posune. Kliknutí přitom proběhne bez chyby - jen do prázdného místa.
Proto je hlavní způsob výběru jiný. Nástroj browser_click má dvě důležitá pole: element je srozumitelný popis, třeba "tlačítko Nová hra", díky kterému víte, kam agent chce kliknout; target je odkaz na prvek ze snapshotu nebo jednoznačný selektor. Tady si ukážeme výběr podle odkazu ze snapshotu. Odkaz platí pro snapshot, ze kterého pochází, a kliknutí zamíří právě na daný prvek. Zadávání textu funguje podobně, jen se používá nástroj browser_type a k popisu prvku se přidá samotný text.
Stabilní není samotný odkaz, ale způsob, jak prvek najít. Role a název tvoří poměrně stálou dvojici: tlačítko "Nová hra" zůstane tlačítkem "Nová hra", i když ho designér přesune na druhý konec obrazovky. Agent podle této dvojice najde prvek v každém novém snapshotu a získá čerstvý odkaz. Proto článek opakuje pravidlo "po akci se podívejte znovu".
U políčka šachovnice je to složitější: je jich 64 a z hlediska role jsou stejná. Pomůže značka, kterou poskytuje samotná aplikace. Má-li políčko vlastní název, například e2 nebo e4, lze ho přesně vybrat. Pokud jsou všechna políčka ve snapshotu bez názvu, podle samotné role a názvu správné nevyberete. Ověřte, jestli má políčko jiný jednoznačný znak v kódu stránky, případně použijte dostupné nástroje pro klikání podle souřadnic.
Nástroje pro práci se souřadnicemi Playwright MCP také nabízí, v běžné konfiguraci jsou ale vypnuté a zapínají se zvlášť. Hodí se, když prvek nelze získat jinak, například na canvasu. Když v běžné konfiguraci nejsou k dispozici, podle pouhého obrázku agent opravdu nemá jak jednat. Přesně na to upozorňovala poznámka o snímku obrazovky výše.
Akce a nový stav
Šipka vlevo cyklus uzavírá: před další akcí agent použije aktuální popis stránky. Pokud odpověď na předchozí akci už obsahuje nový snapshot, můžete vycházet z něj. Samotné provedení kliknutí ještě nepotvrzuje, že se stránka změnila podle očekávání.
Složme vše do jednoho postupu, který můžete zadat najednou. Má pět kroků a po každém je jasné, co má být vidět. Počítá s tím, že políčka na naší šachovnici mají názvy - ta e2 a e4 z předchozí části. Bez nich bude pro čtvrtý krok potřeba jiný způsob, jak políčka jednoznačně vybrat.
| Krok | Co agent udělá | Co bude vidět |
|---|---|---|
| 1 | otevře adresu hry | titulek stránky, šachovnice na místě |
| 2 | klikne na tlačítko "Nová hra" | figurky ve výchozím postavení |
| 3 | načte data-turn | white |
| 4 | provede tah e2-e4 přes rozhraní stránky | pěšec postoupil o dvě pole |
| 5 | znovu načte data-turn a zjistí, co stojí na e4 | black, na e4 bílý pěšec |
Vlevo je původní stav, vpravo očekávaný výsledek tahu. Spodní blok oba stavy propojuje ověřením: agent znovu načte značku tahu i pozice figurek a pak hodnoty porovná. Chcete-li ověřit tah důkladněji, zkontrolujte také, že se pole e2 uvolnilo. Samotná změna white na black ještě nepotvrzuje, že pěšec skončil právě na e4.
U data-turn je dobré říct to jasně: jde o dohodu konkrétní aplikace. Autor stránky se rozhodl tuto značku nastavovat, a proto ji lze přečíst. Playwright ji nevytváří ani odnikud nezískává, umí pouze načíst to, co už na stránce je. Na cizí stránce bez této značky tenhle postup fungovat nebude. Budete se muset opřít o to, co je vidět.
A hlavní pravidlo po každé akci zní: stav načtěte znovu. Snapshot pořízený před kliknutím popisuje stránku před kliknutím, ať působí jakkoli aktuálně. Odkazy na prvky po překreslení šachovnice už nemusí nikam vést a mohla se změnit i hodnota data-turn, kterou jste načetli před kliknutím. Provedli jste akci? Podívejte se znovu.
Pokud aplikace požadovanou hodnotu neposkytla, správná odpověď agenta zní: "nepodařilo se ji načíst, tento atribut na stránce není". Věrohodně vypadající hodnota black, odvozená z toho, že tah nejspíš proběhl, vypadá stejně jako skutečně načtená hodnota, ale nic nedokazuje. Požádejte agenta, aby ukázal přímo načtené hodnoty, ne jejich převyprávění.
Když se akce nepodaří
Nejčastější problém zní "prvek nebyl nalezen". Projděte krátký seznam:
- ověřte, že je otevřená správná stránka. Zkontrolujte adresu a titulek, tedy stejné dvě věci jako na začátku;
- ujistěte se, že je stránka připravená. Hra se ještě mohla načítat a tlačítko se mohlo objevit až chvíli po požadavku;
- pořiďte nový snapshot. Ne ten, který už máte v konverzaci, ale opravdu nový;
- vyberte prvek znovu podle aktuálního popisu v novém snapshotu a akci opakujte.
Jednu z možných příčin najdete ve třetím kroku: prvek je na stránce pořád, ale jeho odkaz už není aktuální.
Snímek obrazovky se při analýze také hodí, ale ne jako univerzální řešení. Odpovídá na otázku "jak stránka vypadá a co je kde umístěné" - ukáže třeba prázdnou šachovnici nebo vyskakovací okno. Pokud stránka ukazuje textem, kdo je na tahu, uvidíte to i na snímku obrazovky. Přesnou hodnotu atributu data-turn ale potvrdí pouze jeho načtení. Jde o dvě různé otázky a dva různé nástroje. Když si je spletete, budete nad obrázkem diskutovat o údajích, které z něj nelze zjistit.
Jak to mění způsob práce
Zadání pro agenta už není seznam kliknutí, ale postup s kontrolními body. Tady je celý příklad pohromadě:
Otevři přes Playwright http://localhost:5173/.
1) klikni na "Nová hra";
2) načti data-turn a ukaž jeho hodnotu;
3) proveď tah e2-e4 přes rozhraní stránky;
4) znovu načti data-turn a zjisti, jaká figurka je na e4.
Pokud některá z těchto hodnot na stránce chybí, řekni to
a nic za ni nedoplňuj.Co je dobré mít na paměti:
- adresa musí být skutečná, převzatá z výstupu spuštění, ne odhadnutá;
- zadání obsahuje pokyny "načti a ukaž" - bez nich dostanete jen popis výsledku;
- stavy porovnávejte před akcí a po ní. Jedna hodnota na konci nic nedokazuje, protože nevíte, jaká byla na začátku;
- snapshot, snímek obrazovky a načtení atributu odpovídají na různé otázky. Vybírejte nástroj podle otázky, ne ze zvyku;
- pro začátek stačí jeden cvičný postup. Provedený tah e2-e4 neznamená, že celá partie dál proběhne podle pravidel. To by vyžadovalo samostatnou a mnohem důkladnější kontrolu.
Nejjednodušší je zapamatovat si to takto: prohlížeč dá agentovi ruce a oči, ale hotové závěry za něj neudělá. Stránku může sám otevřít, kliknout a přečíst hodnotu. Co tato hodnota znamená, ale musíte posoudit vy.
Názvy nástrojů a jejich parametry jsme ověřili 19. září 2026 v README Playwright MCP. Mohou se měnit podle verze. Obecný postup - otevřít, prohlédnout, vybrat prvek, provést akci a znovu načíst stav - zůstává stejný.
GO TO FULL VERSION