Casos de uso

Descripción general

Casos de uso es la biblioteca central donde se definen los escenarios que luego se van a probar contra un agente de IA. Cada caso describe una situación concreta —una consulta típica, un flujo conversacional, una validación de negocio, un escenario límite— y se compone de una secuencia de pasos con el comportamiento esperado que el evaluador usará como referencia.

Es el insumo obligatorio del módulo Ejecuciones: sin al menos un caso cargado no se puede lanzar una corrida. La calidad del testing depende directamente de cómo estén redactados los casos, porque son la fuente sobre la que el Agent Tester emite sus veredictos.

El módulo cumple el rol de fuente de verdad de lo que se prueba, no de dónde se almacenan resultados (eso lo maneja Ejecuciones). Los casos son reutilizables: un mismo caso puede ejecutarse contra distintos agentes o versiones sin tener que duplicarse.

Para quién es este módulo

• QA y analistas funcionales que diseñan y mantienen la batería de pruebas.
• Product managers que definen el comportamiento esperado del agente.
• Desarrolladores y prompt engineers que usan los casos para validar cambios.
• Administradores técnicos que hacen cargas masivas desde Excel.

No se requieren permisos especiales más allá de una sesión activa en Verifi. El aislamiento de datos es por idClient: cada cliente ve y administra solamente su propia biblioteca.

Acceso al módulo

Desde el menú lateral, opción Casos de uso (ruta /dashboard/casos-de-uso).

Requiere sesión activa. Los casos visibles están filtrados automáticamente por el idClient del usuario; no existe una vista global ni un selector de cliente en la UI.

Cómo funciona el módulo

Cada caso de uso se compone de:

• Nombre (obligatorio, hasta 255 caracteres). Identificador corto y descriptivo.
• Descripción (opcional, texto libre). Contexto general del escenario.
• Comportamiento esperado general (opcional, texto libre). Resultado final que debería lograr el agente al completar el caso.
• Pasos (uno o más, ordenados secuencialmente). Cada paso contiene:
  • Descripción (obligatoria): la entrada o acción que se le enviará al agente.
  • Comportamiento esperado (opcional): qué debería responder el agente en ese paso.
  • Ejemplo de error (opcional): una respuesta que el evaluador debe reconocer como incorrecta.

Al lanzar una ejecución, Verifi congela una fotografía (snapshot) del caso en el momento exacto de la corrida: copia nombre, descripción, comportamiento esperado y la lista de pasos. Ese snapshot queda asociado a la ejecución y es inmutable. Editar o eliminar el caso original no altera las ejecuciones pasadas: cada una conserva la versión exacta que se usó.

Consideración técnica: el campo Ejemplo de error de cada paso no se incluye en el snapshot que recibe el Agent Tester. Se usa como guía para quien redacta el caso y puede aparecer en la evidencia, pero no forma parte del payload evaluativo.

Tareas más comunes

Crear un caso de uso

1. Hacer clic en Nuevo caso de uso.
2. Completar el nombre (obligatorio).
3. Opcionalmente completar descripción.
4. Agregar los pasos. Cada paso nuevo aparece con su número automáticamente asignado. Para cada uno, completar al menos la descripción.
5. Opcionalmente completar el comportamiento esperado general.
6. Guardar con Crear caso de uso.

Validaciones que bloquean el guardado:

• Nombre vacío.
• Ningún paso con descripción no vacía (los pasos vacíos se filtran antes de enviar).

Si la validación falla, aparece el toast Por favor completa el nombre y al menos un paso y no se envía nada al servidor.

Los pasos se renumeran automáticamente al guardar en orden 1, 2, 3... por lo que no hay que preocuparse por saltos o huecos aun si se eliminan pasos intermedios antes de guardar.

Editar un caso de uso

1. En la tabla, abrir el menú de tres puntos de la fila y seleccionar Editar.
2. El formulario aparece pre-cargado con los datos actuales.
3. Modificar los campos o los pasos. Se pueden agregar, editar o eliminar pasos. Siempre queda al menos uno visible.
4. Guardar con Actualizar caso de uso.

Importante: al actualizar un caso con nuevos pasos, internamente los pasos anteriores se eliminan por completo y se crean los nuevos. Esto significa que los identificadores internos de los pasos cambian. No afecta al usuario funcional, pero puede ser relevante si alguna integración externa hace referencia directa a esos identificadores.

Eliminar un caso de uso

1. Abrir el menú de tres puntos de la fila y seleccionar Eliminar.
2. Confirmar en el diálogo ¿Estás seguro? Esta acción no se puede deshacer....

La eliminación es física y en cascada: se borran tanto el caso como todos sus pasos asociados. Las ejecuciones históricas que lo usaron mantienen su snapshot intacto, por lo que sus reportes siguen siendo navegables aun después de eliminar el caso.

Buscar un caso de uso

Usar el buscador superior. La búsqueda se aplica sobre los campos nombre y descripción en forma case-insensitive. Es instantánea (sin debounce) y se ejecuta en el cliente sobre el conjunto ya cargado. Al cambiar el criterio, la paginación vuelve automáticamente a la página 1.

La lista se pagina en bloques de 10 casos por página (valor fijo). Los controles inferiores permiten navegar entre páginas.

Importar desde Excel

Pensado para cargas iniciales grandes o migraciones desde documentos de QA preexistentes.

1. Hacer clic en Importar desde Excel.
2. Descargar la plantilla oficial con el botón Descargar plantilla (incluye ejemplos precargados).
3. Completar el archivo respetando la estructura de columnas.
4. Arrastrar el archivo al área de carga o hacer clic para seleccionarlo. Formatos admitidos: .xlsx, .xls, .csv.
5. Verifi procesa el archivo en el navegador y muestra una vista previa con el estado de cada fila.
6. Revisar el resumen de casos válidos vs. casos con errores. Las filas inválidas muestran un ícono rojo; al pasar el cursor se listan los motivos.
7. Confirmar con Importar N casos válidos. Solo se importan las filas marcadas como válidas.

Durante la importación:

• Los casos se crean de a uno (no en batch). Si alguno falla por error del servidor, los demás igual se crean.
• El resultado final puede ser éxito total (N casos de uso importados exitosamente) o parcial (X casos importados, Y fallaron).

Estructura del archivo Excel

La plantilla contempla hasta 10 pasos por caso y valida los encabezados literalmente (trimeo y case-insensitive sobre "Nombre"). Los encabezados esperados son:

Si un encabezado no coincide, el parser rechaza el archivo completo con un mensaje del tipo Encabezado incorrecto en columna A: esperado "Nombre", encontrado "(vacío)". En ese caso, el modal ofrece re-descargar la plantilla correcta.

Validaciones por fila:

• Nombre vacío → El nombre es requerido.
• Sin ningún paso con descripción → Se requiere al menos un paso.

Las filas vacías se ignoran silenciosamente. Las filas parciales (con algunos campos completos) se procesan si pasan las validaciones mínimas.

Campos y configuraciones importantes

El orden de los pasos define el flujo conversacional que seguirá el agente durante la ejecución. Los números se asignan automáticamente de manera secuencial (1, 2, 3, ...).

Resultados esperados

Al crear o editar un caso correctamente:

• Aparece en la lista con el conteo de pasos y un extracto del comportamiento esperado.
• Queda disponible de inmediato para ser seleccionado en el wizard de una nueva ejecución.
• Se registra un evento de auditoría en el sistema interno (Caso de uso creado/actualizado/eliminado), asociado al usuario que ejecutó la acción.

Al importar desde Excel:

• Se crea un caso nuevo por cada fila válida. No hay deduplicación: importar dos veces el mismo archivo genera duplicados (mismo nombre, distinto identificador interno).
• Un toast final indica cuántos casos se crearon y cuántos fallaron.

Al eliminar:

• El caso y sus pasos desaparecen de la biblioteca.
• Las ejecuciones históricas que lo usaron siguen siendo navegables porque trabajan sobre snapshots.

Problemas comunes y soluciones

El botón de guardar está deshabilitado o muestra toast de validación

• Verificar que el nombre no esté vacío.
• Verificar que al menos un paso tenga descripción no vacía. Los pasos solo con comportamiento esperado o ejemplo de error se descartan al guardar.

El servidor rechaza el guardado con error 400 mencionando Step numbers must be sequential

• Aparece cuando la numeración de pasos llega al backend con huecos (por ejemplo 1, 3, 5). El cliente renumera automáticamente antes de enviar, por lo que este error indica que alguna integración externa está enviando payloads mal formados.

La importación falla con error de formato

• Usar siempre la plantilla oficial. Modificar los encabezados hace que el parser rechace el archivo completo.
• Verificar que el archivo sea .xlsx, .xls o .csv.
• Si se usan archivos exportados desde otras herramientas, confirmar que los nombres de columna coincidan letra por letra (el parser hace trim y lower-case, pero no sinónimos).

Algunas filas del Excel aparecen con errores

• Pasar el cursor sobre el ícono rojo de la fila para ver la lista de errores detectados.
• Los errores más frecuentes son nombre vacío o pasos faltantes.
• Las filas válidas pueden importarse aun cuando otras estén marcadas como inválidas.

Importé un Excel con más de 10 pasos por caso

• Solo se consideran los primeros 10 pasos por caso (límite fijo del parser). Los pasos 11 en adelante se ignoran silenciosamente. Si se necesitan más pasos, dividir el caso o crearlo manualmente después.

No aparece un caso recién creado

• Revisar si hay un filtro de búsqueda activo.
• Los casos aparecen ordenados por fecha de creación descendente; si hay muchos, navegar a la primera página.

Edité un caso y una ejecución antigua sigue mostrando la versión anterior

• Es el comportamiento esperado. Cada ejecución conserva un snapshot inmutable del caso al momento de lanzarse. Para evaluar con la versión nueva, lanzar una nueva ejecución.

Quise eliminar un caso y el servidor retornó 404

• El caso pertenece a otro cliente o ya fue eliminado en otra sesión. Refrescar la lista.

Buenas prácticas

• Nombres específicos y únicos. Consulta de saldo — usuario autenticado es mejor que Caso 1 porque luego aparece en los reportes como referencia.
• Un caso, un objetivo. Si un caso prueba múltiples comportamientos independientes, conviene dividirlo para que el puntaje del reporte sea interpretable.
• Pasos chicos y verificables. Pasos que contienen varias acciones a la vez dificultan la evaluación; los evaluadores funcionan mejor cuando el comportamiento esperado es atómico.
• Comportamiento esperado en términos observables. El evaluador compara contra lo que está escrito; ambigüedad en el esperado produce evaluaciones inconsistentes.
• Usar Ejemplo de error para fallos recurrentes. Si se identificó un patrón de error típico del agente, dejarlo como ejemplo ayuda al equipo a reconocerlo en la revisión.
• Versionar la batería fuera de Verifi. Si se administran cientos de casos, mantener el Excel fuente bajo control de versiones permite reconstruir la biblioteca ante cambios grandes.
• Nomenclatura consistente. Prefijos por área (Ventas — ..., Soporte — ...) o por nivel de criticidad facilitan búsquedas.

Consideraciones importantes

• La eliminación de un caso es permanente desde la UI; no existe papelera ni soft-delete. Sí quedan referencias inmutables en las ejecuciones históricas.
• Los cambios en un caso no migran a ejecuciones ya realizadas. Para comparar el agente contra la versión nueva del caso, hay que lanzar una nueva ejecución.
• La lista se pagina en el cliente sobre el conjunto completo cargado. Con volúmenes muy altos (miles de casos) la experiencia puede degradarse.
• La importación desde Excel no detecta duplicados por nombre; los registros se crean siempre como nuevos.
• El campo Ejemplo de error es de uso documental: ayuda a quien redacta el caso y al equipo de revisión, pero no se incluye en el snapshot que recibe el Agent Tester al evaluar.
• Todos los eventos CRUD sobre casos generan un registro de auditoría en el sistema interno (fire-and-forget): crear, actualizar, eliminar. Esto permite trazabilidad posterior desde el sistema central de auditoría.

Resumen rápido

Casos de uso es la biblioteca reutilizable donde se definen los escenarios que se probarán sobre un agente. Cada caso es una secuencia numerada de pasos con su comportamiento esperado. Se pueden crear manualmente, editar y eliminar, o cargar masivamente desde Excel. Cada ejecución congela un snapshot del caso al momento de lanzarse, por lo que editar o eliminar no afecta los reportes históricos. La claridad en la redacción del caso es el principal factor que determina la calidad de las evaluaciones.