Tienes un endpoint de GraphQL y necesitas saber si funciona. No "el servidor está en línea", sino lo real: ¿la consulta user devuelve los campos que tu aplicación lee, una mutación createOrder realmente persiste un pedido y las formas se mantienen cuando cambias una variable? Una herramienta REST que solo conoce llamadas de ruta y verbo hace esto incómodo. GraphQL envía todo a una única URL como un cuerpo POST, por lo que necesitas un cliente que entienda el lenguaje de consulta en sí, te dé sugerencias de campos y te permita hacer aserciones sobre el JSON que regresa.
Apidog maneja GraphQL como un tipo de solicitud de primera clase, junto a HTTP, gRPC, WebSocket, SSE y SOAP. Esta guía te lleva a través de la construcción de una solicitud GraphQL desde cero: escribiendo una consulta, obteniendo el esquema para la autocompletado de código, pasando variables, ejecutando una mutación y haciendo aserciones sobre la respuesta. El ejemplo que se utiliza es una API de comercio electrónico donde consultas un usuario y sus pedidos, y luego creas un nuevo pedido. Si deseas conocer los antecedentes conceptuales de por qué GraphQL envía una única consulta tipada en lugar de muchos endpoints, la documentación oficial de GraphQL es la referencia canónica, y nuestra comparación de REST vs GraphQL cubre cuándo encaja cada uno.
Qué estás probando y por qué GraphQL es diferente
REST te da muchos endpoints, cada uno devolviendo una forma fija. GraphQL te da un único endpoint y permite al llamador solicitar exactamente los campos que desea. Esa flexibilidad es el punto clave, y también es lo que hace que las pruebas se sientan diferentes.
Dos cosas cambian. Primero, la solicitud es un documento de consulta en el cuerpo, no una URL que varías. Un GET /users/42 se convierte en una selección user(id: 42) { ... } enviada por POST. Segundo, GraphQL casi nunca devuelve un estado que no sea 200 para un error de negocio. Una consulta fallida aún regresa 200 OK con un array errors en el JSON. Por lo tanto, verificar el código de estado no es suficiente. Tienes que leer el cuerpo. Ese único hecho moldea cómo haces aserciones más adelante en esta guía.
Apidog te ofrece un tipo de cuerpo GraphQL dedicado, autocompletado de código consciente del esquema, variables para consultas reutilizables y las mismas herramientas de aserción y escenarios de prueba que usarías para REST. Diseñas y ejecutas la solicitud en la aplicación, luego la guardas en un escenario que puedes volver a ejecutar. Construyamos uno.
Crear una solicitud GraphQL en Apidog
Primero, descarga Apidog o ábrelo en tu navegador, luego abre tu proyecto. Si estás comenzando de nuevo, crea un proyecto para que la solicitud tenga dónde vivir.
Paso 1: Crea una nueva solicitud y cambia el cuerpo a GraphQL
Haz clic en el botón + y elige New Request (Nueva Solicitud). Esto abre el constructor de solicitudes estándar, el mismo que usarías para una llamada REST: método, URL, parámetros y Authorization.
Establece el método en POST y pega tu endpoint GraphQL en la barra de URL. Uno típico se ve así:
https://api.yourstore.com/graphql
Ahora dile a Apidog que esta es una solicitud GraphQL. En el área del cuerpo de la solicitud, haz clic en Body, luego selecciona GraphQL. El editor del cuerpo cambia a una vista consciente de GraphQL con un cuadro Query, que es donde reside el lenguaje de consulta.
Si tu endpoint necesita un token, abre la sección Authorization y añádelo allí, por ejemplo, un token Bearer. La autenticación en una solicitud GraphQL funciona igual que cualquier otra solicitud HTTP en Apidog, porque debajo del capó sigue siendo un HTTP POST.
Paso 2: Escribe tu primera consulta
En la pestaña Run, escribe tu consulta en el cuadro Query. Comienza con algo concreto. Aquí quieres un usuario y los pedidos asociados a él:
query GetUserWithOrders {
user(id: "usr_1024") {
id
name
email
orders {
id
total
status
createdAt
}
}
}
Esto solicita un usuario y una lista anidada de sus pedidos. Los nombres de los campos deben coincidir exactamente con el esquema de tu servidor. Si tu esquema lo llama emailAddress en lugar de email, esta consulta fallará. Ese es el trabajo del siguiente paso para evitarlo.
Paso 3: Obtener el esquema para la autocompletado de código
Adivinar los nombres de los campos es donde las pruebas de GraphQL se vuelven lentas. Apidog puede leer tu esquema para que el editor sugiera campos y tipos válidos mientras escribes, en lugar de que tengas que verificar un documento en otra pestaña.
Esta es una acción manual y bajo demanda. Haz clic en el botón Fetch Schema (Obtener Esquema) en el cuadro de entrada. Apidog ejecuta una consulta de introspección contra tu endpoint y extrae el sistema de tipos. Una vez que tiene éxito, se activa la autocompletado de código: comienza a escribir un campo dentro de una selección y obtendrás sugerencias de estilo IntelliSense para lo que realmente está disponible en ese tipo.
Dos cosas que vale la pena saber. La autocompletado de código no es automática; solo se activa después de hacer clic en Fetch Schema. Y si tu endpoint tiene la introspección deshabilitada (algunos servidores de producción lo hacen por seguridad), la obtención no devolverá un esquema, por lo que tendrás que escribir los campos a mano según tu propia documentación. Si la obtención funciona, vuelve a obtenerla después de cualquier cambio de esquema para que las sugerencias se mantengan actualizadas.
Paso 4: Ejecutarlo y leer la respuesta
Haz clic en Send (Enviar). La respuesta aparece en la mitad inferior de la interfaz. Un resultado saludable se ve así:
{
"data": {
"user": {
"id": "usr_1024",
"name": "Dana Whitfield",
"email": "dana@example.com",
"orders": [
{ "id": "ord_5001", "total": 89.90, "status": "SHIPPED", "createdAt": "2026-07-01T09:14:00Z" },
{ "id": "ord_5002", "total": 12.50, "status": "PENDING", "createdAt": "2026-07-12T16:03:00Z" }
]
}
}
}
Observa la clave data de nivel superior. Cada respuesta GraphQL anida tu resultado bajo data, y cualquier problema aparece en un array errors hermano. Ten en cuenta esa estructura, porque tus aserciones apuntarán a data.user..., no a la raíz.
Pasar variables para hacer la solicitud reutilizable
Programar "usr_1024" directamente en la consulta funciona una vez. Para una solicitud que ejecutarás repetidamente con diferentes usuarios y entornos, mueve ese valor a una variable. GraphQL tiene una sintaxis de variables de primera clase para esto, y Apidog la soporta. La sintaxis en sí es GraphQL estándar en lugar de una invención de Apidog, por lo que la documentación oficial de GraphQL sobre variables es la fuente de verdad.
Declara la variable en la firma de la consulta con un prefijo $ y un tipo, luego úsala en los argumentos:
query GetUserWithOrders($userId: ID!) {
user(id: $userId) {
id
name
orders {
id
total
status
}
}
}
Luego proporciona el valor como un pequeño objeto JSON de variables:
{
"userId": "usr_1024"
}
Ahora la misma consulta se ejecuta para cualquier usuario cambiando un valor JSON. Combina esto con las variables de entorno de Apidog y podrás apuntar la misma solicitud a entornos de desarrollo y producción sin editar la consulta. Esto es lo que convierte una llamada única en algo que puedes guardar, compartir y ejecutar en una suite.
Escribir una mutación para crear un pedido
Una mutación cambia los datos. En GraphQL no hay un protocolo o UI separado para ello; una mutación se escribe como GraphQL en el mismo cuadro Query, con la palabra clave mutation en lugar de query. Así que el flujo de trabajo que ya conoces se traslada directamente.
Aquí creas un pedido para el usuario que consultaste anteriormente:
mutation CreateOrder($input: CreateOrderInput!) {
createOrder(input: $input) {
id
total
status
createdAt
}
}
Las variables llevan la carga útil:
{
"input": {
"userId": "usr_1024",
"items": [
{ "sku": "TSHIRT-BLK-M", "quantity": 2 },
{ "sku": "MUG-CERAMIC", "quantity": 1 }
],
"currency": "USD"
}
}
Haz clic en Send (Enviar). Una buena respuesta muestra el pedido creado:
{
"data": {
"createOrder": {
"id": "ord_5003",
"total": 42.30,
"status": "PENDING",
"createdAt": "2026-07-15T10:22:11Z"
}
}
}
Debido a que las mutaciones escriben datos reales, ejecútalas en un entorno de prueba o staging, no en producción. Un patrón común es ejecutar la mutación, capturar el id devuelto, luego ejecutar tu consulta GetUserWithOrders nuevamente y confirmar que el nuevo pedido aparece en la lista. Ese bucle de consulta-mutación-consulta es una verificación realista de extremo a extremo, y es exactamente el tipo de cosa que querrás guardar como un escenario en la siguiente sección.
Hacer aserciones sobre la respuesta en lugar de revisarla a ojo
Leer JSON a mano está bien mientras exploras. Para una prueba que se ejecuta sin supervisión, necesitas aserciones que pasen o fallen por sí solas. Apidog te permite añadir aserciones a una solicitud para que una ejecución se juzgue automáticamente, que es lo que configuras en aserciones de API.
Para GraphQL, tres comprobaciones cubren la mayoría de los casos:
- Asegura que el estado HTTP sea
200. Necesario pero no suficiente, ya que GraphQL devuelve 200 incluso en errores de negocio. - Asegura que el campo
errorsesté ausente. Esta es la verdadera puerta de paso o fallo de GraphQL. Sierrorsexiste, la operación falló sin importar lo que diga el estado. - Haz aserciones sobre valores específicos dentro de
data, usando una ruta JSONPath como$.data.createOrder.statuses igual aPENDING, o$.data.user.orderstiene una longitud mayor que cero.
Esa combinación captura los modos de fallo que una comprobación solo de estado pasa por alto: una consulta que devuelve 200 con un array errors, o una que tiene éxito pero devuelve la forma incorrecta. Dirige tus aserciones de valor a la ruta anidada bajo data, coincidiendo con la estructura de respuesta que viste anteriormente.
Guardarlo en un escenario de prueba
Una única solicitud asertiva es una buena prueba de humo. La verdadera recompensa es encadenar solicitudes en un escenario: consultar al usuario, crear un pedido, luego consultar de nuevo para confirmar que se ha persistido. Los escenarios de prueba de Apidog te permiten secuenciar estos pasos, pasar datos entre ellos (capturar el id de la mutación, introducirlo en la consulta de confirmación) y ejecutar todo el flujo con un solo clic. El recorrido completo se encuentra en cómo escribir un escenario de prueba con Apidog.
A alto nivel: crea un nuevo escenario de prueba, añade tu consulta y mutación GraphQL como pasos en orden, extrae el id del pedido de la respuesta de la mutación en una variable, y haz referencia a esa variable en el paso final de la consulta. Adjunta las aserciones de la sección anterior a cada paso. Ahora tienes una prueba de regresión repetible para tu API GraphQL que un humano, un horario o un pipeline pueden ejecutar.
Para los equipos que sopesan GraphQL frente a otros estilos antes de comprometerse, nuestro desglose de REST vs GraphQL vs gRPC y el resumen de herramientas de prueba y simulación de GraphQL les ayudan a situar este flujo de trabajo en contexto. Y si tu pila también habla SOAP, el mismo patrón de solicitud y aserción se aplica en cómo probar APIs SOAP en Apidog.
Automatizar el flujo de trabajo con la CLI de Apidog
Una vez que tus escenarios GraphQL residen en el proyecto, puedes ejecutar los escenarios de prueba guardados del proyecto desde una terminal o un ejecutor de CI con la CLI de Apidog. Instálala e inicia sesión:
npm install -g apidog-cli
apidog login --with-token <tu-token>
Luego ejecuta un escenario guardado por id, apuntando a un entorno:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <id_escenario> -e <id_entorno> -r cli
Aquí -t es el ID del escenario de prueba, -e es el ID del entorno, y -r es el reportero (cli, html, o junit; sepáralos por comas, como -r html,cli, para más de uno). La CLI ejecuta escenarios guardados y suites de prueba desde tu proyecto en la nube e informa si pasa o falla, que es lo que conecta Apidog a una compilación. Una advertencia honesta: la documentación de la CLI confirma la ejecución de escenarios HTTP, y no especifica si los escenarios que contienen pasos GraphQL se ejecutan sin interfaz gráfica. Trata la CLI como tu motor para ejecuciones de regresión HTTP y para mantener las especificaciones sincronizadas a través de su comando import (OpenAPI, HAR, Postman y más), y haz tu trabajo de consulta, mutación y aserción de GraphQL en la aplicación. Consulta la guía de instalación de la CLI de Apidog para la configuración de tokens y la CLI de Apidog en un pipeline de GitHub Actions para conectarla a CI.
Preguntas frecuentes
¿Necesito un plan de pago para probar GraphQL en Apidog? La documentación de solicitudes GraphQL no limita esta característica a un nivel de plan, y tampoco establece una línea entre la nube y el autoalojamiento. Puedes empezar con el nivel gratuito: pruébalo gratis, no se requiere tarjeta de crédito, y consulta Apidog para conocer los detalles del plan actual.
¿Por qué mi solicitud GraphQL devuelve 200 pero aún así falla? Ese es el comportamiento normal de GraphQL. El transporte tuvo éxito, por lo que el estado HTTP es 200, pero la operación encontró un error de negocio o de validación que aparece en el array errors del cuerpo JSON. Siempre asegúrate de que errors esté ausente además de verificar el estado, como se cubre en aserciones de API.
¿Cómo obtengo sugerencias de campos mientras escribo una consulta? Haz clic en el botón Fetch Schema (Obtener Esquema) en el cuadro de entrada. Apidog inspecciona tu endpoint y habilita la autocompletado de código para que el editor sugiera campos y tipos válidos. Es un paso manual, no automático, así que haz clic una vez que tu URL de endpoint esté configurada, y vuelve a obtener el esquema después de cualquier cambio en el mismo.
¿Dónde van las mutaciones? No veo una pestaña separada para mutaciones. No hay una. Una mutación se escribe como GraphQL en el mismo cuadro Query, usando la palabra clave mutation en lugar de query. Pasa su carga útil a través de variables, luego haz clic en Send, al igual que una consulta.
¿Cómo paso diferentes valores sin reescribir la consulta? Usa variables GraphQL. Decláralas en la firma de la operación con un prefijo $ y proporciona un objeto JSON de valores. La sintaxis sigue la especificación estándar de GraphQL, y el soporte de variables de Apidog se combina con las variables de entorno para que una solicitud se ejecute en entornos de desarrollo y producción.
Conclusión
Probar GraphQL se reduce a unos pocos hábitos honestos: escribir la consulta en el cuadro Query, obtener el esquema para que el editor te ayude, mover los valores fijos a variables y hacer aserciones sobre el cuerpo en lugar de confiar en el código de estado. Ejecuta una mutación de la misma manera que ejecutas una consulta, luego encadena ambas en un escenario guardado para que la verificación se repita. Descarga Apidog para seguir los pasos, construye el flujo de usuario y pedidos anterior, y tendrás una prueba de regresión de GraphQL que podrás volver a ejecutar cada vez que tu esquema cambie.