theus-cli 0.2.83 → 0.2.85

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

@@ -1,879 +0,0 @@
----
-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++