DEV Community

Cover image for Pruebas de API con Karate: Guía Práctica del DSL
Roobia
Roobia

Posted on • Originally published at apidog.com

Pruebas de API con Karate: Guía Práctica del DSL

Desea pruebas de API que se lean como inglés sencillo, vivan en Git junto a su código y se ejecuten en cualquier pipeline de CI. Karate está diseñado para eso: permite escribir pruebas como pasos Given / When / Then en archivos .feature, sin crear métodos Java ni código “pegamento”. En esta guía verá cómo estructurar un proyecto, escribir escenarios ejecutables, validar JSON y llevar las pruebas a CI.

Prueba Apidog hoy

Qué es Karate

Karate es un framework de automatización de pruebas de código abierto, basado en Java, para APIs. Las pruebas se escriben como escenarios en archivos .feature usando Gherkin, con la estructura Given / When / Then del Desarrollo Dirigido por Comportamiento.

La diferencia frente a herramientas como Cucumber es práctica: con Karate no necesita escribir step definitions. El framework ya incluye pasos HTTP, aserciones, manejo de JSON y utilidades para validar respuestas.

Karate API testing

Karate también incluye módulos para mocks, pruebas de rendimiento con Gatling y automatización de interfaz de usuario. En esta guía nos enfocaremos en el núcleo: pruebas automatizadas de API.

Como las pruebas son archivos de texto plano, funcionan bien con Git. En una pull request puede revisar exactamente qué endpoint, payload o aserción cambió. Esto encaja con un flujo de trabajo basado en código y nativo de Git.

Si es nuevo en Given / When / Then, esta introducción al Desarrollo Dirigido por Comportamiento explica el origen del enfoque y por qué se usa en equipos de API.

Cómo funciona: archivos .feature y karate-config.js

Una prueba de Karate comienza con un archivo .feature. Cada archivo tiene un bloque Feature: y uno o más bloques Scenario:.

Ejemplo mínimo:

Feature: User API

Scenario: List all users
  Given url 'https://jsonplaceholder.typicode.com'
  And path 'users'
  When method get
  Then status 200
  And match response == '#[10]'
Enter fullscreen mode Exit fullscreen mode

Qué hace cada línea:

  • url define la URL base.
  • path agrega el recurso.
  • method get envía la solicitud HTTP.
  • status 200 valida el código de estado.
  • match response == '#[10]' verifica que la respuesta sea un array JSON con 10 elementos.

El marcador #[10] es propio de Karate. No es JavaScript. Sirve para validar la forma de una respuesta sin escribir lógica adicional.

Para profundizar en la sintaxis, consulte esta guía de Gherkin para BDD y pruebas de API.

Configurar entornos con karate-config.js

En proyectos reales normalmente necesita cambiar valores por entorno: desarrollo, QA, staging o producción.

Karate usa un archivo llamado karate-config.js. Se ejecuta antes de las pruebas y devuelve un objeto de configuración disponible para todos los escenarios.

function fn() {
  var env = karate.env || 'dev';

  var config = {
    baseUrl: 'https://jsonplaceholder.typicode.com'
  };

  if (env === 'qa') {
    config.baseUrl = 'https://qa.example.com';
  }

  return config;
}
Enter fullscreen mode Exit fullscreen mode

Luego puede usar baseUrl dentro del archivo .feature:

Feature: User API

Background:
  * url baseUrl

Scenario: List all users
  Given path 'users'
  When method get
  Then status 200
Enter fullscreen mode Exit fullscreen mode

Para cambiar de entorno en tiempo de ejecución:

java -Dkarate.env=qa ...
Enter fullscreen mode Exit fullscreen mode

Así evita hardcodear URLs o tokens en cada archivo de prueba.

Crear un escenario con body JSON

Este ejemplo envía una solicitud POST, valida el código HTTP y comprueba la forma de la respuesta.

Feature: Create user

Background:
  * url baseUrl

Scenario: Create a new user returns 201
  Given path 'users'
  And request { name: 'Ada', job: 'engineer' }
  When method post
  Then status 201
  And match response.name == 'Ada'
  And match response.id == '#string'
Enter fullscreen mode Exit fullscreen mode

Puntos importantes:

  • Background: se ejecuta antes de cada escenario del archivo.
  • * es un comodín que Karate acepta como paso de configuración.
  • request permite definir el JSON directamente.
  • #string valida que response.id exista y sea una cadena.
  • No necesita crear POJOs, serializadores ni clases Java.

Aserciones y coincidencia JSON

La palabra clave principal para validar respuestas es match.

And match response == { id: '#number', name: 'Ada', job: 'engineer' }
Enter fullscreen mode Exit fullscreen mode

Karate incluye “fuzzy matchers” para validar tipos sin fijar valores exactos:

Matcher Valida
#string Cadena
#number Número
#boolean Booleano
#uuid UUID
#[10] Array con 10 elementos

Esto es útil cuando la API devuelve IDs, timestamps u otros valores generados dinámicamente.

Si solo quiere validar algunos campos, use contains:

And match response contains { name: 'Ada' }
Enter fullscreen mode Exit fullscreen mode

La prueba pasa aunque la respuesta incluya más campos.

Karate también soporta:

And match response !contains { error: true }
And match response contains only { name: 'Ada', job: 'engineer' }
And match response contains any [{ name: 'Ada' }, { name: 'Grace' }]
And match response contains deep { user: { name: 'Ada' } }
Enter fullscreen mode Exit fullscreen mode

Para validar arrays, puede combinar each con matchers:

And match each response == { id: '#number', name: '#string' }
Enter fullscreen mode Exit fullscreen mode

Esta línea verifica que cada objeto del array tenga un id numérico y un name de tipo cadena. En un framework genérico requeriría un bucle y múltiples aserciones.

Para más patrones de validación, consulte esta guía práctica de aserciones de API.

Pruebas dirigidas por datos

Cuando necesita ejecutar el mismo escenario con múltiples entradas, use Scenario Outline y Examples.

Scenario Outline: Create users from a table
  Given url baseUrl
  And path 'users'
  And request { name: '<name>', job: '<job>' }
  When method post
  Then status 201
  And match response.name == '<name>'

  Examples:
    | name  | job       |
    | Ada   | engineer  |
    | Grace | scientist |
    | Alan  | analyst   |
Enter fullscreen mode Exit fullscreen mode

Karate ejecuta el escenario una vez por cada fila.

También puede leer datos desde un archivo externo:

Examples:
  | read('classpath:test-data/users.json') |
Enter fullscreen mode Exit fullscreen mode

Karate puede leer JSON y CSV, lo que ayuda a mantener grandes conjuntos de datos fuera del archivo .feature.

Ejecutar Karate en CI

Tiene dos opciones comunes para ejecutar Karate en integración continua.

Opción 1: Maven o Gradle con JUnit 5

En un proyecto Maven o Gradle, agregue la dependencia karate-junit5 y cree un runner que apunte a sus archivos .feature.

Así puede ejecutar las pruebas con:

mvn test
Enter fullscreen mode Exit fullscreen mode

Esto permite integrarlas en el mismo paso de CI donde ya ejecuta pruebas unitarias.

Opción 2: JAR autónomo

Si no quiere depender de Maven o Gradle, use el JAR autónomo de Karate.

java -jar karate.jar src/test/java/features
Enter fullscreen mode Exit fullscreen mode

También puede filtrar por etiquetas, ejecutar en paralelo y definir el directorio de salida:

java -jar karate.jar --tags @smoke --threads 4 --output reports src/test/java/features
Enter fullscreen mode Exit fullscreen mode

Para seleccionar entorno:

java -jar karate.jar -Dkarate.env=qa src/test/java/features
Enter fullscreen mode Exit fullscreen mode

Karate genera un informe HTML después de cada ejecución, útil como artefacto del pipeline.

Para una visión más amplia, vea cómo automatizar pruebas de API en CI/CD.

Fortalezas y compromisos

Karate funciona bien cuando el equipo quiere pruebas versionadas como código.

Fortalezas principales:

  • Sintaxis legible basada en Given / When / Then.
  • Sin step definitions para pruebas HTTP comunes.
  • Aserciones JSON integradas.
  • Matchers flexibles como #string, #number y each.
  • Archivos .feature fáciles de revisar en Git.
  • Ejecución compatible con CI.
  • Posibilidad de extender hacia mocks, performance testing y UI testing.

Compromisos:

  • Requiere Java para ejecutar las pruebas.
  • El DSL de Karate tiene su propia curva de aprendizaje.
  • La reutilización avanzada puede requerir JavaScript o interoperabilidad con Java.
  • Los perfiles no técnicos normalmente necesitan ayuda para crear o mantener pruebas.
  • La suite sigue siendo un proyecto “code-first”.

No es una desventaja en sí misma. Es una decisión de arquitectura: Karate encaja mejor cuando los desarrolladores son dueños de la suite de pruebas.

Karate vs un enfoque sin código con Apidog

Karate es code-first y Git-native. Usted escribe archivos .feature, los versiona y los ejecuta con Maven, Gradle o el JAR autónomo.

Apidog sigue un enfoque visual y sin código. Permite construir escenarios de prueba desde una interfaz, encadenar solicitudes y agregar aserciones sin escribir DSL. Como el ciclo de vida de la API —diseño, depuración, mocking y documentación— vive en un solo lugar, las pruebas pueden reutilizar endpoints y esquemas ya definidos.

Apidog API testing

Las suites visuales también pueden ejecutarse en CI con la CLI de Apidog.

Instalación:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Ejecución de un escenario o suite guardado:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t <scenarioOrSuiteId> -e <environmentId> -r cli,html,junit
Enter fullscreen mode Exit fullscreen mode

Parámetros comunes:

  • -t: escenario, carpeta o suite.
  • -e: entorno.
  • -r: reporteros como cli, html, json o junit.
  • -d / --iteration-data: archivo o ID de datos para pruebas dirigidas por datos.

La CLI se ejecuta sin interfaz gráfica y puede correr en cualquier pipeline con Node. Ejecuta escenarios guardados de Apidog; no es un cliente interactivo ni un generador de carga.

Más detalles en Apidog CLI para CI/CD y en la comparación Apidog CLI vs Newman.

Ambos enfoques automatizan pruebas de API y pueden ejecutarse en CI. La diferencia está en la autoría:

  • Karate: escribir DSL en Git.
  • Apidog: crear escenarios en una interfaz visual y ejecutarlos por CLI.

Cómo elegir

Elija Karate si:

  • Su equipo está compuesto principalmente por desarrolladores.
  • Quiere pruebas versionadas junto al código de la aplicación.
  • Ya usa Java, Maven o Gradle.
  • Necesita control fino sobre los archivos de prueba.
  • Prefiere una suite de pruebas code-first.

Elija una herramienta sin código como Apidog si:

  • QA, producto u otros perfiles también crearán pruebas.
  • Quiere conectar pruebas con diseño, debugging, mocking y documentación.
  • Prefiere evitar mantener un proyecto Java solo para validar APIs.
  • Necesita ejecución en CI, pero con autoría visual.

Algunos equipos usan ambos: Karate para regresión profunda mantenida por ingeniería y una herramienta visual para cobertura amplia que más personas puedan extender.

Si está comparando alternativas, esta guía sobre cómo elegir un framework de automatización de pruebas de API resume los criterios principales.

Preguntas frecuentes

¿Necesito saber Java para usar Karate?

No para escribir pruebas básicas de API. Los archivos .feature usan el DSL de Karate sobre Gherkin. Sí necesita Java instalado para ejecutar las pruebas, y conocer Java o JavaScript ayuda cuando requiere helpers personalizados o reutilización avanzada.

¿En qué se diferencia Karate de Cucumber?

Ambos usan Given / When / Then. Con Cucumber normalmente escribe step definitions para respaldar cada paso. Karate ya incluye pasos HTTP, aserciones y manejo de JSON, por lo que no necesita código “pegamento” para pruebas de API comunes.

¿Puede Karate ejecutarse sin Maven o Gradle?

Sí. Puede usar el JAR autónomo:

java -jar karate.jar <path>
Enter fullscreen mode Exit fullscreen mode

También admite etiquetas, ejecución paralela y directorio de salida personalizado.

¿Qué significa #string o #[10]?

Son fuzzy matchers de Karate. #string valida que un campo sea una cadena, #number valida un número y #[10] valida un array con 10 elementos. Sirven para comprobar la forma de la respuesta sin fijar valores dinámicos.

¿Las pruebas de API sin código pueden ejecutarse en CI?

Sí. Una herramienta visual como Apidog puede ejecutar escenarios guardados mediante la CLI de Apidog. La CLI no tiene interfaz gráfica y puede correr en pipelines que soporten Node.

Top comments (0)