Imported from GabrielGNP/Karate-API-test (.github/skills/implement-karate-tests/SKILL.md). Install upstream with npx skills add GabrielGNP/Karate-API-test --skill implement-karate-tests. Copyright stays with the author.

Implement Karate Tests (Standalone)

Genera archivos .feature ejecutables por grupo funcional desde cualquier fuente de información de API. No requiere ASDD, specs ni Gherkin previo.

⚠️ PASO 0: Verificación previa — OBLIGATORIO

Antes de generar ningún .feature, verifica SIEMPRE:

1. ¿Existe pom.xml en la raíz?
   NO → EJECUTA /setup-karate AHORA
        Luego continúa con el Paso 1
   
2. ¿Existe src/test/java/KarateRunnerTest.java?
   NO → El setup anterior falló. Verifica errores y reintenta.
   
3. ¿Existe src/test/java/karate-config.js?
   NO → El setup anterior incompleto. Reintenta /setup-karate.

4. ¿Existe src/test/java/logback-test.xml?
   NO → El setup anterior incompleto. Reintenta /setup-karate.

Si algo falta, DETENTE y ejecuta setup antes de continuar.

Definition of Done — verificar al completar

• Proyecto Karate existe (pom.xml en raíz) — si no, ejecutar /setup-karate primero
• Todos los endpoints descubiertos tienen al menos un Scenario happy path
• Cada Scenario es independiente (no depende de otro Scenario)
• No hay URLs, tokens ni credenciales hardcodeadas
• Tags @smoke, @regresion, @positivo, @negativo aplicados correctamente
• Datos externos en archivos .json separados (para requests complejos)
• karate-config.js actualizado con la baseUrl correcta
• Se generaron runners por grupo: <Dominio>Runner.java en cada carpeta de grupo
• Se mantiene KarateRunner.java global para ejecutar todo

Lógica de resolución de input

¿Qué proporcionó el usuario?
├─ URL de documentación → hacer fetch, parsear HTML, extraer endpoints
├─ Archivo Swagger/OpenAPI (.json/.yaml) → parsear contrato, extraer endpoints + schemas
├─ Archivo local (.md/.json/.txt) → leer y parsear, extraer endpoints
├─ Definición manual en chat → estructurar la información del usuario
├─ Colección Postman (.json) → parsear colección, extraer requests
└─ Nada (sin fuente explícita) → buscar archivo por defecto:
         ├─ ¿Existe karate-tests.md en la raíz? → leer y parsear
         ├─ ¿Existe api-definition.md en la raíz? → leer y parsear
         └─ No existe ninguno → preguntar al usuario qué API quiere testear

Archivo de definición por defecto: karate-tests.md

Cuando el usuario no especifica fuente, el agente busca karate-tests.md en la raíz del proyecto. Este archivo usa un formato markdown flexible que el agente parsea automáticamente.

Formato mínimo

Cada caso de test se define como un bloque ## con campos clave-valor. El agente reconoce los siguientes campos (case-insensitive, orden libre):

Ejemplo de karate-tests.md

# Tests de API — Automation Exercise

Base URL: https://automationexercise.com

## Caso 1
título: API 1 - GET All Products List
API URL: https://automationexercise.com/api/productsList
Request Method: GET
Response Code: 200
Response JSON: All products list
Status: NOT_IMPLEMENTED

## Caso 2
título: API 2 - POST To All Products List
API URL: https://automationexercise.com/api/productsList
Request Method: POST
Response Code: 200
Response JSON: All products list (should fail without search params)
Status: IMPLEMENTED

## Caso 3
título: API 5 - POST To Search Product
API URL: https://automationexercise.com/api/searchProduct
Request Method: POST
Request Body: { "search_product": "top" }
Response Code: 200
Response JSON: Searched products list
Status: NOT_IMPLEMENTED

## Caso 4
título: API 11 - POST Create Account
API URL: https://automationexercise.com/api/createAccount
Request Method: POST
Request Body:
  {
    "name": "Test User",
    "email": "test@example.com",
    "password": "pass123",
    "firstname": "Test",
    "lastname": "User",
    "address": "123 Street",
    "country": "USA",
    "state": "CA",
    "city": "LA",
    "zipcode": "90001",
    "mobile_number": "1234567890"
  }
Response Code: 200
Response JSON: User created
Auth: No
Status: NOT_IMPLEMENTED

Reglas de parsing

1. # Título principal (h1): nombre del grupo / suite. Si incluye Base URL: en esta sección, se usa como baseUrl.
2. ## Caso N (h2): cada h2 delimita un caso de test independiente.
3. Campos clave-valor: el agente busca campo: seguido del valor. Acepta variantes en español e inglés.
4. Request Body multilínea: si el body ocupa varias líneas, se parsea como JSON hasta el siguiente campo o bloque ##.
5. Campos no reconocidos: se ignoran sin error (el formato es extensible).
6. Base URL: si se define en el h1, el agente actualiza karate-config.js. Si cada caso tiene URL completa, el agente extrae el dominio común como baseUrl.

Agrupación automática

El agente agrupa los casos por dominio funcional basándose en:

• Prefijo de path común: /api/productsList, /api/searchProduct → grupo "products"
• Palabras clave en el título: "Products", "Account", "Brand" → un grupo por cada una
• Si no puede agrupar, crea un solo feature con todos los casos

Campo STATUS

El agente respeta el estado de cada caso para decidir si implementarlo:

Lógica de decisión

FOR cada caso en karate-tests.md:
  READ status = case.STATUS (default: NOT_IMPLEMENTED)
  
  IF status == IMPLEMENTED:
    SKIP - No generar, no sobrescribir
  ELSE:
    GENERATE .feature normalmente
    UPDATE karate-tests.md: Status = IMPLEMENTED

Flags de control

Ejemplos de uso

Implementar solo NOT_IMPLEMENTED (default):

Implementa los tests del karate-tests.md

Implementar caso específico:

Implementa el caso 1 del karate-tests.md

Implementar todos sin importar estado:

Implementa los tests del karate-tests.md --status ALL

Sobrescribir un caso ya implementado:

Implementa el caso 2 --force

Mostrar estado actual:

Muestra el status de los tests del karate-tests.md

Proceso de generación

Paso 1: Descubrir endpoints

Según la fuente, extraer para cada endpoint:

• URL / path: /api/productsList
• Método HTTP: GET, POST, PUT, DELETE, PATCH
• Request body (si aplica): campos, tipos, required/optional
• Response esperada: status code, estructura JSON
• Headers requeridos: autenticación, content-type
• Parámetros: path params, query params

Parsing de URL de documentación

Cuando la fuente es una URL:

1. Hacer fetch de la URL
2. Parsear el HTML para extraer tablas o listas de APIs
3. Buscar patrones como:
   • "API URL:", "Request Method:", "Response Code:"
   • Tablas con columnas de endpoint, método, descripción
   • Bloques de código con curl o request examples
4. Si la página no es parseable, pedir al usuario que copie la información

Parsing de Swagger/OpenAPI

Cuando la fuente es un archivo OpenAPI:

1. Leer el archivo .json o .yaml
2. Extraer paths con sus operaciones
3. Extraer schemas / definitions para request/response bodies
4. Extraer securityDefinitions para autenticación
5. Mapear tags a grupos funcionales

Paso 2: Agrupar por dominio

Organizar los endpoints en grupos funcionales:

• Por recurso: todos los endpoints de /api/products* → grupo "products"
• Por tag (si Swagger): usar los tags definidos
• Por prefijo de path: /users/*, /orders/*, etc.

Paso 3: Generar .feature por grupo

Para cada grupo funcional:

Archivo principal <dominio>.feature (happy path)

@smoke @<dominio>
Feature: API de <Dominio>
  Tests de integración para los endpoints de <dominio>

Background:
  * url baseUrl

@positivo
Scenario: <Descripción del endpoint> - Happy path
  Given path '<endpoint>'
  When method <metodo>
  Then status <code>
  And match response == '#notnull'

Paso 4: Detectar y generar tipos especiales

API REST (por defecto)

@positivo @smoke
Scenario: Obtener todos los <recursos>
  Given path '<endpoint>'
  When method get
  Then status 200
  And match response == '#notnull'

GraphQL (si se detecta)

Scenario: Query GraphQL - <operación>
  Given url baseUrl + '/graphql'
  And request { query: '#(query)' }
  When method post
  Then status 200
  And match response.data == '#notnull'
  And match response.errors == '#notpresent'

SOAP (si se detecta)

Scenario: Llamada SOAP - <operación>
  Given url baseUrl + '/ws'
  And request read('data/soap-request.xml')
  And header Content-Type = 'text/xml'
  When method post
  Then status 200
  And match /Envelope/Body/Response/Status == 'OK'

UI (si se solicita con --type ui)

Scenario: Flujo E2E - <descripción>
  Given driver baseUiUrl
  And input('#field', 'value')
  When click('#button')
  Then waitForUrl('/expected-path')

Performance (si se solicita con --type perf)

@performance
Scenario: Carga en <endpoint>
  Given url baseUrl
  And path '<endpoint>'
  When method get
  Then status 200
  And assert responseTime < 2000

Mock (si hay dependencias externas)

@ignore
Feature: Mock - <servicio>

Scenario: pathMatches('/external-api/resource')
  * def response = read('data/mock-response.json')
  * def responseStatus = 200

WebSocket (si se detecta)

Scenario: Conexión WebSocket
  Given def socket = karate.webSocket(wsUrl)
  And socket.send('{"type": "subscribe"}')
  When def result = socket.listen(5000)
  Then match result contains { type: 'subscribed' }

Patrones de .feature

Background estándar (sin auth)

Background:
  * url baseUrl
  * configure headers = { Accept: 'application/json', Content-Type: 'application/json' }

Background con autenticación

Background:
  * url baseUrl
  * def authData = callonce read('classpath:helpers/auth.feature') { usuario: 'testuser', password: 'testpass' }
  * header Authorization = 'Bearer ' + authData.token
  * configure headers = { Accept: 'application/json', Content-Type: 'application/json' }

Scenario Outline para data-driven

@regresion
Scenario Outline: <descripción> con datos variados
  Given path '<endpoint>'
  And request { field: '<valor>' }
  When method post
  Then status <status>

  Examples:
    | valor    | status |
    | válido   | 200    |
    |          | 400    |
    | especial | 200    |

Validaciones con fuzzy matching

* match response ==
  """
  {
    id: '#number',
    name: '#string',
    created_at: '#string'
  }
  """

Actualizar karate-config.js

Tras descubrir la API, actualizar karate-config.js con:

• baseUrl correcto para el entorno dev (URL real de la API)
• Variables adicionales si se necesitan (API keys, tokens)

Runners por grupo funcional

Por cada grupo detectado, se genera un runner específico que GENERA REPORTES:

// ProductsRunnerTest.java en src/test/java/products/
package products;

import com.intuit.karate.Results;
import com.intuit.karate.Runner;
import static org.junit.jupiter.api.Assertions.*;
import org.junit.jupiter.api.Test;

public class ProductsRunnerTest {
    @Test
    void testProducts() {
        Results results = Runner.path("classpath:products")
                .parallel(5);
        assertEquals(0, results.getFailCount(), results.getErrorMessages());
    }
}

Notas importantes:

• Nombre de clase: <Dominio>RunnerTest (termina con Test) — OBLIGATORIO para que Surefire lo detecte
• Usa Runner.path() con el classpath del grupo (e.g., "classpath:products")
• Usa @Test de JUnit 5 (no @Karate.Test)
• Genera reportes HTML automáticamente cuando se ejecuta mvn test

Ejecución

# Ejecutar todos los tests (via KarateRunnerTest.java global)
mvn test

# Ejecutar solo un grupo
mvn test -Dtest=ProductsRunnerTest
mvn test -Dtest=AccountsRunnerTest

# Ejecutar todos los runners
mvn test -Dtest=*RunnerTest

Output

src/test/java/
├── KarateRunnerTest.java              ← Runner global (ejecuta TODO)
├── karate-config.js
├── <dominio>/
│   ├── <DominioRunnerTest>.java       ← Runner por grupo (nombre termina con "Test")
│   ├── <dominio>.feature              ← Happy path
│   └── data/
│       └── <datos>.json
├── helpers/
│   └── auth.feature                   ← Si la API requiere autenticación
├── performance/
│   └── <dominio>-perf.feature         ← Si se solicita
├── mocks/
│   └── <servicio>-mock.feature        ← Si aplica
└── ui/
    └── <dominio>-ui.feature           ← Si se solicita

Importante: Todos los nombres de runner DEBEN terminar con Test.java (*RunnerTest.java) para que Surefire los detecte automáticamente.

Reportes

Tras ejecutar mvn test, los reportes se generan automáticamente en:

target/site/surefire-report.html    ← Reporte HTML (abre en navegador)
target/karate.log                   ← Log detallado de ejecución

Los reportes incluyen:

• ✅ Resultado de cada Scenario (PASSED/FAILED)
• 📊 Detalles de requests/responses
• ⏱️ Tiempos de ejecución
• 📈 Estadísticas de cobertura

Restricciones

• Solo crear archivos en src/test/java/ — nunca tocar código del proyecto host.
• No hardcodear URLs — usar karate-config.js.
• Cada Scenario debe ser independiente.
• Tags obligatorios: @smoke, @regresion, @positivo, @negativo.
• No hardcodear tokens ni credenciales.
• Organizar features por grupo funcional.
• Si no hay suficiente información de un endpoint, generar el Scenario con # TODO: completar y preguntar al usuario.
• No inventar endpoints que no se hayan descubierto en la fuente.