Una API inestable rara vez falla porque “nadie la probó”. Falla porque la prueba validó lo incorrecto: solo un 200 OK, ningún campo del cuerpo, ningún contrato, ningún tiempo de respuesta. Un buen caso de prueba de API te ayuda a detectar un contrato roto antes del release, no después de una incidencia en producción.
En esta guía verás qué es un caso de prueba de API, qué campos debe incluir y cómo escribir uno desde cero. También construiremos un ejemplo completo para POST /auth/login y luego lo llevaremos a Apidog sin escribir scripts.
Qué es realmente un caso de prueba de API
Un caso de prueba de API define:
- entradas concretas,
- una acción específica,
- resultados esperados,
- criterios de validación.
No es lo mismo que un escenario de prueba.
Un escenario dice:
Verificar inicio de sesión de usuario.
Un caso de prueba dice:
Enviar credenciales válidas a
POST /auth/loginy confirmar una respuesta200, un JWT no vacío en el cuerpo y un tiempo de respuesta menor a800 ms.
La diferencia importa porque cada caso debe validar un solo comportamiento. Si una prueba grande falla, todavía tienes que investigar qué parte se rompió. Si un caso enfocado falla, el nombre del caso ya apunta al problema.
Si necesitas separar mejor estos conceptos, revisa escenario de prueba vs caso de prueba y caso de prueba vs script de prueba.
Una suite de pruebas de API debería cubrir, como mínimo, estos ángulos:
- Funcional: el endpoint devuelve los datos correctos para una entrada válida.
- Negativo: rechaza entradas inválidas con el código y error esperados.
- Rendimiento: responde dentro de un tiempo aceptable.
- Seguridad: aplica autenticación, autorización y límites de entrada.
- Contrato: la respuesta coincide con el esquema documentado.
Una suite que solo valida el camino feliz pasará hasta que un usuario real envíe una contraseña vacía.
Por qué necesitas una plantilla de caso de prueba
Escribir casos desde cero genera inconsistencias. Un tester valida códigos de estado, otro valida cuerpos de respuesta, otro escribe “debería funcionar”.
Una plantilla evita eso porque obliga a capturar la misma información cada vez.
Beneficios prácticos:
Cobertura auditable
Si todos los casos tienen los mismos campos, las lagunas son visibles.Onboarding más rápido
Un nuevo miembro del equipo aprende un formato único, no cinco estilos distintos.Reutilización entre versiones
Un caso estructurado se puede clonar, ajustar y volver a ejecutar.Trazabilidad
Cada caso se vincula a un endpoint, requisito o contrato.Automatización más sencilla
Un caso claro se puede convertir en una prueba automatizada. Un caso ambiguo debe reescribirse antes de que una herramienta pueda ejecutarlo.
Anatomía de un caso de prueba de API sólido
Una plantilla útil debería incluir estos campos:
| Campo | Propósito |
|---|---|
| ID del caso de prueba | Referencia única, por ejemplo AUTH-LOGIN-001
|
| Título | Descripción breve del comportamiento bajo prueba |
| Endpoint | Método y ruta, por ejemplo POST /auth/login
|
| Precondiciones | Estado requerido antes de ejecutar la prueba |
| Headers | Encabezados requeridos para la solicitud |
| Cuerpo de la solicitud / parámetros | Payload exacto enviado al endpoint |
| Estado esperado | Código HTTP esperado |
| Respuesta esperada | Campos, esquema o valores que deben validarse |
| Tiempo de respuesta esperado | Presupuesto máximo de latencia |
| Prioridad | Crítica, alta, media o baja |
| Tipo de prueba | Funcional, negativa, seguridad, rendimiento o contrato |
Los campos que más se omiten suelen ser:
- respuesta esperada,
- tiempo de respuesta esperado.
Omitirlos permite que una prueba “pase” aunque devuelva un 200 con un cuerpo vacío, o una respuesta correcta pero tres segundos tarde.
Cómo escribir casos de prueba de API paso a paso
1. Lee la documentación de la API
Antes de escribir pruebas, identifica:
- método HTTP,
- ruta,
- headers requeridos,
- autenticación,
- parámetros obligatorios,
- códigos de estado documentados,
- esquema de respuesta.
Cada caso de prueba debe validar un comportamiento esperado del contrato.
Si trabajas con OpenAPI, puedes usar herramientas que generen una base inicial desde la especificación. Por ejemplo, una especificación OpenAPI para generar colecciones de prueba puede acelerar el primer borrador.
2. Lista las condiciones que debes probar
Para un endpoint típico, crea casos para:
- entrada válida,
- cada campo requerido faltante,
- cada campo malformado,
- solicitud sin autenticación,
- token caducado,
- payload demasiado grande,
- entradas potencialmente peligrosas.
Cada condición debe convertirse en un caso separado.
3. Prepara datos de prueba específicos
No reutilices el mismo payload inválido en todos los casos negativos.
Ejemplo incorrecto:
{
"email": "",
"password": ""
}
Ese payload mezcla dos errores. Si la API responde 400, no sabes si falló por email, por password o por ambos.
Mejor:
{
"email": "dana@example.com"
}
Este caso prueba únicamente la ausencia de password.
4. Escribe resultados esperados verificables
Evita afirmaciones vagas como:
Devuelve éxito.
Escribe algo ejecutable:
Estado esperado: 200
Respuesta esperada:
- token existe
- token es string
- token no está vacío
- token_type es "Bearer"
- expires_in es 3600
Tiempo máximo: 800 ms
La precisión es lo que convierte una intención en una prueba real.
5. Agrega el caso a una suite ejecutable
Un caso en una hoja de cálculo documenta intención. Un caso en una herramienta de pruebas produce un resultado: aprobado o fallido.
Agrupa los casos por endpoint o flujo. Las suites de prueba sirven precisamente para ejecutar conjuntos completos con un solo disparador.
6. Mantén los casos sincronizados con la API
Cuando cambia el contrato, deben cambiar los casos.
Un caso obsoleto es peor que ningún caso porque falla por la razón equivocada y acostumbra al equipo a ignorar builds en rojo.
Ejemplo práctico: probando un endpoint de inicio de sesión
Supongamos este endpoint:
POST /auth/login
Content-Type: application/json
Recibe:
{
"email": "dana@example.com",
"password": "Correct-Horse-9"
}
Y devuelve un JWT si las credenciales son válidas.
AUTH-LOGIN-001: credenciales válidas
Tipo: funcional
Prioridad: crítica
POST /auth/login
Content-Type: application/json
Payload:
{
"email": "dana@example.com",
"password": "Correct-Horse-9"
}
Validaciones esperadas:
Status: 200
Body:
- token existe
- token es string
- token no está vacío
- token_type == "Bearer"
- expires_in == 3600
Tiempo de respuesta < 800 ms
AUTH-LOGIN-002: contraseña incorrecta
Tipo: negativa
Prioridad: crítica
Payload:
{
"email": "dana@example.com",
"password": "wrong"
}
Validaciones esperadas:
Status: 401
Body:
- error == "invalid_credentials"
- token no existe
Nota de seguridad:
El mensaje no debe revelar si el email existe.
AUTH-LOGIN-003: campo password faltante
Tipo: negativa
Prioridad: alta
Payload:
{
"email": "dana@example.com"
}
Validaciones esperadas:
Status: 400
Body:
- error == "validation_error"
- details menciona el campo "password"
AUTH-LOGIN-004: email malformado
Tipo: negativa
Prioridad: media
Payload:
{
"email": "not-an-email",
"password": "Correct-Horse-9"
}
Validaciones esperadas:
Status: 400
Body:
- error == "validation_error"
Con estos cuatro casos ya validas:
- camino feliz,
- errores de autenticación,
- validación de campos requeridos,
- validación de formato,
- forma del error,
- códigos de estado,
- latencia.
También podrías agregar un caso de seguridad con una cadena de inyección SQL en email.
Ejemplo:
{
"email": "' OR '1'='1",
"password": "Correct-Horse-9"
}
Validación esperada:
Status: 400 o 401, según el contrato
Body:
- no expone detalles internos
- no devuelve token
Escribiendo el mismo caso de prueba en Apidog
Puedes implementar los casos anteriores en Apidog sin escribir una línea de script.
1. Importa o define el endpoint
Carga POST /auth/login desde:
- un archivo OpenAPI,
- una colección de Postman,
- una definición manual.
El esquema de solicitud y respuesta sirve como base para las validaciones.
2. Agrega los datos de la solicitud
Para AUTH-LOGIN-001, configura el body:
{
"email": "dana@example.com",
"password": "Correct-Horse-9"
}
Para casos repetitivos, puedes usar datos externos en CSV o JSON. Así, las pruebas de API basadas en datos permiten ejecutar el mismo caso contra varias filas de credenciales.
3. Configura las afirmaciones visualmente
Agrega validaciones como:
status == 200
body.token existe
body.token no está vacío
body.token_type == "Bearer"
body.expires_in == 3600
response_time < 800 ms
No necesitas scripting para este flujo.
4. Agrupa los casos en un escenario
Incluye:
AUTH-LOGIN-001AUTH-LOGIN-002AUTH-LOGIN-003AUTH-LOGIN-004
Así puedes ejecutar toda la cobertura del endpoint de login en una sola corrida.
5. Ejecuta y revisa el reporte
Apidog muestra:
- casos aprobados,
- casos fallidos,
- afirmación exacta que falló,
- respuesta real recibida.
Puedes ejecutar el escenario:
- localmente,
- de forma programada,
- dentro de CI.
El objetivo no es evitar siempre el código. El objetivo es que los casos simples y repetitivos sean más rápidos de crear, revisar y mantener. Cuando necesitas lógica personalizada, Apidog también permite usar scripts.
Si quieres un flujo más amplio sin depender de Postman, revisa las pruebas de API sin Postman.
Errores comunes a evitar
Afirmar solo el código de estado
Un 200 solo indica que la solicitud fue procesada. No garantiza que la respuesta sea correcta.
Valida siempre el cuerpo:
status == 200
body.data.id existe
body.data.email == "dana@example.com"
Crear un caso gigante por endpoint
Si un único caso valida login correcto, contraseña incorrecta, email inválido y token caducado, cuando falle no sabrás qué se rompió.
Divide por condición.
Reutilizar los mismos datos negativos
Cada caso negativo debe fallar por una razón específica.
Mal:
{
"email": "",
"password": ""
}
Mejor:
{
"email": "dana@example.com"
}
No validar latencia
Sin una afirmación de tiempo, una regresión de rendimiento puede pasar inadvertida.
Ejemplo:
response_time < 800 ms
Documentar casos que nunca se ejecutan
Un caso que nadie ejecuta es documentación, no una prueba.
Muévelo a una suite automática y ejecútalo en cada build. Una forma rápida de empezar es generar scripts de prueba a partir de una especificación OpenAPI.
Descarga Apidog si quieres seguir el ejemplo y construir los cuatro casos de inicio de sesión por tu cuenta.
Preguntas frecuentes
¿Cuántos casos de prueba necesita un endpoint?
Los suficientes para cubrir:
- camino feliz,
- campos requeridos faltantes,
- entradas malformadas,
- falla de autenticación,
- al menos una prueba de seguridad,
- contrato de respuesta.
Para un endpoint simple suelen ser entre cuatro y seis casos. Para endpoints complejos, más.
¿Debo escribir casos antes de construir la API?
Sí. Escribir casos contra el diseño ayuda a detectar deficiencias del contrato antes de implementar.
Puedes combinar un enfoque design-first con generación de casos de prueba asistida por IA para obtener un primer borrador y luego refinarlo manualmente.
¿Hoja de cálculo o herramienta de prueba?
Una hoja de cálculo sirve para documentar, pero no ejecuta.
Mantén los casos en una herramienta que pueda:
- ejecutar pruebas,
- reportar resultados,
- mostrar fallos,
- integrarse con CI.
Un caso debe estar en verde o en rojo, no solo escrito.
¿Cuál es la diferencia entre un caso de prueba y un escenario de prueba?
Un escenario es el objetivo de alto nivel:
Verificar inicio de sesión.
Un caso es una validación concreta y ejecutable:
Enviar credenciales válidas a POST /auth/login y confirmar status 200, token JWT y latencia menor a 800 ms.
Consulta escenario de prueba vs caso de prueba para ver la diferencia con más detalle.
Top comments (0)