Si tienes un esquema OpenAPI o GraphQL, Schemathesis puede convertirlo en miles de casos de prueba sin que escribas una sola aserción. Lee la especificación, genera entradas válidas y "salvajes", las dispara a tu API e informa dónde las respuestas rompen el contrato. Esta guía explica qué es Schemathesis, cómo instalarlo y ejecutarlo, qué significa realmente las pruebas basadas en propiedades y cómo encaja junto a un flujo de trabajo de pruebas funcionales y de contrato en Apidog.
¿Qué es Schemathesis?
Schemathesis es una herramienta de Python de código abierto que genera pruebas de API automáticamente a partir de un esquema. Lo apuntas a una definición OpenAPI o GraphQL, y construye casos de prueba a partir de los tipos, formatos y restricciones que ya declaraste. Está construido sobre Hypothesis, la biblioteca de pruebas basada en propiedades para Python, y se distribuye bajo la licencia MIT.
La idea central es simple. Tu especificación ya describe cómo deben ser una solicitud y una respuesta válidas. Schemathesis trata esa descripción como una fuente de verdad y verifica si tu API en ejecución realmente la respeta. Cuando la API devuelve un 500, envía una respuesta que viola el esquema declarado o acepta una entrada que debería haber rechazado, Schemathesis lo señala.
Lo ejecutas desde la línea de comandos con schemathesis run (o el alias más corto st run). También hay una integración de Python si deseas ejecutarlo desde pytest en lugar de la CLI. La mayoría de los equipos comienzan con la CLI porque casi no necesita configuración.
Qué significan las pruebas basadas en propiedades
La mayoría de las pruebas de API se basan en ejemplos. Escribes una solicitud, afirmas una respuesta específica y la prueba pasa o falla en ese único caso. Eso es útil, pero solo detectas los errores para los que pensaste escribir una prueba.
Las pruebas basadas en propiedades invierten el enfoque. En lugar de un ejemplo fijo, describes una propiedad que siempre debería cumplirse, y luego dejas que la herramienta genere cientos de entradas para intentar romperla. Para Schemathesis, la propiedad es, en esencia: "ninguna solicitud válida debería colapsar el servidor ni producir una respuesta que viole el esquema".
Schemathesis genera entradas a partir de las restricciones de tu especificación. Si un campo es un número entero con un mínimo de 1, intentará con 1, números grandes, valores límite y los tipos de entradas que hacen fallar la validación ingenua. Cuando una prueba falla, Hypothesis reduce la entrada al caso más pequeño que aún reproduce el error, de modo que obtienes una reproducción mínima y legible en lugar de una carga útil aleatoria de 4 KB.
Esto es diferente del monkey testing, que lanza entradas aleatorias a una interfaz para ver qué falla. Las pruebas basadas en propiedades son estructuradas. Utiliza el esquema para generar entradas que son plausibles y dirigidas, y sabe cómo debe ser un resultado correcto porque la especificación se lo indicó.
Instalación y ejecución de Schemathesis
Schemathesis es un paquete de Python, por lo que necesitas Python 3 y pip. Instálalo de la forma habitual:
pip install schemathesis
También puedes ejecutarlo sin una instalación permanente usando uvx schemathesis si tienes uv configurado. Una vez instalado, el comando básico apunta a un esquema y a una URL base:
st run http://127.0.0.1:8000/openapi.json
Si tu esquema se encuentra en el disco en lugar de detrás de una URL, pasa la ruta del archivo e indica a Schemathesis dónde se encuentra la API en vivo:
st run ./openapi.yaml --url http://127.0.0.1:8000
Para una API autenticada, añade una cabecera:
st run http://127.0.0.1:8000/openapi.json \
--header 'Authorization: Bearer your-token'
Schemathesis descubre cada operación en la especificación, genera casos para cada una e imprime un resumen de qué comprobaciones pasaron y cuáles fallaron. Los fallos vienen con la solicitud exacta que envió, para que puedas reproducirlos con curl o en cualquier cliente de API. Los nombres de las banderas y los valores predeterminados cambian entre versiones principales, así que consulta st run --help con tu versión instalada en lugar de confiar en un fragmento de blog, incluido este.
Qué detecta Schemathesis
Las comprobaciones predeterminadas apuntan a la brecha entre lo que promete tu especificación y lo que hace tu servidor. Esto es lo que tiende a aparecer.
| Problema | Cómo se ve |
|---|---|
| Errores del servidor | Una solicitud activa un 500 en lugar de un 4xx manejado o una respuesta válida |
| Violaciones de esquema | El cuerpo de la respuesta no coincide con el esquema que declaraste para ese código de estado |
| Discrepancias de código de estado | La API devuelve un código de estado que la especificación nunca documentó |
| Desviación del tipo de contenido | El tipo de contenido de la respuesta no coincide con lo que anuncia la especificación |
| Errores con estado | Una operación funciona sola pero falla dentro de un flujo de trabajo realista de varios pasos |
Ese último punto merece una mirada más cercana. Schemathesis puede ejecutar pruebas con estado, donde encadena operaciones basándose en enlaces de tu especificación, por ejemplo, crear un recurso, luego obtenerlo y luego eliminarlo. Los errores que solo aparecen en secuencia, como un recurso que informa un estado incorrecto después de una actualización, son difíciles de encontrar con pruebas de solicitud única. La fase con estado impulsa esas secuencias como una máquina de estados.
Puedes extender el comportamiento predeterminado con hooks (ganchos). Los hooks son funciones de Python que te permiten personalizar la generación de datos, añadir tus propias comprobaciones o filtrar qué operaciones se prueban. Así es como los equipos adaptan Schemathesis a las API con flujos de autenticación o restricciones no obvias que la especificación no puede expresar.
Cuándo usar Schemathesis
Schemathesis se gana su lugar cuando tienes una especificación OpenAPI o GraphQL razonablemente precisa y deseas una cobertura amplia y económica de casos extremos. Es fuerte para encontrar los fallos para los que nunca escribirías una prueba manual: entradas no manejadas, formas de error no documentadas y desviación de contrato entre la especificación y la implementación.
Es una buena opción cuando:
- Mantienes una especificación OpenAPI y quieres que se aplique contra el servidor real.
- Te preocupan los 500 no manejados y quieres una capa de fuzzing en CI.
- Tu API tiene flujos de trabajo con estado donde el orden importa.
- Tu equipo ya trabaja en Python y se siente cómodo con
pipypytest.
Es menos adecuado cuando tu especificación es escasa o está desactualizada, ya que Schemathesis solo puede probar lo que describe el esquema. "Basura entra, basura sale". Tampoco reemplazará tus pruebas funcionales basadas en ejemplos. Saber que un endpoint nunca falla no es lo mismo que saber que devuelve el valor correcto para una entrada conocida. Quieres ambas cosas.
Schemathesis y Apidog: dónde encaja cada uno
Apidog y Schemathesis resuelven problemas diferentes y funcionan bien juntos. Apidog es una plataforma todo en uno para diseñar, depurar, probar, simular y documentar APIs. Schemathesis es un fuzzer basado en propiedades enfocado. Ser honesto sobre el límite es importante aquí.
Apidog no realiza fuzzing basado en propiedades. Su característica adyacente más cercana es el monkey testing, que envía entradas aleatorias para detectar fallos. Eso es útil, pero no es lo mismo que las pruebas basadas en propiedades impulsadas por esquemas. Schemathesis genera entradas a partir de las restricciones de tu especificación y verifica las respuestas contra el esquema. Así que, si el fuzzing basado en propiedades es lo que necesitas, recurre a Schemathesis, no a Apidog.
Donde Apidog encaja es en el resto del ciclo de vida en torno a esa pasada de fuzzing.
| Etapa del flujo de trabajo | Schemathesis | Apidog |
|---|---|---|
| Fuzzing basado en propiedades a partir de una especificación | Sí, característica principal | No |
| Diseño visual de API y edición de especificaciones | No | Sí |
| Pruebas funcionales basadas en ejemplos | Limitado | Sí, constructor visual de pruebas |
| Pruebas de contrato contra una especificación | Parcial, mediante comprobaciones de esquema | Sí, flujo de trabajo dedicado |
| Servidores mock a partir de un esquema | No | Sí, mock inteligente |
| Ejecutor de pruebas de CI | Sí, st run |
Sí, apidog run |
| Documentación auto-generada | No | Sí |
Una combinación práctica se ve así. Diseñas y mantienes la especificación en Apidog, generas casos de prueba funcionales y un servidor mock a partir de ella, y los ejecutas en CI con apidog run. Luego añades una pasada de Schemathesis que realiza fuzzing sobre la misma especificación para detectar fallos en casos extremos y violaciones de contrato. Las dos capas detectan diferentes clases de errores. Apidog confirma que la API hace lo correcto para casos conocidos; Schemathesis busca los casos desconocidos que la rompen.
Si tu objetivo es convertir una especificación en una suite funcional ejecutable en lugar de una ejecución de fuzzing, Apidog puede generar colecciones de pruebas de API directamente a partir de tus especificaciones OpenAPI, y puedes descargar Apidog para probar ese flujo.
Preguntas frecuentes
¿Es Schemathesis gratuito?
Sí. Schemathesis es de código abierto bajo la licencia MIT, y la CLI es gratuita para instalar y ejecutar a través de pip install schemathesis. También existe una oferta comercial alojada para equipos que desean una experiencia gestionada, pero la herramienta principal que ejecutas localmente y en CI no cuesta nada.
¿Cuál es la diferencia entre schemathesis run y st run?
Son el mismo comando. st es un alias corto para schemathesis, por lo que st run y schemathesis run hacen exactamente lo mismo. Usa el que prefieras. Ambos aceptan una ruta o URL de esquema más opciones como --url y --header.
¿Puede Schemathesis reemplazar mis pruebas funcionales de API?
No, y no está diseñado para eso. Schemathesis comprueba que tu API no falle y que las respuestas coincidan con el esquema. No verifica la lógica de negocio, como si un cálculo de descuento es correcto. Para eso, sigues necesitando pruebas funcionales basadas en ejemplos y pruebas de contrato, las cuales puedes construir y ejecutar en Apidog. Trata Schemathesis como una capa de fuzzing adicional, no como un reemplazo.
¿Funciona Schemathesis con GraphQL?
Sí. Schemathesis es compatible con esquemas OpenAPI y GraphQL. Para GraphQL, genera consultas a partir de las definiciones de tipos del esquema y verifica las respuestas de la misma manera que lo hace para las API REST definidas en OpenAPI.
Conclusión
Schemathesis es una herramienta potente para un solo trabajo: tomar tu especificación OpenAPI o GraphQL y someter a tu API en vivo a pruebas de estrés con generación basada en propiedades. Encuentra los fallos y las violaciones de contrato que las pruebas basadas en ejemplos pasan por alto, y no te cuesta casi nada añadirlo a tu CI. Lo que no hace es diseñar, simular, documentar o verificar la lógica de negocio.
Ahí es donde Apidog lo complementa. Diseña la especificación, genera pruebas funcionales y mocks, ejecútalos en CI con apidog run, y documenta el resultado, todo en un solo lugar, luego añade Schemathesis para el fuzzing. Descarga Apidog para construir el lado de diseño y funcional de ese flujo de trabajo, y deja que Schemathesis se encargue de la búsqueda de casos extremos.