Stránka s hrou je hotová a otvára sa v prehliadači: doska sa vykresľuje, figúrky sa hýbu a tlačidlo "Nová partia" je na svojom mieste. Lenže samotný agent túto stránku ešte ani raz nevidel. Pracoval s textom súborov, no prehliadač ste spustili vy, pozerali ste sa doň vy a aj to, čo sa stalo, ste mu opisovali vy. Playwright zapĺňa práve túto medzeru: agent otvorí tú istú stránku, nájde na nej potrebný prvok, klikne naň a prečíta, čo sa potom zmenilo.
Nižšie si tento cyklus prejdeme krok za krokom na príklade šachovej stránky: otvoriť ju, pozrieť sa, vybrať prvok, vykonať akciu a prečítať nový stav. Inštaláciu ani pripojenie servera tu neopakujeme. Ak Playwright ešte nemáte pripojený, návod nájdete v README projektu.
Otvorte správnu stránku
Čo dokazuje nápis Connected?
Len jedno: Claude Code sa spojil so serverom Playwright a dostal od neho zoznam nástrojov. Zatiaľ nie je otvorená ani jedna stránka a je dosť možné, že prehliadač ešte ani nie je spustený. Connected hovorí o spojení, nie o tom, že vaša hra funguje a agent ju vidí.
Aktuálny stav si môžete pozrieť príkazom /mcp: vypíše pripojené servery a to, čo každý z nich dokáže. Potom sa začína skutočná práca. Ako prvú potrebujete adresu stránky.
Lokálna hra môže byť súborom na disku alebo bežať na lokálnom serveri. Port takého servera nie je vždy rovnaký. 5173, 8000, 3000 - závisí od toho, ako ste hru spustili. Adresu vezmite odtiaľ, kde sa naozaj vypísala: z výstupu príkazu na spustenie alebo z adresného riadka prehliadača, v ktorom ste si hru práve pozerali. Ak port iba odhadnete, môže sa otvoriť prázdna stránka alebo úplne iný projekt. Z odpovede nástroja to nemusí byť vždy zrejmé.
Otvorenie stránky je samostatné volanie browser_navigate s jediným parametrom url. Zadanie pre agenta pritom môže znieť celkom obyčajne:
Otvor http://localhost:5173/ cez Playwright
a ukáž titulok otvorenej stránky.Po otvorení skontrolujte dve veci: adresu, ktorú agent naozaj navštívil, a titulok stránky. Zaberie to sekundu a ušetrí celú sériu akcií vykonaných inde. Hodí sa to najmä vtedy, keď vám súčasne beží niekoľko lokálnych projektov a jeden z nich tiež odpovedá na localhost.
Playwright spustí vlastný prehliadač. Vaše karty, rozšírenia ani už prihlásené účty sa doň neprenesú: predvolene používa samostatný profil, oddelený od vášho bežného prehliadača. Pri lokálnej hre to nič nemení, ale očakávanie, že "otvorí stránku, kde som prihlásený", sa nemusí splniť samo od seba.
Čo agent vidí na stránke
Otvorenú stránku možno preskúmať tromi rôznymi spôsobmi. Každý z nich poskytne niečo iné:
| Čo chceme | Nástroj | Čo dostaneme v odpovedi |
|---|---|---|
| Vidieť, ako vyzerá | browser_take_screenshot | obrázok stránky |
| Zistiť, z čoho sa skladá | browser_snapshot | textový strom prvkov: roly, názvy, odkazy na prvky |
| Prečítať konkrétnu hodnotu | browser_evaluate | výsledok krátkeho výrazu vypočítaného priamo na stránke |
Všetky tri možnosti začínajú na tej istej stránke, ale vracajú odlišné údaje. Snímka prístupnosti pomôže nájsť tlačidlo, no hodnotu data-turn treba prečítať zvlášť. Samotný obrázok dosky neodhaľuje jej HTML atribúty.
Snímka obrazovky je obrázok. Výborne odpovedá na otázky "ako to vyzerá" a "čo sa kde nachádza", sama však neposkytne odkaz na prvok pre browser_click. V základnom režime Playwright MCP sa na vykonávanie akcií používa snímka prístupnosti. Klikanie podľa súradníc je dostupné osobitne, ak zapnete príslušné nástroje.
Snímka prístupnosti je opis prvkov. Nie obrázok, ale text: zoznam toho, z čoho sa stránka skladá, s rolami (tlačidlo, odkaz, vstupné pole), názvami a odkazmi, pomocou ktorých sa dá na prvok neskôr odkázať. Agent sa o ňu opiera, keď niekam kliká. Zjednodušene môže jedno tlačidlo v snímke vyzerať približne takto:
- button "Nová partia" [ref=e12]
- button "Vrátiť ťah" [ref=e13]Toto je ukážka formátu na vysvetlenie, nie skutočný výstup nástroja. Presný formát závisí od verzie servera a spúšťať nástroj kvôli článku nebudeme. Dôležitá nie je interpunkcia, ale to, že agent dostane tlačidlo ako riadok s rolou, názvom a odkazom, nie ako obdĺžnik s textom.
A teraz miesto, na ktorom sa ľudia najčastejšie zaseknú. Značka data-turn, podľa ktorej v našej hre vidno, kto je práve na ťahu, sa v snímke prístupnosti neobjaví: tá sa tvorí z rolí, názvov, stavov a odkazov na prvky, nie zo značkovania stránky. Ľubovoľný atribút data do tohto zoznamu nepatrí. Jeho hodnota sa však môže v snímke objaviť ako viditeľný text, ak ju stránka vypisuje. Vtedy ide o text na stránke, nie o prečítaný atribút, a tieto dve veci si netreba zamieňať.
Takéto hodnoty sa čítajú osobitnou operáciou pomocou nástroja browser_evaluate. Vykoná krátky výraz v kontexte stránky a vráti výsledok. To už znamená spustenie kódu na stránke, nie iba čítanie, preto si agent niekedy pred akciou vypýta povolenie. Výraz zostaví sám, no môže vyzerať približne takto:
// nájde prvok so značkou ťahu a vráti jej hodnotu
() => document.querySelector('[data-turn]')?.getAttribute('data-turn') ?? nullSnímka prístupnosti je výťah, nie úplná kópia značkovania stránky. Obsahuje informácie, podľa ktorých možno rozpoznať a stlačiť prvok, ale nie všetko. Preto "agent vytvoril snímku" a "agent prečítal všetky atribúty" sú dve odlišné tvrdenia. To druhé z prvého nevyplýva.
Ako agent vyberá prvok
Prečo kliknutie podľa súradníc niekedy minie tlačidlo?
Súradnice totiž označujú bod na obrazovke, nie tlačidlo. Zväčšíte okno, skryjete bočný panel, zmeníte veľkosť písma alebo stránka pridá hore riadok - bod zostane na mieste, ale tlačidlo sa posunie. Kliknutie sa pritom bez chyby vykoná, len do prázdneho miesta.
Preto je hlavný spôsob výberu iný. Nástroj browser_click má dve dôležité polia: element je zrozumiteľný opis, napríklad "tlačidlo Nová partia", podľa ktorého vidíte, kam agent plánuje kliknúť, a target je odkaz na prvok zo snímky alebo jedinečný selektor. Tu si ukážeme výber podľa odkazu zo snímky. Odkaz patrí k snímke, z ktorej pochádza, a kliknutie sa vykoná práve na danom prvku. Podobne funguje aj zadávanie textu, len sa nástroj volá browser_type a spolu s opisom prvku dostane aj samotný text.
Stabilný nie je samotný odkaz, ale spôsob, akým prvok nájdeme. Rola a názov tvoria pomerne stálu dvojicu: tlačidlo "Nová partia" zostane tlačidlom "Nová partia", aj keď ho dizajnér presunie na druhý okraj obrazovky. Agent podľa tejto dvojice nájde prvok v každej novej snímke a získa čerstvý odkaz. Preto sa v článku opakuje pravidlo "po akcii sa pozrite znova".
Pri políčkach na šachovnici je to zložitejšie: je ich 64 a všetky majú rovnakú rolu. Pomôže označenie z aplikácie. Ak má políčko vlastný názov, napríklad e2 alebo e4, možno ho presne vybrať. Ak sú všetky políčka v snímke bez názvu, iba podľa roly a názvu to nepôjde. Vtedy treba overiť, či má políčko v značkovaní stránky inú jednoznačnú vlastnosť, alebo použiť dostupné nástroje pracujúce so súradnicami.
Nástroje na prácu so súradnicami sú v Playwright MCP tiež dostupné, no v bežnej zostave sú vypnuté a zapínajú sa osobitne. Hodí sa to vtedy, keď sa k prvku nedá dostať inak, napríklad na canvase. Keďže v bežnej zostave nie sú zapnuté, samotný obrázok na akciu nestačí. Presne na to upozorňovala zmienka o snímke obrazovky vyššie.
Akcia a nový stav
Šípka vľavo uzatvára cyklus: pred ďalšou akciou agent použije aktuálny opis stránky. Ak odpoveď na predchádzajúcu akciu už obsahuje novú snímku, môžete vychádzať z nej. Samotné vykonanie kliknutia ešte nepotvrdzuje, že sa stránka zmenila podľa očakávania.
Poskladajme to do jedného postupu, ktorý môžete zadať celý naraz. Má päť krokov a po každom je jasné, čo by malo byť viditeľné. Počíta s tým, že políčka na našej doske majú označenia e2 a e4 z predchádzajúcej časti. Ak chýbajú, pri kroku 4 bude treba inak jednoznačne vybrať políčka.
| Krok | Čo agent urobí | Čo uvidíme |
|---|---|---|
| 1 | otvorí adresu hry | titulok stránky, doska je zobrazená |
| 2 | klikne na tlačidlo "Nová partia" | figúrky sú v základnom postavení |
| 3 | prečíta data-turn | white |
| 4 | urobí ťah e2-e4 cez rozhranie stránky | pešiak sa posunie o dve políčka |
| 5 | znova prečíta data-turn a obsah políčka e4 | black, na e4 je biely pešiak |
Vľavo vidíte pôvodný stav, vpravo očakávaný výsledok ťahu. Spodný blok ich prepája kontrolou: agent znovu prečíta značku ťahu aj polohu figúrok a potom hodnoty porovná. Pre dôkladnejšiu kontrolu treba overiť aj to, že sa políčko e2 uvoľnilo. Samotná zmena white na black ešte nepotvrdzuje, že pešiak skončil práve na e4.
Pri data-turn treba povedať jednu vec priamo: ide o dohodu konkrétnej aplikácie. Autor stránky sa rozhodol nastaviť takúto značku, preto ju možno prečítať. Playwright ju nevytvára ani nikde nehľadá. Vie len získať to, čo už na stránke je. Na cudzej stránke bez tejto značky tento postup nebude fungovať a budete sa musieť oprieť o to, čo vidíte.
A hlavné pravidlo po každej akcii: stav si prečítajte znova. Snímka vytvorená pred kliknutím opisuje stránku pred kliknutím, nech sa zdá akokoľvek aktuálna. Odkazy na prvky po prekreslení dosky už nemusia nikam viesť a mohla sa zmeniť aj osobitne prečítaná hodnota data-turn. Vykonali ste akciu? Pozrite sa znova.
Ak aplikácia nevrátila potrebnú hodnotu, správna odpoveď agenta znie: "nepodarilo sa ju prečítať, tento atribút na stránke nie je". Vierohodne pôsobiace black, odvodené z toho, že ťah zrejme prebehol, vyzerá rovnako ako skutočne prečítaná hodnota, ale nedokazuje vôbec nič. Požiadajte agenta, aby ukázal priamo prečítané hodnoty, nie ich prerozprávanie.
Keď sa akcia nepodarí
Najčastejšia chyba znie "prvok sa nenašiel". Skúste tento krátky postup:
- skontrolujte, či je otvorená správna stránka. Overte adresu a titulok, rovnako ako na začiatku;
- uistite sa, že sa stránka načítala. Hra sa možno ešte načítava a tlačidlo sa objaví až chvíľu po požiadavke;
- vytvorte novú snímku. Nie tú, ktorá už je v konverzácii, ale aktuálnu;
- znova vyberte prvok podľa aktuálneho opisu v snímke a zopakujte akciu.
Jednu z možných príčin odhalíte v treťom kroku: prvok je stále na stránke, ale odkaz naň už nie je aktuálny.
Snímka obrazovky pomôže aj pri hľadaní príčiny, no nie je univerzálnym riešením. Odpovie na otázku "ako stránka vyzerá a čo sa kde nachádza" - napríklad ukáže prázdnu dosku alebo modálne okno, ktoré ju prekrýva. Ak stránka ukazuje textom, kto je na ťahu, uvidíte to aj na snímke obrazovky. Presnú hodnotu atribútu data-turn však potvrdí iba jeho prečítanie. Sú to dve rôzne otázky a dva rôzne nástroje. Ak si ich pomýlite, budete sa pozerať na obrázok a dohadovať sa o údajoch.
Ako to mení spôsob práce
Zadanie pre agenta už nie je zoznam kliknutí, ale postup s kontrolnými bodmi. Tu je celý postup, ktorý sme si ukázali:
Otvor http://localhost:5173/ cez Playwright.
1) klikni na "Nová partia";
2) prečítaj data-turn a ukáž hodnotu;
3) urob ťah e2-e4 cez rozhranie stránky;
4) znova prečítaj data-turn a to, čo je na e4.
Ak niektorá z týchto hodnôt na stránke nie je, povedz to
a nedopĺňaj ju sám.Majte na pamäti niekoľko vecí:
- adresa musí byť skutočná, prevzatá z výstupu spustenia, nie iba odhadnutá;
- zadanie obsahuje pokyn "prečítaj a ukáž" - bez neho dostanete iba opis výsledku;
- stav sa ukazuje v dvojici, pred akciou aj po nej. Samotná konečná hodnota nič nedokazuje, keď nevieme, aká bola na začiatku;
- snímka prístupnosti, snímka obrazovky a prečítanie atribútu odpovedajú na odlišné otázky. Vyberajte nástroj podľa toho, čo chcete zistiť, nie zo zvyku;
- na učenie stačí jeden takýto postup. To, že ťah e2-e4 prebehol, neznamená, že celá partia bude pokračovať podľa pravidiel. To by si vyžadovalo samostatnú a oveľa dôkladnejšiu kontrolu.
Najľahšie si to zapamätáte takto: prehliadač dá agentovi ruky a oči, ale nie hotové závery. Stránku dokáže otvoriť, kliknúť a prečítať hodnotu sám. Rozhodnúť, čo táto hodnota znamená, však stále musíte vy.
Názvy nástrojov a ich parametre sme 19. septembra 2026 overili v README Playwright MCP. Môžu sa meniť podľa verzie. Základný postup - otvoriť stránku, pozrieť sa, vybrať prvok, vykonať akciu a znova prečítať údaje - zostáva rovnaký.
GO TO FULL VERSION