¿Cómo detecto la deriva del esquema de API?

Una prueba que verifica el código de estado y algunos campos sigue pasando cuando la API agrega un campo, elimina uno que no afirmas, o convierte un número en cadena. Nexus Studio almacena la forma de cada respuesta de API, nombres y tipos de campos pero nunca valores, la compara con la ejecución anterior y reporta API_DRIFTED cuando cambia. Con NEXUS_API_DRIFT_STRICT=true, el mismo cambio falla la suite.

Por el equipo de Nexus Studio, Verdict System LLC. 27 de octubre de 2026.

¿Qué es la deriva del esquema de API?

La deriva del esquema es el cambio en la forma de una respuesta entre ejecuciones: un campo agregado, un campo eliminado o un campo cuyo tipo cambió. Una API puede evolucionar. El problema ocurre cuando sus consumidores lo descubren en producción, porque nada en la suite de pruebas indicó que había cambiado.

¿Por qué una prueba de contrato que pasa no detecta la deriva?

Porque solo afirma lo que su autor contempló. Una regla como validate(res, { status: 200, hasFields: ['id'] }) sigue pasando cuando price cambia de número a cadena, ya que price no está en la regla. El cliente que suma precios es el que falla.

¿Puedo verlo ocurrir en un ejemplo ejecutable?

Guarda esto como server.mjs. Responde a un endpoint, y la variable SHAPE elige qué devuelve el endpoint: un precio como número o un precio como cadena con un nuevo campo currency.

import http from 'node:http';

// SHAPE=v1 answers {id, price: 9.99}; SHAPE=v2 answers {id, price: "9.99", currency: "USD"}.
const v2 = process.env.SHAPE === 'v2';
http.createServer((req, res) => {
    res.setHeader('Content-Type', 'application/json');
    res.end(JSON.stringify(v2 ? { id: 7, price: '9.99', currency: 'USD' } : { id: 7, price: 9.99 }));
}).listen(4010, '127.0.0.1');

Guarda esta prueba de API como APIT900_drift_demo.api.js en la carpeta api-tests/rest de tu workspace. Afirma el estado y un campo, como hacen muchas suites reales.

// type: rest
import { runApiSuite } from '../../utils/base-api-fixture.js';

await runApiSuite([{
    id: 'APIT900-1',
    name: 'GET /product/7 returns 200 with an id',
    fn: async ({ request, validate }) => {
        const res = await request({ method: 'GET', url: '/product/7' });
        validate(res, { status: 200, hasFields: ['id'] });
    },
}]);

Inicia el servidor en una ventana de PowerShell y ejecuta la prueba en otra. La primera ejecución no tiene nada con qué comparar, por lo que registra la forma y pasa.

$env:SHAPE = "v1"; node server.mjs

$env:API_BASE_URL = "http://127.0.0.1:4010"; nexus api APIT900 --no-app

Detén el servidor, inícialo de nuevo con $env:SHAPE = "v2" y ejecuta la misma prueba. Sigue pasando, pero la ejecución ya no es API_SECURE. Esta es la salida, reducida a las líneas relevantes:

schema drift: +1 field, 1 type change
   + currency
   ~ price: number → string
API_DRIFTED  7ms
1/1 passed
1 endpoint changed shape since the last run, set NEXUS_API_DRIFT_STRICT=true to fail the suite on it

¿Puede la deriva fallar el build?

Sí, si lo pides. Por defecto API_DRIFTED cuenta como un paso y sale con 0, porque el movimiento de la API es información y no un defecto. Se imprime en su propia línea y se registra con la diferencia en la evidencia de la ejecución, por lo que nunca se lee como un paso limpio. Establece NEXUS_API_DRIFT_STRICT=true y el mismo cambio sale con 1. Para verlo, ejecuta la prueba una vez contra v1 y una vez contra v2 con esa variable establecida.

La línea base es siempre la ejecución anterior. Después de una ejecución con deriva, la nueva forma es la línea base, por lo que la siguiente ejecución contra la misma respuesta no reporta deriva.

¿Cuáles son los límites?

• La primera ejecución de una prueba solo registra una forma. Todavía no hay nada con qué comparar.
• La forma son nombres y tipos, no significado. Si price sigue siendo un número pero cambia de dólares a centavos, nada cambia.
• La comparación es con la ejecución anterior, no con un contrato acordado. Te indica que algo cambió, no si el cambio estaba permitido.
• Cada caso de prueba conserva una forma, tomada del cuerpo de su última solicitud. Una lista se describe por su primer elemento, un objeto por hasta 200 claves, y el anidamiento se detiene en seis niveles.

¿Dónde puedo verlo?

La guía de veredictos cubre los veredictos de prueba, y la página de Evidence lista los archivos que una ejecución deja en tu disco. La prueba de 30 días ejecuta el mismo motor en tus propias pruebas de API.