Capturas de Tela da UI

Capture capturas de tela de aplicativos web e UIs gráficas durante o desenvolvimento para documentar mudanças visuais.

Quando Usar Esta Habilidade

Use esta habilidade quando precisar:

• Capturar o estado atual de um aplicativo web em execução
• Documentar uma UI antes e depois de uma mudança de código
• Fazer capturas de tela de estados interativos (tooltips, hovers, elementos selecionados)
• Capturar seções específicas de uma página sem precisar tirar uma nova captura de tela

Pré-requisitos

pip install playwright Pillow -q
playwright install chromium

Fluxo de Trabalho Principal

1. Tire uma captura de tela bruta de página inteira

from playwright.async_api import async_playwright

async def capture(url="http://localhost:3000", out="screenshot-raw.png", width=1400, height=5000):
    async with async_playwright() as p:
        browser = await p.chromium.launch()
        page = await browser.new_page(viewport={"width": width, "height": height})
        await page.goto(url, wait_until="networkidle")
        await page.wait_for_timeout(4000)  # let charts/animations render
        await page.screenshot(path=out, full_page=True)
        await browser.close()

• Use uma viewport alta (altura=5000) para que a página renderize tudo sem rolagem
• wait_until="networkidle" + wait_for_timeout(4000) garantem que os gráficos assíncronos sejam carregados
• full_page=True captura todo o conteúdo rolável

2. Visualize a imagem bruta e, em seguida, corte com PIL

NÃO tente obter cortes perfeitos através do parâmetro clip do Playwright. Ele é não confiável com capturas de página inteira.

from PIL import Image

img = Image.open("screenshot-raw.png")
cropped = img.crop((left, top, right, bottom))  # adjust based on what you see
cropped.save("screenshot-final.png")

1. Tire a captura de tela bruta
2. Visualize-a para ver as posições reais dos pixels
3. Corte com PIL com base no que você vê
4. Visualize o resultado — se não estiver certo, corte novamente (instantâneo, sem necessidade de nova captura)

3. Itere no corte, não na captura

• Tirar novas capturas de tela é lento (inicialização do navegador + carregamento da página + espera de renderização)
• Cortar novamente é instantâneo (apenas PIL)
• Obtenha uma boa captura bruta e, em seguida, fatie-a quantas vezes forem necessárias

4. Estados interativos

element = page.locator("selector").first
await element.hover()
await page.wait_for_timeout(1000)  # let tooltip appear
await page.screenshot(path="screenshot-hover.png", full_page=True)

Para o estado "selecionado" sem efeito de hover, mova o mouse para longe após clicar:

await element.click()
await page.mouse.move(300, 300)  # move away so hover doesn't show
await page.wait_for_timeout(500)
await page.screenshot(path="screenshot-selected.png", full_page=True)

5. Capturas específicas de seções

Corte diferentes seções de uma única captura de tela de página inteira:

img.crop((0, 200, 920, 900)).save("screenshot-header.png")
img.crop((0, 900, 920, 1600)).save("screenshot-main.png")

Diretrizes

1. Sempre capture o estado ANTES de fazer qualquer alteração — se você esquecer, terá que reverter o código para obter uma captura "antes"
2. Pares de antes/depois devem usar a mesma largura de viewport e corte — caso contrário, a comparação é inútil
3. Para obter um "antes" depois de já ter alterado o código: use git checkout HEAD~1 -- <files> para reverter, tirar a captura de tela e, em seguida, git checkout HEAD -- <files> para restaurar
4. Para estados interativos: capture antes E depois para cada estado — não assuma que o "normal" antes cobre todos os casos
5. Use device_scale_factor=1 no Playwright para forçar pixels 1x para que as capturas de tela correspondam ao que os usuários veem com zoom de 100%
6. Gráficos precisam de tempo de espera extra — Plotly, D3, etc. renderizam de forma assíncrona; 4s no mínimo após networkidle
7. Viewport estreita revela bugs de renderização — alguns problemas de borda/alinhamento só aparecem em larguras específicas

Capturas de Tela de Aplicativos Não Web

Para aplicativos de desktop (VS, WPF, WinForms, aplicativos de console, terminais) onde o Playwright não pode alcançar.

mss + ctypes (recomendado para janelas de desktop)

Encontre uma janela pelo título via API Win32, capture sua região com mss. Testado a ~33ms por captura.

import ctypes
from ctypes import c_int, Structure, byref, windll
import mss
from PIL import Image

user32 = windll.user32

def find_window(title_contains):
    """Encontra janelas visíveis que correspondem a uma substring do título."""
    results = []
    WNDENUMPROC = ctypes.WINFUNCTYPE(ctypes.c_bool, ctypes.c_void_p, ctypes.c_void_p)
    def cb(hwnd, _):
        if user32.IsWindowVisible(hwnd):
            buf = ctypes.create_unicode_buffer(256)
            user32.GetWindowTextW(hwnd, buf, 256)

…