Como detectar drift de schema de API antes dos testes

Um teste que verifica o código de status e alguns campos continua passando quando a API adiciona um campo, remove um que você não valida ou transforma um número em string. O Nexus Studio armazena o formato de cada resposta da API, nomes e tipos de campos, nunca valores, compara com a execução anterior e informa API_DRIFTED quando ele muda. Com NEXUS_API_DRIFT_STRICT=true, a mesma mudança faz a suíte falhar.

Pela equipe do Nexus Studio, Verdict System LLC. 27 de outubro de 2026.

O que é drift de schema de API?

Drift de schema é a mudança do formato de uma resposta entre execuções: um campo adicionado, um campo removido ou um campo cujo tipo mudou. Uma API pode evoluir. O problema é quando seus consumidores descobrem isso em produção, porque nada na suíte de testes avisou que ela mudou.

Por que um teste de contrato que passa não o detecta?

Porque ele valida apenas o que o autor imaginou. Uma regra como validate(res, { status: 200, hasFields: ['id'] }) continua passando quando price muda de número para string, já que price não está na regra. O cliente que soma os preços é o que quebra.

Posso ver isso acontecer em um exemplo executável?

Salve isto como server.mjs. Ele responde a um endpoint, e a variável SHAPE escolhe o que o endpoint retorna: um preço como número ou um preço como string com um novo 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');

Salve este teste de API como APIT900_drift_demo.api.js na pasta api-tests/rest do seu workspace. Ele valida o status e um campo, como fazem muitas suítes reais.

// 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'] });
    },
}]);

Inicie o servidor em uma janela do PowerShell e execute o teste em outra. A primeira execução não tem com o que comparar, então registra o formato e passa.

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

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

Pare o servidor, inicie-o novamente com $env:SHAPE = "v2" e execute o mesmo teste. Ele ainda passa, mas a execução deixa de ser API_SECURE. Esta é a saída, reduzida às linhas que importam:

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

O drift pode falhar o build?

Sim, sob demanda. Por padrão, API_DRIFTED conta como aprovação e sai com 0, porque a API mudar é informação, não um defeito. Ele é impresso em uma linha própria e registrado com a diferença nas evidências da execução, portanto nunca é lido como uma aprovação limpa. Defina NEXUS_API_DRIFT_STRICT=true e a mesma mudança sai com 1. Para ver isso, execute o teste uma vez contra v1 e outra contra v2 com essa variável definida.

A linha de base é sempre a execução anterior. Depois de uma execução com drift, o novo formato passa a ser a linha de base, então a próxima execução contra a mesma resposta não informa drift.

Quais são os limites?

A primeira execução de um teste apenas registra um formato. Ainda não há nada de que ele possa divergir.
O formato são nomes e tipos, não significado. Se price continua sendo um número, mas passa de dólares para centavos, nada muda.
A comparação é com a execução anterior, não com um contrato que você acordou. Ela informa que algo mudou, não se a mudança era permitida.
Cada caso de teste mantém um único formato, tirado do corpo da sua última requisição. Uma lista é descrita pelo primeiro elemento, um objeto por até 200 chaves, e o aninhamento para em seis níveis.

Onde posso ver isso?

O guia de veredictos cobre os veredictos de teste, e a página Evidence lista os arquivos que uma execução deixa no seu disco. O teste de 30 dias executa o mesmo mecanismo nos seus próprios testes de API.