fn_registry/.claude/commands/e2e-cpp.md

# /e2e-cpp — Crear/ejecutar tests e2e para apps C++

Genera y corre tests e2e con **Dear ImGui Test Engine** sobre las apps C++ del registry. Cada app gana un ejecutable `<app>_tests` que reabre la app dentro de un harness de testing y ejecuta scripts de UI (clicks, escritura, asserts) sobre los componentes ImGui.

Suite ya instalada en `cpp/vendor/imgui_test_engine/`. Integracion en framework: `fn::run_app_test()` (ver `cpp/framework/app_base.h`). Opt-in via `-DFN_BUILD_TESTS=ON`. Sin la opcion los builds normales de `/compile` no cambian.

## Argumento

`$ARGUMENTS` — formato libre. Casos:

- `<app_name>` — solo el nombre. Si la app ya tiene tests, los ejecuta. Si no, pide al usuario que describa el flujo a testear.
- `<app_name> <descripcion del flujo>` — genera un test nuevo para ese flujo y lo ejecuta. Ej: `chart_demo abrir cada tab y verificar que renderiza`.
- vacio — detectar app desde `pwd` (si estas en `cpp/apps/<X>/` o `projects/*/apps/<X>/`); si no, listar apps disponibles.

## Pasos

### 1. Resolver app y directorio

```bash
ROOT=$HOME/fn_registry
ARGS="$ARGUMENTS"
APP_ARG="${ARGS%% *}"   # primera palabra
FLOW_DESC="${ARGS#* }"  # resto (puede coincidir con APP_ARG si solo hay una palabra)
[ "$FLOW_DESC" = "$APP_ARG" ] && FLOW_DESC=""

# Detectar desde CWD si no hay arg
if [ -z "$APP_ARG" ]; then
  CWD="$(pwd)"
  case "$CWD" in
    "$ROOT"/cpp/apps/*|"$ROOT"/projects/*/apps/*)
      APP_ARG="$(basename "$CWD")" ;;
  esac
fi

if [ -z "$APP_ARG" ]; then
  echo "Apps C++ disponibles:"
  ls "$ROOT"/cpp/apps/ 2>/dev/null
  ls "$ROOT"/projects/*/apps/ 2>/dev/null
  echo "Uso: /e2e-cpp <app> [descripcion del flujo]"
  exit 1
fi

APP_DIR=""
for cand in "$ROOT/cpp/apps/$APP_ARG" "$ROOT"/projects/*/apps/"$APP_ARG"; do
  [ -d "$cand" ] && [ -f "$cand/CMakeLists.txt" ] && APP_DIR="$cand" && break
done
[ -z "$APP_DIR" ] && { echo "App C++ no encontrada: $APP_ARG"; exit 1; }
echo "App: $APP_ARG"
echo "Dir: $APP_DIR"
```

### 2. Inspeccionar la app

Lee:
- `$APP_DIR/main.cpp` — identifica:
  - El nombre de la funcion principal de render (suele ser `render()` o `static void render()`).
  - El **window title** que aparece en `ImGui::Begin("...")` — sera el primer arg de `ctx->SetRef("...")` en los tests. Si tiene em-dash u otros UTF-8 no ASCII, anotar la secuencia de bytes (ej: `\xe2\x80\x94` para `—`).
  - Los IDs/labels de los widgets candidatos: tabs (`BeginTabItem`), botones (`Button`), inputs (`InputText`), checkboxes, etc.
- `$APP_DIR/app.md` — para entender el dominio y proposito.
- `$APP_DIR/CMakeLists.txt` — para saber que `.cpp` del registry enlaza la app (los tests linkearan los mismos).

### 3. Decidir tests a escribir

**Si `$FLOW_DESC` esta vacio**: pregunta al usuario que flujo testear. Sugiere 2-3 candidatos basados en los widgets vistos en main.cpp. NO inventes flujos sin confirmacion.

**Si `$FLOW_DESC` viene en el comando**: convierte la descripcion en una secuencia de pasos atomicos del Test Context API. Ejemplos canonicos:

| Descripcion humano | Llamada Test Engine |
|---|---|
| "abrir tab X" | `ctx->ItemClick("##tabs/X")` o el path real del TabBar |
| "escribir 'hola' en el input search" | `ctx->ItemInput("Search", "hola")` |
| "click boton Aceptar" | `ctx->ItemClick("Aceptar")` |
| "verificar que aparece el modal Y" | `IM_CHECK(ctx->WindowInfo("Y").ID != 0)` |
| "checkbox Z marcado" | `IM_CHECK(ctx->ItemIsChecked("Z"))` |
| "menu File > Open" | `ctx->MenuClick("File/Open")` |

Ver `cpp/vendor/imgui_test_engine/imgui_te_context.h` para el catalogo completo de helpers.

### 4. Preparar la app para tests (idempotente)

Si es la primera vez que la app gana tests, hay que:

**a) Hacer la funcion render() linkable desde otra TU**

```cpp
// Antes:    static void render() { ... }
// Despues:  void render() { ... }
```

**b) Excluir `int main()` con guarda `FN_TEST_BUILD`**

```cpp
#ifndef FN_TEST_BUILD
int main() {
    return fn::run_app({...}, render);
}
#endif
```

Verifica con `grep -n "FN_TEST_BUILD\|^static void render" "$APP_DIR/main.cpp"`. Si ya esta, no toques nada.

### 5. Generar/extender el archivo de tests

`$APP_DIR/tests/<app>_tests.cpp` — un solo archivo por app, varias `IM_REGISTER_TEST` dentro de `register_tests()`.

**Plantilla**:

```cpp
// E2E tests para <app> — Dear ImGui Test Engine.
// Construido solo con -DFN_BUILD_TESTS=ON. Reusa el mismo main.cpp con
// FN_TEST_BUILD definido para excluir su int main().

#include "app_base.h"
#include "imgui.h"
#include "imgui_te_engine.h"
#include "imgui_te_context.h"

void render();   // definido en <app>/main.cpp

static void register_tests(ImGuiTestEngine* e) {
    ImGuiTest* t = nullptr;

    t = IM_REGISTER_TEST(e, "<app>", "<test_name>");
    t->TestFunc = [](ImGuiTestContext* ctx) {
        ctx->SetRef("<window_title_exacto>");
        // ... pasos del flujo
    };

    // mas tests aqui
}

int main() {
    fn::AppConfig cfg{};
    cfg.title  = "<app>_tests";
    cfg.width  = 1280;
    cfg.height = 800;
    return fn::run_app_test(cfg, render, register_tests);
}
```

Si el archivo ya existe: **AGREGA** un nuevo `IM_REGISTER_TEST` dentro de la funcion `register_tests` existente. NO sobreescribas tests previos.

### 6. Actualizar CMakeLists.txt (idempotente)

Si `$APP_DIR/CMakeLists.txt` no tiene aun el bloque de tests, agregar al final:

```cmake
# --- E2E tests (opt-in via -DFN_BUILD_TESTS=ON) ---
if(FN_BUILD_TESTS)
    add_imgui_app(<app>_tests
        main.cpp
        tests/<app>_tests.cpp
        # mismos .cpp del registry que la app principal
        ${CMAKE_SOURCE_DIR}/functions/<dom>/<func>.cpp
        ...
    )
    target_compile_definitions(<app>_tests PRIVATE FN_TEST_BUILD)
endif()
```

Las fuentes deben replicar las del target principal (mismas funciones del registry). Si la app ya tiene un bloque `if(FN_BUILD_TESTS)`, no lo dupliques.

### 7. Build

```bash
cd "$ROOT/cpp"
cmake -S . -B build/linux_tests -DFN_BUILD_TESTS=ON 2>&1 | tail -5
cmake --build build/linux_tests --target ${APP_ARG}_tests -j4 2>&1 | tail -20
```

Si el build falla:
- Errores de compilacion en `tests/...cpp` → revisa nombres de widgets/paths con el codigo real de main.cpp.
- "undefined reference to render" → falta quitar `static` o falta el `#ifndef FN_TEST_BUILD` en main.cpp.
- "multiple definition of main" → falta el `target_compile_definitions(... FN_TEST_BUILD)` en CMakeLists.

### 8. Ejecutar (headless en WSL)

WSL no tiene GLX 4.3 nativo — los tests corren bajo `xvfb` con software renderer Mesa. Wrapper canonico:

```bash
cd "$ROOT/cpp/build/linux_tests"
TEST_BIN="$(find . -name "${APP_ARG}_tests" -type f -executable | head -1)"
[ -z "$TEST_BIN" ] && { echo "no encuentro el binario de tests"; exit 1; }

timeout 90 xvfb-run -a -s "-screen 0 1280x800x24" \
    env LIBGL_ALWAYS_SOFTWARE=1 GALLIUM_DRIVER=llvmpipe \
    "$TEST_BIN" 2>&1
EXIT=$?
echo "EXIT: $EXIT"
```

Si en el host el usuario tiene GL nativo y `DISPLAY` funciona, el wrapper xvfb-run sigue siendo seguro (ejecuta dentro de su propio display).

### 9. Reportar

- Si `EXIT == 0` y la salida contiene `Tests Result: OK` → reporta `N/M tests passed` con la lista de tests ejecutados.
- Si `EXIT != 0` → muestra el bloque de log del test fallido (test engine imprime el path del widget que no encontro, el archivo y la linea del IM_CHECK que fallo). Sugiere correcciones (widget renombrado, path mal escrito, race entre frames — usar `ctx->Yield()`).

### 10. Despues de añadir tests

NO ejecutes `fn index` automaticamente — los tests no son funciones del registry, son artefactos de la app. Si el usuario los queria persistir, ya los tiene en `<app_dir>/tests/`.

Si la app es un sub-repo (lo normal segun ADR 0002), recordar al usuario que los archivos nuevos viven dentro del repo de la app y necesitan un commit alli (no en `fn_registry`).

## Referencias

- API de Test Context: `cpp/vendor/imgui_test_engine/imgui_te_context.h`
- API del engine: `cpp/vendor/imgui_test_engine/imgui_te_engine.h`
- Implementacion del harness: `cpp/framework/app_base.cpp` (funcion `fn::run_app_test`)
- Ejemplo canonico: `cpp/apps/chart_demo/tests/chart_demo_tests.cpp`
- Licencia del test engine: personal/open-source gratis (`cpp/vendor/imgui_test_engine/LICENSE.txt`)