Seu Agente de IA Pode Ler o DOM. Ele Não Pode Ver a Tela.

Este é um teste que passa toda vez:

await expect(page.locator('.checkout-button')).toBeVisible();

E aqui está o que o agente de IA não sabe: o botão de checkout está em y: 1450px em uma viewport móvel de 375px. Ele existe. Está visível de acordo com o DOM. O teste está verde. O usuário não consegue alcançá-lo sem rolar três telas para baixo, e em alguns dispositivos um banner de cookie fixo se sobrepõe a ele em 60%.

O agente leu a árvore de acessibilidade. Ele não viu a tela.

A lacuna entre o DOM e a renderização

Quando um agente de IA analisa uma falha do Playwright ou escreve um novo teste, ele trabalha com o que o Playwright expõe por padrão: funções, rótulos, conteúdo de texto, atributos ARIA. Esta é a abstração correta para testes funcionais.

Mas os bugs de layout não vivem no DOM. Eles vivem na saída do mecanismo de renderização — em coordenadas, z-indexes, caixas delimitadoras e razões de interseção. Um botão pode estar display: block, visibility: visible, opacity: 1, e completamente inacessível para um usuário real.

As ferramentas atuais para esse problema são baseadas em diferença de pixels (barulhentas, quebram com anti-aliasing) ou IA empresarial proprietária (Applitools, Percy). Não há ferramenta de código aberto que forneça a um agente de IA dados geométricos estruturados de um navegador ao vivo.

É isso que playwright-spatial-layout-mcp faz.

Como funciona

O servidor MCP inicia um navegador Chromium sem cabeça, navega para uma URL e extrai dados geométricos usando getBoundingClientRect() e getComputedStyle() em uma única chamada page.evaluate() — uma viagem de ida e volta ao navegador por lote de elementos.

Quatro ferramentas:

extract_bounding_boxes — retorna posição, tamanho, z-index e visibilidade da viewport para qualquer conjunto de seletores.

{
  "url": "https://your-app.com/checkout",
  "selectors": [".checkout-button", ".cookie-banner", "nav"],
  "viewport": { "width": 375, "height": 812 }
}

[
  {
    "selector": ".checkout-button",
    "box": { "x": 16, "y": 892, "width": 343, "height": 48 },
    "z_index": "auto",
    "is_visible": true,
    "is_in_viewport": false
  }
]

O botão existe. Ele não está na viewport. O agente agora sabe disso.

detect_visual_occlusion — calcula a razão de interseção entre as caixas delimitadoras de dois elementos.

{
  "url": "https://your-app.com/checkout",
  "target_selector": ".checkout-button",
  "overlay_selector": ".cookie-banner"
}

{
  "is_occluded": true,
  "intersection_ratio": 0.61,
  "occluded_area_px": 4128
}

61% da área do botão está sob o banner de cookies. O agente agora pode relatar isso como um bug, não como um teste passando.

verify_spatial_relationships — valida regras de layout e retorna um pass/fail com uma razão legível por humanos por regra.

Seis tipos de regras: left_of, right_of, above, below, contains, not_overlapping.

{
  "url": "https://your-app.com",
  "rules": [
    {
      "type": "above",
      "element_a":