Automatizzare i test delle API in integrazione continua

Uno scenario costruito nell’interfaccia gira così com’è nella propria pipeline. Questa guida copre il passaggio di scala.

Prerequisiti

• Un piano Pro o Enterprise.
• Un token di organizzazione (rstk_…) da collocare nel vault dei segreti della propria CI. (La creazione di questo token in self-service dal pannello di controllo arriverà prossimamente.)

Il principio

RESTORM_TOKEN=$RESTORM_TOKEN restorm \
  --open ./api.restorm \
  --run "Tests de fumée" \
  --headless \
  --all-logs \
  --out run.log \
  --param baseUrl=$BASE_URL

Codice di uscita 0 = successo, 1 = fallimento dello scenario, 2 = errore di invocazione, 3 = diritto negato.

Serve un display virtuale

Restorm è un’applicazione desktop: anche senza finestra ha bisogno di un server di visualizzazione. Su un runner Linux occorre aggiungere il prefisso xvfb-run -a.

xvfb-run -a restorm --open ./api.restorm --run "Tests de fumée" --headless

I segreti

Non va mai scritto un segreto nel progetto. Le variabili sensibili vanno dichiarate con la sorgente di segreti variabile d’ambiente; il vault della propria CI le inietta, Restorm le legge. Si veda Segreti.

env:
  API_TOKEN: ${{ secrets.API_TOKEN }}

Parametrizzare per ambiente

Due approcci complementari:

1. Un parametro di scenario tipizzato environment: --param Env=staging. Lo stesso scenario gira contro qualunque destinazione.
2. Parametri semplici: --param baseUrl=…, --param tenant=….

La conversione segue il tipo dichiarato del parametro, e una conversione impossibile fa fallire il lancio immediatamente anziché eseguire con un valore errato. Si veda Variabili e dati.

Pubblicare il log

--out run.log scrive il log man mano. Conviene pubblicarlo come artefatto, anche quando il job fallisce — è proprio allora che serve.

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: journal-restorm
    path: run.log

Scrivere scenari leggibili in CI

Alcune abitudini che cambiano tutto quando un job rosso appare alle 3 del mattino:

• Messaggi di asserzione espliciti. Il campo message dell’azione Asserzione è ciò che comparirà nel log: conviene scrivervi che cosa si attendeva.
• Log nei passaggi chiave. Senza --all-logs vengono emesse soltanto le voci dell’azione Log: è il proprio filo narrativo.
• Validazione dello schema anziché asserzioni campo per campo. Collegando l’uscita errors di Valida uno schema a un Log si ottiene l’elenco preciso delle violazioni.
• Throw sulle uscite else critiche, perché il codice di uscita rifletta il fallimento.
• Retry attorno alle chiamate di rete instabili, anziché accettare test intermittenti. Si veda Controllo.

Ripulire

La pulizia va concatenata alla porta done dello scenario principale: done attende che tutto il sottografo sia terminato. Si veda Porte e collegamenti.

Insidie da conoscere

Insidia	Soluzione
Il job attende un inserimento	Fornire tutti i parametri con --param; in headless non si può chiedere nulla
Un’azione Toast non compare	È normale: in headless non ha effetto. Conviene usare Log
Il server MCP non compare	È voluto: senza un display reale non si avvia mai
Uscita 3	Il token o il piano — il messaggio precisa quale dei quattro casi
Il file di progetto si è spostato	--open accetta un percorso relativo al repository: conviene tenerlo relativo

Esempi completi

Le pipeline GitHub Actions e GitLab CI si trovano in Esecuzione headless e CI.