Karate Framework desde Cero: Tutorial Completo de Instalación y Primeras Pruebas

✍️ Jorge Escorcia📅 Abril 2026🏷️ TUTORIAL⏱️ 12 min de lectura

Cuando empecé a aprender automatización de APIs, lo primero que me frustraba era la cantidad de código Java que necesitaba para hacer algo tan simple como validar una respuesta JSON. Fue entonces cuando descubrí Karate Framework — y desde el primer día cambió completamente mi forma de trabajar.

En este tutorial voy a mostrarte exactamente cómo instalé Karate en mi máquina, cómo configuré mi primer proyecto desde cero y cómo escribí mis primeras pruebas funcionales de API. Sin rodeos, con ejemplos reales que puedes copiar y ejecutar hoy mismo.

💡 ¿Ya sabes qué es Karate pero quieres ir directo a la práctica? Si quieres repasar los conceptos antes de seguir, tengo una guía introductoria: Karate Framework: Automatización de APIs Simple y Efectiva.

Requisitos Previos

Antes de comenzar, necesitas tener instalado en tu máquina:

• Java JDK 11 o superior — Karate corre sobre la JVM
• Maven 3.6+ o Gradle 7+ — para gestionar dependencias
• IntelliJ IDEA (recomendado) o cualquier IDE con soporte Java

Para verificar que tienes Java instalado, abre la terminal y ejecuta:

TERMINAL

java --version
# Deberías ver algo como: openjdk 17.0.x o java 11.0.x

mvn --version
# Deberías ver: Apache Maven 3.x.x

Si no tienes Java instalado, descárgalo desde adoptium.net — es gratuito y funciona en Windows, macOS y Linux.

Paso 1 — Crear el Proyecto Maven

Vamos a crear el proyecto usando el arquetipo estándar de Maven. Abre tu terminal y ejecuta:

TERMINAL

mvn archetype:generate \
  -DgroupId=com.mundoqa.tests \
  -DartifactId=karate-api-tests \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DarchetypeVersion=1.4 \
  -DinteractiveMode=false

Esto crea una carpeta llamada karate-api-tests con la estructura base de Maven. Ábrela en IntelliJ IDEA.

Paso 2 — Agregar la Dependencia de Karate al pom.xml

Abre el archivo pom.xml en la raíz del proyecto y reemplaza su contenido por este:

pom.xml

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mundoqa.tests</groupId>
  <artifactId>karate-api-tests</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
    <karate.version>1.4.1</karate.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>com.intuit.karate</groupId>
      <artifactId>karate-junit5</artifactId>
      <version>${karate.version}</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <testResources>
      <testResource>
        <directory>src/test/resources</directory>
      </testResource>
      <testResource>
        <directory>src/test/java</directory>
        <excludes><exclude>**/*.java</exclude></excludes>
      </testResource>
    </testResources>
  </build>
</project>

✅ Tip de experiencia La sección <testResources> es crítica. Sin ella, Maven no incluye los archivos .feature en el classpath y las pruebas no se ejecutan. Es el error más común al configurar Karate por primera vez.

Paso 3 — Estructura de Carpetas

Karate organiza sus pruebas en archivos .feature. Crea la siguiente estructura dentro de src/test/java:

ESTRUCTURA DEL PROYECTO

karate-api-tests/
├── pom.xml
└── src/
    └── test/
        └── java/
            └── com/
                └── mundoqa/
                    ├── TestRunner.java        <-- Clase de ejecución
                    └── usuarios/
                        └── usuarios.feature   <-- Tus pruebas aquí

Paso 4 — Crear el TestRunner

El TestRunner es la clase Java que le dice a JUnit 5 que ejecute las pruebas de Karate. Crea el archivo TestRunner.java:

TestRunner.java

package com.mundoqa;

import com.intuit.karate.junit5.Karate;
import org.junit.jupiter.api.Test;

class TestRunner {

    @Test
    void testAll() {
        Karate.run().relativeTo(getClass()).call();
    }
}

Con esta configuración, Karate buscará automáticamente todos los archivos .feature en el mismo paquete y los ejecutará.

Paso 5 — Tu Primera Prueba con Karate

Ahora viene la parte divertida. Vamos a escribir pruebas reales contra una API pública. Usaré JSONPlaceholder — una API de pruebas gratuita perfecta para practicar.

Crea el archivo usuarios.feature:

usuarios.feature

Feature: Pruebas de la API de Usuarios

  Background:
    * url 'https://jsonplaceholder.typicode.com'

  Scenario: Obtener todos los usuarios
    Given path '/users'
    When method GET
    Then status 200
    And match response #array
    And match response[0].name == 'Leanne Graham'

  Scenario: Obtener un usuario por ID
    Given path '/users/1'
    When method GET
    Then status 200
    And match response.id == 1
    And match response.email == '#string'
    And match response.address == '#object'

  Scenario: Crear un nuevo usuario (POST)
    Given path '/users'
    And request { name: 'Jorge QA', username: 'jorgeqa', email: 'jorge@mundoqa.com' }
    When method POST
    Then status 201
    And match response.name == 'Jorge QA'
    And match response.id == '#number'

¿Qué está pasando en este archivo?

• Background: Define la URL base que se reutiliza en todos los escenarios del feature. Evita repetición.
• Given / When / Then: La sintaxis Gherkin que hace las pruebas legibles para cualquier persona del equipo.
• match response #array: Karate valida que la respuesta sea un array JSON. No necesitas escribir código Java para eso.
• ‘#string’ y ‘#number’: Son los “fuzzy matchers” de Karate — validan el tipo de dato sin importar el valor exacto.

Paso 6 — Ejecutar las Pruebas

Desde la terminal en la raíz del proyecto:

TERMINAL

mvn test

Karate genera automáticamente un reporte HTML detallado en:

RUTA DEL REPORTE

target/karate-reports/karate-summary.html

Ábrelo en el navegador y verás cada escenario ejecutado, el tiempo de respuesta, el cuerpo de la petición y la respuesta completa. Es uno de los reportes más completos que he visto en frameworks de testing.

✅ Lo que ves en el reporte El reporte muestra: código de estado HTTP, headers de respuesta, cuerpo JSON formateado, tiempo de ejecución por escenario y el resultado de cada assertion. Perfecto para compartir con el equipo o adjuntar a un bug report.

Paso 7 — Pruebas con Variables y Datos Dinámicos

Una de las funcionalidades más potentes de Karate es el manejo de variables entre pasos. Esto es especialmente útil para flujos que dependen de datos generados en pasos anteriores — como crear un recurso y luego consultarlo.

flujo-completo.feature

Feature: Flujo completo — crear y validar post

  Background:
    * url 'https://jsonplaceholder.typicode.com'

  Scenario: Crear un post y luego obtenerlo por ID
    # Paso 1: Crear el post
    Given path '/posts'
    And request
      """
      {
        "title": "Mi Primer Post Automatizado",
        "body": "Contenido generado por Karate Framework",
        "userId": 1
      }
      """
    When method POST
    Then status 201
    * def postId = response.id
    * print 'Post creado con ID:', postId

    # Paso 2: Consultar el post creado usando el ID guardado
    Given path '/posts/' + postId
    When method GET
    Then status 200
    And match response.id == postId

La línea * def postId = response.id extrae el ID del post recién creado y lo guarda en una variable. En el siguiente paso, usamos esa variable directamente en la URL. Así de simple.

Paso 8 — Pruebas con Múltiples Datos (Data-Driven Testing)

En QA siempre queremos probar con múltiples conjuntos de datos. Karate lo maneja con Scenario Outline:

data-driven.feature

Feature: Consultar múltiples usuarios por ID

  Background:
    * url 'https://jsonplaceholder.typicode.com'

  Scenario Outline: Validar usuario <userId>
    Given path '/users/' + <userId>
    When method GET
    Then status 200
    And match response.id == <userId>
    And match response.username == '<username>'

    Examples:
      | userId | username   |
      | 1      | Bret       |
      | 2      | Antonette  |
      | 3      | Samantha   |

Con este patrón, Karate ejecuta el mismo escenario tres veces — una por cada fila de la tabla — y genera resultados individuales para cada uno. Ideal para pruebas de regresión donde necesitas validar múltiples usuarios, productos o endpoints.

Errores Comunes al Empezar con Karate (y cómo resolverlos)

En mis primeros días con Karate cometí varios errores que me costaron horas. Aquí los más frecuentes:

Error	Causa	Solución
No tests found	Falta la sección <testResources> en el pom.xml	Agregar la configuración mostrada en el Paso 2
ClassNotFoundException	Versión de Java incompatible (Java 8 con Karate 1.4+)	Usar Java 11 o superior
match failed en tipos	Comparar número con string: == "1" en vez de == 1	Sin comillas para números, con comillas para strings
Feature no encontrado	El archivo .feature no está en src/test/java	Moverlo a la misma ruta del paquete Java
Reporte no generado	Tests ejecutados desde IDE sin Maven	Usar siempre mvn test para el reporte

Próximos Pasos: ¿A dónde ir desde aquí?

Con lo que aprendiste en este tutorial ya puedes automatizar pruebas funcionales de APIs REST básicas. Pero Karate tiene mucho más:

• Autenticación: JWT, OAuth 2.0, API Keys — Karate los maneja de forma nativa
• Ambientes: Configura URLs y tokens por entorno (dev, staging, prod) con karate-config.js
• Ejecución paralela: Corre cientos de pruebas en segundos usando parallel(5)
• Mock Servers: Karate puede simular APIs completas para pruebas de contratos
• Integración CI/CD: Enchufa tu suite a Jenkins, GitHub Actions o Azure DevOps con un solo comando Maven

🎥 ¿Quieres ver todo esto en video? Si prefieres aprender con ejemplos visuales, el canal de Juan Pablo Gómez Monsalve tiene un curso gratuito en YouTube donde cubre Karate de forma muy didáctica. Es un recurso complementario excelente para reforzar lo que aprendiste aquí.

Conclusión

Karate Framework elimina la mayor barrera del testing de APIs: necesitar escribir Java para validar JSON. Con Gherkin, los tests se escriben rápido, se leen fácil y se mantienen sin drama.

En este tutorial configuramos un proyecto completo desde cero, escribimos pruebas GET y POST reales, manejamos variables entre pasos y aplicamos data-driven testing. Eso es exactamente lo que necesitas para empezar a automatizar APIs en proyectos reales.

Si tienes dudas sobre algún paso o quieres que cubra algún caso específico de Karate, escríbeme a contacto@mundoqa.com — con gusto te ayudo.

Posts relacionados

→ Karate Framework: Automatización de APIs Simple y Efectiva→ Testing de APIs con Bruno: Tutorial Completo→ Postman para Testing de APIs: Tutorial Paso a Paso