Runtime

La validación runtime confirma si las decisiones de dominio y API se comportan como se espera bajo el uso real de consultas. Es la capa donde tu modelo pasa del diseño a la ejecución — y donde detecta los problemas antes que tus consumidores.

Propósito del runtime

El runtime responde a preguntas prácticas tempranamente en tu proceso de desarrollo:

• ¿Las estructuras de campos son predecibles y consistentes?
• ¿Las resoluciones de relaciones son coherentes y correctamente anidadas?
• ¿Las suposiciones de paginación y ordenamiento se sostienen con datos reales?
• ¿Las expresiones de filtro coinciden con el subconjunto correcto de registros?
• ¿Los valores null se tratan como tus consumidores esperan?

Al validar estos comportamientos durante el modelado — no después de la implementación — elimina toda una categoría de errores de integración.

rt-01-query-playgroundMissing

Panel de consulta runtime para pruebas de comportamiento en vivo.

Cómo funciona el mock runtime

El motor de mock runtime es el núcleo de Mockomat. Acepta consultas GraphQL y las traduce en operaciones MongoDB mediante una pipeline de cuatro etapas:

1. GraphQL Request Parser

La cadena de consulta entrante se parsea en un árbol de sintaxis abstracta (AST). Esta etapa valida la sintaxis de la consulta y extrae los campos solicitados, argumentos y selecciones anidadas.

2. Query Planner

El AST se analiza conjuntamente con los metadatos de tu modelo (definiciones de entidades, flags de atributos, configuraciones de relaciones) para crear un plan de ejecución. El planificador determina:

• Qué colecciones MongoDB consultar
• Qué campos proyectar
• Qué operaciones de filtrado y ordenamiento aplicar
• Qué relaciones necesitan resolverse

3. MongoDB Query Builder

El plan de ejecución se traduce en una pipeline de agregación MongoDB. Como MongoDB almacena los datos en colecciones planas (desnormalizadas), el query builder simula las estructuras relacionales:

• Etapas de lookup — ensamblan datos relacionados entre colecciones
• Etapas de match — aplican las expresiones de filtro
• Etapas de sort — ordenan los resultados según los campos solicitados
• Etapas de skip y limit — gestionan la paginación

4. Result Assembler

Los resultados brutos de MongoDB se reestructuran para coincidir con la estructura de respuesta GraphQL esperada. Las relaciones anidadas se ensamblan en la jerarquía padre-hijo correcta, y los nombres de campos se asocian a sus equivalentes GraphQL.

Esta pipeline se ejecuta en cada consulta. Lo que ves en la previsualización es exactamente lo que los consumidores externos recibirán del mismo endpoint.

rt-01b-runtime-pipelineMissing

Pipeline runtime de cuatro etapas: Parse → Plan → Build → Assemble.

Ejemplos de consultas

Todas las consultas usan el mismo endpoint:

POST /mock/{slug}/graphql

Consulta de lista

Obtener una colección paginada de registros:

query {
  products(offset: 0, limit: 20) {
    id
    name
    price
    category {
      id
      name
    }
  }
}

Consulta de detalle

Obtener un solo registro por su identificador:

query {
  product(id: "abc-123") {
    id
    name
    price
    description
    category {
      id
      name
    }
  }
}

Consulta con filtrado

Aplicar expresiones de filtro para refinar los resultados:

query {
  products(
    filter: {
      filterGroup: {
        operator: AND
        items: [
          { attribute: "price", operator: GE, value: "10" }
          { attribute: "price", operator: LE, value: "50" }
        ]
      }
    }
    limit: 10
  ) {
    id
    name
    price
  }
}

Consulta con ordenamiento

Ordenar resultados por un campo ordenable:

query {
  products(
    sort: { field: "price", direction: DESC }
    limit: 10
  ) {
    id
    name
    price
  }
}

Consulta con relaciones anidadas

Recorrer relaciones para incluir datos relacionados:

query {
  customers(limit: 5) {
    id
    firstName
    lastName
    orders {
      id
      totalAmount
      createdAt
      items {
        id
        productName
        quantity
      }
    }
  }
}

Filtrado en detalle

El sistema de filtrado soporta expresiones tipadas y combinables que pueden combinarse con lógica booleana.

Operadores disponibles

Operador	Descripción	Funciona con
EQ	Igual	Todos los tipos
NE	No igual	Todos los tipos
LT	Menor que	Números, fechas
GT	Mayor que	Números, fechas
LE	Menor o igual	Números, fechas
GE	Mayor o igual	Números, fechas
LIKE	Contiene subcadena	Cadenas
IS_NULL	El campo es null	Todos los tipos
IS_NOT_NULL	El campo no es null	Todos los tipos

Combinar filtros

Los filtros usan álgebra booleana con los operadores AND y OR. Los grupos de filtros pueden anidarse para expresiones complejas:

filter: {
  filterGroup: {
    operator: OR
    groups: [
      {
        operator: AND
        items: [
          { attribute: "status", operator: EQ, value: "active" }
          { attribute: "price", operator: GT, value: "100" }
        ]
      }
      {
        operator: AND
        items: [
          { attribute: "status", operator: EQ, value: "featured" }
        ]
      }
    ]
  }
}

Este ejemplo devuelve los productos que son (activos Y caros) O destacados.

Campos filtrables

Solo los atributos marcados como filterable: true en el modelo pueden usarse en expresiones de filtro. Intentar filtrar por un campo no filtrable no tiene efecto. Configura los flags de filtrable en el editor de tablas del workspace.

Paginación

Mockomat usa paginación basada en offset:

Parámetro	Descripción	Predeterminado
offset	Número de elementos a saltar	0
limit	Número de elementos a devolver	20

Una consulta paginada típica:

query {
  products(offset: 40, limit: 20) {
    id
    name
    price
  }
}

Esto devuelve los elementos 41 a 60. Para obtener la página siguiente, aumenta el offset en el valor del limit.

Ordenamiento

Los campos marcados como sortable: true en el modelo pueden usarse para ordenar los resultados.

Dirección	Significado
ASC	Ascendente (A→Z, 0→9, más antiguo→más reciente)
DESC	Descendente (Z→A, 9→0, más reciente→más antiguo)

Un solo campo de ordenamiento puede aplicarse por consulta. Si no se especifica ordenamiento, los resultados se devuelven en su orden natural de almacenamiento.

Recorrido de relaciones

Una de las funcionalidades más poderosas del runtime es su capacidad de simular datos relacionales a partir de colecciones MongoDB planas.

Cómo funciona

MongoDB almacena datos en colecciones desnormalizadas — cada registro es un documento plano sin uniones de clave foránea. El runtime simula las estructuras relacionales mediante:

1. Lectura de la definición de relación desde tu modelo (entidad origen, entidad destino, cardinalidad).
2. Construcción de etapas de lookup en la pipeline de agregación MongoDB que unen las colecciones relacionadas.
3. Ensamblaje de resultados anidados que coinciden con la estructura de respuesta GraphQL.

Esto significa que tus consultas GraphQL se comportan como si se ejecutaran contra una base de datos completamente relacional, aunque el almacenamiento subyacente sea basado en documentos.

Qué validar

Al verificar el recorrido de relaciones:

• Relaciones 1:1 deben devolver un solo objeto anidado (o null si no hay coincidencia).
• Relaciones 1:n deben devolver un arreglo de objetos anidados.
• Relaciones vacías deben devolver un arreglo vacío [], no null.
• Relaciones profundamente anidadas (ej. Customer → Order → OrderItem) deben resolverse correctamente en cada nivel.

Lista de verificación del comportamiento de consultas

Para cada entidad clave de tu modelo, valida:

• Estabilidad de consultas de lista — ¿la misma consulta devuelve una estructura consistente en llamadas repetidas?
• Consistencia de elementos individuales — ¿una consulta de detalle devuelve todos los campos esperados?
• Comportamiento de campos null y faltantes — ¿los campos opcionales están correctamente representados como null?
• Recorrido de relaciones — ¿los objetos anidados se resuelven con la cardinalidad correcta?
• Precisión de filtros — ¿las expresiones de filtro coinciden con el subconjunto esperado?
• Exactitud del ordenamiento — ¿el ordenamiento produce un orden predecible y estable?
• Límites de paginación — ¿offset y limit producen porciones de página limpias sin duplicados?

rt-02-filter-sort-paginationMissing

Validación del comportamiento de filtrado, ordenamiento y paginación.

Inspección y depuración runtime

Cuando el comportamiento parece incorrecto, inspecciona en este orden:

1. Verificar definiciones de tablas y atributos

La causa más común de comportamiento inesperado es un atributo mal configurado:

• ¿El tipo de campo es correcto? (Un precio almacenado como string no se ordenará numéricamente.)
• ¿El campo está marcado como ordenable/filtrable/buscable?
• ¿El campo tiene una asociación configurada?

2. Verificar metadatos de endpoint y consulta

Comprueba que la consulta está correctamente configurada en la vista de diseño API:

• ¿La consulta está activada?
• ¿El nombre y los parámetros de la consulta son correctos?
• ¿La configuración de paginación es apropiada?

3. Verificar el estado de la asociación de la fuente

Si los campos devuelven null o valores inesperados:

• ¿El tipo de asociación es correcto (OFF_FIELD, FAKE, CONST)?
• Para las asociaciones OFF_FIELD, ¿el registro fuente contiene los datos esperados?
• Para las asociaciones FAKE, ¿el generador Faker está configurado para el tipo de datos correcto?

4. Verificar las políticas de relaciones

Si los datos anidados faltan o son incorrectos:

• ¿La dirección de la relación es correcta (origen → destino)?
• ¿La cardinalidad coincide (1:1 vs 1:n)?
• ¿La entidad destino existe y tiene datos asociados?
• ¿Las columnas de unión están correctamente especificadas?

Problemas comunes y soluciones

Síntoma	Causa probable	Solución
Respuesta vacía	No hay datos importados para esa colección	Verificar que la importación de datos esté completa
Campos que devuelven null	Ninguna asociación configurada	Agregar una asociación OFF_FIELD, FAKE o CONST
Relación anidada vacía	Relación mal configurada	Verificar la dirección, entidad destino y columnas de unión
El ordenamiento no funciona	Campo no marcado como ordenable	Activar el flag de ordenable en el editor de tabla
El filtro devuelve todo	Campo no marcado como filtrable	Activar el flag de filtrable en el editor de tabla
Tipos de datos incorrectos	Incompatibilidad de tipo de asociación	Verificar que la asociación produce el tipo esperado
La paginación salta elementos	Error de cálculo de offset	Verificar que los incrementos de offset coincidan con el valor del limit

rt-03-runtime-inspectionMissing

Flujo de inspección runtime y puntos de control de depuración.

Validación antes de la exportación

El runtime debe confirmar la disponibilidad antes de pasar a la generación de código backend. Un modelo que pasa la validación runtime tiene significativamente más probabilidades de producir un backend generado limpio y funcional.

Criterios de disponibilidad

Antes de la exportación, confirma que:

• Los campos obligatorios son estables — todos los atributos obligatorios tienen valores consistentes y no-null.
• La superficie de operaciones es intencional — solo las consultas que deseas exponer están activadas.
• El comportamiento de las relaciones es explicable — cada consulta anidada se resuelve correctamente y la cardinalidad coincide con tus reglas de negocio.
• El comportamiento de filtros y ordenamiento es predecible — los consumidores pueden confiar en el funcionamiento documentado de estas operaciones.
• No hay indicaciones sin resolver — la previsualización no muestra advertencias sobre atributos no asociados o configuración faltante.

Flujo de validación pre-exportación

1. Ejecutar consultas de lista para cada entidad — verificar la estructura y calidad de datos.
2. Ejecutar consultas de detalle para las entidades clave — verificar la completitud de campos.
3. Probar todos los filtros configurados — verificar el subconjunto correcto.
4. Probar el ordenamiento en cada campo ordenable — verificar el orden.
5. Probar los límites de paginación — verificar transiciones de página limpias.
6. Probar consultas de relaciones anidadas — verificar el ensamblaje correcto en cada nivel.

rt-04-runtime-validationMissing

Resumen de validación runtime pre-exportación.

Consejo para integradores

Developer / Integrator

Usa la validación runtime como verificación de contrato antes de integrar consumidores frontend o downstream. El endpoint runtime proporciona los mismos datos en previsualización y a los consumidores externos, así que lo que validas en el workspace es exactamente lo que tu aplicación recibirá. Esto reduce considerablemente el esfuerzo de integración.

Expectativas runtime enterprise

Enterprise User

Los equipos enterprise deben tratar la validación runtime como un gate de calidad formal. Define criterios de validación por entidad (campos obligatorios, profundidad de relaciones, cobertura de filtros) e integra las verificaciones runtime en tu proceso de revisión antes de que los modelos sean aprobados para uso en producción.