Desea pruebas de API que se lean como inglés sencillo, que vivan en Git junto a su código y que se ejecuten en cualquier pipeline de CI. Karate está diseñado exactamente para eso. Utiliza un lenguaje de dominio específico (DSL) para que escriba las pruebas como pasos Given / When / Then en lugar de métodos Java. Esta guía explica qué es Karate, cómo funcionan sus archivos de características y un ejemplo ejecutable.
Qué es Karate
Karate es un framework de automatización de pruebas de código abierto, basado en Java, para APIs. Se describe cada prueba como un escenario en un archivo .feature usando Gherkin, la misma estructura Given/When/Then que proviene del Desarrollo Dirigido por Comportamiento. La diferencia con herramientas como Cucumber es que no se escribe código "pegamento" (step-definition glue code). Karate incluye los pasos HTTP, las aserciones y el manejo de JSON incorporados, por lo que una prueba de API funcional no necesita Java en absoluto.
El proyecto agrupa más que pruebas de API. El repositorio incluye módulos para mocks, pruebas de rendimiento (a través de Gatling) y automatización de la interfaz de usuario. Para esta guía, el enfoque es el núcleo de las pruebas de API, que es lo que la mayoría de los equipos buscan primero.
Debido a que las pruebas son archivos de texto plano, se versionan bien. Un diff de una pull request muestra exactamente qué aserción cambió. Esto encaja bien con la revisión de código y con un flujo de trabajo basado en código y nativo de Git.
Si eres nuevo en el estilo Given/When/Then, nuestro manual introductorio sobre Desarrollo Dirigido por Comportamiento explica de dónde viene y por qué los equipos lo utilizan.
Cómo funciona: Archivos de características y karate-config.js
Una prueba de Karate comienza con un archivo de características. Cada archivo tiene un bloque Feature: y uno o más bloques Scenario:. Dentro de un escenario, se configura la solicitud con Given, se ejecuta con When y se afirma con Then.
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]'
Léalo de arriba abajo. url establece la dirección base. path añade el recurso. method get envía la solicitud. status 200 verifica el código HTTP. La última línea afirma que la respuesta es un array JSON con exactamente 10 elementos. El #[10] es un marcador de Karate, no JavaScript. Más sobre estos marcadores en la sección de aserciones.
El Gherkin aquí es el estándar Given/When/Then. Si desea una mirada más profunda a esa sintaxis por sí sola, consulte nuestra guía de Gherkin para BDD y pruebas de API.
La mayoría de los proyectos necesitan valores específicos del entorno: una URL base de desarrollo, un token de staging, un endpoint de producción. Karate maneja esto con un único archivo llamado karate-config.js. Se ejecuta una vez antes de las pruebas y devuelve un objeto de configuración que cada escenario puede leer.
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;
}
karate.env proviene de una propiedad del sistema que se pasa en tiempo de ejecución. Cambie de entorno sin tocar un solo archivo de características. En un escenario, escribiría entonces Given url baseUrl en lugar de codificar la dirección.
Un Escenario de Ejemplo
Escribamos algo con un cuerpo de solicitud. Este escenario crea un usuario, verifica el estado y valida 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'
Algunas cosas a tener en cuenta. El bloque Background: se ejecuta antes de cada escenario en el archivo, por lo que se establece la URL base una vez. El * es un paso comodín; Karate trata * igual que Given, When o Then, lo que le permite escribir pasos de configuración sin preocuparse por la gramática. La palabra clave request toma una carga útil JSON directamente. Sin serializador, sin POJO. Y #string es un "fuzzy matcher" que afirma que el campo id existe y es una cadena, sin fijarlo a un valor específico.
Aserciones y Coincidencia JSON
Las aserciones son donde Karate demuestra su valía. La palabra clave central es match. Compara un valor real con uno esperado y falla la prueba ante cualquier discrepancia.
And match response == { id: '#number', name: 'Ada', job: 'engineer' }
Los tokens #number, #string, #boolean y #uuid son "fuzzy matchers". Afirman el tipo y la presencia sin exigir un valor literal, lo que mantiene las pruebas estables cuando el servidor devuelve IDs o marcas de tiempo generadas.
Cuando solo le interesa un subconjunto de campos, use contains:
And match response contains { name: 'Ada' }
Eso pasa siempre que name sea igual a Ada, incluso si la respuesta tiene otros diez campos. Karate también soporta !contains, contains only, contains any y contains deep para un control más preciso sobre la coincidencia parcial.
También puede validar arrays. match response == '#[10]' afirma un array de longitud 10. Puede aplicar un esquema a cada elemento con each:
And match each response == { id: '#number', name: '#string' }
Esta única línea verifica que cada objeto en el array tiene un id numérico y un name de cadena. Ese tipo de validación de forma requeriría un bucle y varias aserciones en un framework de pruebas de propósito general. Si desea una visión más amplia sobre la validación de respuestas, nuestra guía práctica de aserciones de API cubre los patrones entre herramientas.
Pruebas Dirigidas por Datos y CI
Las suites de pruebas reales ejecutan la misma lógica contra muchas entradas. Karate maneja esto con Scenario Outline y una tabla Examples. Los marcadores de posición entre corchetes angulares se rellenan desde cada fila.
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 |
Eso ejecuta el escenario tres veces, una por fila. También puede leer filas de un archivo externo en lugar de una tabla en línea, lo que mantiene grandes conjuntos de datos fuera de sus archivos de características:
Examples:
| read('classpath:test-data/users.json') |
Karate lee archivos JSON y CSV de esta manera, por lo que sus datos de prueba pueden residir donde su equipo prefiera gestionarlos.
Para la integración continua, tiene dos caminos. En un proyecto Maven o Gradle, Karate se ejecuta a través de JUnit 5. Añade la dependencia karate-junit5 y apunta un ejecutor a sus archivos de características, de modo que mvn test los ejecuta como cualquier otra prueba unitaria. Eso significa que su paso de CI existente no necesita herramientas especiales.
El segundo camino es el jar autónomo, que no necesita ninguna herramienta de construcción. Descargue karate.jar de los lanzamientos del proyecto y ejecute los archivos de características directamente. Tenga en cuenta que el jar requiere una versión reciente de Java, así que consulte las notas de la versión para conocer el mínimo.
java -jar karate.jar src/test/java/features
Puede filtrar por etiqueta, ejecutar en paralelo y elegir un directorio de salida:
java -jar karate.jar --tags @smoke --threads 4 --output reports src/test/java/features
Pase un entorno con una propiedad del sistema, que fluye hacia karate.env dentro de karate-config.js:
java -jar karate.jar -Dkarate.env=qa src/test/java/features
Karate escribe un informe HTML en el directorio de salida después de cada ejecución, por lo que los fallos son fáciles de inspeccionar en un artefacto de pipeline. Para una visión más amplia de CI, vea cómo automatizar pruebas de API en CI/CD.
Fortalezas y Compromisos
Karate tiene fortalezas claras. Las pruebas se leen de forma similar al inglés sencillo, lo que reduce la barrera para las personas que no dominan Java. La coincidencia de JSON incorporada, incluidos los "fuzzy matchers" y each, elimina gran parte del código repetitivo de las aserciones. Todo reside en archivos de texto bajo Git, por lo que las pruebas se revisan y comparan como código fuente. Y cubre más que HTTP, por lo que un equipo puede añadir mocks o pruebas de rendimiento más tarde sin cambiar de herramientas.
Los compromisos también son reales. Karate se ejecuta en la JVM, por lo que necesita tener Java instalado y un nivel de comodidad con el ecosistema de la JVM para cualquier cosa más allá de lo básico. El DSL es algo propio que aprender; la sintaxis se lee fácilmente, pero escribir "matchers" correctos y patrones de reutilización requiere práctica. La lógica reutilizable, los "helpers" personalizados y la configuración compleja a menudo lo llevan de vuelta a las funciones de JavaScript o a la interoperabilidad con Java. Y debido a que las pruebas son código, los no desarrolladores del equipo usualmente no pueden crearlas o editarlas sin ayuda.
Nada de eso es una crítica. Es el perfil de un framework "code-first". La pregunta es si ese perfil coincide con la forma en que su equipo quiere trabajar.
Karate vs un Enfoque Sin Código (Apidog)
Karate se basa en código y es nativo de Git. Se escriben los archivos de características, se confirman y se ejecutan desde una herramienta de construcción o el jar. Esto se adapta a los ingenieros que desean tener las pruebas en el control de versiones junto a la aplicación y que se sienten cómodos con la JVM.
Apidog toma un camino visual y sin código para lograr el mismo objetivo. Construye escenarios de prueba en una interfaz de usuario, encadena solicitudes y agrega aserciones haciendo clic en lugar de escribir DSL. Debido a que todo el ciclo de vida de la API (diseño, depuración, mocking, documentación) reside en un solo lugar, las pruebas pueden reutilizar los endpoints y esquemas que ya definió. Esto reduce la barrera para los ingenieros de QA y las personas de producto que no desean gestionar un proyecto Java.
Las suites visuales no se quedan atascadas en la interfaz de usuario. Apidog las ejecuta sin interfaz gráfica en CI a través de la CLI de Apidog, por lo que una suite sin código aún encaja en un pipeline automatizado. Se instala con Node:
npm install -g apidog-cli
Luego, active un escenario o suite guardado por ID, apuntando a un entorno y eligiendo formatos de informe:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t <scenarioOrSuiteId> -e <environmentId> -r cli,html,junit
El flag -t apunta a un escenario, carpeta o suite; -e selecciona el entorno; -r elige uno o más reporteros (cli, html, json, junit). Para ejecuciones dirigidas por datos, -d (o --iteration-data) toma una ruta de archivo de datos o un ID de datos de prueba. La CLI es sin interfaz gráfica y se ejecuta en cualquier paso de CI que pueda ejecutar Node. Ejecuta sus escenarios de Apidog guardados; no es un remitente de solicitudes interactivo ni un generador de carga. Vea una explicación completa en Apidog CLI para CI/CD, y una comparación lado a lado con otro ejecutor en Apidog CLI vs Newman.
Ambos enfoques producen pruebas de API automatizadas que se ejecutan sin interfaz gráfica en CI. La diferencia radica en el estilo de autoría: Karate quiere que escribas DSL en Git; Apidog quiere que hagas clic en una interfaz de usuario que también se exporta al pipeline.
Cómo Elegir
Elija Karate cuando su equipo tenga muchos desarrolladores, se sienta cómodo con la JVM y quiera que las pruebas se versionen como código junto a la aplicación. Los archivos de características de texto plano y la coincidencia de JSON incorporada valen la pena cuando los ingenieros son dueños de la suite de pruebas de principio a fin.
Elija una herramienta sin código como Apidog cuando los autores incluyan a personas de QA y de producto, cuando quiera que las pruebas estén vinculadas a un flujo de trabajo de diseño y documentación existente, o cuando prefiera no mantener una construcción Java para ejecutar verificaciones de API. Todavía obtiene cobertura de CI a través de la CLI.
Algunos equipos utilizan ambos: Karate para suites de regresión profundas y de propiedad de código, y una herramienta visual para una cobertura amplia y rápida que los no desarrolladores pueden extender. Si todavía está evaluando opciones, nuestro resumen sobre cómo elegir un framework de automatización de pruebas de API expone los criterios de decisión.
Preguntas Frecuentes
¿Necesito saber Java para usar Karate? No, no para escribir pruebas de API básicas. Los archivos de características utilizan el DSL de Gherkin, y Karate incluye los pasos HTTP y las aserciones incorporados. Querrá tener Java instalado para ejecutar las pruebas, y cierto conocimiento de Java o JavaScript ayuda una vez que necesite "helpers" personalizados o una reutilización compleja.
¿En qué se diferencia Karate de Cucumber? Ambos utilizan la sintaxis Given/When/Then de Gherkin. Con Cucumber, se escribe código de definición de pasos para respaldar cada paso. Karate proporciona los pasos de prueba de API, por lo que no hay código "pegamento" que mantener para las pruebas HTTP estándar.
¿Puede Karate ejecutarse sin Maven o Gradle? Sí. Descargue el archivo karate.jar autónomo de los lanzamientos del proyecto y ejecute los archivos de características con java -jar karate.jar <path>. Admite etiquetas, hilos paralelos y un directorio de salida personalizado sin ninguna herramienta de construcción.
¿Qué significa la sintaxis #string o #[10]? Esos son los "fuzzy matchers" de Karate. #string afirma que un campo es una cadena de cualquier valor, #number un número, y #[10] afirma un array JSON de longitud 10. Le permiten validar la forma de la respuesta sin codificar valores generados.
¿Pueden las pruebas de API sin código seguir ejecutándose en CI? Sí. Una herramienta visual como Apidog exporta los escenarios guardados a la CLI de Apidog, que no tiene interfaz gráfica y se ejecuta en cualquier paso de CI con Node. Así, usted crea pruebas en una interfaz de usuario y aún obtiene ejecuciones de pipeline automatizadas.