===========================================
REFERENCIA RÁPIDA - API TESTING
Framework Hakalab - Testing de APIs REST
===========================================

Esta guía proporciona una referencia rápida de todos los steps de API testing
disponibles en el framework, organizados por funcionalidad.

===========================================
ÍNDICE RÁPIDO
===========================================

1. Requests HTTP Básicos
2. Validación de Respuestas
3. Validación Avanzada de JSON
4. Comparación con Archivos
5. Validación de Esquemas JSON Schema
6. Validación de Tipos y Patrones
7. Validación de Arrays
8. Autenticación
9. Headers y Configuración
10. Performance y Seguridad

===========================================
1. REQUESTS HTTP BÁSICOS
===========================================

GET:
----
envío petición GET a "{url}" y guardo la respuesta en la variable "{variable_name}"
I send GET request to "{url}" and store response in variable "{variable_name}"

POST:
-----
envío petición POST a "{url}" con cuerpo "{body}" y guardo la respuesta en la variable "{variable_name}"
I send POST request to "{url}" with body "{body}" and store response in variable "{variable_name}"

PUT:
----
envío petición PUT a "{url}" con cuerpo "{body}" y guardo la respuesta en la variable "{variable_name}"
I send PUT request to "{url}" with body "{body}" and store response in variable "{variable_name}"

PATCH:
------
envío petición PATCH a "{url}" con cuerpo "{body}" y guardo la respuesta en la variable "{variable_name}"
I send PATCH request to "{url}" with body "{body}" and store response in variable "{variable_name}"

DELETE:
-------
envío petición DELETE a "{url}" y guardo la respuesta en la variable "{variable_name}"
I send DELETE request to "{url}" and store response in variable "{variable_name}"

HEAD:
-----
envío petición HEAD a "{url}" y guardo la respuesta en la variable "{variable_name}"
I send HEAD request to "{url}" and store response in variable "{variable_name}"

OPTIONS:
--------
envío petición OPTIONS a "{url}" y guardo la respuesta en la variable "{variable_name}"
I send OPTIONS request to "{url}" and store response in variable "{variable_name}"

DESDE ARCHIVO:
--------------
cargo JSON del archivo "{file_path}" y envío POST a "{url}" guardando respuesta en variable "{variable_name}"
I load JSON from file "{file_path}" and send POST to "{url}" storing response in variable "{variable_name}"

===========================================
2. VALIDACIÓN DE RESPUESTAS
===========================================

CÓDIGO DE ESTADO:
------------------
verifico que el código de estado de la respuesta API es "{expected_status}"
I verify API response status code is "{expected_status}"

verifico que el estado de respuesta API está en el rango "{min_status}" a "{max_status}"
I verify API response status is in range "{min_status}" to "{max_status}"

CONTENIDO:
----------
verifico que la respuesta API contiene "{key}" con valor "{expected_value}"
I verify API response contains "{key}" with value "{expected_value}"

verifico que el cuerpo de respuesta API contiene el texto "{expected_text}"
I verify API response body contains text "{expected_text}"

HEADERS:
--------
verifico que el header de respuesta API "{header_name}" es igual a "{expected_value}"
I verify API response header "{header_name}" equals "{expected_value}"

verifico que el header de respuesta API "{header_name}" contiene "{expected_text}"
I verify API response header "{header_name}" contains "{expected_text}"

TIEMPO DE RESPUESTA:
--------------------
verifico que el tiempo de respuesta de la API es menor a "{max_seconds}" segundos
I verify API response time is less than "{max_seconds}" seconds

CONTENT TYPE:
-------------
verifico que el tipo de contenido de respuesta API es "{expected_content_type}"
I verify API response content type is "{expected_content_type}"

JSON VÁLIDO:
------------
verifico que la respuesta API es JSON válido
I verify API response is valid JSON

===========================================
3. VALIDACIÓN AVANZADA DE JSON
===========================================

VALIDACIÓN DE TIPOS:
--------------------
verifico que el JSON de respuesta API tiene el campo "{field_path}" con tipo "{expected_type}"
I verify API response JSON has field "{field_path}" with type "{expected_type}"

Tipos soportados: string, number, integer, boolean, array, object, null

Ejemplos:
- verifico que el JSON de respuesta API tiene el campo "user.age" con tipo "integer"
- verifico que el JSON de respuesta API tiene el campo "user.email" con tipo "string"
- verifico que el JSON de respuesta API tiene el campo "user.roles" con tipo "array"

VALIDACIÓN CON REGEX:
---------------------
verifico que el campo "{field_path}" del JSON de respuesta API coincide con el patrón "{pattern}"
I verify API response JSON field "{field_path}" matches regex "{pattern}"

Ejemplos:
- Email: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
- Teléfono: "^\\+?[1-9]\\d{1,14}$"
- UUID: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
- Fecha ISO: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}"

VALIDACIÓN DE RANGOS:
---------------------
verifico que el campo "{field_path}" del JSON de respuesta API está en el rango {min_value} a {max_value}
I verify API response JSON field "{field_path}" is in range {min_value} to {max_value}

Ejemplos:
- verifico que el campo "age" del JSON de respuesta API está en el rango 18 a 65
- verifico que el campo "price" del JSON de respuesta API está en el rango 0 a 9999.99
- verifico que el campo "rating" del JSON de respuesta API está en el rango 1 a 5

VALIDACIÓN DE VALORES NULOS:
-----------------------------
verifico que el JSON de respuesta API no tiene valores nulos
I verify API response JSON has no null values

===========================================
4. COMPARACIÓN CON ARCHIVOS
===========================================

COMPARACIÓN EXACTA:
-------------------
verifico que el JSON de respuesta API coincide exactamente con el archivo "{expected_file}"
I verify API response JSON exactly matches file "{expected_file}"

IGNORANDO ORDEN:
----------------
verifico que el JSON de respuesta API coincide con el archivo "{expected_file}" ignorando orden
I verify API response JSON matches file "{expected_file}" ignoring order

IGNORANDO CAMPOS:
-----------------
verifico que el JSON de respuesta API coincide con el archivo "{expected_file}" ignorando campos "{ignored_fields}"
I verify API response JSON matches file "{expected_file}" ignoring fields "{ignored_fields}"

Ejemplo:
- ignorando campos "id,created_at,updated_at"

GUARDAR RESPUESTA:
------------------
guardo el JSON de respuesta API en el archivo "{file_path}"
I save API response JSON to file "{file_path}"

===========================================
5. VALIDACIÓN DE ESQUEMAS JSON SCHEMA
===========================================

VALIDAR CON ESQUEMA:
--------------------
verifico que el JSON de respuesta API coincide con el esquema del archivo "{schema_file}"
I verify API response JSON matches schema file "{schema_file}"

ESTRUCTURA DE ESQUEMA JSON SCHEMA (Draft 7):
--------------------------------------------
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "User",
  "type": "object",
  "required": ["id", "name", "email"],
  "properties": {
    "id": {"type": "integer", "minimum": 1},
    "name": {"type": "string", "minLength": 1, "maxLength": 100},
    "email": {"type": "string", "format": "email"},
    "age": {"type": "integer", "minimum": 18, "maximum": 100},
    "roles": {
      "type": "array",
      "items": {"type": "string"},
      "minItems": 1
    }
  },
  "additionalProperties": false
}

VALIDACIONES SOPORTADAS:
------------------------
✅ Tipos de datos (string, number, integer, boolean, array, object, null)
✅ Formatos (email, uri, date-time, uuid, etc.)
✅ Rangos (minimum, maximum, minLength, maxLength)
✅ Enumeraciones (enum)
✅ Campos requeridos (required)
✅ Propiedades adicionales (additionalProperties)
✅ Patrones (pattern)
✅ Arrays (minItems, maxItems, uniqueItems)

===========================================
6. VALIDACIÓN DE TIPOS Y PATRONES
===========================================

TIPOS PRIMITIVOS:
-----------------
- string: Cadenas de texto
- number: Números (enteros o decimales)
- integer: Números enteros
- boolean: true/false
- array: Arrays/listas
- object: Objetos/diccionarios
- null: Valores nulos

PATRONES COMUNES:
-----------------

Email:
^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$

Teléfono Internacional:
^\\+?[1-9]\\d{1,14}$

UUID:
^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Fecha ISO 8601:
^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}

URL:
^https?://[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}

Código Postal (España):
^\\d{5}$

===========================================
7. VALIDACIÓN DE ARRAYS
===========================================

LONGITUD:
---------
el array "{array_name}" en la respuesta debería tener {expected_length} elementos
array "{array_name}" in response should have {expected_length} elements

CONTIENE ELEMENTO:
------------------
verifico que el array "{array_path}" del JSON de respuesta API contiene un elemento con "{field}" igual a "{value}"
I verify API response JSON array "{array_path}" contains item with "{field}" equals "{value}"

TODOS LOS ELEMENTOS TIENEN CAMPO:
----------------------------------
verifico que todos los elementos del array "{array_path}" del JSON de respuesta API tienen el campo "{field}"
I verify API response JSON array "{array_path}" all items have field "{field}"

ELEMENTO ESPECÍFICO:
--------------------
el elemento {index} del array "{array_name}" debería tener el campo "{key}" con valor "{expected_value}"
element {index} of array "{array_name}" should have field "{key}" with value "{expected_value}"

===========================================
8. AUTENTICACIÓN
===========================================

BEARER TOKEN:
-------------
establezco el header "Authorization" con valor "Bearer {token}"
I set header "Authorization" with value "Bearer {token}"

envío petición GET autenticada a "{url}" con token "{token}" y guardo la respuesta en la variable "{variable_name}"
I send authenticated GET request to "{url}" with token "{token}" and store response in variable "{variable_name}"

API KEY:
--------
establezco el header "X-API-Key" con valor "{api_key}"
I set header "X-API-Key" with value "{api_key}"

BASIC AUTH:
-----------
establezco autenticación básica con usuario "{user}" y contraseña "{password}"
I set basic authentication with user "{user}" and password "{password}"

===========================================
9. HEADERS Y CONFIGURACIÓN
===========================================

ESTABLECER HEADER:
------------------
establezco el header de API "{header_name}" a "{header_value}"
I set API header "{header_name}" to "{header_value}"

URL BASE:
---------
establezco la URL base de API a "{base_url}"
I set API base URL to "{base_url}"

TIMEOUT:
--------
establezco el timeout de API a "{timeout}" segundos
I set API timeout to "{timeout}" seconds

LIMPIAR SESIÓN:
---------------
limpio todos los datos de sesión API
I clear all API session data

===========================================
10. PERFORMANCE Y SEGURIDAD
===========================================

PERFORMANCE:
------------
mido el rendimiento de API para "{iterations}" peticiones a "{url}" y guardo métricas en variable "{variable_name}"
I measure API performance for "{iterations}" requests to "{url}" and store metrics in variable "{variable_name}"

envío peticiones API concurrentes "{count}" veces a "{url}" y verifico que todas tengan éxito
I send concurrent API requests "{count}" times to "{url}" and verify all succeed

SEGURIDAD:
----------
verifico que la respuesta API tiene headers de seguridad
I verify API response has security headers

verifico que el endpoint API "{endpoint}" soporta CORS
I verify API endpoint "{endpoint}" supports CORS

RATE LIMITING:
--------------
verifico que los headers de rate limit están presentes en la respuesta API
I verify API response rate limit headers are present

===========================================
EJEMPLOS DE FLUJOS COMPLETOS
===========================================

FLUJO 1: CRUD Completo con Validación
--------------------------------------
# Crear
When cargo JSON del archivo "payloads/create_user.json" y envío POST a "/api/users" guardando respuesta en variable "response"
Then la respuesta debería tener código 201
And verifico que el JSON de respuesta API coincide con el esquema del archivo "schemas/user_schema.json"
And extraigo el campo "id" de la respuesta y lo guardo en la variable "user_id"

# Leer
When envío petición GET a "/api/users/${user_id}"
Then la respuesta debería tener código 200
And verifico que el JSON de respuesta API coincide con el archivo "expected/user.json" ignorando campos "created_at,updated_at"

# Actualizar
When cargo JSON del archivo "payloads/update_user.json" y envío PUT a "/api/users/${user_id}" guardando respuesta en variable "update_response"
Then la respuesta debería tener código 200

# Eliminar
When envío petición DELETE a "/api/users/${user_id}"
Then la respuesta debería tener código 204


FLUJO 2: Validación Completa de Estructura
-------------------------------------------
When envío petición GET a "/api/products"
Then la respuesta debería tener código 200

# Validar con esquema
And verifico que el JSON de respuesta API coincide con el esquema del archivo "schemas/products_schema.json"

# Validar tipos
And verifico que el JSON de respuesta API tiene el campo "products" con tipo "array"
And verifico que el JSON de respuesta API tiene el campo "total" con tipo "integer"

# Validar arrays
And verifico que todos los elementos del array "products" del JSON de respuesta API tienen el campo "id"
And verifico que todos los elementos del array "products" del JSON de respuesta API tienen el campo "price"

# Validar rangos
And verifico que el campo "products.0.price" del JSON de respuesta API está en el rango 0 a 999999

# Validar patrones
And verifico que el campo "products.0.sku" del JSON de respuesta API coincide con el patrón "^[A-Z]{3}-\\d{6}$"


FLUJO 3: Testing de Paginación
-------------------------------
When envío petición GET a "/api/users?page=1&limit=20"
Then la respuesta debería tener código 200

# Validar estructura de paginación
And verifico que el JSON de respuesta API tiene el campo "data" con tipo "array"
And verifico que el JSON de respuesta API tiene el campo "pagination.total" con tipo "integer"
And verifico que el JSON de respuesta API tiene el campo "pagination.page" con tipo "integer"
And verifico que el JSON de respuesta API tiene el campo "pagination.limit" con tipo "integer"

# Validar valores
And el campo "pagination.page" debería ser 1
And el campo "pagination.limit" debería ser 20
And el array "data" en la respuesta debería tener 20 elementos


FLUJO 4: Validación de Errores
-------------------------------
When cargo JSON del archivo "payloads/invalid_user.json" y envío POST a "/api/users" guardando respuesta en variable "error_response"
Then la respuesta debería tener código 400

# Validar estructura de error
And verifico que el JSON de respuesta API coincide con el esquema del archivo "schemas/error_schema.json"
And verifico que el JSON de respuesta API tiene el campo "error.code" con tipo "string"
And verifico que el JSON de respuesta API tiene el campo "error.message" con tipo "string"
And verifico que el JSON de respuesta API tiene el campo "error.details" con tipo "array"

# Validar detalles
And el array "error.details" en la respuesta debería tener al menos 1 elemento
And verifico que todos los elementos del array "error.details" del JSON de respuesta API tienen el campo "field"
And verifico que todos los elementos del array "error.details" del JSON de respuesta API tienen el campo "message"

===========================================
TIPS Y MEJORES PRÁCTICAS
===========================================

1. ORGANIZACIÓN DE ARCHIVOS
----------------------------
✅ Mantén esquemas en schemas/
✅ Mantén respuestas esperadas en expected/
✅ Mantén payloads en payloads/
✅ Usa nombres descriptivos

2. VALIDACIÓN INCREMENTAL
--------------------------
✅ Empieza con código de estado
✅ Luego valida tipos de campos
✅ Finalmente valida esquemas completos

3. COMPARACIÓN CON ARCHIVOS
----------------------------
✅ Usa "ignorando orden" para arrays sin orden específico
✅ Usa "ignorando campos" para timestamps y IDs
✅ Mantén archivos esperados actualizados

4. ESQUEMAS JSON SCHEMA
-----------------------
✅ Versiona tus esquemas
✅ Documenta cambios
✅ Mantén compatibilidad hacia atrás
✅ Usa $ref para reutilizar esquemas

5. DEBUGGING
------------
✅ Guarda respuestas actuales para comparar
✅ Usa herramientas de diff para JSON
✅ Valida esquemas con herramientas online
✅ Activa logging detallado

===========================================
RECURSOS ADICIONALES
===========================================

DOCUMENTACIÓN:
--------------
- Guía completa: GUIA_API_TESTING_NotebookLM.txt
- Ejemplos: api_testing_advanced_example.feature
- Esquemas de ejemplo: examples/schemas/

HERRAMIENTAS ONLINE:
--------------------
- JSON Schema Validator: jsonschemavalidator.net
- JSON Diff: jsondiff.com
- Regex Tester: regex101.com
- JSON Formatter: jsonformatter.org

===========================================
FIN DE LA REFERENCIA RÁPIDA
===========================================

Versión: 1.3.0
Última actualización: 2026-02-12
