implement-karate-tests

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):

Campo	Obligatorio	Descripción
Status / estado	No	Estado del caso: NOT_IMPLEMENTED, IMPLEMENTED (default: NOT_IMPLEMENTED)
título / title	Sí	Nombre descriptivo del caso
API URL / url / endpoint	Sí	URL completa o path relativo
Request Method / method	Sí	GET, POST, PUT, DELETE, PATCH
Response Code / status	Sí	Código HTTP esperado
Response JSON / response	No	Descripción o estructura de la respuesta
Request Body / body	No	JSON del body (para POST/PUT/PATCH)
Headers	No	Headers adicionales requeridos
Params / Query Params	No	Parámetros de query string
Auth / Authorization	No	Tipo de autenticación requerida
Notas / notes	No	Información adicional para el agente
Status	No	Estado de implementación: NOT_IMPLEMENTED, IMPLEMENTED

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": "[email protected]",
    "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:

Estado	Comportamiento
NOT_IMPLEMENTED	Se implementa por defecto
IMPLEMENTED	Se omite por defecto (no se sobrescribe)

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

Flag	Propósito	Ejemplo
--case <número>	Implementar solo un caso	--case 1
--status ALL	Implementar todos sin importar estado	--status ALL
--force	Sobrescribir casos IMPLEMENTED	--force
--skip-update	No actualizar el STATUS en karate-tests.md	--skip-update

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 dr

---

*Content truncated.*