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 los datos importados?
• ¿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, con una clave API del proyecto (los proyectos de invitado usan su token de compartición; consulta Integradores):

POST /mock/{slug}/graphql
Authorization: Bearer mck_your_api_key

El campo raíz es el nombre de una operación del diseño de API. Una consulta de lista selecciona sus registros dentro de items y puede añadir total, page y pageSize; una consulta de detalle selecciona los campos directamente. La respuesta incluye todos los atributos asociados de la tabla y sus relaciones: la selección no la reduce.

Consulta de lista

Obtener una colección paginada de registros:

query {
  products(page: 1, pageSize: 20) {
    items {
      id
      name
      price
      category {
        id
        name
      }
    }
    total
    page
    pageSize
  }
}

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

Pasa los parámetros que la operación define en el diseño de API — aquí minPrice (sobre price, gte) y maxPrice (sobre price, lte):

query {
  products(minPrice: 10, maxPrice: 50, pageSize: 10) {
    items {
      id
      name
      price
    }
    total
  }
}

Consulta con ordenamiento

Ordena los resultados con sortField (un nombre de atributo) y sortDirection:

query {
  products(sortField: "price", sortDirection: DESC, pageSize: 10) {
    items {
      id
      name
      price
    }
    total
  }
}

Consulta con relaciones anidadas

Las relaciones de la tabla vuelven anidadas, con un nivel de profundidad:

query {
  customers(pageSize: 5) {
    items {
      id
      firstName
      lastName
      orders {
        id
        totalAmount
        createdAt
      }
    }
    total
  }
}

Filtrado en detalle

Los filtros pertenecen a la operación: los defines en el diseño de API y el runtime los aplica en cada solicitud. Los filtros de alcance son condiciones fijas de la operación; los parámetros son argumentos que envía quien llama — cada uno ligado a un atributo y un operador, opcionalmente obligatorio o con un valor por defecto.

Operadores disponibles

Operador	Descripción	Funciona con
eq	Igual	Todos los tipos
neq	Distinto	Todos los tipos
gt / gte	Mayor que / mayor o igual	Números, fechas
lt / lte	Menor que / menor o igual	Números, fechas
in	Uno de los valores de una lista	Todos los tipos
like	Contiene (sin distinguir mayúsculas)	Cadenas
notIn	Ninguno de los valores de una lista (solo filtros de alcance)	Todos los tipos
isNull / isNotNull	Es null / no es null (solo filtros de alcance)	Todos los tipos

Combinar filtros

Todos los filtros de alcance y parámetros de una operación se combinan con AND: no hay OR ni anidamiento en el momento de la consulta. Pasa los valores de los parámetros en línea o como variables GraphQL:

query ProductsInRange($min: Float, $max: Float) {
  products(minPrice: $min, maxPrice: $max, pageSize: 20) {
    items {
      id
      name
      price
    }
    total
  }
}

Con las variables { "min": 10, "max": 50 }, esto devuelve los productos con un precio de 10 a 50.

Validación de parámetros

Un argumento que la operación no define se rechaza con BAD_USER_INPUT, igual que un parámetro obligatorio que falta y no tiene valor por defecto. Las operaciones sin parámetros ignoran los argumentos desconocidos. Define los parámetros en el diseño de API.

Búsqueda

searchTerm busca sin distinguir mayúsculas en todos los atributos marcados como buscables (hasta 64 caracteres):

query {
  products(searchTerm: "oak", pageSize: 10) {
    items {
      id
      name
    }
    total
  }
}

Paginación

Mockomat usa paginación por páginas:

Parámetro	Descripción	Predeterminado
page	Número de página, empezando en 1	1
pageSize	Registros por página, como máximo 100	Tamaño de página por defecto de la operación (25 salvo que se cambie)

Una consulta paginada típica:

query {
  products(page: 3, pageSize: 20) {
    items {
      id
      name
      price
    }
    total
    page
    pageSize
  }
}

Esto devuelve los registros 41 a 60. total cuenta todos los registros que coinciden, así que la última página es total / pageSize, redondeado hacia arriba.

Ordenamiento

Ordena con sortField (un nombre de atributo) y sortDirection:

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)

Solo puede aplicarse un campo de ordenamiento por consulta. Sin sortField se aplica el ordenamiento por defecto de la operación; si no tiene, los resultados llegan en el orden 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.
• Las relaciones anidadas se resuelven con un nivel de profundidad: un registro relacionado incluye sus propios atributos, no sus relaciones (Customer → Order funciona; las líneas del pedido no se incluyen). Cada registro padre recibe como máximo 50 registros relacionados.

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 — ¿page y pageSize 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.)
• Para la búsqueda: ¿el campo está marcado como buscable?
• Para el ordenamiento: ¿sortField es el nombre de un atributo vinculado a una columna de datos?
• ¿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 (Fuente de datos o Constante)?
• Para las asociaciones Fuente de datos, ¿el atributo está vinculado a la columna correcta de los datos importados y esa columna tiene valores para estos registros?
• Los valores constantes aparecen en cada fila, tanto en las filas de datos importados como en las filas compuestas a partir de pools de valores.
• En las asociaciones calculadas, el runtime no evalúa expresiones, por lo que un campo calculado no forma parte de la respuesta.

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	La tabla no está vinculada a datos importados (NOT_READY)	Vincular la tabla a datos importados en el panel Mappings del board
Campos que devuelven null	Ninguna asociación configurada	Vincular el atributo a una columna de los datos importados (asociación Fuente de datos)
Relación anidada vacía	Relación mal configurada	Verificar la dirección, entidad destino y columnas de unión
El ordenamiento no funciona	sortField no es un atributo asociado	Usar el nombre de un atributo asociado
El filtro devuelve todo	La operación no define ningún parámetro para ese argumento	Añadir el parámetro en el diseño de API
Tipos de datos incorrectos	Incompatibilidad de tipo de asociación	Verificar que la asociación produce el tipo esperado
La paginación salta elementos	pageSize cambió entre solicitudes	Mantener pageSize constante y avanzar page de 1 en 1

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 por los atributos con los que ordenan tus consumidores — 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.