SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor · Aggiornato 2026-10-30

Mocking e test API self-hosted su un VPS

WireMock gestisce gli stub versionati in Git, Hurl esegue le suite in CI: scopri come farli girare su un VPS e conservare i report dopo un rebuild.

Due processi che condividono un repository

Il mocking e il testing self-hosted delle API sono due attività diverse; trattarle come se fossero una sola può far perdere una settimana. Un mock server sostituisce una dipendenza che non è possibile chiamare dalla CI: un provider di pagamenti, un’API di un partner, un servizio upstream soggetto a rate limiting oppure un servizio che un altro team non ha ancora rilasciato. Un runner per i test delle API chiama i propri endpoint in un ordine prestabilito e verifica le risposte, trasferendo i valori di una risposta nella richiesta successiva.

Alcuni strumenti svolgono entrambe le attività. Il compito principale di un mock server è rispondere alle richieste. Un test runner non stabilisce che cosa debba restituire un provider di pagamenti quando una carta viene rifiutata. La maggior parte dei team che dispone già di un server finisce per eseguire un’istanza di ciascun tipo, avviate dallo stesso file Docker Compose e revisionate nella stessa pull request.

Perché eseguire in autonomia il mocking e i test delle API?

I tuoi fixture contengono dati strutturati come quelli di produzione. Il body di una richiesta in un test API è un record cliente reale con il nome modificato, oppure con il nome invariato perché nessuno lo ha verificato. Gli stub registrati sono ancora più rischiosi: la registrazione tramite proxy memorizza ciò che il servizio upstream ha effettivamente restituito. Di conseguenza, una directory di stub creata tramite registrazione contiene token attivi e indirizzi email dei clienti finché qualcuno non legge ogni file. In un servizio in hosting, questi dati diventano un incidente di sicurezza a carico di terzi e una tua divulgazione di informazioni.

La seconda ragione è la raggiungibilità. Un servizio in ascolto su un indirizzo privato richiede una connessione di rete privata prima che un runner in hosting possa raggiungerlo. Ogni soluzione alternativa ha un costo. Pubblicare l'API su Internet per poterla testare elimina il motivo per cui era privata. Un tunnel o una copia pubblica di staging sono altri sistemi da gestire, e una copia di staging si discosta dalla produzione tra una release e l'altra. I runner GitHub-hosted supportano anche l'accesso privato tramite un overlay WireGuard o una Azure Virtual Network. Un runner sulla stessa rete privata chiama direttamente il servizio e non richiede nulla di tutto questo. Questo è il motivo pratico alla base di un runner self-hosted di GitHub Actions.

Quale mock server self-hosted dovresti eseguire?

Ognuno di questi strumenti viene eseguito come container su un server di tua proprietà. La domanda importante è quale consideri la fonte autorevole dei dati, perché da questo dipende se ricreare il container non ha alcun costo oppure richiede un pomeriggio di lavoro.

  • WireMock conserva ogni stub come file JSON in una directory mappings/, con i corpi delle risposte di grandi dimensioni in __files/. L'immagine è wiremock/wiremock, la directory root al suo interno è /home/wiremock e lo strumento può essere eseguito anche come proxy di registrazione. I file su disco fanno sì che il mock possa essere gestito in git come qualsiasi altro codice.
  • Mockoon CLI conserva un'intera API mock in un unico file di dati JSON. Installalo con npm install -g @mockoon/cli e avvialo con mockoon-cli start --data ./data-file.json, oppure esegui l'immagine mockoon/cli montando quel file tramite bind mount. L'applicazione desktop modifica lo stesso file, quindi la progettazione tramite interfaccia grafica e il commit del risultato restano compatibili.
  • MockServer viene eseguito dall'immagine mockserver/mockserver e resta in ascolto sulla porta 1080. Le expectation arrivano tramite la relativa API REST, una soluzione pratica dal codice dei test ma rischiosa in fase di deployment: per impostazione predefinita, un'expectation creata tramite una chiamata HTTP scompare quando il container viene riavviato. Usa il relativo file JSON di inizializzazione per gli stub che devono essere permanenti. Per conservare le modifiche apportate durante l'esecuzione, abilita persistExpectations, salva il file di output al di fuori del container e caricalo all'avvio tramite initializationJsonPath.
  • Prism crea il mock a partire dal documento OpenAPI, invece che da file di stub separati. Installalo con npm install -g @stoplight/prism-cli, quindi esegui prism mock openapi.yaml. In un container aggiungi -h 0.0.0.0, perché per impostazione predefinita Prism si associa a localhost e altrimenti non è raggiungibile dall'esterno del container.
  • Microcks è l'opzione più completa: offre un'interfaccia web che importa documenti OpenAPI e raccolte Postman, quindi li espone come mock ed esegue contract test. Un'installazione completa richiede MongoDB e Keycloak, oltre a Kafka per le funzionalità asincrone. L'immagine microcks-uber all-in-one include un MongoDB in memoria, che il progetto indica come adatto all'uso effimero. Considera quindi temporaneo tutto ciò che viene creato nell'interfaccia e conserva gli artefatti sorgente in git.

Quale esecutore di test API self-hosted dovresti usare?

Il lavoro consiste in una sequenza: autenticazione, creazione di un ordine, lettura dell’ordine e verifica della modifica dello stato. È necessario acquisire un valore da una risposta e usarlo nella richiesta successiva. Uno strumento che non sa mantenere lo stato tra le chiamate esegue un controllo di disponibilità, non un test API.

  • Hurl esegue file di testo semplice contenenti richieste HTTP tramite un singolo binario. Una sezione [Captures] estrae i valori da una risposta, una sezione [Asserts] li verifica e --test trasforma il tutto in un esecutore di test con riepilogo e codice di uscita. La versione 8.0.1 è quella corrente ad agosto 2026.
  • Bruno CLI esegue una directory di file .bru. Installalo con npm install -g @usebruno/cli, quindi esegui bru run folder --env Local --reporter-junit results.xml. Il formato della raccolta è costituito intenzionalmente da file di testo in una directory, quindi le differenze sono leggibili durante la revisione.
  • Newman esegue le raccolte Postman al di fuori di Postman: npm install -g newman, quindi newman run collection.json -r cli,junit --reporter-junit-export results.xml. Il limite riguarda il formato. Newman esegue le raccolte esportate nel formato JSON v2.1. Postman supporta ora anche un formato di raccolta v3 e i flussi di lavoro Native Git tramite Postman CLI. La documentazione di Postman indica che Newman non riceverà ulteriori aggiornamenti o correzioni e consiglia di migrare gli script e le pipeline CI a Postman CLI.
  • Schemathesis esegue un tipo di controllo diverso. Legge uno schema OpenAPI e genera casi che cercano di produrre risposte che lo schema dichiara impossibili: uvx schemathesis run https://your.api/openapi.json. Individua arresti anomali e violazioni del contratto, ma non conosce le regole di business. Va quindi affiancato a una suite con test descritti tramite script, non usato per sostituirla.
  • Hoppscotch self-hosted è l’opzione con interfaccia web e richiede un’istanza Postgres. Valuta questo compromesso prima di installarlo: le raccolte risiedono in un database, non nel repository.

Uno strumento da evitare è Step CI. Compare ancora nelle raccolte di strumenti e il suo formato di workflow YAML è leggibile, ma l’ultimo commit nel repository risale ad agosto 2024. Un programma che si trova tra la CI e l’API è un punto inadatto per usare codice non mantenuto.

Metti il server mock dietro il firewall

La configurazione seguente esegue WireMock come sostituto di un provider di pagamenti. Se il formato dei file Compose è nuovo per te, Docker Compose su un VPS descrive i comandi del ciclo di vita utilizzati in questa sezione.

services:
  mock-payments:
    image: wiremock/wiremock:3.13.2
    command: ["--verbose"]
    volumes:
      - ./mocks/payments:/home/wiremock
    ports:
      - "127.0.0.1:8080:8080"
    restart: unless-stopped

Il prefisso 127.0.0.1: sulla porta è la parte importante. Un semplice 8080:8080 pubblica il mock su tutte le interfacce, incluso il tuo IP pubblico, e resta raggiungibile anche se ufw nega quella porta, perché Docker instrada il traffico pubblicato attraverso la tabella nat prima che raggiunga le regole INPUT di ufw. Associa la porta all'indirizzo di loopback per renderla accessibile soltanto dall'host, usando la rete bridge predefinita di Docker su Engine 28.0.0 o versioni successive. Le versioni precedenti consentono agli host sulla stessa rete layer 2 di raggiungere le porte pubblicate su localhost. L'associazione a un indirizzo di un'interfaccia privata consente comunque l'accesso dalle reti che possono instradare il traffico verso quell'indirizzo.

Il servizio sottoposto a test deve quindi puntare al mock. Quando il servizio viene eseguito nello stesso progetto Compose, l'URL di base del mock è http://mock-payments:8080, perché Compose risolve i nomi dei servizi sulla propria rete. Quando il servizio viene eseguito sull'host, è http://127.0.0.1:8080. Imposta questo valore tramite una variabile d'ambiente, mai nel codice, altrimenti l'URL di test finisce in produzione.

Gli stub si trovano in ./mocks/payments/mappings/, un file JSON per ciascuno.

{
  "request": {
    "method": "POST",
    "urlPath": "/v1/charges",
    "bodyPatterns": [{ "matchesJsonPath": "$.amount" }]
  },
  "response": {
    "status": 201,
    "headers": { "Content-Type": "application/json" },
    "jsonBody": { "id": "ch_test_001", "status": "succeeded", "amount": 4200 }
  }
}

Avvialo, quindi verifica cosa è stato effettivamente caricato.

docker compose up -d --wait mock-payments
curl -fsS http://127.0.0.1:8080/__admin/mappings

--wait attende che il container segnali uno stato healthy. Questo funziona perché l'immagine WireMock include un HEALTHCHECK per il proprio endpoint /__admin/health. La chiamata mappings elenca tutti gli stub letti dal server. Se uno stub che hai scritto non compare nell'elenco, non è mai stato caricato: verifica che il file si trovi sotto mappings/ e non nella radice montata, quindi controlla che il JSON sia valido.

Quando arriva una richiesta e nessuno stub corrisponde, WireMock risponde con 404. Se trova una corrispondenza parziale, il corpo inizia con Request was not matched, seguito da un confronto con lo stub più vicino. Se non esistono mappature di stub, il corpo è No response could be served as there are no stub mappings in this WireMock instance. Leggi il confronto quando è presente prima di modificare qualsiasi cosa, perché indica il campo esatto che differisce. Di solito è un percorso con /v1/charge, mentre nello stub è indicato /v1/charges.

Scrivere il test come una sequenza con stato mantenuto tra le chiamate

I file Hurl sono semplici file di testo. Installate il pacchetto deb dalle release del progetto.

VERSION=8.0.1
curl --location --remote-name https://github.com/Orange-OpenSource/hurl/releases/download/$VERSION/hurl_${VERSION}_amd64.deb
sudo apt update && sudo apt install ./hurl_${VERSION}_amd64.deb

Una suite che verifica la propria API rispetto al mock si trova in tests/checkout.hurl.

POST {{base_url}}/orders
Content-Type: application/json
{
  "sku": "ssd-1tb",
  "amount": 4200
}
HTTP 201
[Captures]
order_id: jsonpath "$['id']"

GET {{base_url}}/orders/{{order_id}}
HTTP 200
[Asserts]
jsonpath "$.status" == "paid"
jsonpath "$.charge_id" == "ch_test_001"

Il blocco [Captures] trasforma il test in un test API, anziché in due richieste non correlate. order_id viene letto dalla prima risposta e inserito nell'URL della seconda. L'asserzione su charge_id è il punto centrale dell'esercizio: dimostra che il servizio ha chiamato il provider di pagamenti e ha memorizzato la risposta, mentre il valore usato per il confronto è quello scritto nello stub WireMock. Un unico file copre ora entrambe le parti del flusso.

hurl --test --variable base_url=http://127.0.0.1:3000 \
  --report-junit reports/junit.xml \
  --report-json reports/json \
  tests/

Un'esecuzione completata correttamente stampa una riga per file e un riepilogo.

tests/checkout.hurl: Success (2 request(s) in 61 ms)
Executed files:    1
Executed requests: 2 (30.1/s)
Succeeded files:   1 (100.0%)
Failed files:      0 (0.0%)
Duration:          64 ms

In caso di errore, stampa error: Assert failure con il file e il numero di riga, quindi il valore ottenuto e quello atteso; hurl termina con un codice diverso da zero, così la CI si interrompe. Se status legge pending dove era atteso paid, il servizio non ha elaborato la risposta del mock. Il controllo successivo va eseguito nel journal delle richieste di WireMock, disponibile in /__admin/requests, che mostra se la chiamata ha raggiunto il mock.

Avviare la suite dal proprio runner CI

Con un runner registrato sullo stesso host, il workflow è breve. Il runner è un semplice processo sull'host, quindi docker e hurl devono essere installati su quell'host. Dal sistema operativo usato per un runner ospitato non viene ereditato nulla.

name: api-tests
on: [push]
jobs:
  hurl:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
      - name: Start the mock
        run: docker compose up -d --wait mock-payments
      - name: Run the suite
        run: hurl --test --variable base_url=http://127.0.0.1:3000 --report-junit reports/junit.xml tests/
      - name: Archive the reports
        if: always()
        run: install -d /srv/api-tests/reports/$GITHUB_SHA && cp -r reports/. /srv/api-tests/reports/$GITHUB_SHA/
      - name: Stop the mock
        if: always()
        run: docker compose down

if: always() nel passaggio di archiviazione è importante. Senza questa opzione, un'esecuzione dei test non riuscita salta la copia e si perde esattamente il report che si voleva analizzare. La copia deve inoltre essere eseguita al di fuori della workspace, perché actions/checkout@v4 esegue git clean -ffdx per impostazione predefinita prima del recupero del codice. Al checkout successivo, questa operazione rimuove i report non tracciati dalla directory del repository.

Conservare i risultati, non solo quelli dell’ultima esecuzione

Un file JUnit XML per commit risponde a una sola domanda: il test è passato? Non indica quando un endpoint ha iniziato a rallentare, perché nessuno legge quei file dopo che si smette di aprirli. Per ottenere uno storico, aggiungi una riga per ogni esecuzione a un piccolo database sullo stesso server. È sufficiente una singola tabella con SHA del commit, nome del file, numero di test superati, numero di test falliti e durata. SQLite in produzione su un VPS è una soluzione ragionevole: un solo file, nessun processo server e tutto lo storico incluso nel backup che già esegui. Analizza l’output --report-json di Hurl per ottenere i dati dettagliati delle esecuzioni; sia JSON sia JUnit XML sono leggibili dalle macchine.

Cosa deve sopravvivere alla ricostruzione di un container

Le definizioni dei mock e le suite di test sono codice sorgente. Devono trovarsi in un repository insieme al servizio che descrivono e devono essere modificate nella stessa pull request che modifica un endpoint. Uno stub modificato in un'interfaccia web, oppure un'aspettativa inviata a MockServer tramite la relativa API REST durante l'esecuzione, richiede una configurazione di esportazione o persistenza per sopravvivere a una ricostruzione. Eseguendo docker compose down, la memoria del container e i layer scrivibili vanno persi; i dati archiviati in bind mount o volumi denominati sopravvivono. Se i repository vengono eseguiti anche su hardware di proprietà, un server Git self-hosted mantiene fixture e servizio all'interno dello stesso perimetro di sicurezza.

Ecco quindi le regole pratiche. Fissa i tag delle immagini, perché latest può modificare il modo in cui il mock gestisce le richieste senza alcuna modifica nel repository, e collegare questo errore alla sua causa è molto difficile. Monta le directory degli stub in sola lettura quando lo strumento non deve scrivervi. Non archiviare mai gli stub di un mock in un volume Docker denominato, perché il volume diventerebbe la fonte autorevole e la copia in Git diventerebbe silenziosamente obsoleta.

Ce n'è un'altra, che spesso causa problemi. Se crei gli stub registrando traffico reale tramite un proxy, leggi ogni file generato prima di eseguirne il commit. Una registrazione contiene esattamente ciò che il servizio upstream ha restituito, inclusi bearer token e indirizzi email dei clienti. Eseguirne il commit inserisce definitivamente quei dati nel repository, perché Git conserva il contenuto eliminato nella cronologia.

FAQ

Qual è la differenza tra un mock server API e un test runner API?

Un mock server risponde alle richieste. Sostituisce una dipendenza che non puoi chiamare da CI; alcuni strumenti eseguono anche contract test e ne riportano i risultati. Un test runner API invia richieste al tuo servizio, verifica le risposte con asserzioni, trasferisce i valori di una chiamata a quella successiva e termina con un codice diverso da zero quando un'asserzione fallisce. Risolvono problemi diversi e, in una configurazione tipica, vengono eseguiti entrambi: il runner chiama il tuo servizio, mentre il tuo servizio chiama il mock.

Posso testare un'API interna da un runner CI ospitato?

Sì, usando una rete privata. I runner ospitati da GitHub supportano un overlay WireGuard o una Azure Virtual Network per raggiungere risorse private senza pubblicare l'API. Pubblicare l'API, eseguire un tunnel o mantenere una copia pubblica di staging sono altre possibilità, ma ognuna aggiunge un sistema che può guastarsi o causare una fuga di dati. Un runner sulla stessa rete privata chiama direttamente il servizio. Questo è il principale motivo pratico per cui i team ospitano autonomamente questo tipo di attività.

Dove devono risiedere gli stub dei mock e le suite di test API?

In git, accanto al servizio che descrivono. Gli strumenti che memorizzano le definizioni come file, ad esempio la directory mappings/ di WireMock, il file di dati di Mockoon, i file Hurl e la directory .bru di Bruno, consentono la revisione del codice e una nuova build del container senza costi aggiuntivi. Gli strumenti che memorizzano le definizioni in un database o in un'interfaccia web richiedono un piano di backup e un passaggio di esportazione. L'esportazione è proprio la parte che spesso viene dimenticata finché il container non è già scomparso.

Perché il mio mock restituisce 404 quando lo stub sembra corretto?

WireMock fornisce uno stub solo quando la richiesta soddisfa i matcher configurati. Una richiesta senza corrispondenza riceve 404; quando esiste una corrispondenza parziale, il body inizia con Request was not matched, seguito da una differenza rispetto allo stub più vicino. La differenza indica il campo che non corrisponde. Se non esistono stub mapping, il body spiega invece che l'istanza non ne contiene alcuno. Le cause comuni sono una slash finale nel path, un header Content-Type richiesto dallo stub ma non inviato dal client, urlPath usato quando lo stub richiede urlPathPattern per un segmento variabile e un body matcher non compatibile con il payload. Controlla prima /__admin/requests per verificare che la richiesta abbia effettivamente raggiunto il mock.

Mi servono ancora i mock se ho un ambiente di staging?

Sì, per due motivi. Una copia di staging di un servizio upstream che non controlli può comunque non essere disponibile e applicare comunque il rate limiting. Di conseguenza, la suite può fallire per motivi che non hanno nulla a che vedere con il tuo codice. Inoltre, l'ambiente non può produrre le risposte che devi testare più spesso, come il rifiuto di una carta o un timeout del gateway. Un mock restituisce queste risposte su richiesta alla velocità della rete locale. In questo modo, una suite che richiede minuti contro un sandbox può essere eseguita in pochi secondi. Conserva staging per il controllo finale prima del rilascio e usa i mock in CI.

Questo articolo ti è stato utile?