Esecuzione headless e integrazione continua

Uno scenario costruito nell’interfaccia si esegue senza finestra dalla riga di comando. È la strada che trasforma i test di API in una fase di pipeline.

restorm \
  --open ./projet.restorm \
  --run "Find pets by status" \
  --headless \
  --param status=available

Edizione Pro

L’esecuzione headless è inclusa nelle edizioni Pro ed Enterprise. Richiede un token di organizzazione, fornito nella variabile d’ambiente RESTORM_TOKEN. Si veda Piani e funzionalità.

Gli argomenti

Argomento	Ruolo
--open <path>, -o	Il progetto da aprire. Obbligatorio con --run
--run <target>	Lo scenario da eseguire. La sua presenza attiva la modalità riga di comando
--by <name|id>	Come --run designa lo scenario: per nome (predefinito) o per identificatore
--headless	Nessuna finestra. Senza questo argomento la finestra appare mentre il log scorre sulla console
--param name=value	Un valore per un parametro di input dello scenario (un riquadro Input / Param). Ripetibile
--all-logs	Include le voci del motore; per impostazione predefinita vengono emesse solo quelle dell’azione Log
--out <file>	Scrive il log anche in un file, man mano
--clear-settings, -cls	Reimposta le preferenze prima del lancio

Un --param mal formato (senza =) viene segnalato sull’output di errore e ignorato. nom= (valore vuoto) è accettato.

I valori vengono convertiti in base al tipo dichiarato del parametro — si veda Variabili e dati.

--param prende di mira gli input dello scenario, non le variabili d’ambiente

--param alimenta i riquadri Input / Param dichiarati nello scenario — non modifica una variabile d’ambiente. Perciò --param status=available qui sopra funziona soltanto perché lo scenario espone un parametro di input denominato status. Volere sovrascrivere l’URL di base con --param baseUrl=… non avrebbe alcun effetto se baseUrl è una variabile d’ambiente: un valore che vive in un ambiente non è sovrascrivibile dalla riga di comando. Per rendere un valore di questo tipo pilotabile dalla CI, occorre esporlo come parametro di input dello scenario (un riquadro Input / Param) e cablarlo dove serve.

I codici di uscita

Codice	Significato
0	Lo scenario si è concluso correttamente
1	Fallimento, annullamento oppure errore del motore
2	Destinazione non trovata, file --out inaccessibile, oppure --run senza --open
3	Diritto negato: RESTORM_TOKEN assente, non valido o revocato, piano insufficiente, oppure punto di verifica non raggiungibile

È questa convenzione che rende il risultato direttamente utilizzabile da un runner di CI.

L’output

Il log viene scritto sullo standard output, una voce alla volta, appena viene prodotta, sotto forma di sequenza YAML:

- message: "🔵 [2026-07-29 10:30:00.123] Commande créée"
  data: { id: 4271 }

I livelli sono preceduti da una pastiglia: ⚪ debug, 🔵 info, 🟠 warn, 🔴 error. Le righe non vengono mai troncate — l’output resta grep-abile. Gli errori vanno sullo standard error.

È esattamente il testo che produce il pulsante «copia il log» dell’interfaccia: lo stesso formato da entrambe le parti.

I segreti in CI

Conviene usare la sorgente di segreti variabile d’ambiente: il segreto viene iniettato dal vault della CI, Restorm si limita a leggerlo e nulla viene scritto nel progetto. Si veda Segreti.

Fissare la versione

Il canale di download pubblica file versionati (restorm_<version>_amd64.deb): non esiste un alias latest. Conviene fissare la versione nella pipeline — è comunque ciò che si vuole in CI, perché una nuova versione non cambi il comportamento di un job senza revisione. I nomi esatti dei file dell’ultima versione sono elencati nel manifest latest-linux.yml dello stesso canale.

Installare Restorm sul runner

• Da npm — npm i -g restorm-cli@<versione>, poi restorm …. La build ufficiale viene scaricata una sola volta, verificata con il checksum pubblicato e messa in cache: i job successivi sulla stessa macchina non scaricano nulla. Il numero di versione del pacchetto npm è la versione di Restorm che avvia: fissare l’uno fissa l’altro.
• Dal pacchetto di sistema (.deb, .rpm), come negli esempi qui sotto — la scelta migliore se costruite la vostra immagine di runner, perché il job non scarica più nulla.

L’action GitHub ufficiale

Su GitHub, Monsieur-Dev/restorm-action riunisce tutto ciò che questa pagina descrive in un solo passo: installa Restorm tramite restorm-cli (un download verificato con checksum e messo in cache tra i job), lo avvolge in xvfb, esegue lo scenario headless e traduce ogni codice di uscita in un errore di job con nome.

- uses: Monsieur-Dev/restorm-action@v1
  with:
    project: ./api.restorm
    scenario: Smoke tests
    params: |
      status=available
  env:
    RESTORM_TOKEN: ${{ secrets.RESTORM_TOKEN }}

Il tag dell’action fissa la versione di Restorm (@v1.2.3 esegue Restorm 1.2.3), oppure passate un input version: esplicito. Tutti gli input sono documentati nel README del repository. La ricetta manuale qui sotto resta per chi vuole il controllo completo.

GitHub Actions

name: Tests d'API
on: [push]

jobs:
  api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Installer Restorm
        env:
          RESTORM_VERSION: '1.4.2' # la versione che si desidera fissare
        run: |
          curl -sSL -o restorm.deb \
            "https://dl.restorm.app/restorm_${RESTORM_VERSION}_amd64.deb"
          sudo apt-get install -y ./restorm.deb

      - name: Exécuter les tests de fumée
        env:
          RESTORM_TOKEN: ${{ secrets.RESTORM_TOKEN }}
          API_TOKEN: ${{ secrets.API_TOKEN }}
        run: |
          xvfb-run -a restorm \
            --open ./api.restorm \
            --run "Find pets by status" \
            --headless \
            --all-logs \
            --out run.log \
            --param status=available

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

GitLab CI

tests-api:
  image: ubuntu:24.04
  variables:
    RESTORM_TOKEN: $RESTORM_TOKEN
    RESTORM_VERSION: '1.4.2' # la versione che si desidera fissare
  before_script:
    - apt-get update && apt-get install -y curl xvfb
    - curl -sSL -o restorm.deb "https://dl.restorm.app/restorm_${RESTORM_VERSION}_amd64.deb"
    - apt-get install -y ./restorm.deb
  script:
    - >
      xvfb-run -a restorm
      --open ./api.restorm
      --run "Find pets by status"
      --headless --all-logs --out run.log
      --param status=$PET_STATUS
  artifacts:
    when: always
    paths: [run.log]

Che cosa cambia in headless

• Le azioni Toast non fanno nulla; l’esecuzione prosegue normalmente.
• I parametri non possono essere richiesti in modo interattivo: occorre fornirli tutti con --param, oppure lasciare che assumano il valore predefinito.
• Il server MCP non si avvia mai su una macchina senza display, indipendentemente dall’impostazione.

Ottenere un token

Il token RESTORM_TOKEN (con prefisso rstk_) si genera dal pannello di controllo del proprio account. È collegato all’organizzazione, non a una persona: è il token da mettere nel vault della CI. Si veda Account e accesso.