theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/e2e-escritorio-windows/SKILL.md

@@ -0,0 +1,879 @@
+---
+name: e2e-escritorio-windows
+description: Testing E2E de aplicaciones de escritorio nativas de Windows (WPF, WinForms, Win32/MFC, Qt) usando pywinauto y Windows UI Automation. Incluye Page Object Model, aislamiento por niveles, CI y fallback por capturas.
+---
+
+# Testing E2E de escritorio en Windows
+
+Testing end-to-end de aplicaciones de escritorio nativas de Windows usando **pywinauto** sobre Windows UI Automation (UIA). Cubre WPF, WinForms, Win32/MFC y Qt (5.x / 6.x) — con una sección dedicada a las particularidades de Qt.
+
+## Cuándo activarla
+
+- Escribir o ejecutar tests E2E para una aplicación de escritorio nativa de Windows
+- Montar una suite de tests de GUI de escritorio desde cero
+- Diagnosticar tests de automatización de escritorio inestables o fallidos
+- Añadir testabilidad (AutomationId, nombres accesibles) a una app existente
+- Integrar E2E de escritorio en un pipeline CI/CD (GitHub Actions `windows-latest`)
+
+### Cuándo NO usarla
+
+- Aplicaciones web → usa la skill `testing-e2e` (Playwright)
+- Apps Electron / CEF / WebView2 → la capa HTML necesita automatización de navegador, no UIA
+- Apps móviles → usa herramientas específicas de plataforma (UIAutomator, XCUITest)
+- Tests unitarios o de integración puros que no necesitan una GUI en ejecución
+
+## Conceptos centrales
+
+Toda la automatización de escritorio en Windows se apoya en **UI Automation (UIA)**, una API de accesibilidad integrada en Windows. Cada framework soportado expone un árbol de elementos UIA con propiedades que el agente puede leer y sobre las que puede actuar:
+
+```
+Tu test (Python)
+    └── pywinauto (backend UIA)
+        └── API Windows UI Automation   ← integrada en Windows, agnóstica del framework
+            └── Proveedor UIA de la app ← cada framework trae el suyo
+                └── .exe en ejecución
+```
+
+**Calidad de UIA por framework:**
+
+| Framework | AutomationId | Fiabilidad | Notas |
+|-----------|-------------|------------|-------|
+| WPF | 5/5 | Excelente | `x:Name` se mapea directamente a AutomationId |
+| WinForms | 4/5 | Buena | `AccessibleName` = AutomationId |
+| UWP / WinUI 3 | 5/5 | Excelente | Soporte completo de Microsoft |
+| Qt 6.x | 5/5 | Excelente | Accesibilidad habilitada por defecto; los nombres de clase cambian a `Qt6*` |
+| Qt 5.15+ | 4/5 | Buena | Módulo de accesibilidad mejorado |
+| Qt 5.7–5.14 | 3/5 | Regular | Necesita `QT_ACCESSIBILITY=1`; objectName manual |
+| Win32 / MFC | 3/5 | Regular | IDs de controles accesibles; el matching por texto es común |
+
+## Instalación y prerrequisitos
+
+```bash
+# Python 3.8+, solo Windows
+pip install pywinauto pytest pytest-html Pillow pytest-timeout
+# Opcional: grabación de pantalla
+# Instala ffmpeg y añádelo al PATH: https://ffmpeg.org/download.html
+```
+
+Verifica que UIA es alcanzable:
+
+```python
+from pywinauto import Desktop
+Desktop(backend="uia").windows()  # lista todas las ventanas de nivel superior
+```
+
+Instala **Accessibility Insights for Windows** (gratuito, de Microsoft) — tu equivalente a DevTools para inspeccionar el árbol de elementos UIA antes de escribir cualquier test.
+
+## Preparar la testabilidad (por framework)
+
+Lo más impactante que puedes hacer es **dar a cada control interactivo un AutomationId estable** antes de escribir tests.
+
+### WPF
+
+```xml
+<!-- XAML: x:Name se convierte en AutomationId automáticamente -->
+<TextBox x:Name="usernameInput" />
+<PasswordBox x:Name="passwordInput" />
+<Button x:Name="btnLogin" Content="Login" />
+<TextBlock x:Name="lblError" />
+```
+
+### WinForms
+
+```csharp
+// Se establece en el diseñador o en código
+usernameInput.AccessibleName = "usernameInput";
+passwordInput.AccessibleName = "passwordInput";
+btnLogin.AccessibleName = "btnLogin";
+lblError.AccessibleName = "lblError";
+```
+
+### Win32 / MFC
+
+```cpp
+// Los IDs de recurso de controles del archivo .rc se exponen como strings de AutomationId
+// IDC_EDIT_USERNAME -> AutomationId "1001"
+// Prefiere SetWindowText para Name; añade IAccessible para soporte más rico
+```
+
+### Qt — ver la sección dedicada más abajo
+
+---
+
+## Page Object Model
+
+```
+tests/
+├── conftest.py          # fixture de arranque de la app, captura en fallo
+├── pytest.ini
+├── config.py
+├── pages/
+│   ├── __init__.py      # requerido para los imports
+│   ├── base_page.py     # localizadores, esperas, helpers de captura
+│   ├── login_page.py
+│   └── main_page.py
+├── tests/
+│   ├── __init__.py
+│   ├── test_login.py
+│   └── test_main_flow.py
+└── artifacts/           # capturas, videos, logs
+```
+
+### base_page.py
+
+```python
+import os, time
+from pywinauto import Desktop
+from config import ACTION_TIMEOUT, ARTIFACT_DIR
+
+class BasePage:
+    def __init__(self, window):
+        self.window = window
+
+    # --- Localizadores (en orden de prioridad) ---
+
+    def by_id(self, auto_id, **kw):
+        """AutomationId — el más estable. Úsalo como primera opción."""
+        return self.window.child_window(auto_id=auto_id, **kw)
+
+    def by_name(self, name, **kw):
+        """Texto visible / nombre accesible."""
+        return self.window.child_window(title=name, **kw)
+
+    def by_class(self, cls, index=0, **kw):
+        """Clase del control + índice — frágil, evítalo si es posible."""
+        return self.window.child_window(class_name=cls, found_index=index, **kw)
+
+    # --- Esperas ---
+
+    def wait_visible(self, spec, timeout=ACTION_TIMEOUT):
+        spec.wait("visible", timeout=timeout)
+        return spec
+
+    def wait_gone(self, spec, timeout=ACTION_TIMEOUT):
+        spec.wait_not("visible", timeout=timeout)
+        return spec
+
+    def wait_window(self, title, timeout=ACTION_TIMEOUT):
+        """Espera una nueva ventana de nivel superior (diálogos, ventanas hijas)."""
+        dlg = Desktop(backend="uia").window(title=title)
+        dlg.wait("visible", timeout=timeout)
+        return dlg
+
+    def wait_until(self, fn, timeout=ACTION_TIMEOUT, interval=0.3):
+        """Sondea una condición arbitraria — úsalo cuando los eventos UIA no son fiables."""
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            try:
+                if fn():
+                    return True
+            except Exception:
+                pass
+            time.sleep(interval)
+        raise TimeoutError(f"Condición no cumplida en {timeout}s")
+
+    # --- Acciones ---
+
+    def click(self, spec):
+        self.wait_visible(spec)
+        spec.click_input()
+
+    def type_text(self, spec, text):
+        self.wait_visible(spec)
+        ctrl = spec.wrapper_object()
+        try:
+            ctrl.set_edit_text(text)
+        except Exception as e:
+            # Fallback para Qt 5.x: el Value Pattern de UIA puede estar incompleto
+            import sys, pywinauto.keyboard as kb
+            print(f"[e2e-escritorio-windows] set_edit_text falló ({e}), usando fallback de teclado", file=sys.stderr)
+            ctrl.click_input()
+            kb.send_keys("^a")
+            kb.send_keys(text, with_spaces=True)
+
+    def get_text(self, spec):
+        ctrl = spec.wrapper_object()
+        for attr in ("window_text", "get_value"):
+            try:
+                v = getattr(ctrl, attr)()
+                if v:
+                    return v
+            except Exception:
+                pass
+        return ""
+
+    # --- Artefactos ---
+
+    def screenshot(self, name):
+        os.makedirs(ARTIFACT_DIR, exist_ok=True)
+        path = os.path.join(ARTIFACT_DIR, f"{name}.png")
+        self.window.capture_as_image().save(path)
+        return path
+```
+
+### login_page.py
+
+```python
+from pages.base_page import BasePage
+
+class LoginPage(BasePage):
+    @property
+    def username(self): return self.by_id("usernameInput")
+
+    @property
+    def password(self): return self.by_id("passwordInput")
+
+    @property
+    def btn_login(self): return self.by_id("btnLogin")
+
+    @property
+    def error_label(self): return self.by_id("lblError")
+
+    def login(self, user, pwd):
+        self.type_text(self.username, user)
+        self.type_text(self.password, pwd)
+        self.click(self.btn_login)
+
+    def login_ok(self, user, pwd, main_title="Main Window"):
+        self.login(user, pwd)
+        return self.wait_window(main_title)
+
+    def login_fail(self, user, pwd):
+        self.login(user, pwd)
+        self.wait_visible(self.error_label)
+        return self.get_text(self.error_label)
+```
+
+### conftest.py
+
+> Para proyectos nuevos prefiere el **fixture sandbox de Nivel 1** (ver más abajo) — añade aislamiento de sistema de archivos a costo cero. Este fixture básico es solo para montajes mínimos o legados.
+
+```python
+import os, pytest
+os.environ["QT_ACCESSIBILITY"] = "1"  # Requerido para soporte UIA en Qt 5.x
+
+from pywinauto import Application
+from config import APP_PATH, MAIN_WINDOW_TITLE, LAUNCH_TIMEOUT, ARTIFACT_DIR
+
+@pytest.fixture
+def app(request):
+    if not APP_PATH:
+        pytest.exit("La variable de entorno APP_PATH no está definida", returncode=1)
+    proc = Application(backend="uia").start(APP_PATH, timeout=LAUNCH_TIMEOUT)
+    win  = proc.window(title=MAIN_WINDOW_TITLE)
+    win.wait("visible", timeout=LAUNCH_TIMEOUT)
+    yield win
+    # Captura de pantalla en caso de fallo
+    if getattr(getattr(request.node, "rep_call", None), "failed", False):
+        os.makedirs(ARTIFACT_DIR, exist_ok=True)
+        try:
+            win.capture_as_image().save(
+                os.path.join(ARTIFACT_DIR, f"FAIL_{request.node.name}.png")
+            )
+        except Exception:
+            pass
+    # Salida ordenada primero, kill forzado como respaldo
+    # proc es una Application de pywinauto — usa wait_for_process_exit(), no wait_for_process()
+    try:
+        win.close()
+        proc.wait_for_process_exit(timeout=5)
+    except Exception:
+        proc.kill()
+
+@pytest.hookimpl(tryfirst=True, hookwrapper=True)
+def pytest_runtest_makereport(item, call):
+    outcome = yield
+    setattr(item, f"rep_{outcome.get_result().when}", outcome.get_result())
+```
+
+### config.py
+
+```python
+import os
+APP_PATH          = os.environ.get("APP_PATH", "")           # se define por env — sin ruta por defecto
+MAIN_WINDOW_TITLE = os.environ.get("APP_TITLE", "")
+LAUNCH_TIMEOUT    = int(os.environ.get("LAUNCH_TIMEOUT", "15"))
+ACTION_TIMEOUT    = int(os.environ.get("ACTION_TIMEOUT", "10"))
+ARTIFACT_DIR      = os.path.join(os.path.dirname(__file__), "artifacts")
+```
+
+### pytest.ini
+
+```ini
+[pytest]
+testpaths = tests
+markers =
+    smoke: tests de humo rápidos para rutas críticas
+    flaky: tests conocidos como inestables
+addopts = -v --tb=short --html=artifacts/report.html --self-contained-html
+```
+
+## Estrategia de localizadores
+
+```
+AutomationId  >  Name (texto)  >  ClassName + índice  >  XPath
+  (estable)       (legible)         (frágil)             (último recurso)
+```
+
+Inspecciona con Accessibility Insights → panel **Properties** → busca `AutomationId` primero.
+
+```python
+# Inspección en tiempo de ejecución — pégalo en un REPL para explorar el árbol
+win.print_control_identifiers()
+# o acota el alcance:
+win.child_window(auto_id="groupBox1").print_control_identifiers()
+```
+
+## Patrones de espera
+
+```python
+# Esperar a que un control aparezca
+page.wait_visible(page.by_id("statusLabel"))
+
+# Esperar a que un control desaparezca (p. ej., spinner de carga)
+page.wait_gone(page.by_id("spinnerOverlay"))
+
+# Esperar a que aparezca un diálogo
+dlg = page.wait_window("Confirm Delete")
+
+# Condición personalizada (p. ej., cambio de texto)
+page.wait_until(lambda: page.get_text(page.by_id("lblStatus")) == "Ready")
+```
+
+**Nunca uses `time.sleep()` como sincronización primaria** — usa `wait()` o `wait_until()`.
+
+## Gestión de artefactos
+
+```python
+# Captura bajo demanda
+page.screenshot("after_login")
+
+# Captura de pantalla completa (cuando la ventana está fuera de pantalla o minimizada)
+import pyautogui
+pyautogui.screenshot("artifacts/fullscreen.png")
+
+# Grabación de pantalla con ffmpeg (inicia antes del test, detén después)
+import subprocess
+
+def start_recording(name):
+    return subprocess.Popen([
+        "ffmpeg", "-f", "gdigrab", "-framerate", "10",
+        "-i", "desktop", "-y", f"artifacts/videos/{name}.mp4"
+    ], stdin=subprocess.PIPE, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+
+def stop_recording(proc):
+    proc.stdin.write(b"q"); proc.stdin.flush(); proc.wait(timeout=10)
+```
+
+## Traza por paso (opt-in)
+
+La captura por defecto al fallar suele ser insuficiente para diagnosticar tests inestables. La traza a nivel de paso está **desactivada por defecto** — habilítala solo al reproducir un caso flaky.
+
+### Habilitar
+
+```bash
+E2E_TRACE=1 pytest tests/test_login.py -v
+# Incluir el texto tecleado en el log JSONL (NO usar en tests que teclean credenciales/PII):
+E2E_TRACE=1 E2E_TRACE_INCLUDE_TEXT=1 pytest ...
+```
+
+### Parche en BasePage
+
+```python
+import os, json, time
+TRACE_ENABLED      = os.environ.get("E2E_TRACE") == "1"
+TRACE_INCLUDE_TEXT = os.environ.get("E2E_TRACE_INCLUDE_TEXT") == "1"
+
+class BasePage:
+    _step = 0
+
+    def _trace(self, action, spec=None, text=None):
+        if not TRACE_ENABLED:
+            return
+        BasePage._step += 1
+        idx = f"{BasePage._step:03d}"
+        os.makedirs(ARTIFACT_DIR, exist_ok=True)
+        try:
+            self.window.capture_as_image().save(
+                os.path.join(ARTIFACT_DIR, f"step_{idx}_{action}.png"))
+        except Exception:
+            pass  # un fallo de captura no debe romper el test
+        rec = {
+            "ts": time.time(), "step": BasePage._step, "action": action,
+            "locator": getattr(spec, "criteria", None),
+            "text": text if TRACE_INCLUDE_TEXT else ("<redactado>" if text else None),
+        }
+        with open(os.path.join(ARTIFACT_DIR, "trace.jsonl"), "a") as f:
+            f.write(json.dumps(rec) + "\n")
+
+    def click(self, spec):
+        self.wait_visible(spec); self._trace("click_before", spec)
+        spec.click_input();      self._trace("click_after",  spec)
+
+    def type_text(self, spec, text):
+        self.wait_visible(spec); self._trace("type_before", spec, text)
+        # ... el set_edit_text / fallback de teclado existente ...
+        self._trace("type_after", spec)
+```
+
+### Advertencias
+
+- **PII / credenciales**: el contenido de `type_text` queda `<redactado>` por defecto. Nunca actives `E2E_TRACE_INCLUDE_TEXT=1` en flujos de login o de pago.
+- **Sobrecoste**: ~50–200 ms por acción + un PNG por paso en disco. No lo habilites en la matriz de CI por defecto — solo en un job dedicado a reproducir flakiness.
+- **Inflado de artefactos**: un flujo largo produce decenas de MB; ajusta `retention-days` en consecuencia.
+- **Higiene en paralelo/reintentos**: este ejemplo simple hace append a `trace.jsonl` y usa un contador a nivel de clase. Limpia el directorio de artefactos antes de reejecutar, y usa directorios de artefactos por worker para tests paralelos.
+- **Hueco de cobertura**: las acciones realizadas fuera de `BasePage` (llamadas crudas a `pywinauto` en el código del test) no quedan trazadas.
+
+## Manejo de tests inestables
+
+```python
+# Cuarentena — equivalente a test.fixme() de Playwright
+@pytest.mark.skip(reason="Flaky: carrera de animación en CI lento. Issue #42")
+def test_animated_transition(self, app): ...
+
+# Saltar solo en CI
+@pytest.mark.skipif(os.environ.get("CI") == "true", reason="Flaky en CI #43")
+def test_heavy_load(self, app): ...
+```
+
+Causas comunes y soluciones:
+
+| Causa | Solución |
+|-------|----------|
+| Control no listo | Reemplaza `time.sleep` por `wait_visible` |
+| Ventana sin foco | Añade `win.set_focus()` antes de interactuar |
+| Animación en curso | `wait_until(lambda: not loading_indicator.exists())` |
+| Timing de diálogos | `wait_window(title, timeout=15)` |
+| Pantalla de CI no lista | Define `DISPLAY` o usa escritorio virtual en CI |
+| `set_edit_text` lanza NotImplementedError | Falta el ValuePattern de UIA (común en Qt 5.x) — `BasePage.type_text` ya cae a `keyboard.send_keys` |
+| El control existe pero `wait_visible` expira | Ventana minimizada o fuera de pantalla — llama a `win.restore()` + `win.set_focus()` antes de esperar |
+
+## Aislamiento de tests y sandbox
+
+Tres niveles de aislamiento — usa el más ligero que satisfaga tus necesidades.
+
+### Nivel 1 — Aislamiento de sistema de archivos (por defecto, úsalo siempre)
+
+Cada test recibe su propio `APPDATA` / `LOCALAPPDATA` / `TEMP` vía `subprocess.Popen` y `Application.connect()`. El fixture `tmp_path` de pytest se encarga de la limpieza automáticamente.
+
+```python
+# conftest.py — reemplaza el fixture `app` básico por este
+import os, subprocess, pytest
+from pywinauto import Application
+from config import APP_PATH, APP_ARGS, APP_TITLE, LAUNCH_TIMEOUT, ACTION_TIMEOUT, ARTIFACT_DIR
+
+@pytest.fixture(scope="function")
+def app(request, tmp_path):
+    """Proceso fresco + directorios de datos de usuario aislados por test."""
+    if not APP_PATH:
+        pytest.exit("APP_PATH no está definido", returncode=1)
+
+    # Redirige todo el almacenamiento por usuario a un directorio tmp aislado
+    sandbox_env = os.environ.copy()
+    sandbox_env["QT_ACCESSIBILITY"]  = "1"
+    sandbox_env["APPDATA"]           = str(tmp_path / "AppData" / "Roaming")
+    sandbox_env["LOCALAPPDATA"]      = str(tmp_path / "AppData" / "Local")
+    sandbox_env["TEMP"] = sandbox_env["TMP"] = str(tmp_path / "Temp")
+    for p in (sandbox_env["APPDATA"], sandbox_env["LOCALAPPDATA"], sandbox_env["TEMP"]):
+        os.makedirs(p, exist_ok=True)
+
+    if not APP_TITLE:
+        pytest.exit("La variable de entorno APP_TITLE no está definida", returncode=1)
+
+    # shlex.split maneja argumentos entrecomillados con espacios; split() plano se rompe con ellos
+    import shlex
+    # Arranca vía subprocess para poder pasar env; conecta pywinauto por PID
+    proc = subprocess.Popen(
+        [APP_PATH] + shlex.split(APP_ARGS),
+        env=sandbox_env,
+    )
+    pw_app = Application(backend="uia").connect(process=proc.pid, timeout=LAUNCH_TIMEOUT)
+    win    = pw_app.window(title=APP_TITLE)
+    win.wait("visible", timeout=LAUNCH_TIMEOUT)
+    yield win
+
+    if getattr(getattr(request.node, "rep_call", None), "failed", False):
+        os.makedirs(ARTIFACT_DIR, exist_ok=True)
+        try:
+            win.capture_as_image().save(
+                os.path.join(ARTIFACT_DIR, f"FAIL_{request.node.name}.png")
+            )
+        except Exception:
+            pass
+    try:
+        win.close()
+        proc.wait(timeout=5)
+    except Exception:
+        proc.kill()
+    # pytest limpia tmp_path automáticamente
+
+@pytest.hookimpl(tryfirst=True, hookwrapper=True)
+def pytest_runtest_makereport(item, call):
+    outcome = yield
+    setattr(item, f"rep_{outcome.get_result().when}", outcome.get_result())
+```
+
+### Nivel 2 — Job Object de Windows (opcional: contención del ciclo de vida del proceso)
+
+Adjunta el proceso a un Job Object para que sea **terminado automáticamente** cuando el handle del job del fixture sea recolectado por el GC. También evita que la app genere procesos hijos que escapen a la limpieza del fixture.
+
+> **Alcance del aislamiento:** los Job Objects NO virtualizan el acceso al sistema de archivos ni bloquean el tráfico de red. El aislamiento de escritura de archivos y de red requiere AppContainer, reglas de Windows Firewall o el Nivel 3 (Windows Sandbox). Usa el Nivel 2 solo para contención del ciclo de vida del proceso y de procesos hijos.
+
+No requiere dependencias adicionales.
+
+```python
+import ctypes, ctypes.wintypes as wt
+
+def restrict_process(pid: int):
+    """
+    Adjunta el proceso a un Job Object que le impide:
+    - generar procesos fuera del job (LIMIT_KILL_ON_JOB_CLOSE)
+    NO bloquea la red — usa reglas de Windows Firewall para eso.
+    """
+    JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x00002000
+    # Derechos mínimos: SET_QUOTA (0x0100) | TERMINATE (0x0001)
+    PROCESS_SET_QUOTA_AND_TERMINATE    = 0x0101
+
+    kernel32 = ctypes.windll.kernel32
+    job   = kernel32.CreateJobObjectW(None, None)
+    hproc = kernel32.OpenProcess(PROCESS_SET_QUOTA_AND_TERMINATE, False, pid)
+
+    # Layout correcto de la estructura — LimitFlags está en el offset +16, no +44
+    class JOBOBJECT_BASIC_LIMIT_INFORMATION(ctypes.Structure):
+        _fields_ = [
+            ("PerProcessUserTimeLimit", wt.LARGE_INTEGER),
+            ("PerJobUserTimeLimit",     wt.LARGE_INTEGER),
+            ("LimitFlags",             wt.DWORD),
+            ("MinimumWorkingSetSize",   ctypes.c_size_t),
+            ("MaximumWorkingSetSize",   ctypes.c_size_t),
+            ("ActiveProcessLimit",      wt.DWORD),
+            ("Affinity",               ctypes.c_size_t),
+            ("PriorityClass",          wt.DWORD),
+            ("SchedulingClass",        wt.DWORD),
+        ]
+
+    info = JOBOBJECT_BASIC_LIMIT_INFORMATION()
+    info.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE
+    ok = kernel32.SetInformationJobObject(job, 2, ctypes.byref(info), ctypes.sizeof(info))
+    if not ok:
+        raise ctypes.WinError()
+    kernel32.AssignProcessToJobObject(job, hproc)
+    kernel32.CloseHandle(hproc)
+    return job  # mantenlo vivo — el job se cierra (mata el proceso) al ser recolectado
+
+# Después de proc = subprocess.Popen(...):  job = restrict_process(proc.pid)
+```
+
+### Nivel 3 — Windows Sandbox (aislamiento de SO completo en CI)
+
+Cuando necesitas una imagen limpia de Windows por ejecución (sin claves de registro residuales, sin estado de GPU compartido, aislamiento real), ejecuta **la suite completa** dentro de [Windows Sandbox](https://learn.microsoft.com/windows/security/application-security/application-isolation/windows-sandbox/windows-sandbox-overview).
+
+**Requisito:** Windows 10/11 Pro o Enterprise, con virtualización habilitada.
+
+Crea `e2e-sandbox.wsb` en la raíz del proyecto:
+
+```xml
+<Configuration>
+  <MappedFolders>
+    <!-- Binario de la app (solo lectura) -->
+    <MappedFolder>
+      <HostFolder>C:\ruta\a\tu\build\Release</HostFolder>
+      <SandboxFolder>C:\app</SandboxFolder>
+      <ReadOnly>true</ReadOnly>
+    </MappedFolder>
+    <!-- Suite de tests (lectura-escritura para los artefactos) -->
+    <MappedFolder>
+      <HostFolder>C:\ruta\a\tu\e2e_test</HostFolder>
+      <SandboxFolder>C:\e2e_test</SandboxFolder>
+      <ReadOnly>false</ReadOnly>
+    </MappedFolder>
+  </MappedFolders>
+  <LogonCommand>
+    <!--
+      Windows Sandbox arranca sin Python. Instálalo en silencio primero,
+      luego instala las dependencias y ejecuta los tests. Los artefactos se
+      escriben de vuelta al host vía el MappedFolder de arriba.
+    -->
+    <Command>powershell -Command "
+      winget install --id Python.Python.3.11 --silent --accept-package-agreements;
+      $env:PATH += ';' + $env:LOCALAPPDATA + '\Programs\Python\Python311\Scripts';
+      cd C:\e2e_test;
+      pip install -r requirements.txt;
+      pytest tests\ -v
+    "</Command>
+  </LogonCommand>
+</Configuration>
+```
+
+Lanzamiento: `WindowsSandbox.exe e2e-sandbox.wsb`
+
+> pywinauto y la app corren ambos **dentro** del sandbox (se requiere la misma sesión).
+> Los artefactos se escriben de vuelta al host vía la carpeta mapeada.
+
+### Comparación de niveles
+
+| Nivel | Aislamiento | Costo de montaje | Funciona en CI | Úsalo cuando |
+|-------|-------------|------------------|----------------|--------------|
+| 1 — Redirección env a `tmp_path` | Sistema de archivos | Cero | Siempre | Por defecto para todos los tests |
+| 2 — Job Object | Árbol de procesos | Bajo | Siempre | Evitar fugas de procesos hijos |
+| 3 — Windows Sandbox | SO completo | Medio | Necesita imagen Pro/Enterprise | Ejecuciones nocturnas en sala limpia |
+
+### Prevenir tests colgados
+
+Añade `pytest-timeout` para acotar cualquier test individual. En `pytest.ini` define `timeout = 60` y `timeout_method = thread`. Nota: el método `thread` no puede matar subprocesos de apps Qt en Windows — añade `atexit.register(lambda: [p.kill() for p in psutil.Process().children(recursive=True)])` en `conftest.py` para recoger huérfanos.
+
+## Integración CI/CD
+
+```yaml
+# .github/workflows/e2e-desktop.yml
+name: Desktop E2E
+on: [push, pull_request]
+
+jobs:
+  e2e:
+    runs-on: windows-latest   # entorno GUI real, no hace falta Xvfb
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+
+      - name: Instalar dependencias
+        run: pip install pywinauto pytest pytest-html Pillow
+
+      - name: Compilar la app
+        run: cmake --build build --config Release  # ajusta a tu sistema de build
+
+      - name: Ejecutar E2E
+        env:
+          APP_PATH: ${{ github.workspace }}\build\Release\MyApp.exe
+          APP_TITLE: "My Application"
+          CI: "true"
+        run: pytest tests/ --html=artifacts/report.html --self-contained-html --junitxml=artifacts/results.xml -v
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: e2e-artifacts
+          path: artifacts/
+          retention-days: 14
+```
+
+## Particularidades de Qt
+
+### Habilitar UIA en Qt 5.x
+
+La accesibilidad de Qt 5.x está deshabilitada por defecto en algunos builds (especialmente 5.7–5.14). Define la variable de entorno **antes** de arrancar. Qt 6.x habilita la accesibilidad por defecto — omite este paso para Qt 6.
+
+```python
+# conftest.py — añadir al inicio del módulo
+import os
+os.environ["QT_ACCESSIBILITY"] = "1"
+```
+
+O expórtala en CI:
+
+```yaml
+env:
+  QT_ACCESSIBILITY: "1"
+```
+
+### Añadir identificadores estables a widgets Qt
+
+```cpp
+// Preferido: tanto objectName como accessibleName
+void setTestId(QWidget* w, const char* id) {
+    w->setObjectName(id);
+    w->setAccessibleName(id);  // se convierte en la propiedad Name de UIA
+}
+
+// En el constructor de tu diálogo:
+setTestId(ui->usernameEdit, "usernameInput");
+setTestId(ui->passwordEdit, "passwordInput");
+setTestId(ui->loginButton,  "btnLogin");
+setTestId(ui->errorLabel,   "lblError");
+```
+
+Centraliza todos los IDs en un header para evitar erratas:
+
+```cpp
+// test_ids.h
+#define TID_USERNAME   "usernameInput"
+#define TID_PASSWORD   "passwordInput"
+#define TID_BTN_LOGIN  "btnLogin"
+#define TID_LBL_ERROR  "lblError"
+```
+
+### Peculiaridades específicas de Qt
+
+**QComboBox** — el desplegable es una ventana de nivel superior separada:
+
+```python
+from pywinauto import Desktop
+
+def select_combo_item(page, combo_spec, item_text):
+    page.click(combo_spec)
+    # El desplegable aparece como una nueva ventana raíz
+    # class_name varía según la versión de Qt — verifica con Accessibility Insights
+    # Qt 5.x: "Qt5QWindowIcon"  |  Qt 6.x: "Qt6QWindowIcon" — verifica con Accessibility Insights
+    popup = Desktop(backend="uia").window(class_name_re="Qt[56]QWindowIcon")
+    popup.wait("visible", timeout=5)
+    popup.child_window(title=item_text).click_input()
+```
+
+**QMessageBox / QDialog** — también son ventanas de nivel superior separadas:
+
+```python
+dlg = page.wait_window("Confirm")          # espera el título del diálogo
+dlg.child_window(title="OK").click_input() # clic en el botón interior
+```
+
+**QTableWidget / QTableView** — acceso a filas/celdas:
+
+```python
+table = page.by_id("tblUsers").wrapper_object()
+cell  = table.cell(row=0, column=1)
+print(cell.window_text())
+```
+
+**Controles autodibujados** (`paintEvent` puro, `QGraphicsView`, `QOpenGLWidget`) — UIA no puede ver su interior. Usa la sección de fallback más abajo.
+
+## Fallback: modo de capturas
+
+Cuando un control no es alcanzable vía UIA (autodibujado, de terceros, motor de juego):
+
+```bash
+pip install pyautogui Pillow opencv-python
+```
+
+```python
+import pyautogui, cv2, numpy as np
+from PIL import Image
+
+def find_image_on_screen(template_path, confidence=0.85):
+    """Localiza una imagen plantilla en pantalla. Devuelve el centro (x, y) o None."""
+    screen   = np.array(pyautogui.screenshot())
+    template = np.array(Image.open(template_path))
+    result   = cv2.matchTemplate(
+        cv2.cvtColor(screen, cv2.COLOR_RGB2BGR),
+        cv2.cvtColor(template, cv2.COLOR_RGB2BGR),
+        cv2.TM_CCOEFF_NORMED,
+    )
+    _, max_val, _, max_loc = cv2.minMaxLoc(result)
+    if max_val >= confidence:
+        h, w = template.shape[:2]
+        return max_loc[0] + w // 2, max_loc[1] + h // 2
+    return None
+
+def click_image(template_path, confidence=0.85):
+    pos = find_image_on_screen(template_path, confidence)
+    if pos is None:
+        raise RuntimeError(f"Imagen no encontrada en pantalla: {template_path}")
+    pyautogui.click(*pos)
+```
+
+### Reglas de DPI / escalado (solo modo de capturas)
+
+El matching por capturas es brutalmente sensible al escalado de pantalla de Windows (100 % / 125 % / 150 %). Tres reglas duras:
+
+1. **Captura las plantillas a la misma escala que la máquina objetivo.** No intentes rescatar un desajuste con `PIL.Image.resize` — `cv2.matchTemplate` es muy frágil frente a artefactos de remuestreo.
+2. **Fija el escalado de pantalla en CI.** En `windows-latest` añade un paso como `Set-DisplayResolution 1920 1080 -Force` y deshabilita el escalado DPI por monitor, para que las dimensiones de las capturas sean reproducibles.
+3. **Registra la escala junto a cada artefacto.** Al capturar, escribe `GetDpiForWindow(hwnd) / 96` en `artifacts/<test>/metadata.json` — los postmortems se vuelven obvios en lugar de adivinanzas.
+
+> La conciencia de DPI a nivel de proceso (`SetProcessDpiAwarenessContext`) **puede entrar en conflicto con la gestión de DPI propia de Qt** cuando la app bajo prueba es Qt. Prefiere "plantillas a la misma escala + fijar CI" antes que cambiar el modo DPI de todo el proceso en los fixtures.
+
+### Depurar la confianza del match
+
+Al ajustar el umbral de `confidence`, el único flujo sensato es **ver** dónde cayó el match. El helper de abajo es solo para diagnóstico — no lo llames desde código de tests.
+
+```python
+def debug_match(template_path, out="artifacts/match_debug.png", confidence=0.85):
+    """Solo diagnóstico. Dibuja el rectángulo del mejor match + puntuación sobre la pantalla actual.
+
+    NO es para tests de producción — úsalo al calibrar la confianza o al perseguir falsos matches.
+    """
+    import os, cv2, pyautogui, numpy as np
+    screen = np.array(pyautogui.screenshot())[:, :, ::-1]
+    tpl    = cv2.imread(template_path)
+    if tpl is None:
+        raise RuntimeError(f"Plantilla ilegible: {template_path}")
+    res    = cv2.matchTemplate(screen, tpl, cv2.TM_CCOEFF_NORMED)
+    _, mv, _, ml = cv2.minMaxLoc(res)
+    h, w   = tpl.shape[:2]
+    colour = (0, 255, 0) if mv >= confidence else (0, 0, 255)  # verde pasa / rojo falla
+    cv2.rectangle(screen, ml, (ml[0]+w, ml[1]+h), colour, 2)
+    cv2.putText(screen, f"score={mv:.3f} thr={confidence}",
+                (ml[0], max(20, ml[1]-6)),
+                cv2.FONT_HERSHEY_SIMPLEX, 0.7, colour, 2)
+    os.makedirs(os.path.dirname(out) or ".", exist_ok=True)
+    cv2.imwrite(out, screen)
+    return mv
+```
+
+**Úsalo con moderación** — el matching de imágenes se rompe con cambios de DPI, cambios de tema y oclusión parcial.
+Intenta siempre UIA primero; cae a capturas solo para controles genuinamente inalcanzables.
+
+## Antipatrones
+
+```python
+# MAL: sleep fijo
+time.sleep(3)
+page.click(page.by_id("btnSubmit"))
+
+# BIEN: espera por condición
+page.wait_visible(page.by_id("btnSubmit"))
+page.click(page.by_id("btnSubmit"))
+```
+
+```python
+# MAL: localizador frágil clase+índice como estrategia primaria
+page.by_class("Edit", index=2).type_keys("hola")
+
+# BIEN: AutomationId
+page.by_id("usernameInput").set_edit_text("hola")
+```
+
+```python
+# MAL: aserciones sobre coordenadas de píxeles
+assert btn.rectangle().left == 120
+
+# BIEN: aserciones sobre contenido / estado
+assert page.get_text(page.by_id("lblStatus")) == "Logged in"
+assert page.by_id("btnLogout").is_enabled()
+```
+
+```python
+# MAL: compartir la instancia de la app entre todos los tests (fugas de estado)
+@pytest.fixture(scope="session")
+def app(): ...
+
+# BIEN: proceso fresco por test (o por clase como máximo)
+@pytest.fixture(scope="function")
+def app(): ...
+```
+
+## Ejecutar los tests
+
+```bash
+# Todos los tests
+pytest tests/ -v
+
+# Solo smoke
+pytest tests/ -m smoke -v
+
+# Un archivo específico
+pytest tests/test_login.py -v
+
+# Con ruta de app personalizada
+APP_PATH="C:\build\Release\MyApp.exe" APP_TITLE="MyApp" pytest tests/ -v
+
+# Detectar tests inestables (repetir cada uno 5 veces)
+pip install pytest-repeat
+pytest tests/test_login.py --count=5 -v
+```
+
+## Skills relacionadas
+
+- `testing-e2e` — E2E con Playwright para aplicaciones web
+- `testing-cpp` — testing unitario/de integración en C++ con GoogleTest
+- `estandares-cpp` — estilo y patrones de código C++