Testare il percorso di acquisto a ogni deploy con GitHub Actions

Il workflow completo, da copiare

Ecco il file intero. Il job deploy mette il Suo sito in produzione. Poi il job tunnel-paiement chiede a Pathly di rieseguire il Suo Flow in un vero browser, dal prodotto fino alla pagina di pagamento. Se un passaggio si rompe, il job diventa rosso.

La riga needs: deploy fissa l’ordine. Il job tunnel-paiement parte solo se il deploy è riuscito. Il Flow verifica quindi la versione appena arrivata in produzione, non la precedente.

timeout_sec dà alla Action il tempo di attendere il verdetto. Il valore predefinito è di 120 secondi. Un percorso di acquisto attraversa più pagine, perciò il workflow lascia cinque minuti. Trascorso questo tempo, la Action si ferma e il job fallisce.

Le restano tre cose da preparare: il Flow, la chiave API e le due impostazioni del repository. Le sezioni seguenti le descrivono in quest’ordine.

• GitHub pathly-action

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # Sostituisca con il Suo comando di deploy
      - run: ./scripts/deploy.sh

  tunnel-paiement:
    name: Percorso di acquisto
    needs: deploy
    runs-on: ubuntu-latest
    steps:
      - name: Pathly Flow
        uses: pathlyhq/pathly-action@v1
        with:
          api_token: ${{ secrets.PATHLY_API_TOKEN }}
          operation: run-scenario
          scenario_id: ${{ vars.PATHLY_CHECKOUT_SCENARIO_ID }}
          timeout_sec: "300"

Perché testare dopo il rilascio in produzione

I Suoi test prima del merge verificano il codice. Non vedono la produzione: le sue variabili d’ambiente, la sua cache, il suo fornitore di pagamento, i suoi script di terze parti. Un rilascio può rompere il percorso di acquisto con tutti i test verdi.

Il caso tipico: il Ping è verde, il Flow è rosso. Il sito risponde 200 e la home page si carica, ma il pulsante Ordina non fa più nulla. Un controllo di disponibilità non lo vede. Un browser che fa clic, sì.

Questo controllo non sostituisce i Suoi test prima del merge. Si aggiunge dopo. I test dicono che il codice è corretto. Il Flow dice che un cliente può ancora raggiungere la pagina di pagamento, sul sito reale, pochi minuti dopo il deploy.

Creare il Flow del percorso di acquisto

Il Flow si crea nella console, con il registratore, senza scrivere codice. Apra il Suo negozio nel registratore e percorra il cammino di un cliente. Pathly conserva ogni clic come un passaggio.

Passaggi tipici: aprire una scheda prodotto, aggiungere il prodotto al carrello, aprire il carrello, proseguire fino alla pagina di pagamento. Aggiunga una verifica alla fine, per esempio un testo che solo la pagina di pagamento mostra.

Il Flow si ferma alla pagina di pagamento. Non paga nulla e inserisce solo valori di test. Scelga un prodotto sempre disponibile, riservato a questo controllo se può.

Una volta salvato il Flow, annoti il suo identificativo. È un UUID, visibile nell’indirizzo della pagina del Flow nella console. Lo metterà in una variabile del repository nel passaggio successivo.

Una chiave API con due ambiti

Crei una chiave API nella console, in Impostazioni → Chiavi API. Inizia con sp_… e il suo segreto viene mostrato una sola volta. Le assegni solo due ambiti: runs:trigger per avviare un run, runs:read per leggerne il risultato.

Crei una chiave per ogni repository. Se un repository viene esposto, revoca la sua chiave senza toccare le altre. Con questi due ambiti, una chiave rubata non può creare, modificare né eliminare un Flow.

In GitHub, apra Settings → Secrets and variables → Actions. Metta la chiave nel secret PATHLY_API_TOKEN. Metta l’identificativo del Flow nella variabile PATHLY_CHECKOUT_SCENARIO_ID. L’identificativo non è un segreto: basta una variabile, e resta leggibile nei log.

Prima di collegare il Flow, faccia un primo controllo con operation: ping. Questa operazione verifica soltanto che l’API riconosca la chiave. Non avvia alcun run.

- name: Pathly ping
  uses: pathlyhq/pathly-action@v1
  with:
    api_token: ${{ secrets.PATHLY_API_TOKEN }}
    operation: ping

run-scenario o assert-scenario

La Action offre due operazioni che si somigliano. Dopo un deploy, Le serve run-scenario. Avvia un nuovo run con POST /v1/scenarios/{id}/run, poi interroga GET /v1/runs/{id} fino a uno stato finale. Il risultato descrive quindi la versione appena rilasciata.

assert-scenario non avvia nulla. Legge l’ultimo risultato noto del Flow, con l’ambito scenarios:read. Quel risultato può risalire a prima del deploy: il job sarebbe verde senza che la nuova versione sia mai stata testata.

assert-scenario resta utile altrove. Non consuma alcuna esecuzione e risponde subito. È adatta a un controllo prima di un passaggio rischioso, quando il Flow gira già a intervalli regolari. Non è adatta subito dopo un rilascio in produzione.

- name: Pathly assert
  uses: pathlyhq/pathly-action@v1
  with:
    api_token: ${{ secrets.PATHLY_API_TOKEN }}
    operation: assert-scenario
    scenario_id: ${{ vars.PATHLY_CHECKOUT_SCENARIO_ID }}

Leggere un fallimento

La Action dichiara tre output: run_id, run_status e ok. run_status vale ok, fail o error. Quando il run non è ok, il job fallisce. Il suo log mostra allora l’identificativo del run, il suo stato e il suo messaggio: parta da lì.

fail: un passaggio o una verifica del Flow fallisce. Il sito risponde, ma il percorso del cliente è interrotto. È il caso che questo controllo deve intercettare: un pulsante che non reagisce più, un carrello vuoto, una pagina di pagamento mai raggiunta.

error: il run non è arrivato in fondo per un errore di rete o del browser. Sito irraggiungibile, timeout di connessione, browser in crash. Un sito che non risponde più del tutto dopo il rilascio dà quindi error, non fail.

Per il dettaglio, chiami GET https://api.pathlyhq.com/v1/runs/{id} con la stessa chiave. La risposta restituisce status, message e, quando esiste uno screenshot, screenshotUrl. È un link firmato allo screenshot del passaggio fallito, valido 15 minuti. screenshotExpiresAt indica l’ora di scadenza. Richiami l’endpoint per ottenere un nuovo link.

# RUN_ID: l'identificativo mostrato nel log del job
curl -sS https://api.pathlyhq.com/v1/runs/$RUN_ID \
  -H "Authorization: Bearer $PATHLY_API_TOKEN" \
  | jq '{status, message, screenshotUrl, screenshotExpiresAt}'

curl -sS "https://api.pathlyhq.com/v1/runs?scenarioId=$PATHLY_CHECKOUT_SCENARIO_ID&limit=1" \
  -H "Authorization: Bearer $PATHLY_API_TOKEN" \
  | jq '.items[0] | {id, status, message}'

Reagire: rollback e avviso

Un job rosso non serve a nulla se nessuno lo guarda. Aggiunga un job rollback con needs: tunnel-paiement e if: failure(). Viene eseguito solo se il controllo è fallito, e rimette in produzione la versione precedente.

failure() è vera non appena un job a monte fallisce, deploy compreso. La condizione needs.tunnel-paiement.result == 'failure' riserva il rollback al solo fallimento del controllo Pathly.

Il job è rosso sia con fail sia con error, ma la risposta è diversa. Con fail, il percorso del cliente è interrotto: torni indietro. Con error, rilanci il job una volta. Se l’errore si ripresenta, torni indietro comunque.

Avvisi anche il team. Un webhook iscritto all’evento run.failed invia il fallimento al Suo strumento di allerta. Lo crei nella console, oppure tramite l’API con una chiave che ha alerting:write, distinta da quella della CI. I canali di terze parti (Slack, Teams, webhook) fanno parte dei piani a pagamento.

  rollback:
    needs: tunnel-paiement
    if: failure() && needs.tunnel-paiement.result == 'failure'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # Sostituisca con il Suo comando di rollback
      - run: ./scripts/rollback.sh

# PATHLY_ALERTING_TOKEN: una chiave con alerting:write, non quella della CI
curl -sS -X POST https://api.pathlyhq.com/v1/webhooks \
  -H "Authorization: Bearer $PATHLY_ALERTING_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.example.com/hooks/pathly",
    "events": ["run.failed"]
  }'

Per andare oltre

Più negozi: crei un Flow per negozio e scorra i loro identificativi con strategy.matrix. Ogni negozio ha il suo job e il suo verdetto. Con fail-fast: false, il fallimento di un negozio non annulla il controllo degli altri.

Finestra di manutenzione: se il deploy interrompe il sito per un istante, apra una finestra prima di rilasciare. Silenzia gli avvisi del monitoraggio ordinario durante quell’intervallo. La Action non ha un’operazione dedicata: chiami l’API /v1/maintenance-windows con un’altra chiave, che abbia maintenance:write.

ensure-scenario crea il Ping del sito se non esiste. Se esiste già, lo lascia così com’è, senza modificarlo. Lo ritrova tramite il nome: rilanciare il workflow non crea duplicati. Questa operazione richiede l’ambito scenarios:write, quindi una chiave distinta da quella del controllo.

Due deploy di seguito: senza protezione, due controlli si sovrappongono e il secondo può testare una versione rilasciata a metà. Un blocco concurrency fa attendere la seconda esecuzione del workflow finché la prima non è terminata, controllo compreso.

  tunnel-paiement:
    needs: deploy
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        scenario_id:
          - ${{ vars.PATHLY_CHECKOUT_FR_SCENARIO_ID }}
          - ${{ vars.PATHLY_CHECKOUT_DE_SCENARIO_ID }}
    steps:
      - name: Pathly Flow
        uses: pathlyhq/pathly-action@v1
        with:
          api_token: ${{ secrets.PATHLY_API_TOKEN }}
          operation: run-scenario
          scenario_id: ${{ matrix.scenario_id }}
          timeout_sec: "300"

START=$(date -u +%Y-%m-%dT%H:%M:%SZ)
END=$(date -u -d "+15 minutes" +%Y-%m-%dT%H:%M:%SZ)

curl -sS -X POST https://api.pathlyhq.com/v1/maintenance-windows \
  -H "Authorization: Bearer $PATHLY_MAINTENANCE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"startsAt\": \"$START\", \"endsAt\": \"$END\"}"

- name: Pathly Ping
  uses: pathlyhq/pathly-action@v1
  with:
    api_token: ${{ secrets.PATHLY_SETUP_TOKEN }}
    operation: ensure-scenario
    scenario_json: |
      {
        "name": "Home",
        "url": "https://www.example.com/",
        "intervalSec": 300
      }

concurrency:
  group: deploy-production
  cancel-in-progress: false

Insidie comuni

La CDN serve ancora la vecchia versione. Il Flow verifica allora il sito precedente e il job è verde a torto. Svuoti la cache nel job deploy e attenda la fine dello svuotamento prima di passare la mano al controllo.

Una protezione anti-bot o un CAPTCHA blocca il browser di Pathly. Il Flow fallisce mentre i Suoi clienti passano. Un CAPTCHA ferma questo browser come qualsiasi robot: lo tenga fuori dalle pagine che il Flow attraversa, oppure preveda una regola per questo traffico di test nel Suo firewall applicativo.

Il prodotto di test è esaurito. Il pulsante di aggiunta al carrello scompare e il Flow diventa rosso senza che il codice sia cambiato. Riservi al test un prodotto sempre disponibile.

La quota. Un run avviato dalla CI conta nella quota di esecuzioni del Suo piano, come gli altri. Con la quota raggiunta e senza pacchetto di esecuzioni, il run termina in fail con un messaggio di quota e il job diventa rosso. Legga il messaggio prima di tornare indietro: qui il sito non c’entra.