Pagina jocului este deja scrisă și se deschide în browser: tabla se afișează, piesele se mișcă, butonul "Joc nou" e la locul lui. Numai că agentul n-a văzut pagina niciodată. El a lucrat cu textul fișierelor, iar browserul l-ați pornit dumneavoastră, l-ați urmărit dumneavoastră și tot dumneavoastră i-ați povestit ce s-a întâmplat. Playwright umple exact acest gol: agentul deschide aceeași pagină, găsește elementul necesar, apasă și citește ce s-a schimbat.
Mai jos parcurgem acest ciclu pas cu pas, folosind o pagină de șah: deschidem, privim, alegem un element, acționăm și citim starea nouă. Nu repetăm instalarea și conectarea serverului. Dacă nu ați conectat încă Playwright, găsiți instrucțiunile în README-ul proiectului.
Deschideți pagina potrivită
Ce dovedește mesajul Connected?
Un singur lucru: Claude Code s-a conectat la serverul Playwright și a primit lista de instrumente. Încă nu e deschisă nicio pagină, ba chiar e posibil ca browserul să nu fi pornit. Connected confirmă conexiunea, nu faptul că jocul dumneavoastră funcționează și că agentul îl vede.
Puteți verifica starea actuală cu comanda /mcp: aceasta enumeră serverele conectate și ce poate face fiecare. De aici începe munca propriu-zisă, iar primul lucru de care aveți nevoie este adresa paginii.
Jocul local poate fi un fișier de pe disc sau poate rula pe un server local. Portul serverului nu e mereu același: 5173, 8000, 3000, în funcție de cum l-ați pornit. Luați adresa de acolo unde apare efectiv: din ieșirea comenzii de pornire sau din bara de adrese a browserului în care tocmai ați deschis jocul. Un port ales la întâmplare duce fie la o pagină goală, fie chiar la alt proiect, iar din răspunsul instrumentului asta nu reiese întotdeauna.
Deschiderea e un apel separat, browser_navigate, cu un singur parametru: url. Instrucțiunea pentru agent poate fi formulată firesc:
Deschide http://localhost:5173/ prin Playwright
și arată titlul paginii care s-a deschis.După deschidere, verificați două lucruri: adresa accesată efectiv de agent și titlul paginii. Durează o secundă, dar vă scutește de o serie întreagă de acțiuni făcute în locul greșit. Mai ales dacă mai aveți câteva proiecte locale pornite în paralel, iar unul dintre ele răspunde tot la localhost.
Playwright pornește un browser separat. Filele, extensiile și autentificările dumneavoastră nu sunt preluate acolo: implicit, folosește un profil separat de browserul dumneavoastră obișnuit. Pentru jocul local nu contează, dar nu vă așteptați ca un site pe care sunteți deja autentificat să se deschidă acolo direct în contul dumneavoastră.
Ce vede agentul pe pagină
Puteți inspecta pagina deschisă în trei feluri, iar rezultatele diferă fundamental:
| Ce vrem | Instrument | Ce primim ca răspuns |
|---|---|---|
| Să vedem cum arată | browser_take_screenshot | imaginea paginii |
| Să aflăm din ce e alcătuită | browser_snapshot | un arbore textual al elementelor: roluri, nume și referințe către elemente |
| Să citim o anumită valoare | browser_evaluate | rezultatul unei expresii scurte, calculate chiar pe pagină |
Toate cele trei variante pornesc de la aceeași pagină, dar returnează date diferite. Instantaneul vă ajută să găsiți butonul, iar valoarea data-turn trebuie citită separat. Imaginea tablei nu dezvăluie de una singură atributele HTML.
O captură de ecran este o imagine. Răspunde foarte bine la întrebări precum "cum arată" și "unde se află fiecare lucru", dar nu oferă o referință către element pentru browser_click. În modul obișnuit Playwright MCP, acțiunile se fac folosind instantaneul de accesibilitate. Clicurile pe coordonate sunt disponibile separat, dacă activați instrumentele corespunzătoare.
Instantaneul de accesibilitate descrie elementele. Nu e o imagine, ci un text: lista componentelor paginii, cu roluri (buton, link, câmp de introducere), nume și referințe pe care le puteți folosi pentru a accesa ulterior elementul. Agentul se bazează pe el când apasă ceva. Schematic, un buton arată acolo cam așa:
- button "Joc nou" [ref=e12]
- button "Anulează mutarea" [ref=e13]Acesta este doar un exemplu orientativ, nu rezultatul real al instrumentului: formatul exact depinde de versiunea serverului, iar pentru articol nu îl vom porni. Importantă nu este punctuația, ci ideea: agentul primește butonul ca text cu rol, nume și referință, nu ca dreptunghi cu text.
Iată locul unde se greșește cel mai des. Marcajul data-turn, care arată a cui este mutarea în jocul nostru, nu intră în instantaneul de accesibilitate: acesta se construiește din rolurile, numele, stările și referințele elementelor, nu din markup-ul paginii. Un atribut data oarecare nu este inclus. Valoarea lui poate apărea totuși separat în instantaneu dacă pagina o afișează și ca text vizibil. Dar atunci e textul paginii, nu atributul citit direct, așa că nu le confundați.
Astfel de valori se citesc separat, cu instrumentul browser_evaluate. Acesta execută o expresie scurtă în contextul paginii și returnează rezultatul. Aici se execută cod pe pagină, nu doar se citește conținut, de aceea agentul vă poate cere uneori permisiunea înainte. Agentul va formula singur expresia, dar iată cum poate arăta:
// găsește elementul cu marcajul mutării și îi returnează valoarea
() => document.querySelector('[data-turn]')?.getAttribute('data-turn') ?? nullInstantaneul de accesibilitate este un rezumat, nu o copie completă a markup-ului paginii. Include informațiile necesare pentru a recunoaște și apăsa un element, nu tot ce există. Așadar, "agentul a făcut un instantaneu" și "agentul a citit toate atributele" sunt afirmații diferite, iar a doua nu rezultă din prima.
Cum alege agentul un element
De ce un clic pe coordonate ajunge uneori pe lângă buton?
Pentru că coordonatele indică un punct de pe ecran, nu un buton. Ați mărit fereastra, ați restrâns panoul lateral, ați schimbat dimensiunea fontului sau pagina a primit un rând în plus sus - punctul a rămas pe loc, dar butonul s-a mutat. Clicul se execută fără eroare, doar că nimerește într-un spațiu gol.
De aceea, metoda principală de selecție e alta. Instrumentul browser_click are două câmpuri importante aici: element, o descriere pe înțelesul oamenilor, precum "butonul Joc nou", ca să știți unde intenționează agentul să apese, și target, o referință la element din instantaneu sau un selector unic. Aici ne uităm la alegerea prin referința din instantaneu. Referința este asociată cu instantaneul din care a fost preluată, iar clicul ajunge exact la acel element. Introducerea textului funcționează similar, doar că instrumentul se numește browser_type, iar la descrierea elementului se adaugă și textul.
Nu referința în sine e stabilă, ci felul în care găsiți elementul. Rolul și numele sunt o pereche destul de constantă: butonul "Joc nou" rămâne tot "Joc nou" chiar și după ce designerul îl mută în celălalt colț al ecranului. În fiecare instantaneu nou, agentul găsește elementul după această pereche și preia o referință actualizată. De aceea revenim mai jos la regula "după fiecare acțiune, verificați din nou".
Cu pătratele tablei e mai complicat: sunt 64 și toate au același rol. Ajută un marcaj furnizat de aplicație. Dacă fiecare pătrat are un nume, precum e2 sau e4, îl puteți selecta precis. Dacă în instantaneu pătratele nu au nume, cel dorit nu poate fi ales doar după rol și nume. Verificați atunci dacă pătratul are un alt indiciu unic în markup sau folosiți instrumentele de coordonate disponibile.
Playwright MCP are și instrumente de coordonate, dar în configurația obișnuită sunt dezactivate și trebuie activate separat. Pot fi utile când nu puteți accesa elementul altfel, de exemplu pe un canvas. Dacă nu sunt activate, o simplă imagine nu vă ajută să acționați. Exact despre asta era avertismentul privind captura de ecran de la începutul secțiunii.
Acțiunea și starea nouă
Săgeata din stânga închide ciclul: înaintea următoarei acțiuni, agentul folosește descrierea actuală a paginii. Dacă răspunsul la acțiunea anterioară include deja un instantaneu nou, vă puteți baza pe el. Faptul că s-a executat un clic nu confirmă încă schimbarea dorită.
Să punem totul într-un singur traseu pe care îl puteți da agentului. Sunt cinci pași și, după fiecare, e clar ce ar trebui să vedeți. Traseul presupune că pătratele tablei noastre au etichete - e2 și e4 din secțiunea anterioară. Fără ele, la pasul 4 vă trebuie o altă metodă de selecție precisă.
| Pas | Ce face agentul | Ce ar trebui să vedem |
|---|---|---|
| 1 | deschide adresa jocului | titlul paginii și tabla de joc |
| 2 | apasă butonul "Joc nou" | piesele sunt în poziția de start |
| 3 | citește data-turn | white |
| 4 | mută e2-e4 prin interfața paginii | pionul avansează două pătrate |
| 5 | recitește data-turn și piesa de pe e4 | black, pion alb pe e4 |
În stânga este starea inițială, iar în dreapta rezultatul așteptat. Blocul de jos le leagă prin verificare: agentul citește din nou marcajul mutării și poziția pieselor, apoi compară valorile. Pentru o verificare mai completă, confirmați și că pătratul e2 s-a eliberat. Schimbarea lui white în black nu dovedește singură că pionul a ajuns pe e4.
Un lucru important despre data-turn: este o convenție a aplicației respective. Autorul paginii a decis să adauge acest marcaj, de aceea îl putem citi. Playwright nu îl creează și nu îl obține din altă parte, ci doar citește ce există deja pe pagină. Pe alt site, unde marcajul lipsește, metoda nu va funcționa și va trebui să vă bazați pe ce se vede.
Iar regula principală după fiecare acțiune: citiți din nou starea. Instantaneul făcut înainte de clic descrie pagina de dinainte, oricât de recent ar părea. După redesenarea tablei, referințele din el s-ar putea să nu mai ducă nicăieri, iar valoarea data-turn citită înainte de clic poate să se fi schimbat deja. Ați acționat? Verificați din nou.
Dacă aplicația nu a furnizat valoarea necesară, răspunsul corect al agentului este "nu am putut citi valoarea, atributul nu există pe pagină". Un black plauzibil, dedus din faptul că mutarea pare să fi fost făcută, arată exact ca o valoare citită, dar nu dovedește nimic. Cereți-i agentului să afișeze valorile citite, nu să le povestească.
Când acțiunea nu reușește
Cea mai frecventă problemă este mesajul "elementul nu a fost găsit". Verificați pe rând:
- asigurați-vă că este deschisă pagina potrivită. Adresa și titlul sunt aceleași două repere de la început;
- verificați dacă pagina s-a încărcat. Jocul poate să nu se fi încărcat complet, iar butonul poate apărea cu o secundă după cerere;
- faceți un instantaneu nou. Nu-l folosiți pe cel deja prezent în conversație;
- alegeți din nou elementul pe baza descrierii actuale din instantaneu și repetați acțiunea.
La pasul al treilea poate deveni clară una dintre cauze: elementul este încă pe pagină, dar referința lui nu mai e valabilă.
O captură de ecran poate fi utilă și la diagnosticare, dar nu este o soluție universală. Răspunde la întrebări precum "cum arată pagina și unde se află fiecare lucru"; de pildă, arată că tabla e goală sau că peste ea s-a deschis o fereastră modală. Dacă pagina afișează textual al cui e rândul, puteți vedea asta și în captură. Dar valoarea exactă a atributului data-turn poate fi confirmată doar citindu-l. Sunt două întrebări diferite și două instrumente diferite. Dacă le confundați, ajungeți să vă uitați la o imagine și să vă certați pe date.
Cum se schimbă modul de lucru
Instrucțiunea pentru agent nu mai e o listă de clicuri, ci un traseu cu puncte de verificare. Iată tot ce am parcurs, într-un singur text:
Deschide http://localhost:5173/ prin Playwright.
1) apasă "Joc nou";
2) citește data-turn și arată valoarea;
3) mută e2-e4 prin interfața paginii;
4) citește din nou data-turn și ce piesă se află pe e4.
Dacă pagina nu conține vreuna dintre aceste valori, spune asta
și nu o inventa.Țineți minte câteva lucruri:
- adresa este întotdeauna cea reală, preluată din ieșirea comenzii de pornire, nu una aproximativă;
- instrucțiunea conține rânduri de tipul "citește și arată". Fără ele, veți rămâne doar cu o poveste despre rezultat;
- stările se arată în pereche, înainte și după acțiune. O singură valoare la final nu dovedește nimic, fiindcă nu știm care era valoarea inițială;
- instantaneul, captura de ecran și citirea unui atribut răspund la întrebări diferite. Alegeți metoda în funcție de întrebare, nu din obișnuință;
- un singur traseu de test este suficient. Mutarea e2-e4 reușită nu înseamnă că restul partidei se va desfășura conform regulilor: aceea e o verificare separată și mult mai serioasă.
Cel mai simplu de reținut: browserul îi oferă agentului mâini și ochi, dar nu și concluzii gata făcute. Agentul poate deschide singur pagina, poate apăsa și poate citi o valoare; ce înseamnă acea valoare decideți tot dumneavoastră.
Denumirile instrumentelor și parametrii lor au fost verificați la 19 septembrie 2026 în README-ul Playwright MCP și se pot schimba de la o versiune la alta. Ordinea generală rămâne aceeași: deschideți, priviți, alegeți elementul, acționați și citiți din nou.
GO TO FULL VERSION