Eseguire test shell nelle pipeline CI

Gli script di shell sono codice e, come tutto il codice, meritano controlli di qualità automatizzati. Senza CI, un errore di battitura in uno script di deployment può arrivare silenziosamente in produzione e causare un'interruzione del servizio alle 3 di notte.

Una pipeline CI solida per i progetti Bash verifica due aspetti a ogni pull request:

• Analisi statica tramite ShellCheck: rileva errori di sintassi, schemi non sicuri e problemi di portabilità POSIX prima ancora che lo script venga eseguito.
• Test unitari e di integrazione tramite Bats (Bash Automated Testing System): esegue le funzioni e verifica che il comportamento sia corretto.

Insieme formano una rete di sicurezza che rende il refactoring più sicuro e accelera l'inserimento dei nuovi collaboratori. In questa lezione integrerà entrambi gli strumenti in GitHub Actions, la piattaforma CI gratuita più utilizzata per i progetti open source e quelli dei piccoli team.

GitHub Actions è una soluzione CI/CD basata sugli eventi e integrata in GitHub. Un workflow è un file YAML archiviato in .github/workflows/. Si attiva in risposta a eventi (push, pull_request e così via) ed esegue job su runner ospitati.

Concetti fondamentali:

• on: — il trigger (ad esempio push, pull_request)
• jobs: — unità di lavoro parallele, ciascuna eseguita su una VM nuova
• steps: — comandi di shell sequenziali o actions riutilizzabili all'interno di un job
• runs-on: — l'immagine del runner (utilizziamo ubuntu-latest)

I file dei workflow devono essere sottoposti a commit nel repository. GitHub li rileva automaticamente: non è necessaria alcuna configurazione esterna.

ShellCheck è preinstallato nei runner ubuntu-latest, quindi nella maggior parte dei casi non è necessario alcun passaggio di installazione. Tuttavia, la versione preinstallata potrebbe essere meno recente dell'ultima disponibile. Per build riproducibili, fissi una versione specifica.

Due strategie di installazione:

• Utilizzare il binario preinstallato — è la soluzione più semplice e sufficiente per la maggior parte dei progetti.
• Installare una versione fissata tramite l'archivio tar della release ufficiale su GitHub: garantisce la stessa versione del linter in locale e nella CI.

Il passaggio seguente mostra l'approccio con versione fissata, utilizzando una stringa di versione memorizzata come variabile d'ambiente, così gli aggiornamenti richiedono una sola modifica.

Dopo l'installazione, è necessario un passaggio che individui e analizzi con il linter tutti gli script di shell presenti nel repository. Utilizzi find per individuare i file, quindi li passi tramite pipe a shellcheck.

Flag importanti da conoscere:

• -e SC2034 — esclude una regola specifica (lo utilizzi con parsimonia e accompagnato da un commento).
• --severity=warning — fa fallire il controllo solo per gli avvisi e i livelli superiori (ignorando i suggerimenti di style).
• -x — segue le direttive source per analizzare con il linter anche i file inclusi.

Se shellcheck rileva un problema, termina con un codice diverso da zero, facendo fallire automaticamente il passaggio CI: non serve alcuna logica aggiuntiva.

Bats (Bash Automated Testing System) è un framework di test per Bash conforme a TAP. Ogni file di test ha estensione .bats e contiene blocchi @test.

Un test ha esito positivo quando il suo corpo termina con codice 0 e fallisce quando termina con un codice diverso da zero. Bats mette a disposizione variabili e funzioni di supporto:

• $status — codice di uscita dell'ultimo comando run.
• $output — stdout+stderr combinati dell'ultimo comando run.
• $lines — array delle righe di output.
• run <cmd> — esegue un comando senza far fallire il test in caso di uscita diversa da zero.

L'helper run è essenziale: senza di esso, un comando che fallisce interromperebbe il test prima che Lei possa esaminare $status.

Il modo canonico per aggiungere Bats a un progetto consiste nell'utilizzare un sottomodulo Git. In questo modo si fissa uno specifico commit, si mantiene la stessa versione del runner in locale e si evita di dipendere dai package manager.

Esegua questi comandi una volta in locale, quindi esegua il commit del risultato:

• git submodule add https://github.com/bats-core/bats-core test/bats
• git submodule add https://github.com/bats-core/bats-support test/test_helper/bats-support
• git submodule add https://github.com/bats-core/bats-assert test/test_helper/bats-assert

Nella CI, ripristini i sottomoduli con actions/checkout@v4 e l'opzione submodules: recursive. Il passaggio seguente mostra la configurazione completa del checkout.

Quando Bats è disponibile (tramite sottomodulo o installazione di un package), eseguire i test richiede un solo comando. Indichi una directory e Bats individuerà ricorsivamente ogni file .bats con il flag --recursive.

Il flag --formatter tap produce l'output nel formato TAP (Test Anything Protocol), che molti sistemi CI analizzano per generare i report dei test. Il formatter predefinito pretty è più adatto alla lettura umana nei log non elaborati.

Utilizzi --timing per individuare subito i test lenti: un test che dura più di 5 secondi generalmente segnala una chiamata di rete indesiderata o un mock mancante.

Ora riunisca tutto in un unico file di workflow pronto per la produzione. Qui vengono applicate le seguenti best practice:

• Due job separati (lint e test) vengono eseguiti in parallelo, fornendo un feedback più rapido.
• Il job test dichiara needs: lint, quindi i test vengono eseguiti solo dopo il superamento del linting, evitando di sprecare minuti del runner su codice evidentemente non funzionante.
• Le versioni fissate delle action (@v4) evitano problemi imprevisti causati dagli aggiornamenti upstream.
• Un blocco permissions: limita il token del workflow ai permessi minimi necessari.

Quando gli helper di Bats o altri strumenti vengono installati tramite un package manager all'interno del workflow, la cache accelera notevolmente le esecuzioni successive. GitHub Actions mette a disposizione l'action actions/cache a questo scopo.

Punti fondamentali per una cache efficace:

• Utilizzi una chiave della cache che includa il sistema operativo, il nome dello strumento e l'hash di un lockfile, così la cache viene invalidata automaticamente quando cambiano le dipendenze.
• Un fallback restore-keys consente al workflow di utilizzare una cache non aggiornata invece di ripartire da zero quando non trova una corrispondenza.
• Per i sottomoduli Git, la cache è raramente necessaria perché il checkout dei sottomoduli è rapido. La cache è più utile per installazioni di npm, pip o di strumenti compilati.

Un workflow CI che non impedisce i merge è, nel migliore dei casi, un semplice suggerimento. Le regole di protezione dei branch di GitHub trasformano i controlli in veri gate obbligatori.

Per configurarle: apra Settings → Branches → Add rule per main, quindi abiliti:

• Require status checks to pass before merging — selezioni ShellCheck e Bats Tests in base al nome.
• Require branches to be up to date before merging — impedisce che una PR che ha superato i controlli su una base obsoleta introduca codice non funzionante.
• Do not allow bypassing the above settings — applica le regole anche agli amministratori del repository.

Con queste regole attive, l'unico modo per eseguire il merge è una PR con tutti i job CI superati: esattamente la rete di sicurezza che desidera.

Quando un'esecuzione CI fallisce, il ciclo di correzione più rapido consiste nel riprodurre localmente il problema prima di inviare un altro commit. Due tecniche:

• Eseguire gli stessi comandi del passaggio non riuscito nel terminale: la CI esegue una normale shell, quindi i comandi possono essere riprodotti con copia e incolla.
• Utilizzare act: uno strumento che esegue localmente i workflow di GitHub Actions all'interno di Docker, offrendo la corrispondenza più vicina possibile all'ambiente del runner ospitato.

Una causa comune dei problemi che si verificano solo nella CI è una differenza di versione degli strumenti tra il Suo Mac (ad esempio find BSD su macOS rispetto a find GNU su Ubuntu). Verifichi sempre con i flag --posix oppure utilizzi act per eseguire localmente l'immagine Ubuntu.

Verifichi la Sua comprensione dell'integrazione di ShellCheck e Bats in GitHub Actions.

In questa lezione ha creato una pipeline CI completa per i progetti Bash utilizzando GitHub Actions. Ecco gli argomenti trattati:

• Nozioni di base su GitHub Actions — il workflow YAML risiede in .github/workflows/, si attiva con push e pull_request ed esegue i job sui runner ubuntu-latest.
• ShellCheck — è preinstallato sui runner Ubuntu; utilizzi find per individuare gli script e --severity=warning -x per un controllo lint pratico.
• Bats tramite sottomodulo — fissi bats-core e gli helper come sottomoduli Git; li ripristini nella CI con submodules: recursive nell'action di checkout.
• Ordine dei job — utilizzi needs: affinché i test vengano eseguiti solo dopo il superamento del linting, mantenendo un feedback rapido ed evitando sprechi di risorse di calcolo.
• Protezione dei branch — imponga i controlli dello stato nelle impostazioni di GitHub, così nessuna PR può essere integrata senza una CI superata.
• Riproduzione locale — copi i comandi CI direttamente nel terminale oppure utilizzi act per eseguire il debug dei problemi senza creare commit aggiuntivi.

Con questa pipeline attiva, ogni modifica alla shell viene verificata automaticamente prima di raggiungere il Suo branch principale.