Cómo Escribir Casos de Prueba API: Plantilla y Ejemplo

Una API inestable rara vez falla porque alguien olvidó probarla. Falla porque la prueba que se ejecutó verificó algo incorrecto, o no verificó nada más allá de un código de estado 200. Un caso de prueba de API bien escrito es la diferencia entre detectar un contrato roto antes del lanzamiento y explicar la interrupción después.

Esta guía explica qué es un caso de prueba de API, los campos que necesita uno bueno y cómo escribir uno desde cero. Verá un ejemplo completo y resuelto para un endpoint de inicio de sesión, y luego construirá la misma prueba en Apidog sin escribir un script.

Qué es realmente un caso de prueba de API

Un caso de prueba de API es un conjunto definido de entradas, acciones y resultados esperados que se utiliza para confirmar que un endpoint se comporta correctamente bajo una condición específica. Es más limitado que un escenario de prueba. Un escenario dice "verificar inicio de sesión de usuario". Un caso de prueba dice "POSTear credenciales válidas a /auth/login y confirmar una respuesta 200 con un JWT en el cuerpo en menos de 800 ms".

Cada caso se enfoca en un único comportamiento. Esa concentración es importante. Cuando una prueba amplia y multipropósito falla, aún tienes que investigar qué parte se rompió. Cuando un caso enfocado falla, el nombre de la falla te da la respuesta. Si aún estás mapeando cómo se relacionan los casos con los escenarios y los scripts, escenario de prueba vs caso de prueba y caso de prueba vs script de prueba delinean las diferencias claramente.

Las pruebas de API generalmente cubren cinco ángulos, y tus casos deben distribuirse entre todos ellos:

• Funcional: ¿el endpoint devuelve los datos correctos para una entrada válida?
• Negativo: ¿rechaza una entrada incorrecta con el error y el código de estado correctos?
• 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 de pruebas que solo verifica el camino feliz pasará hasta que un usuario real envíe un campo de contraseña vacío.

Por qué necesitas una plantilla de caso de prueba

Escribir cada caso desde una página en blanco produce una cobertura inconsistente. Un ingeniero registra códigos de estado esperados; otro registra cuerpos de respuesta; un tercero escribe "debería funcionar". Una plantilla corrige eso al forzar la misma estructura cada vez.

Una plantilla compartida te ofrece cuatro victorias concretas. La cobertura se vuelve auditable, porque cada caso tiene los mismos campos y las lagunas son visibles. La incorporación se acelera, porque un nuevo probador lee un formato en lugar de cinco. Los casos se vuelven reutilizables entre versiones, ya que un caso estructurado es fácil de clonar y ajustar. Y la trazabilidad se mantiene, porque cada caso se vincula a un requisito o endpoint.

Las plantillas también hacen que la automatización sea realista. Un caso estructurado se mapea limpiamente a un paso de prueba automatizado; uno vago debe reescribirse antes de que una máquina pueda ejecutarlo.

La anatomía de un caso de prueba de API sólido

Una plantilla completa de caso de prueba de API incluye estos campos. No necesitas todos ellos para cada caso, pero el conjunto central no es negociable.

Los campos que los equipos suelen omitir con mayor frecuencia son el tiempo de respuesta esperado y el cuerpo de respuesta esperado. Omitirlos es la forma en que una prueba "pasa" mientras devuelve un 200 con una carga útil vacía, o una carga útil correcta tres segundos tarde.

Cómo escribir casos de prueba de API paso a paso

Primero, lee la documentación de la API. Anota los parámetros requeridos, el método de autenticación, los códigos de estado documentados y el esquema de respuesta. Cada caso de prueba es una afirmación sobre el comportamiento documentado, por lo que la documentación es tu fuente de verdad. Las herramientas que leen una especificación OpenAPI para generar colecciones de prueba pueden darte un esqueleto inicial.

Enumera las condiciones que vale la pena probar. Para un solo endpoint, esto generalmente significa: entrada válida, cada campo requerido faltante, cada campo malformado, una solicitud no autorizada, un token caducado y una carga útil demasiado grande. Cada condición se convierte en un caso.

Prepara datos de prueba distintos. Los casos negativos necesitan datos que sean incorrectos de una manera específica. Reutilizar la misma carga útil en varios casos oculta errores, porque solo se ejerce una ruta.

Escribe el resultado esperado con precisión. "Devuelve éxito" no es una afirmación. "Devuelve 200, el cuerpo contiene una cadena token no vacía, expires_in es igual a 3600" sí lo es. La precisión aquí es lo que hace que el caso valga la pena ejecutarlo.

Agrega el caso a una suite ejecutable. Un caso en una hoja de cálculo documenta la intención. Un caso en una herramienta de prueba produce un aprobado o un fallido. Agrupa los casos relacionados para que todo el endpoint se ejecute con un solo clic; las suites de prueba existen exactamente para esto.

Mantén los casos actualizados. Cuando la API cambia, los casos cambian con ella. Un caso obsoleto que afirma un esquema antiguo es peor que ningún caso, porque falla por la razón equivocada y entrena al equipo para ignorar las compilaciones en rojo.

Un ejemplo práctico: probando un endpoint de inicio de sesión

Tomemos un endpoint de autenticación estándar: POST /auth/login, que acepta un correo electrónico y una contraseña y devuelve un JWT. Aquí hay cuatro casos que lo cubren correctamente.

AUTH-LOGIN-001: credenciales válidas (funcional, crítica)

• Endpoint: POST /auth/login
• Precondiciones: existe un usuario con el correo electrónico dana@example.com
• Cuerpo: {"email": "dana@example.com", "password": "Correct-Horse-9"}
• Estado esperado: 200
• Respuesta esperada: el cuerpo contiene un token (cadena) no vacío, token_type es igual a Bearer, expires_in es igual a 3600
• Tiempo de respuesta esperado: menos de 800 ms

AUTH-LOGIN-002: contraseña incorrecta (negativa, crítica)

• Cuerpo: {"email": "dana@example.com", "password": "wrong"}
• Estado esperado: 401
• Respuesta esperada: error es igual a invalid_credentials; no hay campo token presente
• Nota: el mensaje no debe revelar si el correo electrónico existe

AUTH-LOGIN-003: campo de contraseña faltante (negativa, alta)

• Cuerpo: {"email": "dana@example.com"}
• Estado esperado: 400
• Respuesta esperada: error es igual a validation_error; details nombra el campo password

AUTH-LOGIN-004: correo electrónico malformado (negativa, media)

• Cuerpo: {"email": "not-an-email", "password": "Correct-Horse-9"}
• Estado esperado: 400
• Respuesta esperada: error es igual a validation_error

Cuatro casos, un endpoint, y ya estás verificando el contrato, la forma del error, los códigos de estado y un presupuesto de latencia. Agrega un caso de seguridad para una cadena de inyección SQL en el campo del correo electrónico y tendrás una suite que vale la pena ejecutar en cada commit.

Escribiendo el mismo caso de prueba en Apidog

Puedes ejecutar los cuatro casos anteriores sin escribir una línea de script. En Apidog, un caso de prueba de API se construye visualmente.

1. Importa o define el endpoint. Carga POST /auth/login desde un archivo OpenAPI, una colección de Postman, o defínelo directamente. El esquema de la solicitud se convierte en la base de cada afirmación.
2. Agrega los datos de la solicitud. Ingresa el cuerpo para el caso AUTH-LOGIN-001. Para una cobertura basada en datos, adjunta un archivo CSV o JSON para que un caso se ejecute contra cada fila de credenciales; así es como las pruebas de API basadas en datos reemplazan cuatro casos casi idénticos por uno solo.
3. Configura las afirmaciones visualmente. Haz clic para afirmar que el estado es igual a 200, que token existe y es una cadena no vacía, que expires_in es igual a 3600 y que el tiempo de respuesta se mantiene por debajo de 800 ms. No se requiere scripting.
4. Agrupa los casos en un escenario de prueba. Agrega los cuatro casos de inicio de sesión a un escenario para que el endpoint se ejerza completamente en una sola ejecución.
5. Ejecuta y lee el informe. Apidog ejecuta el escenario, genera un informe de aprobado/fallido por caso y muestra la afirmación exacta que falló. Puedes ejecutar el escenario localmente, programado o dentro de CI.

El punto no es que el scripting sea incorrecto; es que un caso visual estructurado es más rápido de escribir, más fácil de revisar y más difícil de equivocarse sutilmente. Cuando necesitas código, Apidog aún te permite usar scripts personalizados. Para un flujo de trabajo completamente libre de scripts, las pruebas de API sin Postman cubren el enfoque más amplio.

Errores comunes a evitar

Afirmar solo el código de estado. Un 200 significa que la solicitud fue manejada, no que la respuesta fue correcta. Siempre afirma los campos del cuerpo.

Un caso gigante por endpoint. Cuando falla, no aprendes nada. Divide por condición.

Datos de prueba reutilizados. Si cada caso negativo envía la misma carga útil, solo pruebas un modo de falla.

Sin afirmación de latencia. Las regresiones de rendimiento pasan desapercibidas cuando nada mide el tiempo de respuesta.

Casos que nunca se automatizan. Un caso documentado que ningún ejecutor ejecuta es un comentario, no una prueba. Mueve los casos a una suite que se ejecute en cada compilación; generar scripts de prueba a partir de una especificación OpenAPI es una forma rápida de iniciar esa suite.

Descarga Apidog si quieres seguir el ejemplo y construir los cuatro casos de inicio de sesión por ti mismo.

Preguntas frecuentes

¿Cuántos casos de prueba necesita un endpoint? Suficientes para cubrir el camino feliz, cada falla de campo requerido, una falla de autenticación y una prueba de seguridad. Para un endpoint simple son de cuatro a seis casos; para uno complejo pueden ser más.

¿Debo escribir casos antes de construir la API? Sí. Escribir casos contra el diseño, con un enfoque de "diseño primero", detecta las deficiencias del contrato a tiempo. Combina esto con la generación de casos de prueba asistida por IA para redactar un primer conjunto rápidamente, y luego refínalo manualmente.

¿Hoja de cálculo o herramienta de prueba para almacenar los casos? Una hoja de cálculo documenta la intención, pero no puede ejecutar. Mantén los casos en una herramienta que los ejecute y reporte los resultados, para que un caso siempre esté en verde o en rojo.

¿Cuál es la diferencia entre un caso de prueba y un escenario de prueba? Un escenario es el objetivo de alto nivel ("verificar el inicio de sesión"); un caso es una verificación concreta y ejecutable dentro de este. Consulta escenario de prueba vs caso de prueba.