Testes E2E para Desktop Windows

Testes de ponta a ponta (end-to-end) para aplicações desktop nativas do Windows usando pywinauto, com suporte do Windows UI Automation (UIA). Abrange WPF, WinForms, Win32/MFC e Qt (5.x / 6.x) — com orientações específicas para Qt em uma seção dedicada.

Quando Ativar

• Escrevendo ou executando testes E2E para uma aplicação desktop nativa do Windows
• Configurando um conjunto de testes de GUI desktop do zero
• Diagnosticando testes de automação de desktop instáveis ou falhando
• Adicionando testabilidade (AutomationId, nomes acessíveis) a uma aplicação existente
• Integrando E2E de desktop em um pipeline de CI/CD (GitHub Actions windows-latest)

Quando NÃO Usar

• Aplicações web → use a habilidade e2e-testing (Playwright)
• Aplicações Electron / CEF / WebView2 → a camada HTML precisa de automação de navegador, não UIA
• Aplicações mobile → use ferramentas específicas da plataforma (UIAutomator, XCUITest)
• Testes puramente unitários ou de integração que não precisam de uma GUI em execução

Conceitos Principais

Toda automação de desktop Windows depende do UI Automation (UIA), uma API de acessibilidade integrada ao Windows. Cada framework suportado expõe uma árvore de elementos UIA com propriedades que o Claude pode ler e agir:

Your test (Python)
    └── pywinauto (UIA backend)
        └── Windows UI Automation API   ← built into Windows, framework-agnostic
            └── App's UIA provider      ← each framework ships its own
                └── Running .exe

Qualidade UIA por framework:

Configuração e Pré-requisitos

# Python 3.8+, Windows only
pip install pywinauto pytest pytest-html Pillow pytest-timeout
# Optional: screen recording
# Install ffmpeg and add to PATH: https://ffmpeg.org/download.html

Verifique se o UIA é alcançável:

from pywinauto import Desktop
Desktop(backend="uia").windows()  # lists all top-level windows

Instale o Accessibility Insights for Windows (gratuito, da Microsoft) — seu equivalente ao DevTools para inspecionar a árvore de elementos UIA antes de escrever qualquer teste.

Configuração de Testabilidade (por Framework)

A coisa mais impactante que você pode fazer é dar a cada controle interativo um AutomationId estável antes de escrever os testes.

WPF

<!-- XAML: x:Name becomes AutomationId automatically -->
<TextBox x:Name="usernameInput" />
<PasswordBox x:Name="passwordInput" />
<Button x:Name="btnLogin" Content="Login" />
<TextBlock x:Name="lblError" />

WinForms

// Set in designer or code
usernameInput.AccessibleName = "usernameInput";
passwordInput.AccessibleName = "passwordInput";
btnLogin.AccessibleName = "btnLogin";
lblError.AccessibleName = "lblError";

Win32 / MFC

// Control resource IDs in .rc file are exposed as AutomationId strings
// IDC_EDIT_USERNAME -> AutomationId "1001"
// Prefer SetWindowText for Name; add IAccessible for richer support

Qt — veja a seção dedicada abaixo

Page Object Model

tests/
├── conftest.py          # app launch fixture, failure screenshot
├── pytest.ini
├── config.py
├── pages/
│   ├── __init__.py      # required for imports
│   ├── base_page.py     # locators, wait, screenshot helpers
│   ├── login_page.py
│   └── main_page.py
├── tests/
│   ├── __init__.py
│   ├── test_login.py
│   └── test_main_flow.py
└── artifacts/           # screenshots, videos, logs

base_page.py

import os, time
from pywinauto import Desktop
from config import ACTION_TIMEOUT, ARTIFACT_DIR

class BasePage:
    def __init__(self, window):
        self.window = window

    # --- Localizadores (ordem de prioridade) ---

    def by_id(self, auto_id, **kw):
        """AutomationId — o mais estável. Use como primeira opção."""
        return self.window.child_window(auto_id=auto_id, **kw)

    def by_name(self, name, **kw):
        """Texto visível / nome acessível."""
        return self.window.child_window(title=name, **kw)

    def by_class(self, cls, index=0, **kw):
        """Classe do controle + índice — frágil, evite se possível."""

…