Pruebas de contratos de API: un ejercicio de n8n antes de una escritura simulada
Practica pruebas de contratos de API en n8n con respuestas sintéticas, comprobaciones de campos y una escritura simulada. Ejercicio con resultados esperados propuestos.
Comprobado con las fuentes citadas el .
Tu tarea de pruebas de contratos de API y sus límites
Este ejercicio editorial utiliza pruebas de contratos de API para responder a una pregunta concreta: ¿contiene una respuesta controlada los campos que necesita la escritura propuesta? Crea tres nodos Code llamados Mock response, Check contract y Simulated write. Tu tarea consiste en dejar que las respuestas compatibles lleguen a un marcador de escritura y detener las incompatibles antes de que lo alcancen.
Los requisitos previos son un flujo de desarrollo editable en n8n y conocimientos básicos de JavaScript. n8n documenta la generación de datos de prueba con nodos Code o Edit Fields. Utiliza únicamente datos sintéticos: sin credenciales, solicitudes a API externas ni escrituras reales. La documentación proporcionada no especifica ninguna versión ni edición de n8n, por lo que no establece una compatibilidad universal con todos los entornos de ejecución o planes.
Los casos de prueba, el algoritmo y los resultados esperados que aparecen a continuación son material didáctico propuesto, no un flujo ejecutado ni validado. Son aserciones de JavaScript escritas a mano, no JSON Schema ni un contrato dirigido por el consumidor y verificado por el proveedor. La gestión de estados HTTP, la infraestructura de regresión, la reversión de cambios y el despliegue en producción quedan fuera de este ejercicio.
Sources: n8n-docs/docs/build/work-with-data/pin-and-mock-data.md at main · n8n-io/n8n-docs · GitHub
Prepara un ejemplo de pruebas de contratos de API
Utiliza una estructura envolvente definida para este ejercicio que contenga fixtureName y body. En Mock response, devuelve un caso de prueba por ejecución como un array que contenga un objeto cuya propiedad json almacene esa estructura. n8n exige que json tenga un objeto como valor dentro de su estructura de array de elementos; un envoltorio correcto no valida por sí solo la respuesta que contiene.
El contrato de éxito propuesto exige que body sea un objeto que no sea null ni un array, con las propiedades propias id de tipo string y amount de tipo number. Permite campos adicionales no relacionados y no conviertas los tipos de los valores. Creemos que un contrato útil para practicar debe expresar lo que necesita el consumidor, en lugar de fijar todos los campos que el proveedor devuelva en ese momento.
Utiliza estos casos de prueba sugeridos. Asigna a fixtureName el nombre de su fila; la tabla muestra el valor de body y el resultado propuesto.
| Caso de prueba | body | Resultado esperado |
|---|---|---|
| baseline | {"id":"order-a","amount":12} | Marcador de escritura |
| extra-field | {"id":"order-a","amount":12,"note":"ok"} | Marcador de escritura |
| missing-id | {"amount":12} | Error de contrato: id |
| string-amount | {"id":"order-a","amount":"12"} | Error de contrato: amount |
| null-body | null | Error de contrato: body |
| array-body | [] | Error de contrato: body |
| upstream-error | {"error":{"code":"RATE_LIMITED","message":"Try later"}} | Error del servicio de origen |
| missing-code | {"error":{"message":"Try later"}} | Error de contrato: error.code |
| wrong-message | {"error":{"code":"RATE_LIMITED","message":12}} | Error de contrato: error.message |
Sources: Common issues | Nodes | n8n Docs, Object.hasOwn() - JavaScript | MDN, typeof - JavaScript | MDN
Construye la comprobación del contrato antes del marcador
Configura Check contract en Run Once for All Items y lee const items = $input.all(). n8n documenta este modo y este método de acceso a los datos de entrada. Implementa el siguiente algoritmo sugerido, examinando todos los elementos antes de devolver nada.
- Recorre items y lee json.fixtureName y json.body de cada elemento.
- Rechaza body cuando sea null, typeof body no sea "object" o Array.isArray(body) sea true.
- Si Object.hasOwn(body, "error"), exige que error sea un objeto que no sea null ni un array. Exige que sus propiedades propias code y message tengan typeof "string".
- Para los objetos de error mal formados, lanza new Error con el nombre del caso de prueba, "Contract error" y el campo que ha fallado. Si la estructura del error es válida, lanza un "Upstream error" que contenga el nombre del caso de prueba y error.code.
- En caso contrario, exige Object.hasOwn(body, "id") y typeof body.id === "string"; exige Object.hasOwn(body, "amount") y typeof body.amount === "number". Lanza un error de contrato descriptivo si falla cualquiera de estas comprobaciones.
- Devuelve items solo después de que termine todo el bucle. No devuelvas los elementos aceptados desde dentro del bucle.
Object.hasOwn() distingue una propiedad propia de una ausente o heredada; aun así, hay que comprobar su valor. En JavaScript, typeof indica que tanto null como los arrays son objetos, así que exclúyelos explícitamente. Confirma que Object.hasOwn() esté disponible en tu entorno de ejecución.
Configura la opción On Error del validador en Stop Workflow: n8n documenta que impide la ejecución de los siguientes nodos tras un error. Continue, en cambio, continúa con los últimos datos válidos. Detener el flujo no deshace escrituras anteriores, por eso este ejercicio sitúa el marcador después de la validación.
Sources: skills/skills/n8n-code-nodes-official/SKILL.md at main · n8n-io/skills · GitHub, Nodeinputdata, Object.hasOwn() - JavaScript | MDN, typeof - JavaScript | MDN, throw - JavaScript | MDN, Work with nodes, n8n-docs/docs/build/understand-workflows/workflow-components/work-with-nodes.md at main · n8n-io/n8n-docs · GitHub
Ejecuta cada caso por separado y registra las evidencias de finalización
En Simulated write, utiliza $input.all().map(item => ({json: {wouldWrite: true, id: item.json.body.id}})) como valor de retorno. Este marcador es únicamente un recurso del ejercicio. Ejecuta la secuencia completa por separado para cada caso de prueba y registra el diagnóstico observado y si se ejecutó el nodo marcador.
Utiliza la siguiente lista como criterios de finalización sugeridos para las pruebas de contratos de API. A nuestro juicio, la observación decisiva es si la ejecución llega al marcador después de un rechazo; un mensaje de error legible no basta.
Si aparece un marcador inesperado, revisa la opción On Error del validador y comprueba que lance el error antes de devolver datos. Si falla la salida de Code, revisa el envoltorio de array y que json tenga un objeto como valor. Si se aceptan null o arrays, revisa las comprobaciones de body en lugar de confiar solo en typeof.
Sources: Nodeinputdata, typeof - JavaScript | MDN, throw - JavaScript | MDN, Work with nodes, n8n-docs/docs/build/understand-workflows/workflow-components/work-with-nodes.md at main · n8n-io/n8n-docs · GitHub, Common issues | Nodes | n8n Docs
Reflexiona sobre lo que demuestra superar las pruebas simuladas
Para este ejercicio de pruebas de contratos de API, la solución sugerida consiste en validar todos los datos de entrada y, después, pasar a un nodo marcador independiente. Reflexiona sobre por qué se permite un campo adicional, por qué un error bien formado del servicio de origen sigue bloqueando el marcador y qué campos obligatorios necesitaría tu consumidor real.
Superar estas pruebas simuladas no demuestra que un proveedor real siga cumpliendo el contrato. El artículo Contract Test de Martin Fowler, publicado en 2011, distingue entre probar con un doble de prueba y comprobar si el servicio externo se ajusta a él. Trata los resultados registrados como evidencia sobre estos casos de prueba y esta configuración del flujo.
Sources: Contract Test
