Sviluppatore trasforma OpenAPI in test eseguibili e avverte sui falsi verdi

Un test che si ferma a “200 OK” non verifica l’API, verifica solo che il server risponde¹.

Uno sviluppatore indipendente sta costruendo uno strumento che converte specifiche OpenAPI in suite di test eseguibili. La parte difficile non è generare codice. È decidere quali asserzioni può fare un test generato¹. Nelle specifiche pubbliche trova spesso lo stesso buco: ogni risposta ha type: object, senza proprietà e senza required. Il generatore invia la richiesta, ottiene 200, non ha nulla da controllare, segna “pass”. La suite è verde e il contratto resta non verificato¹.

La correzione parte dalla specifica. Servono schemi di risposta con proprietà concrete e campi required. Se il corpo può essere qualsiasi cosa, niente fallisce. Servono anche le forme delle risposte di errore: 400, 401 e 404 con uno schema definito, così i test negativi possono controllare qualcosa¹. Una suite generata è lo specchio della specifica. Una specifica vaga produce test vaghi. Per questo, prima di scrivere test, l’autore legge la specifica e cerca i buchi: è noioso, ma lì sta gran parte del valore¹.

Un’asserzione sul codice di stato passa anche con un body vuoto. Aggiungere un controllo di schema sulle risposte fa diventare rossi molti verdi, che è esattamente il risultato utile. Quando manca required, il generatore non invia i campi e il test dimostra meno di quanto sembra¹.

Due controlli anticipati aiutano a scovare difetti che sfuggono fino alla produzione. Primo, 401 contro 403: token mancante uguale 401, token valido senza permessi uguale 403. Usare 401 in entrambi i casi nasconde bug di autorizzazione¹. Secondo, gli spigoli della paginazione: ultima pagina, pagina vuota, cursore scaduto, limit oltre il massimo ammesso. Costano poco da testare, costano molto se emergono dopo il rilascio¹.

Ecco un esempio minimo di come lo schema guida il test.

Prima, schema vago che fa passare tutto:

paths:
  /users:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object

Dopo, schema con proprietà e required che permette asserzioni utili:

paths:
  /users:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        email: { type: string, format: email }
                      required: [id, email]
                  nextCursor: { type: string, nullable: true }
                required: [items]
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                required: [error]

L’autore offre anche un servizio a prezzo fisso: suite di contract test in 48 ore a 149 dollari. Input richiesto: file OpenAPI 3.x in YAML o JSON, via URL pubblico o file condiviso. Output: test eseguibili per pytest, Jest o Newman, un README con le istruzioni e un elenco breve dei buchi trovati. Se sfora le 48 ore, rimborsa. Dettagli e checkout sono pubblici. Per verificare prima l’aderenza, basta inviare il link della specifica in un commento¹.

Takeaway pratico: prima di generare o scrivere un test, apri la specifica e rinforza un endpoint 200 con proprietà e required, definisci gli schemi di 400, 401 e 404, poi verifica la distinzione 401 contro 403 e i bordi della paginazione. Quella lettura preventiva cattura i buchi che una suite “verde” nasconde¹.