Blog di Mattia Natali

Sei cose che avrei voluto sapere prima di diventare Engineering Manager

Mon, 08 Apr 2024 08:50:08 GMT

Ho sempre lavorato come individual contributor in un team. Vedo uno schema ricorrente: inizio come Engineer in un’azienda, ma prima o poi finisco per guidare il team, prendere decisioni difficili che nessuno vuole prendere, assumermi la responsabilità del bene e del male, e le persone fuori dal team mi vedono come una persona di riferimento.

Comincio a pensare: forse posso contribuire di più se gestisco persone e non solo codice. Invece di ricominciare da zero se cambio lavoro, perché non iniziare direttamente come Engineering Manager?

Quindi eccomi qui: sono stato promosso Engineering Manager. Congratulazioni!

Sono Engineering Manager da un po’ di tempo ormai, e voglio condividere qualcosa che avrei voluto sapere prima.

Avere ottime competenze tecniche e fiuto per gli affari non basta più

Penso che la mia più grande abilità sia imparare in fretta: se sei bravo in questo, puoi risolvere qualsiasi problema tecnico. Gli ingegneri sono molto fortunati da questo punto di vista: c’è abbondanza di documentazione su Internet. Puoi letteralmente imparare tutto senza spendere un centesimo, devi solo voler imparare: non devi supplicare nessuno per ottenere informazioni. Se lavori in buone aziende, anche i processi interni e la conoscenza sono aperti.

Quindi puoi crescere senza dipendere troppo dalle persone. Almeno fino a Senior Software Engineer, poi devi affinare la tua capacità di influenzare per diventare Staff Software Engineer.

Ma se sei sul percorso Manager, il tuo team è la tua risorsa più preziosa per crescere. Quindi dovresti “espandere la tua influenza” il prima possibile.

L’ho imparato a mie spese durante la performance review. Ho passato un anno intero a mantenere il mio team coinvolto e a rispettare le scadenze nonostante fossimo sotto organico. Questo significa che ho contribuito anche come Individual Contributor.

Ero felice della mia performance: sono un Engineering Manager che può essere un Individual Contributor quando l’azienda ne ha bisogno. Sto superando le aspettative, giusto?

Ma il mio duro lavoro come individual contributor è valso quasi nulla durante la performance review. E sicuramente non mi ha aiutato nel mio percorso di carriera.

Il giorno dopo ero piuttosto arrabbiato, ma ho imparato a non preoccuparmi troppo di qualcosa che non posso cambiare (le regole del gioco dell’azienda), è sempre meglio concentrarsi sulle cose che posso cambiare (i miei comportamenti).

Quindi non essere come me: se sei un Manager, hai bisogno di un team, e possibilmente di più di uno, e più persone ti conoscono, meglio è.

Devi rinunciare alla cosa più gioiosa del lavoro

Se prima sei stato Software Engineer per diversi anni e sei sopravvissuto, probabilmente significa che ami programmare. Programmare è difficile e anche stressante, soprattutto quando hai scadenze strette.

Tuttavia, la dopamina che ricevi dopo aver finito un compito, risolto un problema complesso o visto il tuo lavoro usato dai clienti non ha prezzo! Lo adoro, e adoro anche costruire cose. Più esperienza accumuli come Software Engineer, meno ti blocchi, quindi senti anche di poter ottenere qualsiasi cosa. Questo aumenta molto l’autostima dell’Engineer.

Tale gioia e felicità sono più difficili da trovare se sei un Manager.

Ogni attività nel backlog dovrebbe essere svolta dai tuoi riporti. E i tuoi riporti sono esseri umani; gli esseri umani sono pigri per natura. Se sei fortunato, trovi ingegneri che combattono la pigrizia automatizzando le cose e facendo comunque le cose difficili perché gli piace. Ma di solito hai ingegneri che hanno ogni sorta di intoppi: passano tempo su qualcosa non richiesto nel task, hanno problemi personali, non sono convinti del task stesso, non seguono ciò che il team ha concordato, ecc.

Quindi devi ottenere risultati attraverso le persone: hai sempre questo livello di indirezione che rende le cose più complicate. E questo è stressante; non avrai lo stesso livello di dopamina che ottieni come individual contributor, di sicuro.

Ora sto cercando di riprogrammare il mio cervello per trovare gioia in cose a cui prima prestavo poca attenzione:

Sono felice quando ho una riunione con alcuni punti d’azione concordati.
Sono felice quando vedo lo sprint funzionare come previsto e i miei riporti trovare soluzioni autonomamente.
Sono felice quando faccio gli 1:1 e sono contenti di come sta lavorando il team, nonostante l’ambiente intorno a noi non sia così buono.
Sono felice quando vedo un neolaureato/riporto crescere e prendermi come mentore, riconoscendo il mio impegno.
Sono felice quando vedo team/clienti diversi avere lo stesso contesto e lavorare insieme per costruire qualcosa di molto grande.

Come puoi vedere, ci sono molte opportunità di felicità qui. Ma devi sempre coinvolgere le persone, e a volte il risultato non è tangibile. Quindi devi praticare alcune tecniche di “mindfulness” per apprezzarlo.

A volte ho davvero bisogno di parlare con me stesso: “Ehi! Hai un sacco di cose. So che sei arrabbiato perché hai passato 1 ora a spiegare una cosa banale a qualcun altro. Ma ora l’altro ne sa di più, e sarà più veloce la prossima volta. Goditi l’interesse composto nei prossimi giorni.” Questo è ciò che faccio per godermi il mio percorso manageriale. Più ci sto dentro, meno ho bisogno di parlare con me stesso per sentire la gioia. Come ho detto, questo è necessario per riprogrammare il cervello e goderti il tuo nuovo lavoro.

Sono sicuro che ci sono persone che lo sentono naturalmente. Ma se tu non lo fai, prova le tecniche di “mindfulness”.

Per avere successo hai bisogno delle persone

È molto allettante fare il task da soli, è certamente più facile: parlare con qualcuno, spiegare cosa fare, convincerlo che è la persona giusta per farlo, impegnarlo a farlo in modo tempestivo richiede molto tempo… Quindi… Perché dovrei prendere quella strada invece di farlo da solo? Perché non è scalabile, non puoi fare tutto da solo. Prima lo capisci, meno dolore provi. L’ho imparato a mie spese: mi stavo lamentando con il mio product owner del fatto che non riuscivo a fare tutto da solo, le cose cominciavano a sfuggirmi di mano, mi ha interrotto bruscamente e ha detto: “hai un intero team a tua disposizione, fallo lavorare!“.

Quello è stato il mio momento di svolta! Ero troppo concentrato su me stesso e non stavo sfruttando il mio team come avrei dovuto. Da quel giorno ho deciso di dedicare più sforzo agli altri che a me stesso. È stato facile? No, perché la tentazione di tornare alla vecchia cattiva abitudine era alta… Ma sapevo che non poteva funzionare nel vecchio modo.

Alla fine sono riuscito a gestire il mio team efficacemente al massimo del suo potenziale. Poi abbiamo avuto un problema di sotto organico, ma almeno nessuno si è lamentato che stessi sottoutilizzando le mie risorse 😅.

Non esiste la tecnica migliore per gestire le persone

Gestire persone che creano software è completamente diverso dal creare da soli: scrivere software richiede esperienza, e questa esperienza che accumuli è ubiqua. Se scrivi buon codice TypeScript, probabilmente sarai in grado di scrivere buon codice anche in altri linguaggi. Le best practice e le tecniche di debugging sono ancora le stesse e rimarranno le stesse negli anni.

Ma le persone sono una bestia completamente diversa; ogni persona è unica. Ciò che funziona con uno dei tuoi riporti può completamente allontanarne un altro. Fare mentoring a un junior è diverso dal fare mentoring a un senior.

Se lavori in un ambiente internazionale, scoprirai presto che le tue capacità manageriali dovrebbero adattarsi a culture diverse.

Per esempio, alle persone nordiche non piace lavorare se uno dei membri del team non è pienamente convinto. Alle persone dell’area mediterranea piace essere in un ambiente amichevole e sono più propense ad agire sulla base dell’amicizia piuttosto che dell’autorità del manager. Amano le chiacchiere. D’altra parte, alle persone tedesche non piacciono le chiacchiere. Gli europei sono più propensi a esprimere quando qualcosa non va, mentre gli americani tendono a dire che tutto va bene anche quando non è così. Le persone indiane spesso dicono di aver capito quello che hai detto, anche se non è vero.

C’è un sacco di informazioni là fuori per imparare queste dinamiche multiculturali. Ti danno un buon punto di partenza, ma poi affronti la realtà dove capisci rapidamente che non funzionerà perché ogni persona è diversa e può differire completamente da ciò che hai imparato.

Quindi qual è la soluzione? Resta semplicemente in silenzio.

Ascolta i tuoi riporti negli 1:1. Puoi imparare come vedono il loro lavoro, come pensano. Guardali lavorare, osserva quando e come si arrabbiano, quando sono felici. Capisci cosa gli interessa e cosa no. Poi puoi iniziare a parlare, assegnare loro compiti e coinvolgerli nel progetto in base a ciò che hai imparato.

Questo è il modo migliore per ottenere risultati con loro. Cercherò di scrivere altri post su questo argomento perché so che c’è molto altro da dire qui.

Devi essere empatico per essere un buon manager

Essere empatico significa “mostrare la capacità di comprendere e condividere i sentimenti di un altro”, e credo che questo sia obbligatorio per essere un buon manager.

Se alcuni dei miei ex colleghi stanno leggendo quello che ho appena scritto, probabilmente stanno ridendo di me: “Dai, sei la persona meno empatica che conosco!“. Sono sicuro che è quello che stanno pensando. E hanno ragione! Ma non voglio negarlo, sono pienamente consapevole che i miei peggiori errori manageriali hanno tutti avuto la stessa radice: la mancanza di empatia.

Scriverò degli errori che ho fatto così non dovrai farli tu per imparare.

Cosa puoi fare se sei un blocco di ghiaccio senza emozioni come me? Puoi comunque imparare a essere empatico. Magari non proverai le stesse emozioni proprio quando il tuo interlocutore parla. Ma puoi chiederti: “Quali emozioni ha provato il tuo riporto quando ti ha parlato? Perché la persona si sente così? Se faccio X, può sentirsi meglio?“. Se non sei una persona empatica, è difficile esprimere empatia e ricavare direttamente dalla conversazione punti d’azione empatici, ma non devi per forza farlo sul momento! Puoi semplicemente digerire offline quello che hai sentito e poi tornare più tardi.

È tua responsabilità avere conversazioni difficili come manager

È tuo dovere avere conversazioni difficili che nessuno vuole avere. Queste conversazioni possono riguardare la gestione di problemi di performance, il fornire feedback costruttivi o la risoluzione di conflitti all’interno del team.

Sebbene queste conversazioni possano essere scomode, sono cruciali per la crescita e lo sviluppo sia degli individui che del team nel suo insieme. Affrontando questi problemi direttamente e onestamente, puoi creare un ambiente di lavoro più produttivo e armonioso, favorendo la crescita personale e professionale di tutti i coinvolti.

Sfortunatamente, non puoi delegarle a qualcun altro. Quindi, se non ti senti a tuo agio nell’avere conversazioni difficili, devi lavorare per migliorare le tue capacità in questo ambito.

Conclusione

Spero che questo post ti abbia dato qualche spunto sulle sfide e le ricompense del passaggio da individual contributor a manager. Sebbene la transizione possa essere impegnativa, può anche essere incredibilmente gratificante. Concentrandoti sulla costruzione di relazioni solide con il tuo team, abbracciando nuovi modi di lavorare e sviluppando le tue capacità di leadership, puoi diventare un manager efficace e di successo.

Se stai considerando di fare il salto, ti incoraggio a prenderti il tempo per riflettere sui tuoi punti di forza e di debolezza, e a considerare come puoi sfruttare le tue capacità ed esperienza per eccellere nel tuo nuovo ruolo.

Ricorda, va bene commettere errori lungo il percorso, purché tu sia disposto a imparare da essi e a crescere come leader.

Ci vediamo nel prossimo post!

Come memorizzare i segreti nei repository pubblici

Sun, 27 Nov 2022 08:04:12 GMT

Prima o poi proviamo tutti questo dolore: stai lavorando duramente sul tuo repository git. Per un motivo qualsiasi cambi PC ma vuoi comunque continuare a lavorare al tuo progetto. Quindi scarichi il repository usando git clone. Sei pronto a partire, ma poi ti blocchi perché non ricordi i segreti che avevi messo nel file .gitignore.

Fortunatamente ora esiste una soluzione. Si chiama git-crypt.

Git-crypt cifra i tuoi segreti prima di fare il push delle modifiche sul branch remoto, e li decifra quando scarichi da esso. Quindi, dopo averlo configurato, tutto è completamente trasparente. Ti dimenticherai di avere dei segreti nel repository!

Bootstrap

Per iniziare devi installarlo. Su Mac puoi eseguire il seguente comando nel terminale dopo aver installato il gestore di pacchetti brew

brew install git-crypt

Poi devi andare nel tuo repository pubblico dove vuoi mettere i segreti. E inizializzare git-crypt

cd <YOUR_REPO_PATH>
git-crypt init

Aggiungere i segreti

Ora devi aggiungere il file .gitattribute nella cartella principale del repository. In questo file dichiari i file e le cartelle che vuoi mantenere segreti. Questo è un esempio di file .gitattribute

# Rendi segreto il file .env
.env filter=git-crypt diff=git-crypt

# Rendi segreti tutti i file che terminano con .key
*.key filter=git-crypt diff=git-crypt

# Rendi segreti tutti i file contenuti nella cartella secretdir
secretdir/** filter=git-crypt diff=git-crypt

Dopo aver creato il file .gitattribute, puoi mettere i segreti nel posto che hai appena dichiarato. Se metti i file prima del .gitattribute, i tuoi segreti non verranno cifrati! Prima di fare commit di qualsiasi cosa, puoi avere la conferma che i file verranno cifrati usando il comando git-crypt status

# Mostra se i file sono cifrati o meno
git-crypt status

# Mostra solo i file cifrati
git-crypt status -e

# Mostra solo i file non cifrati
git-crypt status -u

Se un file era già presente, non verrà cifrato. Devi eseguire il comando git-crypt status -f. Mi ripeto: se stai usando questo comando, significa che il file era già nel tuo repository in chiaro. Quindi devi ruotare i segreti contenuti in quei file. Altrimenti, è molto facile per un attaccante vedere i segreti semplicemente guardando i commit precedenti.

Ora puoi fare commit e push. Vedrai solo alcuni file binari cifrati nel tuo repository pubblico! Ma sarai in grado di vederli localmente.

Spostare la chiave simmetrica su un altro dispositivo

Fin qui tutto bene… Ma se cloni il repository altrove, scaricherai i file cifrati. Quindi come possiamo decifrare di nuovo i file? Per rispondere a questa domanda dobbiamo svelare un po’ di magia. git-crypt decifra i file usando una chiave simmetrica.

Durante l’inizializzazione con git-crypt init, ha creato la chiave simmetrica e l’ha messa in <YOUR_REPO_PATH>/.git-crypt/keys/default. Puoi esportarla facilmente con questo comando

git-crypt export-key /path/to/keyfile

con questa chiave puoi decifrare anche sugli altri tuoi dispositivi. Quindi tienila al sicuro. Per decifrare un repository protetto con git-crypt puoi usare il comando

git-crypt unlock /path/to/keyfile

Usare le chiavi GPG

So cosa stai pensando: “Dai… ho più di 30 repository. Non posso memorizzare e spostare le chiavi per ogni repo! Dovrebbe esserci un modo più semplice per gestirle.”. Esiste, davvero!

Puoi usare la tua chiave GPG per sbloccare il tuo repository. Se non ne hai una, puoi seguire la guida di Github per creare la chiave GPG.

Tutto ciò che devi fare è permettere alla tua chiave GPG di decifrare il repository

# Da questo momento puoi sbloccare usando <YOUR_GPG_KEY>
git-crypt add-gpg-user <YOUR_GPG_KEY_ID>

Per trovare la tua chiave GPG, puoi usare il seguente comando. Presumo che tu abbia già installato GnuPG

gpg --list-secret-keys --keyid-format=long

Poi, se cloni il tuo repository altrove, puoi sbloccarlo con

git-crypt unlock

git-crypt sarà abbastanza intelligente da cercare la chiave GPG sulla tua macchina. Se la trova, decifrerà tutto!

Come funziona la modalità GPG

… Ma come funziona? Presumo che non ti piaccia la magia.

Quando scrivi

git-crypt add-gpg-user <YOUR_GPG_KEY_ID>

git-crypt cifrerà la chiave simmetrica usando la tua chiave GPG pubblica, e farà il commit nel tuo repository nella cartella .git-crypt/keys/default/0.

Poi, quando scrivi

git-crypt unlock

git-crypt troverà la tua chiave GPG sul tuo Mac, decifrerà la chiave simmetrica che ha salvato in .git-crypt/keys/default/0 usando la tua chiave GPG privata. Infine, decifrerà i segreti usando la chiave simmetrica appena decifrata.

Spero di esserti stato d’aiuto nel trovare un buon modo per gestire i segreti nei tuoi repository. Lo uso intensamente sia nei miei progetti hobbistici che al lavoro. Sono così soddisfatto che volevo condividerlo con voi.

Alla prossima!

Come costruire un sensore per la qualità dell'aria utilizzando un Raspberry Pi

Sun, 17 Jan 2021 16:40:20 GMT

Abito a Milano e mi chiedevo quanto l’aria fosse inquinata. Così ho iniziato a imparare come costruire un sensore per la qualità dell’aria e come integrarlo nel mio Home Assistant. Poi me ne sono pentito perché ho capito che la qualità dell’aria a Milano è terribile! Non è una notizia dell’ultima ora, ma è diverso avere il tuo sensore che analizza l’aria che stai respirando invece di sentire il telegiornale che dice: “Stop del traffico a Milano per abbassare le emissioni perché è sopra i limiti”. Poi ho spostato il sensore a Serina, un paesino sperduto tra le montagne, dove la qualità dell’aria è decisamente migliore!

Ora voglio condividere ciò che ho imparato: come creare lo stesso sensore per la qualità dell’aria che ho costruito e come leggere questi dati in Home Assistant proprio in questo modo

L’hardware necessario

Per raggiungere questo obiettivo abbiamo bisogno di:

2 Raspberry Pi con relativo alimentatore e SD Card: uno sarà il sensore per la qualità dell’aria (Rpi Sensor), l’altro sarà il nostro ricevitore con Home Assistant (Rpi Hub). È inoltre necessario un dongle USB WiFi se il Raspberry Pi di qualità dell’aria non lo ha integrato.
Il sensore per la qualità dell’aria SDS011: questo hardware viene comunemente fornito con il dongle USB, quindi è facile da collegare al Raspberry Pi.

Il software che utilizziamo

Mosquitto: broker di messaggi open source che implementa il protocollo MQTT. Il protocollo MQTT è ampiamente utilizzato nei sistemi IoT perché funziona molto bene in condizioni estreme come un segnale WiFi debole e larghezza di banda WiFi molto limitata.
Home Assistant: sistema domotico open source.

Al momento sto utilizzando un Mac, quindi tutti i comandi che vedi funzioneranno su un terminale Mac o Linux. Se utilizzi Windows hai due opzioni:

Installa WSL.
Utilizza una macchina virtuale con Linux installato utilizzando VirtualBox.

Cosa impariamo

Qualcuno può dire: “Ehi! Sei un bugiardo! Non stai costruendo un sensore per la qualità dell’aria, l’hai appena comprato!“. Forse ha ragione, ma penso che il sensore sia solo la punta dell’iceberg. Abbiamo molto lavoro da fare per estrarre i dati dal sensore e renderli utili.

L’architettura complessiva che vogliamo costruire è mostrata nella figura successiva

Quindi, attraverso questo tutorial, impareremo:

Come creare un programma che estrae i dati dal sensore. Lo scriveremo in Go. Per semplificare lo sviluppo impareremo come cross-compilare il binario per l’architettura ARM utilizzando il nostro PC / Mac che ha un’architettura diversa dal Raspberry Pi.
Come collegare automaticamente il Raspberry Pi con il sensore al WiFi con il segnale più forte, come riconnettersi automaticamente in caso di interruzione.
Come avviare automaticamente il programma Go in caso di problemi.
Come passare i dati utilizzando il protocollo MQTT e come digerire quelli all’interno di Home Assistant.

Ora che abbiamo in mente il quadro generale, iniziamo!

Prepariamo il Raspberry Pi con il sensore per la qualità dell’aria

Cominciamo con il Raspberry Pi con il sensore per la qualità dell’aria. La prima cosa di cui abbiamo bisogno è installare il sistema operativo Raspberry Pi Lite. Abbiamo solo bisogno della lite perché usiamo solo il terminale e ci collegheremo usando SSH.

Ora dobbiamo collegare la scheda SD al Raspberry, collegare la porta ethernet per collegarla alla nostra rete domestica per il primo setup e collegare il sensore SDS011 tramite USB. Il Raspberry Pi dovrebbe rilevarlo automaticamente.

Diamo un’occhiata: connettiamoci a questo Raspberry Pi usando tramite SSH usando ssh pi@<RPI_SENSOR_IP>, con password raspberry. Cambia “<RPI_SENSOR_IP>” con l’indirizzo IP del sensore Raspberry Pi. Di solito trovo il suo indirizzo IP tramite il pannello di controllo del mio router, o semplicemente digito sul terminale ping raspberrypi.local. Dovresti trovare qualcosa di simile

PING raspberrypi.local (192.168.1.123): 56 data bytes
64 bytes from 192.168.1.123: icmp_seq=0 ttl=64 time=13.452 ms
64 bytes from 192.168.1.123: icmp_seq=1 ttl=64 time=17.451 ms
--- raspberrypi.local ping statistics ---
2 packets transmitted, 2 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 13.452/15.451/17.451/2.000 ms

L’IP che vedi lì, è l’IP che stai cercando.

Ora che siamo connessi tramite SSH, digitiamo lsusb per verificare che il Raspberry Pi veda il sensore

pi@edge-rpi:~ $ lsusb
Bus 001 Device 005: ID 1a86:7523 QinHeng Electronics HL-340 USB-Serial adapter
Bus 001 Device 004: ID 2001:330d D-Link Corp.
Bus 001 Device 003: ID 0424:ec00 Standard Microsystems Corp. SMSC9512/9514 Fast Ethernet Adapter
Bus 001 Device 002: ID 0424:9512 Standard Microsystems Corp. SMC9512/9514 USB Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

Dovresti vedere alcuni nomi cinesi come “QinHeng Electronics HL-340”. Questo è il nostro sensore. Se digitiamo ls /dev/ttyUSB* dovremmo vedere /dev/ttyUSB0 come risposta: questo è il nostro canale per comunicare con il sensore.

Compilare il programma Go per recuperare i dati

Ora dovremmo creare un programma che prenda i dati del sensore /dev/ttyUSB0 creati e li pubblichi su un topic MQTT.

Se non conosci MQTT, non preoccuparti: Wikipedia spiega brevemente di cosa si tratta. Questa è la mia spiegazione: è un protocollo leggero che si basa sui topics. Qualcuno pubblica qualcosa su un topic, come i dati del sensore per la qualità dell’aria. Qualcun altro può iscriversi a quel topic, in questo modo viene avvisato ogni volta che ci sono nuovi dati su quell’argomento.

Ho creato questa applicazione per te in Go. Puoi trovarlo su GitHub. Dovremmo cambiare la configurazione che si trova in cmd/sensor/main.go, il file dovrebbe essere così

package main

import "mattianatali.it/sds011-mqtt/internal/sensor"

func main() {
  c := sensor.Config{
    Topic: "home/serina/edge-rpi/air-quality",
    SensorPortPath: "/dev/ttyUSB0",
    CycleMinutes: 1,
    MqttBroker: "tcp://192.168.1.117:1883",
  }
  sensor.Start(c)
}

Cambia Topic con una stringa a tua scelta. La mia convenzione è home/<HOME_IDENTIFIER>/<DEVICE_IDENTIFIED>/<DATA>. Il topic è solo una stringa che fa riferimento a dove vogliamo pubblicare i dati e quindi dove vogliamo fare subscribe per recuperarli.
SensorPortPath: dovrebbe essere lo stesso, è dove recuperiamo i dati del sensore.
CycleMinutes: cambialo se 1 campione/minuto è troppo per te. Non puoi mettere meno di 1 minuto.
MqttBroker: Dovresti inserire l’indirizzo IP del Raspberry Pi dove abbiamo messo Mosquitto, il broker di messaggi che gestisce i nostri argomenti MQTT. Ti consiglio di utilizzare lo stesso Raspberry Pi dove installi anche Home Assistant.

Se sei curioso, puoi vedere l’implementazione in internal/sensor/main.go.

Ora è il momento di compilarlo per il nostro Raspberry Pi! Mi aspetto che tu abbia scaricato questo codice sorgente sul tuo Mac / PC e che tu abbia Go installato. Quindi, dobbiamo sapere che tipo di architettura ha il tuo Raspberry Pi.

Lancia questo comando sul Raspberry Pi: cat /proc/cpuinfo Dovresti vedere qualcosa di simile

cat /proc/cpuinfo

processor : 0
model name : ARMv6-compatible processor rev 7 (v6l)
BogoMIPS : 697.95
Features : half thumb fastmult vfp edsp java tls
CPU implementer : 0x41
CPU architecture: 7
CPU variant : 0x0
CPU part : 0xb76
CPU revision : 7

Hardware : BCM2835
Revision : 0002
Serial : 00000000cdea9a84
Model : Raspberry Pi Model B Rev 1

Il mio Raspberry ha “ARMv6”, quindi devo compilare per quel tipo. Se hai un Raspberry Pi 2 dovresti vedere “ARMv7”. Ho creato un Makefile per semplificare la cross-compilazione. Il makefile è molto comune su Linux, viene utilizzato per semplificare le attività comuni. Se non lo sai, ti suggerisco di leggere Learn make in Y minutes.

Se hai ARMv6, digita semplicemente make build-arm6 nella cartella in cui hai scaricato il mio progetto GitHub.
Se hai ARMv7, digita make build-arm.

Ora dovremmo avere un file binario situato in dist/pm-sensor. Dovremmo trasferire al nostro sensore sul Raspberry Pi. Useremo il comando scp.

scp dist/pm-sensor pi@<RPI_SENSOR_IP>:

Come al solito, cambia <RPI_SENSOR_IP> con l’IP reale, ma lascia i due punti alla fine. Ciò significa che posizioneremo il pm-sensor nella cartella home del nostro utente pi all’interno del Raspberry Pi.

Ora possiamo entrare tramite SSH nel Raspberry Pi, dovremmo vedere il nostro nuovo file binario chiamato pm-sensor. Se proviamo a farlo partire, fallisce

# Aggiungi il permesso di esecuzione allo script
sudo chmod +x ./pm-sensor
# Fallo partire
./pm-sensor
# Questo è l'output del programma
panic: Network Error : dial tcp 192.168.1.118:1883: connect: connection refused

goroutine 1 [running]:
mattianatali.it/sds011-mqtt/internal/sensor.Start(0x12d3bcd, 0x20, 0x12cc844, 0xc, 0x1, 0x12d0ec0, 0x18)
 /Users/mattia/Repositories/sds011-mqtt/internal/sensor/main.go:28 +0x7e5
main.main()
 /Users/mattia/Repositories/sds011-mqtt/cmd/sensor/main.go:12 +0xac

si lamenta perché non riesce a connettersi al broker MQTT per pubblicare i dati del sensore. Ha ragione, non abbiamo preparato l’altro Raspberry Pi.

Ora lasciamo per un attimo il sensore, e lavoreremo sul Raspberry Pi che si trova all’interno della nostra casa, lo chiamiamo Hub per semplicità.

Aggiungiamo mosquitto al Raspberry Pi hub

Ora è il momento di configurare la parte “ricevitore” dell’architettura. Quindi abbiamo bisogno dell’altro Raspberry Pi con installato un sistema operativo Raspberry pulito.

Quindi installiamo Mosquitto

wget http://repo.mosquitto.org/debian/mosquitto-repo.gpg.key
sudo apt-key add mosquitto-repo.gpg.key
cd /etc/apt/sources.list.d/
sudo wget http://repo.mosquitto.org/debian/mosquitto-buster.list
apt-get update
sudo apt-get install mosquitto

La nuova versione di Mosquitto ha aggiunto l’autenticazione di default per ottime ragioni. Ho iniziato questo progetto quando Mosquitto non aveva l’autenticazione abilitato di default, quindi il mio script non lo supporta ancora. Per abilitare il supporto per gli utenti anonimi dovremmo aggiungere queste due righe nel file /etc/mosquitto/mosquitto.conf

listener 1883
allow_anonymous true

Il primo abilita i messaggi in arrivo da diversi host alla porta 1883. Ciò è necessario perché il nostro sensore non è su questo Rpi Hub. Il secondo abilita gli utenti anonimi.

Ci assicuriamo che Mosquitto funzioni, prenda il nuovo file di configurazione e si avvia all’avvio di Raspberry.

# Restart mosquitto to get the new config file
sudo systemctl restart mosquitto

# Make sure mosquitto is enabled on startup
sudo systemctl enable mosquitto

Ora abbiamo il Broker MQTT attivo e funzionante! Significa che il nostro sensore può inviare i dati a questo broker. Testiamo se il nostro sensore può inviare dati a questo broker.

# Connetti al Raspberry Pi sensor e digita la password
ssh pi@<RPI_SENSOR_IP>
# Fai partire il programma per inviare i dati sulla qualità dell'aria
./pm-sensor
# Questo è l'output atteso (1 linea ogni minuto)
2021-01-06T05:58:15Z,8.4,21
2021-01-06T05:59:15Z,10.5,60.9
2021-01-06T06:00:15Z,8.5,48.9
2021-01-06T06:01:15Z,12.3,99.5
2021-01-06T06:02:15Z,20.1,214.3
2021-01-06T06:03:14Z,17.6,183.2
2021-01-06T06:04:14Z,16.5,173.7
2021-01-06T06:05:14Z,10.4,52.2

Questo è davvero un buon segno! Significa che possiamo recuperare i dati dal nostro sensore e possiamo inviarli al nostro broker MQTT che è installato sul nostro Hub Raspberry Pi!

Per fare una contro prova, lasciamo il programma attivo e facciamo subscribe sul topic a cui stiamo inviando i dati

# Ci colleghiamo a Raspberry Pi Hub
ssh pi@<RPI_HUB_IP>
# Facciamo subscribe al topic
mosquitto_sub -t 'home/serina/edge-rpi/air-quality'
# Dovremmo vedere un output come questo
{"PM25":14.8,"PM10":18.6,"Timestamp":"2021-01-06T13:42:08.33019206Z"}
{"PM25":14.5,"PM10":16.2,"Timestamp":"2021-01-06T13:43:08.192798603Z"}
{"PM25":8.7,"PM10":9.7,"Timestamp":"2021-01-06T13:44:08.057092356Z"}

Dovresti cambiare <RPI_HUB_IP> con l’IP del tuo Hub e sostituire home/serina/edge-rpi/air-quality con l’argomento che hai inserito nella configurazione Go all’interno della proprietà Topic.

Ora sappiamo cosa pubblica sull’argomento il nostro programma Go: invia un file JSON con tre proprietà:

“PM25”: contiene il PM 2.5 espresso in µg/m^3.
“PM10”: contiene il PM 10 espresso in µg/m^3.
Timestamp: contiene l’ora in ISO 8601 in cui ha recuperato i dati.

Riepilogo

Congratulazioni! Ora abbiamo un sensore che recupera i dati sulla qualità dell’aria e li invia a un broker MQTT, ogni applicazione che desidera questi dati dovrebbe iscriversi al topic scelto e il gioco è fatto! Abbiamo finito?

Beh… Non esattamente.

Vogliamo mettere il sensore all’esterno, quindi dovremmo usare il WiFi e staccare la porta Ethernet. Non vogliamo collegarci al sensore per avviare il programma. Se mettiamo il sensore lontano dal nostro router, il sensore dovrebbe essere in grado di ricollegarsi automaticamente ogni volta, dovrebbe fare lo stesso se riavviamo il router. Abbiamo tutti questi problemi da risolvere!

Quindi potenziamo il nostro sensore per renderlo wireless e abbastanza intelligente da mantenere la connessione automaticamente.

Potenziamo il sensore!

Avviare automaticamente il programma

Il programma non si avvia automaticamente. Dobbiamo connetterci tramite SSH e avviarlo con il comando ./pm-sensor. Questo è molto frustrante.

Per raggiungere questo obiettivo, utilizziamo systemd. Systemd è il gestore di sistema e servizi per Raspberry Pi. Hai notato che abbiamo già utilizzato systemd in questo tutorial? Quando abbiamo avviato mosquitto abbiamo scritto

sudo systemctl restart mosquitto
sudo systemctl enable mosquitto

usando il comando systemctl possiamo avviare / arrestare / riavviare i servizi su una macchina Linux. E possiamo anche avviare automaticamente un servizio all’avvio se scriviamo sudo systemctl enable <SERVICE>. Quindi dobbiamo creare un servizio per il nostro programma di sensori pm.

Fortunatamente è molto semplice: i servizi personalizzati sono archiviati nella cartella /etc/systemd/system. Quindi possiamo aggiungere il nuovo servizio, se aggiungiamo il file chiamato pm-sensor.service in quella cartella. Il contenuto di quel file è il seguente

[Unit]
Description=PM Air Quality Sensor
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=pi
Group=pi
ExecStart=/home/pi/pm-sensor
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Come puoi vedere, la dichiarazione del servizio è composta da tre sezioni: [Unit], [Service] e [Install].

Nella sezione “[Unit]” mettiamo una piccola descrizione del nostro servizio e dichiariamo che vogliamo che la rete sia attiva e funzionante prima di avviarla.
[Service] dichiara il tipo di servizio, il nome e il gruppo dell’utente che dovrebbe avviare lo script, dove si trova il programma e definiamo come dovrebbe comportarsi systemd in caso di panico del servizio. Vogliamo che il programma si riavvii sempre.
[Install] definisce che questo servizio non necessita dell’interfaccia utente grafica.

Systemd è un argomento molto vasto e merita un libro completo su di esso. So che questa spiegazione è molto sommaria, ma è sufficiente per i nostri scopi. Ma so che sei molto curioso! Quindi, se vuoi scavare più a fondo, puoi digitare man systemd.unit e man systemd.service sulla tua macchina Linux. In Linux, se vuoi sapere qualcosa di più basta digitare man <PROGRAM_YOU_WANT_TO_LEARN_MORE>.

Ora che abbiamo creato il servizio, dobbiamo ricaricare la configurazione di systemd, avviare il programma e abilitarlo durante l’avvio.

sudo systemctl daemon-reload
sudo systemctl start pm-sensor
sudo systemctl enable pm-sensor

Possiamo verificare se tutto è avviato correttamente con il seguente comando

sudo systemctl status pm-sensor
# Questo è l'output che abbiamo ottenuto
● pm-sensor.service - PM Air Quality Sensor
 Loaded: loaded (/etc/systemd/system/pm-sensor.service; enabled; vendor preset: enabled)
 Active: active (running) since Wed 2021-01-06 15:01:26 GMT; 1h 43min ago
 Main PID: 1182 (pm-sensor)
 Tasks: 5 (limit: 272)
 CGroup: /system.slice/pm-sensor.service
 └─1182 /home/pi/pm-sensor

Jan 06 16:36:01 edge-rpi pm-sensor[1182]: 2021-01-06T16:36:01Z,21.2,33.9
Jan 06 16:37:00 edge-rpi pm-sensor[1182]: 2021-01-06T16:37:00Z,61.1,303.4

Se tutto è corretto, dovremmo vedere anche i log del nostro programma.

Non è più necessario avviare manualmente il programma! Ma siamo ancora connessi tramite Ethernet, non possiamo mettere il nostro sensore fuori casa. Risolviamo il problema!

Aggiungere la connessione WiFi

Il modo migliore per aggiungere il WiFi al Raspberry Sensor è leggendo la documentazione ufficiale, è inutile fare copia-incolla. Ti suggerisco di aggiungere tutti i tuoi WiFi SSID che hai a casa. In questo modo, imposti il sensore solo una volta. Se desideri spostarlo in un altro luogo, proverà a connettersi al punto di accesso WiFi più vicino.

Tieni presente che ora l’indirizzo IP del sensore potrebbe essere cambiato. Quindi ricordati di trovare il nuovo indirizzo.

Mantenere il WiFi persistente

Ora possiamo mettere il nostro sensore all’esterno! Si connette automaticamente al nostro WiFi e avvia il nostro programma che recupera il sensore. Dovremmo essere orgogliosi del nostro lavoro fatto fino ad ora… Ma ci rendiamo presto conto che c’è un problema. Ce ne rendiamo conto quando riavviamo il nostro router o mettiamo il nostro sensore troppo lontano da esso: il Raspberry Pi non prova a ricollegare il WiFi se perde la connessione!

Sistemiamo. Ho trovato un piccolo script sul web e l’ho adattato per i nostri scopi. Creiamo il file check-wifi.sh

# Connettiti al Raspberry Pi sensor
ssh pi@<RPI_SENSOR_IP>

# Crea il nuovo file
touch check-wifi.sh

# Aggiungi il permesso di esecuzione su di esso
chmod +x check-wifi.sh

mettiamo questo contenuto al suo interno

#!/bin/bash

##################################################################
# Impostazioni
# Quale interfaccia vuoi controllare
wlan='wlan0'
# Quale indirizzo vuoi eseguire il ping per vedere se l'interfaccia di rete è attiva?
pingip='192.168.1.1'
##################################################################

echo "Performing Network check for $wlan"
/bin/ping -c 1 -I $wlan $pingip > /dev/null 2> /dev/null
if [ $? -ge 1 ] ; then
  echo "Network connection down! Attempting reconnection."
  sudo ip link set $wlan down
  sleep 5
  sudo ip link set $wlan up
else
  echo "Network is Okay"
fi

Lo script dovrebbe essere autoesplicativo. Abbiamo due variabili in alto: wlan che non dovresti cambiare e pingip dove metti l’indirizzo IP del tuo router.

Lo script tenta di eseguire il ping del router: se raggiunge il router, va tutto bene. Se non può farlo: disabilita il WiFi, quindi si riattiva. Dovrebbe attivare la riconnessione.

Abbiamo bisogno di qualcuno che chiami questo script ogni minuto… cron ci viene in soccorso! Questo applicativo è uno standard per fare queste cose su Linux.

Per aggiungere un lavoro pianificato che attivi il nostro script ogni minuto, dobbiamo scrivere crontab -e nel terminale. Si aprirà un editor di testo. In quella pagina scrivi questa cosa

* * * * * /home/pi/check-wifi.sh

Questa strana sintassi può spaventare ma è molto semplice. La prima parte, * * * * * indica quando lo script deve essere attivato. L’ultima parte si riferisce allo script che vogliamo lanciare. L’orario programmato è sempre rappresentato da cinque valori. L’ordine di questi cambia il significato di quegli asterischi. Da sinistra a destra si riferiscono a:

Minuto (0-59)
Ora (0-23)
Giorno del mese (1 - 31)
Mese (1-12)
Giorno della settimana (0 - 6): da domenica a sabato

Ma mettiamo *… Non numeri. Abbiamo aggiunto degli asterischi perché hano un significato speciale. * significa “qualsiasi”. Così abbiamo scritto: “Per favore Linux, esegui lo script /home/pi/check-wifi.sh ogni minuto di ogni ora di ogni giorno del mese di ogni giorno della settimana”. Linux è abbastanza intelligente da capire che dovrebbe attivare lo script ogni minuto d’ora in poi.

Ora abbiamo un sensore per la qualità dell’aria molto robusto! Possiamo metterlo fuori casa e, qualunque cosa accada, dovrebbe mantenere sempre la connessione finché raggiunge il segnale WiFi del nostro router.

Usare mosquitto_sub è l’unico modo per vedere i dati dal sensore. Questo va bene solo per scopi di debug, dovremmo avere un modo migliore per vedere quei dati. Home Assistant risolverà questo problema.

Aggiungi il sensore a Home Assistant

Installa e impara Home Assistant

Home Assistant è un ottimo software. Se sei un appassionato di tecnologia che ama automatizzare la casa, penso che tu l’abbia già installato.

Se ancora non lo sai: puoi collegare dispositivi intelligenti e creare regole per automatizzare i tuoi dispositivi domotici. Puoi anche collegare i sensori per vedere facilmente i dati. In altre parole, se decidi di installarlo, Home Assistant può diventare il centro di controllo della tua casa.

Il nostro obiettivo qui è vedere i dati del sensore nell’Home Assistant.

Come primo passo, dobbiamo installarlo sul Raspberry Pi hub. Quindi, ti suggerisco di leggere il manuale di configurazione. Home Assistant utilizza pesantemente i file YAML per installare sensori personalizzati come il nostro.

Forse stai pensando che Home Assistant sia eccessivo per vedere solo i dati del sensore. Ma penso che questo sia solo il punto di partenza: sono sicuro che alla fine avrai più di 20 dispositivi con un totale di 200 sensori collegati e dozzine di automazioni che orchestrano tutto!

Quindi non è eccessivo, è solo il nostro punto di partenza, credimi 😊.

Ora che abbiamo installato Home Assistant e imparato a conoscere dove è installata la sua configurazione, è ora di aggiungere il nostro sensore.

Aggiungere l’integrazione MQTT

Dobbiamo aggiungere l’integrazione MQTT a Home Assistant. Andiamo sul portale Home Assistant, dovrebbe essere esposto sulla porta 8123. Quindi apri il browser e digita l’URL http://<RPI_HUB_IP>:8123 dove <RPI_HUB_IP> è l’IP del nostro Raspberry Pi Hub. Fai clic sull’icona a forma di ingranaggio (Configurazione) e fare clic su “Aggiungi integrazione”. Possiamo vedere un enorme elenco di integrazioni, siamo interessati a MQTT. Quindi cercalo e poi chiederà due campi obbligatori:

Broker: è necessario aggiungere l’IP dell’hub Raspberry Pi. È dove abbiamo installato Mosquitto, il nostro broker MQTT.
Porta: è 1883. Lo avevamo messo nella configurazione mosquitto.

Fai clic su Invia e ora abbiamo collegato Home Assistant al nostro broker MQTT Mosquitto.

Dovremmo vedere la nuovissima integrazione in Configurazione -> Integrazioni. Facciamo clic su configura

e poi possiamo fare subscribe del nostro topic MQTT, solo per verificare se Home Assistant può vedere i nostri dati.

Nella sezione “Subscribe topic”, inserisci il nostro topic MQTT, fai clic su “Start listening” e attendi almeno 1 minuto. L’attesa dipende dalla configurazione impostata sul nostro programma Go. Se non modifichi il mio valore, dovrebbe pubblicare un valore al minuto.

Se vedi i dati come la figura sotto, hai collegato con successo Home Assistant al nostro Broker MQTT!

Aggiungere i sensori di qualità dell’aria tramite la piattaforma MQTT

Sappiamo che i valori sono pubblicati su un argomento MQTT (il mio è home/serina/edge-rpi/air-quality). Dovremmo creare due sensori che fanno subscribe sul topic ed estraggono i dati. Questi sensori lo saranno

Qualità dell’aria PM 10.
Qualità dell’aria PM 2.5.

Per raggiungere questo obiettivo, modifichiamo il file configuration.yaml di Home Assistant. Dobbiamo aggiungere questi due sensori all’interno della sezione sensor:.

sensor:
  - platform: mqtt
    state_topic: "home/serina/edge-rpi/air-quality"
    unit_of_measurement: "μg/m³"
    icon: "mdi:weather-fog"
    value_template: '{{value_json.PM10 | float}}'
    name: 'Air Quality PM 10'
    unique_id: 'rpi-edge:air-quality-pm-10'
  - platform: mqtt
    state_topic: "home/serina/edge-rpi/air-quality"
    unit_of_measurement: "μg/m³"
    icon: "mdi:weather-fog"
    value_template: '{{value_json.PM25 | float}}'
    name: 'Air Quality PM 2.5'
    unique_id: 'rpi-edge:air-quality-pm-2.5'

Fortunatamente, il file YAML è molto leggibile. Stiamo utilizzando la piattaforma sensor MQTT. Riavvia Home Assistant.

Dovresti cambiare state_topic con il tuo. Puoi anche cambiare unique_id con qualsiasi valore, basta che sia univoco.

value_template è il campo dove estraiamo il valore da JSON nell’argomento con la parola chiave value_json e poi prendiamo i valori interessanti PM10 e PM25. Infine, diciamo che siamo interessati a un valore di tipo float, ossia con la virgola. Tutta questa roba è circondata da {{}}: quando vedi questa sintassi significa che stiamo sfruttando il motore di templating che sfrutta Jinja2.

Se vuoi cambiare l’icona del sensore, di solito uso questo sito. Ad esempio, cerco per una parola chiave, fog, e infine passo il mouse sull’icona scelta. Dovresti anteporre al nome che appare con mdi:. Nel nostro esempio è mdi:weather-fog.

Aggiungere i sensori all’interfaccia utente di Home Assistant

Ora dovremmo avere due nuove entità che mostrano la qualità dell’aria. Per vederli, dovremmo andare su configurazione -> entità e cercare “Qualità dell’aria”

come puoi vedere, è abbastanza scomodo. È meglio inserire queste entità nella pagina panoramica / dashboard.

Nell’Home Assistant, fai clic su Panoramica sulla barra di sinistra, i tre punti sulla destra, Modifica dashboard e infine “Aggiungi scheda” in basso. Dovrebbe apparire una modale, fare clic sulla scelta “Entità”.

Scrivi il titolo che desideri; nella sezione “entità”, cerca le entità che abbiamo visto in precedenza. Dovresti vedere un’anteprima della nuova carta in basso. Quando sei soddisfatto, fai clic su “Salva” ed il gioco è fatto!

Ora dovremmo avere questa bella card ogni volta che apriamo Home Assistant! Se clicchiamo su questo, dovremmo vedere anche un grafico che riguarda l’ultimo giorno.

Conclusioni

Finalmente arriviamo alla fine di questo viaggio. Spero che tu abbia imparato qualcosa di nuovo e apprezzi la bellezza di creare un sensore per la qualità dell’aria da solo.

Vorrei raccontarvi di più a riguardo: ad esempio, non ho spiegato come vedere questi dati su Grafana

o come vedere l’SSID WiFi e la sua potenza del segnale direttamente su Home Assistant.

Ne parlerò in altri post del blog perché questo è già molto lungo.

Se vuoi essere aggiornato lascia la tua email qui sotto e ti avviserò. O semplicemente visita il mio blog di tanto in tanto.

Alla prossima!

Autenticazione JWT con Angular

Sun, 15 Dec 2019 16:40:20 GMT

Al lavoro ho dovuto creare un nuovo portale web che dovesse comunicare con il nostro backend. La nostra scelta per il framework frontend è Angular e il nostro backend usa il JWT (JSON Web Token) come sistema di autenticazione.

Quindi il mio obiettivo era integrare quel sistema di autenticazione in Angular per comunicare con il backend. Dato che si trattava di un progetto Angular iniziato da zero, ho avuto la possibilità di pensare a come implementarlo.

Obiettivi

I miei criteri di accettazione erano i seguenti:

Per ottenere il token, il frontend dovrebbe chiamare l’endpoint POST auth/login con email e password. Il backend risponderà con accessToken e refreshToken.
Il frontend dovrebbe persistere entrambi i token, così l’utente resterà autenticato anche se chiude il browser.
Dovrebbe inviare l’accessToken per ogni chiamata API autenticata. Invia il token nell’header X-AUTH-TOKEN.
Se il backend risponde 401 - Unauthorized, significa che il token è scaduto. Quindi il frontend dovrebbe chiamare l’endpoint POST auth/refresh passando refreshToken. Se il refreshToken è valido, il backend risponde con nuovi accessToken e refreshToken nel body della risposta.
- Dopo aver recuperato il nuovo accessToken, dovrebbe ritentare la chiamata fallita con il token aggiornato.
- Se il backend risponde di nuovo con 401 - Unauthorized durante il refresh, significa che il refreshToken non è più valido. Dobbiamo fare il logout dell’utente.
Dovremmo gestire tutte queste cose in modo trasparente, lo sviluppatore non dovrebbe preoccuparsene troppo quando implementa qualche classe per comunicare con il backend.

Questo flusso dovrebbe essere abbastanza standard per un sistema di autenticazione JWT. Ora pensiamo a come strutturarlo!

Prerequisiti

Mi aspetto da te un po’ di conoscenza di questi argomenti:

Angular e gli interceptor di Angular.
RxJS, che è integrato nell’HTTP Client di Angular.

Architettura

Ho costruito questa integrazione JWT usando il Test Driven Development (TDD). Così sono finito con classi facilmente testabili che hanno una sola responsabilità. Questa è la bellezza del TDD: per semplificare i test devi scrivere buon codice!

Ho costruito le seguenti classi:

AuthClient: effettua le chiamate API al backend. Nel nostro esempio implementeremo auth/login e auth/refresh.
AuthStore: persiste i token e mantiene lo stato degli utenti. Possiamo sapere se gli utenti sono autenticati o meno.
AuthService: gestisce la logica di business del nostro sistema di autenticazione, sfrutta sia AuthClient che AuthStore.
AuthInterceptor: inietta il token in ogni chiamata API autenticata, e gestisce anche la logica di retry quando l’accessToken è scaduto.

Possiamo raggiungere i nostri criteri di accettazione con queste classi, ora implementiamole!

Implementazione

Interfacce

Costruire una single page application è complesso. Gestisce molti oggetti diversi ed è molto difficile tenerne traccia senza un sistema di tipi. TypeScript aggiunge i tipi a JavaScript e io lo sfrutto il più possibile. Quindi creo sempre una cartella /model che tiene traccia di tutti gli oggetti che creo o ricevo dal backend. In questo tutorial affronteremo queste interfacce:

export interface ILogin {
    email: string;
    password: string;
}

export interface ILoginResponse {
    accessToken: string;
    refreshToken: string;
}

export interface IRefreshRequest {
  refreshToken: string;
}

AuthClient

AuthClient è molto semplice da implementare. Effettua solo le chiamate API al nostro backend

import { Injectable } from '@angular/core';
import { ILogin } from './model/Login';
import { ILoginResponse } from './model/LoginResponse';
import { IRefreshRequest } from './model/RefreshRequest';
import { Observable } from 'rxjs';
import { HttpClient } from '@angular/common/http';
import { environment } from 'src/environments/environment';
import { INTERCEPTOR_NO_AUTH_HEADER } from './constants';

@Injectable({
  providedIn: 'root'
})
export class AuthClient {

  constructor(
    private http: HttpClient,
  ) { }

  login(request: ILogin): Observable<ILoginResponse> {
    return this.http
      .post<ILoginResponse>(`${environment.portalBaseUrl}/auth/login`,
        request,
        {
          headers: { [INTERCEPTOR_NO_AUTH_HEADER]: 'true' }
        }
      );
  }

  refreshToken(request: IRefreshRequest) {
    return this.http
      .post<ILoginResponse>(`${environment.portalBaseUrl}/refresh`,
        request,
        {
          headers: { [INTERCEPTOR_NO_AUTH_HEADER]: 'true' }
        }
      );
  }
}

Puoi vedere che AuthClient è abbastanza semplice. L’unica cosa strana è l’header INTERCEPTOR_NO_AUTH_HEADER che ha un significato speciale. È il mio modo per comunicare con AuthInterceptor, sto dicendo: “Ehi! Questa è una chiamata API pubblica, non devi iniettare il token”. Ne parlo più in dettaglio dopo.

AuthStore

Memorizza e persiste le credenziali dell’utente. La mia implementazione è fortemente ispirata al pattern Business Logic Component (BLoC) + RxJS. È un pattern nuovo che sta emergendo nel mondo Dart + Flutter. Mi piace e ho portato il concetto in Angular. Non voglio parlare troppo del pattern BLoC dato che ci sono molti articoli a riguardo.

In breve: sfrutto RxJS per creare uno store reattivo delle credenziali, chiunque sia interessato a dei dati di autenticazione dovrebbe sottoscriversi ad esso. Se qualcuno vuole cambiare i dati di autenticazione, può chiamare i metodi di autenticazione. Molto semplice.

Store generico

La prima cosa da fare è creare lo store generico che gestisce lo stato di tipo T. Questo è agnostico rispetto allo stato, quindi è una classe astratta. Questo store si chiama semplicemente Store.

import { Observable, BehaviorSubject } from 'rxjs';

export class Store<T> {
    state$: Observable<T>;
    private stateSubject$: BehaviorSubject<T>;

    protected constructor(initialState: T) {
        this.stateSubject$ = new BehaviorSubject(initialState);
        this.state$ = this.stateSubject$.asObservable();
    }

    get state(): T {
        return this.stateSubject$.getValue();
    }

    setState(nextState: T): void {
        this.stateSubject$.next(nextState);
    }
}

Come puoi vedere:

Accetta lo stato iniziale nel costruttore.
Puoi cambiare lo stato chiamando il metodo setState.
Puoi sottoscriverti ai cambiamenti di stato sottoscrivendoti all’observable state$.
Puoi ottenere lo stato corrente una volta sola tramite il getter state.

Il motore del mio store è il stateSubject$ BehaviorSubject privato. Se è la prima volta che vedi un BehaviorSubject, pensa a uno stream che ha anche un “sink”, dove puoi aggiungere un nuovo elemento nello stream chiamando il metodo next. BehaviorSubject ha anche lo stato iniziale che dovresti fornire nel costruttore.

Un’altra cosa interessante è che puoi mantenere il “sink” privato ed esporre solo il suo observable. Sto esponendo solo la variabile state$ che è l’Observable creato da stateSubject$. In questo modo, nessuno può aggiungere un elemento in questo observable se non chiamando il metodo setState. In altre parole, puoi solo vedere i cambiamenti sottoscrivendoti all’observable state$, e puoi cambiare i dati dello store tramite il metodo setState. L’implementazione dello store è gestita da stateSubject$ che non è esposto esternamente.

Implementazione concreta

Ora possiamo creare il nostro AuthStore, la prima implementazione concreta dello Store.

import { IAuthState } from './auth-store.service';
import { map } from 'rxjs/operators';
import { Injectable } from '@angular/core';
import { Store } from '../shared/store';
import { Observable } from 'rxjs';
import { ILoginResponse } from './model/LoginResponse';

export interface IAuthState {
  accessToken: string;
  refreshToken: string;
}

const ACCESS_TOKEN_LOCAL_STORAGE_KEY = 'auth.accessToken';
const REFRESH_TOKEN_LOCAL_STORAGE_KEY = 'auth.refreshToken';

@Injectable({
  providedIn: 'root'
})
export class AuthStoreService extends Store<IAuthState> {
  constructor() {
    const initialState: IAuthState = {
      accessToken: localStorage.getItem(ACCESS_TOKEN_LOCAL_STORAGE_KEY),
      refreshToken: localStorage.getItem(REFRESH_TOKEN_LOCAL_STORAGE_KEY),
    };
    super(initialState);
  }

  setState(nextState: IAuthState): void {
    if (nextState.accessToken) {
      localStorage.setItem(ACCESS_TOKEN_LOCAL_STORAGE_KEY, nextState.accessToken);
    } else {
      localStorage.removeItem(ACCESS_TOKEN_LOCAL_STORAGE_KEY);
    }
    if (nextState.refreshToken) {
      localStorage.setItem(REFRESH_TOKEN_LOCAL_STORAGE_KEY, nextState.refreshToken);
    } else {
      localStorage.removeItem(REFRESH_TOKEN_LOCAL_STORAGE_KEY);
    }
    super.setState(nextState);
  }

  get isLoggedIn(): boolean {
    return !!this.state.accessToken;
  }

  get isLoggedIn$(): Observable<boolean> {
    return this.state$.pipe(map((state) => !!state.accessToken));
  }

  get accessToken(): string {
    return this.state.accessToken;
  }

  setAccessToken(accessToken: string) {
    this.setState({ ...this.state, accessToken });
  }

  get refreshToken(): string {
    return this.state.refreshToken;
  }

  login(loginResponse: ILoginResponse): void {
    this.setState({ ...this.state, ...loginResponse});
  }

  refresh(newTokens: ILoginResponse): void {
    this.setState({ ...this.state, ...newTokens });
  }

  logout(): void {
    this.setState({
      ...this.state,
      accessToken: null,
      refreshToken: null,
    });
  }
}

Ci sono molti metodi di supporto per semplificare l’uso della classe. Questi sono i punti chiave di questa classe:

È una sottoclasse di Store, ha l’interfaccia IAuthState come stato. IAuthState è molto semplice, contiene solo accessToken e refreshToken.
Ogni volta che qualcuno chiama setState, persiste i dati nel local storage. In questo modo, se l’utente chiude o ricarica la pagina, le credenziali non vanno perse. Se setState viene chiamato con credenziali falsy (ad esempio null o false), le rimuove dal local storage.
Nel costruttore fornisce lo stato iniziale alla superclasse State. Prova a ottenere le credenziali dal local storage.
Molti metodi getter: sia reattivi (terminano con $), sia standard (variabili classiche).
Alcuni metodi di supporto per cambiare lo stato dello store (setAccessToken, login, refresh).

Attenzione: memorizzare accessToken e refreshToken nel local storage può esporre la tua applicazione a problemi di sicurezza. Qualsiasi JavaScript in esecuzione nella tua web app può leggerli. Quindi se la tua web app è vulnerabile al cross-site scripting (XSS), allora qualcuno può rubarli. I framework web, come Angular, sono consapevoli di questo problema: adottano standard di sicurezza elevati per evitare vulnerabilità XSS. Ti consiglio di dedicare un po’ di tempo a leggere del cross-site scripting (XSS). Se hai paura di questo, semplicemente non salvare i token nel local storage, sarai al sicuro… Ma se il tuo utente chiude la pagina, dovrà fare di nuovo il login.

Ora il nostro AuthStore è pronto! Passiamo alla classe che collega tutto insieme: l’AuthService!

AuthService

AuthService è la classe che contiene la logica di business per far funzionare l’autenticazione. Vediamo il codice:

import { Injectable } from '@angular/core';
import { Observable } from 'rxjs';
import { map, switchMap, tap } from 'rxjs/operators';
import { AuthClient, IRefreshRequest } from './auth-client.service';
import { AuthStoreService } from './auth-store.service';
import { ILogin } from './model/Login';
import { ILoginResponse } from './model/LoginResponse';
import { Router } from '@angular/router';

@Injectable({
  providedIn: 'root'
})
export class AuthService {
  constructor(
    private authClient: AuthClient,
    private authStore: AuthStoreService,
    private router: Router,
  ) { }

  login(request: ILogin): Observable<ILoginResponse> {
    return this.authClient.login(request)
      .pipe(
        tap(loginResponse => this.authStore.login(loginResponse)),
      );
  }

  refresh(refreshTokenRequest: IRefreshRequest): Observable<ILoginResponse> {
    return this.authClient.refreshToken(refreshTokenRequest)
      .pipe(
        tap(refreshResponse => this.authStore.refresh(refreshResponse))
      );
  }

  logout(): void {
    this.authStore.logout();
    this.router.navigateByUrl('/auth/login');
  }
}

Questa classe usa sia AuthClient, per effettuare le chiamate API, sia AuthStore, per persistere le credenziali. Ci sono tre metodi che possiamo chiamare:

login: lo chiamiamo quando vogliamo che l’utente faccia il login. Chiama l’API di login e poi persiste le credenziali in AuthStore.
refresh: usato per aggiornare il token. Effettua le chiamate API e poi le persiste.
logout: svuota l’AuthStore e poi porta l’utente alla pagina di login.

Questa è una versione semplificata della mia implementazione. Durante il login ho anche effettuato una chiamata API a un endpoint per ottenere i dati dell’utente (chiamato anche auth/me). Non l’ho aggiunto perché la sua implementazione dipende dalla tua architettura ed è fuori dallo scopo del post. Il punto chiave è questo: dovresti aggiungere tutta la tua logica di business dell’autenticazione qui, delegando la persistenza ad AuthStore e le chiamate API ad AuthClient.

AuthInterceptor

Siamo nell’ultima parte di questo post: possiamo autenticare l’utente e persistere le credenziali nell’AuthStore. Possiamo aggiornare il token quando scade. Possiamo fare il logout dell’utente.

Ora ci concentriamo su questi obiettivi:

Non passare il token quando chiamiamo un’API pubblica.
Passare il token JWT durante le chiamate API autenticate.
Aggiornare il token quando l’accessToken scade. Sappiamo che il token scade solo quando effettuiamo qualche chiamata API: quindi quando una chiamata API fallisce, perché il token è scaduto, dobbiamo chiamare l’API di refresh per ottenere il nuovo token, poi dobbiamo rifare la prima chiamata con il token aggiornato.

Tutte queste cose sono gestite dall’AuthInterceptor. È una sottoclasse dell’HTTP Interceptor di Angular. In breve, un HTTP Interceptor è uno strato che possiamo aggiungere tra la chiamata API che effettuiamo e la vera HTTP Request fatta dal browser. In questo modo possiamo iniettare trasparentemente tutti questi comportamenti di autenticazione senza modificare le nostre classi Client.

Capire l’HTTP Interceptor

Prima di tutto, dobbiamo capire come implementare un HTTP Interceptor: AuthInterceptor dovrebbe implementare l’interfaccia HttpInterceptor. Quindi dobbiamo implementare il metodo

intercept(request: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>>

Il primo parametro è la richiesta HTTP che Angular sta per effettuare. Alla fine della nostra logica, dobbiamo chiamare next.handle(request) per continuare la richiesta HTTP attraverso il flusso normale. In altre parole, assumiamo di creare un HTTP interceptor che non fa assolutamente nulla. Il codice minimo che dobbiamo scrivere è questo

@Injectable()
export class NoOpInterceptor implements HttpInterceptor {

    constructor() { }

    intercept(request: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
      return next.handle(request);
    }
}

Implementazione di AuthInterceptor

Ora facciamo la stessa cosa per il nostro AuthInterceptor, ma questa volta dobbiamo aggiungere tutta la logica di autenticazione di cui abbiamo parlato prima.

Diamo un’occhiata alla sua implementazione:

import { AuthStoreService } from './auth-store.service';
import { HttpInterceptor, HttpRequest, HttpHandler, HttpEvent, HttpErrorResponse } from '@angular/common/http';
import { Observable } from 'rxjs';
import { Injectable } from '@angular/core';
import { tap, mergeMap, catchError } from 'rxjs/operators';
import { AuthService } from './auth.service';
import { INTERCEPTOR_NO_AUTH_HEADER } from './constants';

@Injectable()
export class AuthInterceptor implements HttpInterceptor {

    constructor(
        private authStore: AuthStoreService,
        private authService: AuthService,
    ) { }

    intercept(request: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
        /* Se la richiesta in arrivo ha lo speciale INTERCEPTOR_NO_AUTH_HEADER,
           significa che non dobbiamo aggiungere il token JWT
        */
        if (request.headers.get(INTERCEPTOR_NO_AUTH_HEADER)) {
            /* Quindi invia semplicemente al prossimo handler la stessa richiesta
               rimuovendo lo speciale header INTERCEPTOR_NO_AUTH_HEADER
            */
            return next.handle(request.clone({
                headers: request.headers.delete(INTERCEPTOR_NO_AUTH_HEADER)
            }));
        }
        // Se l'utente ha fatto il login
        if (this.authStore.isLoggedIn) {
            return next
                // Allora aggiungi il token e continua la chiamata API.
                .handle(this.addTokenToRequest(request))
                .pipe(
                    // Ma se la chiamata è fallita, prova a recuperarla usando il metodo retryWhenExpiredToken
                    catchError(this.retryWhenExpiredToken(request, next)),
                    tap({
                        error: (err: HttpErrorResponse) => {
                            /*
                              Se la chiamata, dopo il nostro metodo di refresh, sta ancora fallendo con
                              lo status code 401 UNAUTHORIZED
                            */
                            if (err.status === 401) {
                                // Allora fai il logout dell'utente, non possiamo fare altro.
                                this.authService.logout();
                            }
                        }
                    }),
                );
        }
        /*
          Se l'utente non ha fatto il login, non fare nulla.
          Non abbiamo nessun token JWT da allegare alla richiesta
        */
        return next.handle(request);
    }

    // Questo metodo viene chiamato solo durante una risposta di errore
    private retryWhenExpiredToken(req: HttpRequest<any>, next: HttpHandler): (response: any) => Observable<any> {
        return response => {
            const refreshToken = this.authStore.refreshToken;
            /* Se lo status code è 401 UNAUTHORIZED e non abbiamo il refresh token,
               oppure lo status code è diverso da 401 UNAUTHORIZED
            */
            if (response.status === 401 && !refreshToken || response.status !== 401) {
                // Non possiamo fare nulla, rilancia semplicemente l'errore e continua.
                throw response;
            }

            // Altrimenti, chiama il backend per aggiornare il nostro token
            return this.authService
                .refresh({ refreshToken })
                .pipe(
                    // Poi richiama la richiesta fallita con il token appena aggiornato
                    mergeMap(() => {
                        return next.handle(this.addTokenToRequest(req));
                    }),
                );
        };
    }

    // Clona semplicemente la richiesta, aggiungendo il token JWT alla richiesta
    private addTokenToRequest(request: HttpRequest<any>): HttpRequest<any> {
        return request
            .clone({
                setHeaders: {
                    'X-JWT-TOKEN': this.authStore.accessToken,
                }
            });
    }
}

Prenditi il tuo tempo per leggerlo… Vediamo che il metodo intercept è più complesso. Ho aggiunto tantissimi commenti nel codice, così è più facile capire cosa succede.

Vediamo se abbiamo raggiunto tutti i nostri obiettivi prefissati:

Non passare il token quando chiamiamo un’API pubblica: fatto tramite lo speciale header INTERCEPTOR_NO_AUTH_HEADER.
Passare il token JWT durante le chiamate API: fatto grazie al metodo addTokenToRequest.
Aggiornare il token quando l’accessToken scade: ottenuto tramite il metodo retryWhenExpiredToken.

Il codice non è così lungo, ha più o meno 50 righe. Ma penso che sia abbastanza pieno di concetti complicati di RxJS come mergeMap, tap, catchError.

Ho usato una closure per far funzionare retryWhenExpiredToken. Ho creato una funzione che restituisce una funzione. La prima chiamata ottiene la richiesta originale e l’handler next e restituisce la funzione che passiamo al metodo catchError.

Scrivere questo codice senza bug in un colpo solo è molto difficile, anche se non è lungo. Due cose mi hanno aiutato a raggiungerlo:

Uso massiccio del sistema di tipi di TypeScript: TypeScript aggiunge i tipi a JS, grazie al cielo! Aggiungere i tipi a tutto è il modo migliore per evitare bug fastidiosi. Il transpiler può avvisarti il prima possibile se stai restituendo qualcosa di sbagliato. Se metti any ovunque, o non aggiungi i tipi per i parametri attesi, sei da solo! Il transpiler non può aiutarti, prima o poi farai un errore. L’unico any che vedi in questo codice è perché la firma di intercept viene da Angular e non posso farci nulla.
Usa il Test Driven Development (TDD) per la parte cruciale del tuo sistema, o usa il TDD il più possibile. Testare manualmente questo sistema di autenticazione richiede molto più tempo che scrivere qualche unit test. E non c’è niente di peggio di qualcuno che ti chiama dicendo che gli utenti non riescono ad accedere. L’ho fatto usando il TDD e il risultato sono queste piccole classi facili da testare grazie alla suite di testing di Angular.

Lo sviluppatore perfetto, che non fa bug, non esiste. Alcuni sviluppatori sono migliori di altri non perché sono perfetti, ma perché prendono più contromisure per evitare bug, quindi scrivono codice meno buggato. TypeScript e il TDD sono le contromisure più efficaci che conosco per lo sviluppo frontend. Quindi usali.

Se sei interessato al TDD, ho scritto due articoli sull’argomento. Li trovi qui:

Aggiungere AuthInterceptor all’app Angular

Dobbiamo ricordarci di aggiungere l’AuthInterceptor alla nostra applicazione. È molto facile: dobbiamo dichiararlo nel modulo Angular root dell’app

import { HTTP_INTERCEPTORS } from '@angular/common/http';
import { AuthInterceptor } from './auth/auth-interceptor';

@NgModule({
  declarations: [...],
  imports: [
    AuthModule,
    ...
  ],
  bootstrap: [AppComponent],
  providers: [
    { provide: HTTP_INTERCEPTORS, useClass: AuthInterceptor, multi: true },
    ...
  ]
})
export class AppModule { }

E questo è tutto! Ora la nostra app gestisce l’autenticazione JWT del nostro backend!

Conclusione

Spero che tu ti sia goduto questo viaggio sull’autenticazione JWT + Angular. Questa è la mia implementazione, e ha soddisfatto tutti i miei obiettivi. Spero che questo lavoro ti ispiri a raggiungere i tuoi!

Alla prossima!

Benvenuti nel nuovo blog!

Sun, 25 Aug 2019 07:03:47 GMT

Eccoci qui, con un nuovo blog scintillante!

Ho deciso di creare un altro blog personale. Ma questo è diverso dal mio precedente.

È in inglese.

Scrivevo in italiano dato che sono italiano! Ma mi sono reso conto che per i post tecnici la lingua preferita è l’inglese.

Non è un cambio facile per me, perché amo l’Italia e volevo diffondere un po’ di conoscenza nella mia lingua madre. Ma scrivendo post in italiano raggiungo una nicchia di una nicchia… Non so quanto sia utile.

Un’altra grande ragione è che tutti i riferimenti che collego nei miei post erano in inglese! Quindi anche un lettore italiano dovrebbe conoscere l’inglese per capire bene il contenuto.

Riguarda il mio lavoro

Il mio blog precedente era più personale, è nato senza un’idea fissa su cosa ci avrei scritto. Infatti era più un esercizio su come distribuire un blog Ghost e come costruire un sito Gatsby. I contenuti al suo interno sono più misti: dalla fotografia, ai giochi, ai post tecnici.

In questo blog voglio condividere con voi i miei pensieri sul mio lavoro quotidiano, su come ho affrontato qualche compito impegnativo, o semplicemente su cosa faccio al lavoro.

Voglio condividere contenuti utili per altri sviluppatori.

Spero di avere il tempo di condividere queste cose e spero che vi piacciano!

Impariamo ad automatizzare con Ansible · DevOps

Sun, 25 Aug 2019 07:03:47 GMT

Introduzione

Siete al lavoro e avete il compito di configurare 20 macchine virtuali tutte allo stesso modo? Siete a casa e avete il vostro Raspberry Pi che purtroppo ha corrotto l’SD card e quindi dovete riconfigurarlo per l’ennesima volta? Allora Ansible potrebbe risolvere molti dei vostri problemi!

Se siete come me sono certo che non vi piace passare la giornata ad eseguire task ripetitivi che danno praticamente zero valore aggiunto a voi stessi: eseguire task ripetitivi non è un compito da far svolgere a noi umani, possiamo benissimo delegarlo alle macchine per poterci dedicare a cose che veramente contano.

Come facciamo ad automatizzare questi task? Una risposta sicuramente efficace è Ansible, lo strumento di configurazione che preferisco.

Obiettivo

Se avete avuto di leggere la documentazione ufficiale di Ansible, sono certo che avrete notato che è tanto noiosa quanto è potente il tool stesso. È facile che vi addormentiate a leggerla ancor prima di capire le reali potenzialità di Ansible.

Ecco che allora ho deciso di scrivere questa mini guida sperando che sia un po’ più efficace. Spero di raggiungere questo obiettivo tramite un esempio concreto che è mi è capitato e che utilizzo tutt’ora: andremo a configurare un VPN Server su un Raspberry Pi.

Grazie a questo playbook di Ansible, possiamo creare un VPN Server su un Raspberry Pi lanciando un unico comando ansible-playbook -vv -i hosts vpn.yml. Le funzioni che esegue sotto le quinte sono molte:

Scarica il certificato tramite https://letsencrypt.org/ del dominio che sta puntando a casa nostra, per esempio casamia.mattianatali.it.
Imposta il rinnovo automatico del certificato stesso.
Apre le porte corrette sul Raspberry Pi per far funzionare la VPN.
Installa tutte le librerie ed applicazioni necessarie per installare il VPN Server.
Configura correttamente le impostazioni che decidiamo noi per la VPN, per esempio l’utente per accedervi.
Imposta l’aggiornamento automatico dei certificati in base al rinnovo del certificato di Let’s Encrypt.

Immaginate ora se non avessimo avuto Ansible che facesse tutte queste cose con un comando. Sicuramente dopo 2 giorni che ho eseguito manualmente questi comandi mi sarei già dimenticato tutto, senza contare il numero di tentativi che avrei dovuto fare anche la seconda volta per riconfigurare tutto da zero. Proprio per questo, una volta che ho capito come potevo fare, ho creato lo script Ansible. Ora ho in una repository pubblica il playbook versionato e pronto all’uso.

In questa guida non ci soffermeremo troppo sui dettagli della VPN: a noi interessano di più i ragionamenti che ci sono stati per arrivare a questo risultato e quali funzionalità di Ansible abbiamo utilizzato. La creazione della VPN è solo un esempio concreto che copre molte funzionalità di Ansible.

Requisiti

I requisiti per seguire questa guida sono i seguenti:

Abbiamo un minimo di conoscenze di linux. I comandi sudo, apt-get install, cd, chmod, ssh dovrebbero esserci familiari.
Abbiamo installato sul vostro portatile Ansible.
Il nostro Raspberry Pi deve avere SSH abilitato.

Glossario

Il primo scoglio che si incontra con Ansible è imparare e ricordarsi i vari termini che utilizza. Qui un piccolo riassunto che ci aiuterà nel corso della guida:

Moduli: i moduli sono dei piccoli programmi che Ansible ci offre per portare a termine i task. Per esempio: vogliamo installare un pacchetto tipo vim? Possiamo usare il modulo apt, vogliamo aggiungere un cronjob? C’è il modulo cron. Ce ne sono davvero un’infinità.
Task: per esempio un task è “installa il programma nginx”. Possiamo vederli come l’unità più piccola che abbiamo in Ansible, sostanzialmente è il richiamo di un modulo con i vari parametri. Un esempio di task è il seguente
```
- name: Install nginx
    apt: 
      name:
        - nginx
```
Ruolo: Ansible spiega il ruolo usando una metafora calcistica. Un esempio di ruolo può essere “attaccante”, “difensore”, “centrocampista”. Calando nel nostro esempio abbiamo due ruoli: “installatore del certificato”, “installatore della VPN”. Insomma è un insieme di tasks che hanno una funzione ben precisa, un ruolo appunto.
Playbook: è l’unità più grande che abbiamo in Ansible. Un playbook organizza i vari ruoli per portare a termine il nostro compito. Per esempio nel nostro caso è l’insieme dei due ruoli precedentemente spiegati. La mia repository sulla creazione della VPN è appunto un playbook. Nel nostro caso avremo un playbook che svolgerà il nostro compito, ossia installare la VPN con i vari certificati.
Inventory: È un file che contiene al suo interno dei gruppi che a loro volta contengono delle macchine. Queste macchine sono quelle che verranno influenzate dalla nostro playbook. Ansible è molto potente, con un solo comando potete installare la VPN su 100 macchine. Noi avremo un gruppo chiamato vpns che al suo interno avrà definito la nostra macchina target di nome rpi (il Raspberry Pi).

Ora abbiamo una terminologia comune, non è necessario capire tutto ora, sicuramente è ancora tutto molto fumoso. Ma più avanti, dopo aver visto un esempio concreto, sarà tutto più chiaro.

Eseguiamo il task manualmente

Prima di automatizzare dobbiamo aver chiaro cosa dobbiamo fare, la prima volta magari non abbiamo proprio le idee chiare, facciamo molti tentativi e alcuni finiranno in un nulla di fatto. Quindi la prima cosa da fare è provare manualmente senza scomodare Ansible così da essere più veloci nella fase di “costruzione” dei vari task per raggiungere l’obiettivo. Nel nostro caso ci facciamo prima un po’ di cultura sulla VPN, leggiamo come funziona strongswan, che librerie ha bisogno per funzionare, come configurarlo ecc. Poi ci facciamo una cultura su Let’s Encrypt per rilasciare un certificato valido per il nostro dominio casamia.mattianatali.it che punta a casa nostra, in modo tale da avere il punto di accesso alla nostra VPN.

Tutta questa fase ve la risparmio, la cosa che dobbiamo tenere a mente è questa: durante la fase manuale teniamo a mente ogni passaggio che svolgiamo per portare a termine il nostro compito, ogni singolo file di configurazione che abbiamo modificato, qualsiasi cosa dobbiamo tenerne traccia perché fra poco la automatizzeremo.

Definiamo i ruoli

Una volta raggiunto l’obiettivo manualmente, è tempo di organizzare le idee. Alla fine della nostra analisi il nostro playbook di Ansible deve eseguire i seguenti task:

Scarica il certificato tramite https://letsencrypt.org/ del dominio che sta puntando a casa nostra, per esempio casamia.mattianatali.it.
Imposta il rinnovo automatico del certificato stesso.
Apre le porte corrette sul Raspberry Pi per far funzionare la VPN.
Installa tutte le librerie ed applicazioni necessarie per installare il VPN Server.
Configura correttamente le impostazioni che decidiamo noi per la VPN, per esempio l’utente per accedervi.
Imposta l’aggiornamento automatico dei certificati in base al rinnovo del certificato di Let’s Encrypt.

Di tutti questi task possiamo trovare due ruoli ben distinti che possono essere separati.

La generazione e il mantenimento dei certificati per casamia.mattianatali.it usando Let’s Encrypt.
Installazione della VPN che utilizza i certificati precedentemente creati.

Che vantaggi porta separare i task trovati in questi due ruoli?

Più i ruoli sono autocontenuti e specifici, più sono semplici da mantenere.
Più sono autocontenuti più è facile riutilizzarli per altri playbook.
Se il ruolo definito è abbastanza standard, è facile che qualcuno lo abbia già implementato!

Infatti Ansible ha un sito per cercare questi ruoli: si chiama Ansible Galaxy. La generazione dei certificati tramite Let’s Encrypt è una cosa abbastanza standard, ed infatti siamo fortunati! Abbiamo un ruolo che fa già quello che ci interessa, lo possiamo trovare qui, il modo migliore per imparare ad usarlo è comunque guardare il suo repository su GitHub.

Per installare il ruolo, per poterlo utilizzare fra poco, scriviamo in console:

ansible-galaxy install geerlingguy.certbot

Cercando sempre su quel sito non ho trovato un ruolo che crei la VPN, quindi per quello dobbiamo arrangiarci.

Definiamo il Playbook

Abbiamo detto che i moduli e i task sono la parte atomica di Ansible, questi sono raggruppati in ruoli che svolgono una determinata funzione (nel nostro caso sono due), l’entità che orchestra questi ruoli è il playbook. Se volessimo raffigurarlo in un grafico:

playbook
  ruoli
    tasks

Per creare la configurazione della nostra VPN adottiamo un approccio top-down. In altre parole iniziamo a lavorare sulla parte più “esterna” e generale al problema, per poi entrare sempre più nel dettaglio fino ai vari task. La parte che contiene tutte le altre è il playbook. Il nostro playbook deve far partire in sequenza:

Il ruolo che genera i certificati. Già implementato grazie alla libreria che abbiamo trovato su Ansible Galaxy
Il ruolo che installa la VPN. Dobbiamo implementarlo.

Ansible lavora molto sulle convenzioni, iniziamo fin da subito ad utilizzare le best practices fornite da Ansible.

Possiamo prendere come riferimento la mia repository con il playbook finalizzato. La struttura per creare il nostro playbook è il seguente:

group_vars/
  vpns.yml           # Qui vanno tutte le variabili a livello di gruppo (il nostro gruppo si chiama vpns)
   
host_vars/
   rpi.yml           # Qui assegnamo le variabili per le singole macchine (l'unica nostra macchina si chiama rpi)

vpn.yml              # Questo è il nostro playbook
hosts                # È il nostro inventory, definiamo i gruppi (vpns) e le macchine (rpi) su cui vogliamo eseguire il playbook.

roles/               # Questa cartella contiene tutti i ruoli che andremo a definire
    vpn-install/     # Questa cartella contiene il nostro ruolo per installare la VPN.
      ...            # La struttura delle sottocartelle la vedremo più avanti.

Iniziamo a scrivere il nostro playbook nel file vpn.yml

---
- name: Deploy IKEv2 Road Warrior VPN
  hosts: vpns

  roles:
    - role: geerlingguy.certbot
      become: yes
    - role: vpn-install
      become: yes

Il formato con cui viene scritto il file è YAML, è un formato molto leggibile ed è ormai uno standard de facto negli applicativi che strizzano l’occhio ai DevOps. Se non lo avete mai visto vi consiglio di leggere questa guida, che spiega velocemente il formato.

Il nostro Playbook dovrà fare solo una cosa: creare un VPN Server. Nel gerco di Ansible, un playbook è formato da più plays. Noi abbiamo un solo play nel nostro playbook.

Come si fa a capire come e quando creare un play? Solitamente se abbiamo più ruoli che influenzano un unico gruppo di macchine, allora questo è un buon candidato per essere un play. Se invece avessimo avuto dei ruoli che avevano come target il Raspberry ed altri ruoli che dovevano configurare dei routers, allora il nostro playbook sarebbe composto da due plays. Perché un play andava a lavorare sui Raspberry Pi, l’altro sui routers.

Spieghiamo i vari comandi che ci sono dentro ad un play:

name: possiamo inserire una breve descrizione di cosa farà il nostro play.
hosts: definiamo quale gruppo verrà utilizzato come target del nostro play. Nel nostro caso è il gruppo vpn, che al suo interno avrà il nostro Raspberry Pi.
roles: definiamo i ruoli in ordine cronologico che verranno avviati sui nostri hosts.
role: geerlingguy.certbot: il primo ruolo che verrà avviato sarà quello che abbiamo trovato in Ansible Galaxy, esso installerà e manterrà aggiornati i certificati per la VPN.
become: yes: significa che verrà avviato lo script abilitando il priviledge escalation. In pratica avvieremo il ruolo come root. Sia il ruolo per scaricare i certificati, sia l’installazione della VPN ha bisogno di essere avviato come root. Quindi in entrambi metteremo become: yes.
role: vpn-install: avviamo l’installazione della VPN dopo il ruolo dei certificati. Questo ruolo dobbiamo ancora capire come definirlo.

Il playbook lo abbiamo ultimato. In pratica il nostro playbook sta dicendo questa cosa: “Installa i certificati e poi installa la VPN sulle macchine che fanno parte del gruppo vpns“.

Definiamo l’inventario

Abbiamo detto che il playbook lavorerà sul gruppo di macchine denominato vpns. Ma dove è definito questo gruppo? Qui entra in gioco l’inventario. L’oggetto inventario è dove definiamo i gruppi di macchine e le macchine che compongono questo gruppo. Il file che contiene questo inventario è il file hosts. Il nome è arbitrario, qualsiasi nome gli diamo poi dovrà essere richiamato quando invocheremo il comando per far partire il playbook.

Il nostro file hosts avrà questo contenuto.

[vpns]
rpi

Semplicemente con queste due righe stiamo dicendo che il gruppo vpns contiene la macchina rpi che è il nome che stiamo dando al nostro Raspberry Pi. È facile intuire che se avessimo avuto più Raspberry Pi, potevamo configurarli contemporaneamente definendoli in questo file nel gruppo vpns.

La sintassi dell’inventario è semplice ed è questa

[gruppo1]
macchina1
macchina2

[gruppo2]
macchina3
macchina4

...

Definiamo le variabili di gruppo e di host

Abbiamo definito il playbook che lavora sul gruppo vpns, abbiamo dichiarato il gruppo vpns dicendo che al suo interno ha il nostro Raspberry Pi con il nome rpi tramite l’inventario. Ma Ansible come fa a sapere come connettersi al nostro Raspberry Pi? Come gli forniamo l’IP, utente, password per connettersi con SSH? Come gli diciamo su quale dominio vogliamo ottenere i certificati? Per ora sa solo che c’è una macchina chiamata rpi.

Tutte queste cose sono delle variabili, variano in base alla macchina o al gruppo di macchine su cui vogliamo agire. Ansible ha due cartelle adibite a questo scopo, una cartella chiamata group_vars conterrà le variabili che sono comuni a tutte le macchine che appartengono ad un gruppo, la cartella host_vars conterrà tutte le variabili che sono proprie ad una singola macchina.

Nel nostro progetto possiamo inserire queste due cartelle, queste cartelle avranno dei file YAML che avranno il nome del nostro gruppo in group_vars e il nome rpi.yml in host_vars.

Quindi la struttura delle nostre cartelle, per quanto riguarda le variabili è il seguente:

group_vars/
  vpns.yml           # Contiene tutte le variabili comuni a tutte le macchine che appartengono al gruppo vpns
   
host_vars/
   rpi.yml           # Contiene tutte le variabili che appartengono alla macchina rpi

All’interno del file rpi.yml definito nella cartella host_vars, Ansible potrà trovare tutte le informazioni di cui necessita per portare a termine il playbook. Il file rpi.yml contiene le seguenti variabili:

---
ansible_host: YOUR-SSH-HOST
ansible_user: pi
ansible_password: YOUR-SSH-PASSWORD
domain: casamia.mattianatali.it
# You can add more than one Road Warrior Client.
vpn_users:
  - username: CLIENT-WARRIOR-USERNAME
    password: CLIENT-WARRIOR-PASSWORD
# Change it if you want to restrict the local hosts the Road Warrior Client should see.
vpn_local_ts: "0.0.0.0/0"

# ansible-role-certbot variables
# More info here https://github.com/geerlingguy/ansible-role-certbot
certbot_auto_renew: true
certbot_create_if_missing: true
certbot_create_method: standalone
certbot_auto_renew_user: root
certbot_auto_renew_hour: 3
certbot_auto_renew_minute: 30
certbot_auto_renew_options: "--quiet --no-self-upgrade"
certbot_create_standalone_stop_services: []
certbot_certs:
  - email: YOUR-EMAIL-HERE
    domains:
      - "{{domain}}"

Tramite le variabili ansible_host, ansible_user, ansible_password possiamo fornire ad Ansible tutte le informazioni per connettersi ad SSH, per eseguire il nostro playbook. Possiamo evitare di inserire nome utente e password usando le configurazioni di SSH. In questa guida, nella sezione SSH, spiego come fare.

I campi successivi sono quelli che utilizzeremo quando andremo a creare il ruolo per installare la VPN. Il campo domain conterrà il nome del nostro dominio che punta a casa nostra, nel nostro caso è casamia.mattianatali.it. In vpn_users definiamo l’username e password dei clienti che possono connettersi alla nostra VPN. vpn_local_ts è una variabile che ci permette di limitare l’accesso ai clienti che si connettono alla VPN, per esempio a casa mia ho limitato alla mia sottorete 192.168.1.0/24.

Tutte le variabili che iniziano con certbot_ fanno parte del ruolo che abbiamo scaricato con Ansible Galaxy, ci permettono di configurare qualsiasi cosa riguardo l’aggiornamento dei certificati per il dominio casamia.mattianatali.it. Trovare le variabili che compongono il ruolo che abbiamo scaricato è semplice, basta leggere la documentazione del ruolo che abbiamo utilizzato.

Possiamo notare che l’ultima riga del nostro file ha una variabile particolare {{domain}}. Le doppie graffe ci permettono di richiamare un’altra variabile già definita. In questo modo possiamo definire solo la variabile domain nella quarta riga, che automaticamente la variabile {{domain}} avrà lo stesso valore. Così facendo abbiamo “una singola sorgente di verità” ed evitiamo errori grossolani tipo aggiornare solo una variabile e non l’altra.

Per inserire i valori nelle doppie graffe, Ansible utilizza un template engine molto famoso in Python: Jinja2. Jinja2 è molto potente, per ora ci basta sapere che quando scriviamo {{valore}} significa che stiamo inserendo il contenuto della variabile che troviamo nelle parentesi.

Implementiamo il ruolo per installare la VPN

Abbiamo definito il playbook, l’inventario, le variabili e il ruolo per installare i certificati che abbiamo trovato su Ansible Galaxy; ora ci manca da implementare il ruolo che installa il VPN server sul Raspberry Pi.

I ruoli vengono definiti nella cartella roles/, creiamo una cartella al suo interno che prenderà il nome del ruolo (vpn-install), lo stesso nome che abbiamo definito nel playbook in vpn.yml. La struttura delle nostre cartelle sarà definita così:

...
roles/    
    vpn-install/
        files/        # Contiene i file da copiare sul Raspberry Pi
            ...
        tasks/        # Contiene le istruzioni da eseguire
            ...
        templates/    # Contiene i template sorgenti per poi caricare sul Raspberry Pi
            ...

Anche in questo caso stiamo usando le convenzioni di Ansible, non ci stiamo inventando nulla:

files: contiene tutti i file che dobbiamo caricare sul Raspberry Pi.
tasks: contiene i task da eseguire sul Raspberry Pi per installare la VPN.
templates: è simile alla cartella files, ma in questo caso non avremo i file da copiare, bensì un template che dobbiamo renderizzare prima di poterlo copiare sul Raspberry Pi. Aspettiamo ancora un attimo e poi il suo utilizzo sarà chiaro.

Definiamo i task

Ora ci focalizziamo sulla cartella tasks, come abbiamo detto qui avremo tutti i comandi da eseguire sul Raspberry Pi per installare la VPN. Il primo file che Ansible cerca nella cartella tasks è il main.yml. In questo file scriviamo tutti i task.

Come sappiamo quali task eseguire? Qui dobbiamo recuperare i comandi che abbiamo eseguito manualmente all’inizio dell’articolo. Una volta recuperati li dobbiamo tradurre in task, utilizzando i moduli che ci fornisce Ansible.

Questi sono i “comandi” che dobbiamo tradurre in task Ansible, prendeteli per buoni, non voglio annoiarvi troppo sulla questione VPN:

Installa i seguenti pacchetti usando apt-get: strongswan, strongswan-swanctl, libstrongswan-standard-plugins, libstrongswan-extra-plugins, libcharon-extra-plugins.
Attivare l’Ip-Forwarding.
Aggiungere il file con la configurazione VPN in /etc/swanctl/swanctl.conf.
Aggiungere il file con i vari plugin di Strongswan in /etc/strongswan.conf.
Creare le cartelle x509, x509ca, private in /etc/swanctl/, qui aggiungeremo i vari certificati creati dal ruolo precedente che abbiamo trovato su Ansible Galaxy.
Copiare i certificati creati dal ruolo che li crea dalla cartella /etc/letsencrypt/live/casamia.mattianatali.it/ nelle cartelle corrette create nel punto precedente.
Aggiungere uno script che ripete il punto precedente ogni volta che i certificati vengono aggiornati. I certificati di Let’s Encrypt durano solo 3 mesi.
Aggiungere un cronjob che esegue il punto precedente subito dopo la generazione dei certificati.
Abilitare l’IP Masquerading, cambiando le regole del firewall del Raspberry Pi.
Riavviare il Raspberry Pi.

Queste sono tutte le operazioni che dobbiamo automatizzare per avere la nostra VPN funzionante sul Raspberry Pi. Le operazioni sono tante, alcune complesse, noiose da fare manualmente, la possibilità di errore è alta, i comandi sono praticamente impossibili da ricordare a memoria per una futura configurazione. Forse ora capite perché ho subito pensato ad Ansible quando mi sono cimentato in questa impresa!

Con Ansible possiamo fare tutto questo con poche righe di codice e con una chiarezza disarmante. Il risultato finale del nostro file main.yml, che include tutti i nostri comandi è il seguente. Ho aggiunto dei commenti nel file così da avere la giusta corrispondenza coi punti scritti appena sopra:

---
# Installa i seguenti pacchetti usando `apt-get`: `strongswan`, `strongswan-swanctl`, `libstrongswan-standard-plugins`, `libstrongswan-extra-plugins`, `libcharon-extra-plugins`.
- name: Install strongswan dependencies
  apt: 
    name:
      - strongswan
      - strongswan-swanctl
      - libstrongswan-standard-plugins
      - libstrongswan-extra-plugins
      - libcharon-extra-plugins

# Attivare l'Ip-Forwarding.
- name: Add Client Traffic Forwarding
  sysctl:
    name: "{{ item }}"
    value: 1
  with_items:
    - net.ipv4.ip_forward
    - net.ipv6.conf.all.forwarding

# Aggiungere il file con la configurazione VPN in /etc/swanctl/swanctl.conf
- name: Add VPN configuration
  template:
    src: templates/swanctl.conf.j2
    dest: /etc/swanctl/swanctl.conf

# Aggiungere il file con i vari plugin di Strongswan in /etc/strongswan.conf
- name: Add strongswan.conf with correct plugins
  copy:
    src: files/strongswan.conf
    dest: /etc/strongswan.conf

# Creare le cartelle x509, x509ca, private in /etc/swanctl/
- name: Create folders to store certificates
  file:
    path: /etc/swanctl/{{ item }}
    state: directory
    mode: 0755
  with_items:
    - x509
    - x509ca
    - private

# Copiare i certificati creati dal ruolo che li crea dalla cartella /etc/letsencrypt/live/casamia.mattianatali.it/ nelle cartelle corrette create nel punto precedente
# Notare l'uso della variabile domain per inserire casamia.mattianatali.it
- name: Copy certificates from let's encrypt to strongswan
  shell: |      # In YAML il "|" significa "prendi tutto quello che scrivo dopo come una variabile e preserva i ritorni a capo"
    cp /etc/letsencrypt/live/{{ domain }}/chain.pem /etc/swanctl/x509ca/
    cp /etc/letsencrypt/live/{{ domain }}/privkey.pem /etc/swanctl/private/
    cp /etc/letsencrypt/live/{{ domain }}/fullchain.pem /etc/swanctl/x509/

# Aggiungere uno script che ripete il punto precedente ogni volta che i certificati vengono aggiornati
- name: Add script to copy new certificate
  template:
    src: templates/renew-certs.sh.j2
    dest: /root/renew-certs.sh
    mode: u=rwx,g=r,o=r

# Aggiungere un cronjob che esegue il punto precedente subito dopo la generazione dei certificati
- name: Add cronjob to copy new certs
  cron:
    name: Copy certs to strongswan
    hour: "{{ certbot_auto_renew_hour }}"
    minute: "{{ certbot_auto_renew_minute + 15 }}"
    job: "/root/renew-certs.sh"

# Abilitare l'IP Masquerading]
- name: Add iptable rule permanently
  lineinfile:
    path: /etc/rc.local
    line: iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
    insertbefore: ^exit 0

# Riavviare il Raspberry Pi
- name: Finished! Rebooting the system...
  reboot:

Possiamo subito notare che i tasks hanno tutti la seguente struttura

- name: DESCRIZIONE DEL TASK
  NOME_MODULO:
    OPZIONE_1: VALORE_OPZIONE_1
    OPZIONE_2: VALORE_OPZIONE_2

I moduli forniti da Ansible sono tantissimi.

I moduli che ho utilizzato in questo ruolo sono i seguenti:

apt: per installare i pacchetti usando il comando apt-get.
sysctl: per modificare il file sysctl.conf e quindi modificare gli attributi del kernel di sistema. Nel nostro caso è servito per abilitare l’IP Forwarding.
template: per processare un file usando il template engine Jinja2, e copiare il risultato sul Raspberry Pi. Abbiamo bisogno di Jinja2 per inserire un file che sia dinamico in base alle variabili dell’host e del gruppo su cui stiamo lavorando.
copy: per copiare un file da una cartella locale sul nostro Raspberry Pi, in questo caso non abbiamo bisogno di Jinja2 per inserire delle variabili.
file: per lavorare con i file e le cartelle sul Raspberry Pi, per esempio modificare dei permessi, creare o eliminare cartelle ecc.
shell: per eseguire dei comandi classici tramite la cli sulla macchina di destinazione.
cron: per modificare il file crontab sulla macchina.
lineinfile: per verificare che esista una linea specifica in un determinato file.
reboot: per riavviare il Raspberry Pi a fine di tutto.

Le opzioni dei vari moduli sono abbastanza esplicativi, in ogni caso se qualcuno non è chiaro potete leggere la documentazione dei singoli moduli. I nomi dei moduli, nella lista precedente, puntano tutti alla guida di riferimento.

Ci sono alcuni però che meritano una descrizione più approfondita: per esempio il task

# Creare le cartelle x509, x509ca, private in /etc/swanctl/
- name: Create folders to store certificates
  file:
    path: /etc/swanctl/{{ item }}
    state: directory
    mode: 0755
  with_items:
    - x509
    - x509ca
    - private

sono tre tasks in uno, grazie a with_items si può definire una lista di variabili e poi, tramite {{ item }}, è possibile eseguire il modulo per ogni elemento in lista. Quindi nel caso precedente è come se avessimo scritto:

# Creare le cartelle x509, x509ca, private in /etc/swanctl/
- name: Create folder x509
  file:
    path: /etc/swanctl/x509
    state: directory
    mode: 0755
- name: Create folder x509ca
  file:
    path: /etc/swanctl/x509ca
    state: directory
    mode: 0755
- name: Create folder private
  file:
    path: /etc/swanctl/private
    state: directory
    mode: 0755

Vedendo il tag {{ item }} possiamo intuire che il nostro file main.yml viene processato con Jinja2 prima di essere eseguito. Infatti nel nostro file per definire i tasks possiamo fare riferimento a tutte le variabili degli hosts e dei gruppi precedentemente dichiarati. Per esempio il task:

- name: Add cronjob to copy new certs
  cron:
    name: Copy certs to strongswan
    hour: "{{ certbot_auto_renew_hour }}"
    minute: "{{ certbot_auto_renew_minute + 15 }}"
    job: "/root/renew-certs.sh"

Utilizza le variabili certbot_auto_renew_hour e certbot_auto_renew_minute. Jinja2 è molto potente e ci permette anche di fare operazioni con le variabili. Con questo task stiamo essenzialmente dicendo “esegui il comando /root/renew-certs.sh 15 minuti dopo il task che genera i certificati”. Questo è possibile grazie all’operazione {{ certbot_auto_renew_minute + 15 }}.

Il modulo template

Merita una spiegazione aggiuntiva il modulo template dato che è molto potente. Abbiamo detto che il modulo template permette di inserire un file processato con Jinja2 nella macchina di destinazione. Per esempio noi lo abbiamo usato per il task:

- name: Add script to copy new certificate
  template:
    src: templates/renew-certs.sh.j2
    dest: /root/renew-certs.sh
    mode: u=rwx,g=r,o=r

In questo caso prendiamo il file templates/renew-certs.sh.j2, Jinja2 sostituisce le variabili che trova usando quelle che abbiamo definito nelle cartelle group_vars e host_vars e poi lo inserisce nella cartella /root/renew-certs.sh sul Raspberry Pi settando i permessi a 744.

Vediamo velocemente il contenuto del template:

#!/bin/sh -
cp /etc/letsencrypt/live/{{ domain }}/chain.pem /etc/swanctl/x509ca/
cp /etc/letsencrypt/live/{{ domain }}/privkey.pem /etc/swanctl/private/
cp /etc/letsencrypt/live/{{ domain }}/fullchain.pem /etc/swanctl/x509/
/usr/sbin/swanctl --load-all

nel nostro caso domain verrà sostituito da casamia.mattianatali.it prima di essere copiato sul Raspberry Pi.

Un template ancora più complesso possiamo trovarlo con il task

# Aggiungere il file con la configurazione VPN in /etc/swanctl/swanctl.conf
- name: Add VPN configuration
  template:
    src: templates/swanctl.conf.j2
    dest: /etc/swanctl/swanctl.conf

In questo caso templates/swanctl.conf.j2 contiene:

connections {
    ikev2-eap {
        version = 2
        proposals = aes192gcm16-aes128gcm16-prfsha256-ecp256-ecp521,aes192-sha256-modp3072,default
        rekey_time = 0s
        pools = primary-pool-ipv4
        fragmentation = yes
        dpd_delay = 30s
        send_cert = always
        # dpd_timeout doesn't do anything for IKEv2. The general IKEv2 packet timeouts are used.
        local-1 {
            auth = pubkey
            certs = fullchain.pem
            id = {{ domain }}
        }
        remote-1 {
            auth = eap-mschapv2
            # go ask the client for its eap identity.
            eap_id = %any
        }
        children {
            ikev2-eap {
                local_ts = {{ vpn_local_ts }},
                rekey_time = 0s
                dpd_action = clear
                esp_proposals = aes192gcm16-aes128gcm16-prfsha256-ecp256-modp3072,aes192-sha256-ecp256-modp3072,default
            }
        }
    }
}

pools {
    primary-pool-ipv4 {
        addrs = 172.16.252.0/24
        dns = 8.8.8.8, 8.8.4.4
        split_exclude = 172.16.0.0/12
    }
}

secrets {
  {% for user in vpn_users %}
   eap-{{ user.username }} {
      id = {{ user.username }}
      secret = "{{ user.password }}"
   }
  {% endfor %}
}

Qui verranno sostituite le variabili domain, vpn_local_ts. Grazie al costrutto {% for user in vpn_users %} e {% endfor %} inseriamo gli username e password degli utenti presenti nella variabile vpn_users che abbiamo definito in nel file host_vars/rpi.yml.

Immaginiamo ora di non avere un template engine e di dover far manualmente questa operazione… Non è per niente banale! Grazie ad Ansible possiamo separare nettamente le variabili dal contenuto statico dei file, in questo modo possiamo rendere molto semplice la configurazione personalizzata su più macchine. Infatti il contenuto del ruolo rimarrebbe sempre uguale, quello che cambia è l’inventario, dove definiamo la nuova macchina da configurare e le sue variabili da utilizzare in host_vars.

Esecuzione del playbook

Abbiamo finalmente completato il nostro Playbook per creare un VPN sul nostro Raspberry Pi! Il risultato finale lo potete trovare sulla mia repository. Ci manca solamente da eseguire il nostro playbook attraverso il comando

ansible-playbook -vv -i hosts vpn.yml

Grazie a questo comando, avviamo il playbook definito in vpn.yml in modo verboso (-vv) passando l’inventario definito nel file hosts (-i hosts). Vedremo che Ansible cercherà di connettersi tramite SSH al nostro Raspberry Pi ed eseguirà punto per punto i nostri task, usando tutte le variabili che abbiamo definito in host_vars e group_vars. In meno di 2 minuti avrà finito di fare il tutto e noi possiamo connetterci alla VPN mettendo come indirizzo del server e il suo id il dominio che abbiamo definito (nel mio caso casamia.mattianatali.it) e come username e password quelli inseriti nella variabile vpn_users nel file host_vars/rpi.yml.

Alla fine ci manca di fare il port forwarding delle porte della VPN dal router al Raspberry Pi, questa parte non l’ho automatizzata con Ansible perché i router sono tutti diversi tra di loro, se volete avere la VPN completa vi consiglio di leggere il README del mio repository.

Conclusioni

Spero che questa guida vi abbia fornito delle linee guida su come automatizzare task anche complessi usando Ansible. Ho sorvolato di proposito parecchi punti che erano strettamente legati alla creazione della VPN, questo perché lo scopo della guida è di mostrarvi le potenzialità di Ansible con un esempio che non fosse il semplice “Hello World”.

Quello che deve essere chiaro è il modus operandi con cui siamo arrivati alla soluzione:

Proviamo la configurazione manualmente, registrando i passaggi.
Definiamo eventuali ruoli del nostro procedimento. Cerchiamo su Ansible Galaxy se qualche ruolo è già stato fatto.
Creiamo il playbook per dichiarare il procedimento completo.
Per definire le macchine target, definiamo l’inventario e inseriamo tutte le variabili in group_vars e host_vars.
I task da eseguire li definiamo nel ruolo. I moduli ci aiuteranno nella definizione di questi task.

Ansible si basa molto sulle convenzioni e best practices. Questo è un vantaggio enorme perché se avete capito questo esempio, praticamente potete capire qualsiasi playbook di Ansible perché la struttura è sempre la stessa! Provate a sfogliare i vari esempi che fornisce Ansible, ritroverete gli stessi concetti e cartelle in tutti.

Una volta assimilato questi concetti, non importa se dobbiamo impostare una VPN, un’istanza ridondata di MongoDB, configurare l’NTP su 100 macchine, possiamo fare configurare tutto quello che vogliamo con Ansible in modo efficiente e chiaro.

Alla prossima!

Come sviluppare delle API in TDD con Spring Boot

Tue, 30 Jul 2019 09:03:47 GMT

In questo articolo abbiamo visto cosa significa sviluppare in Test Driven Development (TDD) e i pregi che ne derivano. L’esempio utilizzato potrebbe sembrare un giochino fine a se stesso, ma il mio focus lì era di spiegare il TDD per chi proprio non ne aveva mai sentito parlare.

In questa guida invece vediamo insieme un caso d’uso che ci sarà molto più familiare: lo sviluppo delle API RESTful. Per far ciò ho deciso di utilizzare il framework Spring Boot, il linguaggio scelto è Java. Spring boot è molto utilizzato in ambito enterprise per creare un’architettura a microservizi. Anche Netflix lo utilizza. Inoltre Java è un linguaggio di programmazione ormai noto a tutti e quindi penso sia una buona scelta per vedere insieme un esempio pratico.

Come sempre iniziamo completamente da zero, per non lasciare nulla al caso. Oltre al TDD, vedremo insieme anche come strutturare in modo corretto il progetto e altre librerie molto comode che uso ogni giorno per aumentare la nostra produttività, come per esempio la libreria Lombok.

Requisiti

Il lettore che mi sto immaginando è uno sviluppatore che ha già sentito parlare di Spring Boot, non si spaventa se parliamo di API RESTful, ha voglia di utilizzare il TDD come driver principale di sviluppo ma che non riesce ad applicarlo in modo efficace.

Questo articolo è una continuazione della mia prima puntata sul TDD, quindi vi consiglio caldamente di leggere prima “Come sviluppare in TDD partendo da zero”. Così avrete un’infarinatura iniziale sul TDD e siamo allineati su alcuni concetti che qui darò per scontato.

La mia guida si basa su un sistema operativo UNIX-like (Mac OS X), ma può essere facilmente seguito anche da chi utilizza Windows.

Sul nostro PC deve essere installato Java Development Kit 12.

Obiettivo

Immaginiamo che dobbiamo creare due endpoint:

GET - /api/v1/vehicles/{id}: per il recupero di un veicolo tramite id.
POST - /api/v1/vehicles: per l’aggiunta di un veicolo.

Il veicolo è composto da queste proprietà

{
  "id": 1,
  "brand": "Ferrari",
  "model": "488 GTB",
  "year": 2019
}

Il brand, model e year sono obbligatori, l’anno di produzione del veicolo non può essere antecedente al 1950 per ragioni di business.

Per ora non siamo interessati ad altri endpoint.

Potete trovare l’implementazione di questo piccolo progetto in questa mia repository pubblica, in questo modo se vi state perdendo potete ritrovare il filo del discorso direttamente leggendo il codice.

Creiamo il progetto

Ora che abbiamo le idee chiare su cosa dobbiamo fare, andiamo a generare il progetto. Il modo migliore per farlo è andando sul sito Spring Initializr. Da qui possiamo decidere quali librerie integrare, versione di Java ecc.

La configurazione che ho scelto è la seguente:

Project: Gradle Project. Probabilmente avrete già sentito parlare di Maven come gestore delle dipendenze e build tool per Java. Se invece sviluppate su Android, con Gradle vi sentirete a casa, dato che è quello usato di default.
Language: Java.
Spring Boot: 2.1.6.
Project Metadata:
- Group: it.mattianatali.
- Artifact: tdd-spring-boot-api.
- Name: tdd-spring-boot-api.
- Description: Sample project to explain how to develop APIs in TDD with Spring Boot.
- Package Name: it.mattianatali.tdd-spring-boot-api.
- Packaging: Jar.
- Java: 12.
Dependencies:
- Spring Web Starter: fornisce le varie annotazioni per creare delle API RESTful in modo semplice e veloce.
- Lombok: è una libreria Java che ci permette di ridurre la verbosità del nostro codice Java.
- Spring Data JPA: fornisce tutto l’occorrente per la persistenza dei dati.
- H2 Database: fornisce un DB in memory. In produzione sarebbe opportuno usare un DB PostgreSQL o MySQL, ma per non perderci troppo nella configurazione del DB, ho preferito usare H2.

Premiamo “Generate the project”. Ci ritroviamo un bel file zip. Scompattiamo in una cartella a nostro piacimento. Apriamo il progetto, io utilizzo IntelliJ.

Abilitiamo lombok e l’annotation processor in IntelliJ

Se è la prima volta che usate Lombok, avete bisogno del Plugin “Lombok”. Aprite “Preferences”, andate su “Plugins”, cercate “Lombok” sul marketplace e installatelo.

Una volta aperto il progetto in IntelliJ, dobbiamo abilitare l’annotation processor. Per fare questo aprite “Preferences”, cercate “annotation” e spuntate l’opzione “Enable annotation processing”.

Carichiamo JUnit 5

Purtroppo la dipendenza per i test org.springframework.boot:spring-boot-starter-test, che possiamo trovare nel file build.gradle, utilizza ancora JUnit 4. Siccome più avanti utilizzeremo delle funzionalità avanzate, abbiamo bisogno di JUnit 5.

Per raggiungere l’obiettivo, aggiungiamo nel file build.gradle le dipendenze per JUnit 5.

dependencies {
  ...
  testImplementation 'org.junit.jupiter:junit-jupiter-api'
  testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine'
  testImplementation 'org.junit.jupiter:junit-jupiter-params'
  testImplementation 'org.mockito:mockito-junit-jupiter'
}

Infine ci serve “avvisare” Gradle di utilizzare JUnit 5 durante il comando di test ./gradlew test e di mostrare i log completi. Così ci è più semplice debuggare in caso di problemi. Sempre nel file build.gradle aggiungiamo in fondo

test {
 useJUnitPlatform()
 testLogging {
  exceptionFormat = 'full'
 }
}

Nel nostro progetto, c’è già un file di test scritto in JUnit 4. Il file si trova in src/test/java/it/mattianatali/tddspringbootapi/TddSpringBootApiApplicationTests.java. Questo test prova semplicemente a caricare il contesto di Spring. Può sembrare un test banale, ma a mano a mano che il progetto cresce, basta poco per dimenticarsi qualche annotazione e che quindi Spring non si carichi correttamente.

Il nostro primo passo è di migrarlo a JUnit 5

Dovrebbe essere scritto così:

package it.mattianatali.tddspringbootapi;

import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;

@RunWith(SpringRunner.class)
@SpringBootTest
public class TddSpringBootApiApplicationTests {

	@Test
	public void contextLoads() {
	}

}

Noi lo modifichiamo così:

package it.mattianatali.tddspringbootapi;

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit.jupiter.SpringExtension;

@ExtendWith(SpringExtension.class)
@SpringBootTest
class TddSpringBootApiApplicationTests {

	@Test
	void contextLoads() {
	}

}

Avete notato delle differenze? Per migrare un test da JUnit 4 a JUnit 5 bisogna stare attenti a queste cose:

Modificare l’annotazione @RunWith(SpringRunner.class) con @ExtendWith(SpringExtension.class).
Essere certi di avere sempre la scritta junit.jupiter nell’import di tutte le classi di JUnit. Infatti Se leggete jupiter significa che state usando JUnit 5. Possiamo notare che l’annotazione @Test ha cambiato package… Ricordatevi dovete usare junit.jupiter!
Le classi di test e i metodi non devono essere necessariamente public. Se usate IntelliJ si lamenterà di questo fatto.

Ora proviamo a vedere se la nostra suite di test è configurata correttamente. Per far ciò creiamo un test temporaneo che sicuramente fallisce.

...
import static org.junit.jupiter.api.Assertions.fail;
...
class TddSpringBootApiApplicationTests {
  ...

  @Test
	public void shouldFail() {
        fail("You shall not pass!");
	}
}

I puntini di sospensione ... nel codice significa che c’è altro nel file che però non ho scritto per evitare distrazioni.

Proviamo a far girare i test: utiliziamo IntelliJ oppure Gradle con il comando ./gradlew test. Ci aspettiamo che un test passi e l’altro fallisca.

L’output del test è il seguente


> Task :test FAILED

it.mattianatali.tddspringbootapi.TddSpringBootApiApplicationTests > shouldFail() FAILED
    org.opentest4j.AssertionFailedError: You shall not pass!
        at org.junit.jupiter.api.AssertionUtils.fail(AssertionUtils.java:38)
        at org.junit.jupiter.api.Assertions.fail(Assertions.java:84)
        at it.mattianatali.tddspringbootapi.TddSpringBootApiApplicationTests.shouldFail(TddSpringBootApiApplicationTests.java:20)
2019-07-20 12:56:43.465  INFO 13515 --- [       Thread-4] o.s.s.concurrent.ThreadPoolTaskExecutor  : Shutting down ExecutorService 'applicationTaskExecutor'
2019-07-20 12:56:43.466  INFO 13515 --- [       Thread-4] j.LocalContainerEntityManagerFactoryBean : Closing JPA EntityManagerFactory for persistence unit 'default'
2019-07-20 12:56:43.466  INFO 13515 --- [       Thread-4] .SchemaDropperImpl$DelayedDropActionImpl : HHH000477: Starting delayed evictData of schema as part of SessionFactory shut-down'
2019-07-20 12:56:43.468  INFO 13515 --- [       Thread-4] com.zaxxer.hikari.HikariDataSource       : HikariPool-1 - Shutdown initiated...
2019-07-20 12:56:43.472  INFO 13515 --- [       Thread-4] com.zaxxer.hikari.HikariDataSource       : HikariPool-1 - Shutdown completed.

2 tests completed, 1 failed

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':test'.
> There were failing tests. See the report at: file:///Users/mattia/Repositories/tdd-spring-boot-api/build/reports/tests/test/index.html

* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights.

* Get more help at https://help.gradle.org

BUILD FAILED in 5s
4 actionable tasks: 2 executed, 2 up-to-date

È proprio quello che ci aspettavamo! Ora togliamo il test che fallisce e possiamo essere certi che JUnit 5 è configurato alla perfezione!

Come strutturare il backend

Prima di iniziare a scrivere il codice dobbiamo essere allineati su come andremo ad architettare il nostro software. Solitamente, il minimo indispensabile per creare un backend che espone delle API RESTful è implementare tre tipi di classi:

Controller: il suo unico scopo è di validare i valori in input, dichiarare gli endpoint che vogliamo esporre, di invocare un service e di fornire la risposta data dalla classe service.
Service: al suo interno abbiamo la vera logica di business che dipende dal progetto, fa il lavoro sporco e se deve persistere qualche dato, invoca i repository.
Repository: esiste per persistere i dati da qualche parte, solitamente in un DB.

Ovviamente si può fare tutto in una classe, ma se vogliamo strutturare del buon codice testabile e riusabile, questo è il minimo. Dobbiamo sempre ricordarci che più una classe ha uno scopo ben preciso, più è semplice da implementare ma soprattutto è facile da riutilizzare in altri punti.

Implementiamo la chiamata GET

Iniziamo! La chiamata GET - /api/v1/vehicles/{id} abbiamo detto che deve fornire il dettaglio del veicolo. Per sviluppare immagino di essere la richiesta HTTP. La prima classe che viene intaccata dalla chiamata è il controller, come abbiamo detto la sua funzione è quella di validare i valori di input e di esporre l’endpoint che andiamo a chiamare. Andiamo a creare il controller. Creiamo il file src/main/java/it/mattianatali/tddspringbootapi/vehicle/VehicleController.java.

package it.mattianatali.tddspringbootapi.vehicle;

public class VehicleController {
}

Per ora ci basta questo, stiamo sviluppando in TDD quindi la nostra implementazione deve essere guidata dai test. Con IntelliJ possiamo premere cmd + shift + T, selezionare “Create New Test…” e confermare. In questo modo ci troviamo il file di test creato ad hoc per il nostro controller.

Pensiamo ora cosa deve fare il nostro controller per raggiungere l’obiettivo:

Dichiarare che esiste l’endpoint GET - /api/v1/vehicles/{id}.
Ricevere l’id del veicolo dal path della chiamata.
Chiamare il servizio VehicleService, che non esiste ancora, con l’id preso dal punto precedente.
Se VehicleService restituisce un veicolo, allora risponde con un 200 - Ok come statusCode e il veicolo nel body, altrimenti risponde con un bel 404 - Not Found.

Versione Semplificata

Siccome siamo alle prime armi con il TDD, è veramente difficile fare un test così completo al primo tentativo. Cerchiamo allora di procedere per piccoli passi. Testiamo una versione semplificata.

Il nostro primo test verificherà solo questo, poi pian piano aggiungiamo i punti rimanenti:

Verificare che esiste l’endpoint GET - /api/v1/vehicles/{id}.
Restituisce come statusCode 200 - Ok.

Il nostro test è il seguente:

package it.mattianatali.tddspringbootapi.vehicle;

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.test.context.junit.jupiter.SpringExtension;
import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@ExtendWith(SpringExtension.class)
@WebMvcTest(VehicleController.class)
class VehicleControllerTest {

    @Autowired
    private MockMvc mvc;

    @Test
    void getDetail_shouldReturn200() throws Exception {
        var vehicleId = 1;
        mvc.perform(get("/api/v1/vehicles/" + vehicleId))
                .andExpect(status().isOk());
    }
}

Ora spieghiamo punto per punto le cose nuove che non abbiamo mai visto:

@ExtendWith(SpringExtension.class) serve per collegare il contesto di JUnit con il framework di Spring Boot. In questo modo possiamo usare le annotazioni che comunemente usiamo con Spring Boot più altre annotazioni che esistono apposta per semplificare la vita durante il testing, come la successiva.
@WebMvcTest(VehicleController.class) è il nostro modo per dire a JUnit 5 + Spring Boot: “Voglio testare solo la parte adibita al controller VehicleController, quindi evita di caricare tutto il contesto di Spring Boot”. In altre parole il nostro test si avvierà più velocemente perché il nostro test sa bene che non deve caricare per esempio Hibernate, caricare i drivers del DB, configurazioni, servizi, repositories o altre cose, perché non ne abbiamo bisogno. Stiamo testando solo quel controller. Se invece vogliamo testare qualcosa caricando tutto il contesto di Spring Boot possiamo usare l’annotazione @SpringBootTest. Ma è sempre meglio evitare per non rallentare il caricamente ed esecuzione dei test.
@Autowired private MockMvc mvc significa “Spring Boot: forniscimi un modo per comunicare con il controller che ho definito nell’annotazione precedente (VehicleController), che mi permetta di fare delle chiamate HTTP”. @Autowired significa che è Spring Boot a fornircelo, non dobbiamo preoccuparci come lo istanzia per noi. MockMvc mvc è l’istanza fornita da Spring Boot che useremo per fare le chiamate HTTP.

Io solitamente adotto questa convenzione per i nomi dei test: nomeMetodo_cosaStiamoTestando. Non preoccupatevi di scrivere un nome troppo lungo, non andrete mai a riscrivere il nome del metodo. Qui è importante essere chiarissimi su cosa stiamo testando e cosa ci aspettiamo. Ogni volta che programmate mettetevi nei panni di un altro sviluppatore che non sa nulla di quello che state facendo, cercate di semplificare la vita al prossimo: in questo caso più siamo chiari, più i nostri colleghi saranno felici del nostro lavoro.

mvc.perform(get("api/v1/vehicles/" + vehicleId)) è il nostro modo per fare una chiamata GET all’endpoint che stiamo testando.
.andExpect(status().isOk()) è la nostra asserzione sullo statusCode della nostra chiamata HTTP, ci aspettiamo un bel 200 - Ok.

Facciamo girare il test, ci aspettiamo che fallisca e che invece dello statusCode 200 ci restituisca un 404 - Not Found, perché l’endpoint non è stato ancora dichiarato. Con IntelliJ è molto facile testare un singolo test, basta premere sulla freccia verde vicino al nome del metodo.

Questo è il risultato del nostro test:

2019-07-20 16:33:15.748  WARN 14736 --- [    Test worker] o.s.web.servlet.PageNotFound             : No mapping for GET api/v1/vehicles/1

...
Status expected:<200> but was:<404>
Expected :200
Actual   :404
<Click to see difference>

java.lang.AssertionError: Status expected:<200> but was:<404>
	...

Esattamente come ci aspettavamo.

Ora andiamo ad implementare il minimo indispensabile per far passare il test. Scriviamo in VehicleController

package it.mattianatali.tddspringbootapi.vehicle;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class VehicleController {
    @GetMapping("/api/v1/vehicles/{id}")
    void getVehicleDetails(@PathVariable Long id) {

    }
}

@RestController è l’annotazione di Spring Boot che serve per dichiarare che stiamo creando un Controller.
@GetMapping("/api/v1/vehicles/{id}") dichiariamo l’esistenza del nostro endpoint con il metodo GET e che ha una variabile nel path chiamata id.
@PathVariable Long id serve per estrapolare l’id dal path.

Come possiamo notare non restituiamo nulla dall’endpoint… Infatti non abbiamo messo nessuna asserzione nel test, quindi non è necessario mettere altro. Per ora vogliamo solo testare che risponda con statusCode 200. Che è il valore di default se non inseriamo niente.

Facciamo girare il test, aspettiamo qualche secondo, e stavolta è verde! Possiamo facilmente intuire che il nostro test non è sufficiente, ora miglioriamolo in modo tale da testare almeno “l’happy path” completo.

Versione Completa

Modifichiamo il test rendendolo completo:

package it.mattianatali.tddspringbootapi.vehicle;

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.test.context.junit.jupiter.SpringExtension;
import org.springframework.test.web.servlet.MockMvc;

import java.util.Optional;

import static org.hamcrest.Matchers.is;
import static org.mockito.Mockito.when;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@ExtendWith(SpringExtension.class)
@WebMvcTest(VehicleController.class)
class VehicleControllerTest {

    @Autowired
    private MockMvc mvc;

    @MockBean
    private VehicleService vehicleService;

    @Test
    void getDetail_shouldReturnVehicleIfFound() throws Exception {
        var vehicleId = 1L;
        var returnedVehicle = Vehicle.builder()
                .id(vehicleId)
                .brand("Ferrari")
                .model("488 GTB")
                .year(2019)
                .build();

        when(vehicleService.get(vehicleId)).thenReturn(Optional.of(returnedVehicle));

        mvc.perform(get("/api/v1/vehicles/" + vehicleId))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.id", is(returnedVehicle.getId().intValue())))
                .andExpect(jsonPath("$.brand", is(returnedVehicle.getBrand())))
                .andExpect(jsonPath("$.model", is(returnedVehicle.getModel())))
                .andExpect(jsonPath("$.year", is(returnedVehicle.getYear())));
    }
}

In questo momento c’è il nostro compilatore che si sta disperando perché non trova VehicleService e nemmeno la classe Vehicle… Infatti non li abbiamo ancora creati!

Anche in questo caso vediamo cosa c’è di nuovo:

@MockBean private VehicleService vehicleService stiamo dicendo a Spring Boot: “Se qualche classe ti chiede il servizio VehicleService, tu non passare la vera implementazione, ma fornisci un’istanza finta, dove io posso decidere cosa ritornare nell’invocazione dei metodi”. Infatti più avanti con il metodo when possiamo decidere cosa ritornare come valore, senza andare a richiamare la vera implementazione. Il discorso di cosa vuol dire “Mockare” le classi è già stato trattato nel mio articolo precedente, se non vi è chiaro è meglio che leggiate la puntata precedente.
var returnedVehicle = Vehicle.builder()....build() stiamo semplicemente creando un modello di veicolo che verrà restituito in output dal VehicleService e di conseguenza dal controller. In questo caso useremo il builder che ci fornisce Lombok, non preoccupatevi per ora, quando creeremo la classe sarà più chiaro.
when(vehicleService.get(vehicleId)).thenReturn(Optional.of(returnedVehicle)); stiamo dicendo “se qualcuno invoca vehicleService.get con l’id vehicleId, allora ritorna un opzionale con il nostro veicolo appena creato”.
.andExpect(jsonPath("$.id", is(returnedVehicle.getId()))) significa che ci aspettiamo nel body di risposta un JSON che contiene un campo id, con dentro l’id del nostro veicolo creato. Le altre righe sono molto simili, cambia solo il campo che andiamo a controllare.

Non possiamo far girare i test perché il codice non compila nemmeno. Andiamo allora a creare le classi mancanti. Con IntellJ è molto semplice creare classi o metodi che non esistono ancora, basta spostare il cursore sulla classe inesistente, premere alt + Invio, cliccare su ”Create class …”, come target directory scegliere main e non test, e confermate.

Facciamo questo procedimento con Vehicle. Poi implementiamola. Il file dovrebbe trovarsi in /src/main/java/it/mattianatali/tddspringbootapi/vehicle/Vehicle.java

package it.mattianatali.tddspringbootapi.vehicle;

import lombok.Builder;
import lombok.Data;

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder(toBuilder = true)
public class Vehicle {
    private Long id;
    private String brand;
    private String model;
    private Integer year;
}

Qui possiamo vedere Lombok in azione! Grazie all’annotazione @Data non dobbiamo scrivere né getter, né setter, né fare l’override di equals o hash, fa tutto lui! Con @Builder(toBuilder = true) invece ci viene gratis un comodo builder che abbiamo già usato nel test. toBuilder = true ci fornisce un comodo metodo sull’istanza che ci permette di avere un builder dall’istanza stessa, molto comodo per creare per esempio un clone modificando magari qualche suo campo. @NoArgsConstructor e @AllArgsConstructor sono ancora due annotazioni di Lombok che ci forniscono sia il costruttore con tutti i parametri, sia il costruttore vuoto. Sono molto utili per la serializzazione delle istanze in JSON. Se infatti non mettiamo queste due annotazioni, Jackson, che è la libreria che utilizza Spring Boot per creare i JSON di risposta, si lamenterà perché non riesce a serializzare l’oggetto. Meno codice da scrivere significa meno codice da gestire e testare!

Ora dobbiamo creare il VehicleService. In questo caso scriviamo il minimo indispensabile per poter compilare, ci dobbiamo ricordare che nel test usiamo la versione mockata, quindi la vera implementazione ora non ci interessa. Ci preoccuperemo quando andremo a sviluppare in TDD su di essa. Anche qui possiamo farci aiutare da IntelliJ.

Una volta creata la classe, possiamo dire ad IntelliJ di creare il metodo VehicleService.get che abbiamo invocato nella riga di test when(vehicleService.get(vehicleId)). alt + invio è il nostro migliore amico in questo caso.

Il file src/main/java/it/mattianatali/tddspringbootapi/vehicle/VehicleService.java conterrà quindi

package it.mattianatali.tddspringbootapi.vehicle;

import org.springframework.stereotype.Service;

import java.util.Optional;

@Service
public class VehicleService {
    public Optional<Vehicle> get(long vehicleId) {
        return null;
    }
}

@Service serve a dire che la classe è un servizio e che può essere creata da Spring Boot tramite la Dependency Injection (DI) e che può essere iniettata nelle altre classi quando usano l’annotazione @Autowired.

Il metodo è ovviamente sbagliato, ma ripeto, ora ci interessa solo che compili in modo tale da far girare i test.

Qui c’è una cosa molto interessante da notare: abbiamo definito prima la firma del metodo prima di pensare alla sua attuale implementazione. In questo molto definiamo le classi dal punto di vista dell’utilizzatore e non del creatore. Solitamente questo è un bene perché si creano delle firme dei metodi facilmente utilizzabili. Se invertiamo il procedimento finiamo di semplificare l’implementazione ma rendiamo difficile l’utilizzo delle classi create perché appunto non pensiamo a come un possibile utilizzatore possa sfruttare queste classi.

Facendo girare il test abbiamo il seguente errore

...
java.lang.AssertionError: No value at JSON path "$.id"
...
Caused by: java.lang.IllegalArgumentException: json can not be null or empty
...

Ora si sta lamentando che il nostro endpoint non restituisce nessun JSON e che quindi non può testare le varie proprietà. Perfetto, andiamo ad implementare per far passare il test.

Modifichiamo il nostro VehicleController

package it.mattianatali.tddspringbootapi.vehicle;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class VehicleController {
    private VehicleService vehicleService;

    @Autowired
    public VehicleController(VehicleService vehicleService) {
        this.vehicleService = vehicleService;
    }

    @GetMapping("/api/v1/vehicles/{id}")
    Vehicle getVehicleDetails(@PathVariable Long id) {
        return vehicleService.get(id).get();
    }
}

Possiamo vedere per la prima volta come si può sfruttare la Dependency Injection di Spring Boot. Possiamo chiedere a Spring Boot di fornirci delle istanze di classi che ci servono per svolgere il nostro compito (in questo caso il recupero del veicolo), senza che noi dobbiamo preoccuparci effettivamente di come queste istanze siano create. In altre parole, tramite l’annotazione @Autowired stiamo dicendo a Spring Boot di fornirci nel costruttore tutte le istanze che abbiamo bisogno, delegando al framework il come crearle.

In questo modo possiamo creare delle classi disaccoppiate tra di loro e soprattutto nei test possiamo iniettare delle istanze finte (mockate). Iniettando nei test delle classi mockate possiamo pilotare il flusso di esecuzione senza distogliere lo sguardo dalla classe sotto test. Perché infatti l’unica vera implementazione testata è il controller, il resto è tutta finzione (la finzione è data dall’annotazione @MockBean e dal metodo when().thenReturn()).

Dobbiamo infatti immaginare che durante il test, il controller riceve la nostra istanza mockata nel costruttore, quindi non va a toccare la vera implementazione di VehicleService (che per ora non esiste ancora… ritorna sempre null!).

Magari vi state chiedendo perché c’è un doppio get in vehicleService.get(id).get(). Il primo è l’invocazione del nostro metodo di VehicleService, il secondo serve per estrapolare il valore contenuto in Optional<Vehicle>. È fortemente sconsigliato chiamare get su un opzionale perché non stiamo gestendo il caso in cui l’opzionale sia vuoto, in altre parole quando il veicolo non esiste. Ma per ora il nostro obiettivo è di far passare il test, poi quando faremo il test che testa il caso in cui il veicolo non esiste, lo sistemeremo.

Facendo girare il test vediamo che effettivamente funziona! Ritorniamo il JSON con tutti i campi.

Testiamo il caso di assenza veicolo

Abbiamo testato quando il veicolo viene ritornato dal VehicleService, ma cosa succede quando il veicolo con un determinato id non esiste? Noi ci aspettiamo che l’endpoint ritorni 404 - Not Found.

Andiamo a creare il test che verifica questo caso, nel VehicleControllerTest scriviamo:

@Test
void getDetail_shouldReturn404IfVehicleNotFound() throws Exception {
    var vehicleId = 1L;

    when(vehicleService.get(vehicleId)).thenReturn(Optional.empty());

    mvc.perform(get("/api/v1/vehicles/" + vehicleId))
            .andExpect(status().isNotFound());
}

Facendo girare il test esplode in questo modo


org.springframework.web.util.NestedServletException: Request processing failed; nested exception is java.util.NoSuchElementException: No value present

	...
Caused by: java.util.NoSuchElementException: No value present
  ...
	... 57 more

In pratica è il nostro famoso get sull’opzionale che abbiamo messo nel controller. Stiamo cercando di recuperare un dato che non esiste e quindi va in eccezione.

Andiamo a modificare il controller in modo tale che ci restituisca uno status code 404 - Not Found quando il servizio non ci restituisce alcun veicolo. Per rispondere 404 abbiamo bisogno di un’eccezione che ci generi quello status code. Quindi creiamo l’eccezione in src/main/java/it/mattianatali/tddspringbootapi/vehicle/errors/VehicleNotFoundException.java e scriviamo

package it.mattianatali.tddspringbootapi.vehicle.errors;

import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ResponseStatus;

@ResponseStatus(HttpStatus.NOT_FOUND)
public class VehicleNotFoundException extends RuntimeException {
}

Grazie a @ResponseStatus(HttpStatus.NOT_FOUND) siamo sicuri che lo status code della chiamata sarà 404 - Not Found.

Ora modifichiamo il metodo VehicleController.getVehicleDetails utilizzando questa nuova eccezione

@GetMapping("/api/v1/vehicles/{id}")
Vehicle getVehicleDetails(@PathVariable Long id) {
    return vehicleService
            .get(id)
            .orElseThrow(VehicleNotFoundException::new);
}

In pratica abbiamo sostituito il metodo .get con .orElseThrow(VehicleNotFoundException::new). Questo è il modo per generare un’eccezione in caso di mancato valore nell’opzionale.

Facciamo girare il test ed ora funziona tutto!

Ricapitoliamo

Fermiamoci un secondo per fare mente locale. Il lavoro per ultimare l’endpoint GET non è ancora concluso. Però ora è importante focalizzare cosa abbiamo imparato e fatto fino ad ora:

Abbiamo creato un nuovo progetto Spring Boot utilizzando Spring Initializr.
Abbiamo migrato la suite di test a JUnit 5.
Abbiamo imparato ad utilizzare alcune funzionalità di Lombok.
Abbiamo sviluppato in TDD il controller per la chiamata GET.
Abbiamo imparato a sfruttare la Dependency Injection e l’annotazione @Autowired di Spring Boot per testare in isolamento il controller, ancor prima di aver implementato il servizio VehicleService.
Abbiamo imparato a fare delle finte chiamate HTTP utilizzando @WebMvcTest.

Prendiamoci una pausa, tutti i concetti appena esposti hanno bisogno di un attimo per essere assimilati. Poi continuiamo a sviluppare i due componenti rimanenti: il servizio VehicleService e il repository VehicleRepository.

Implementiamo il servizio VehicleService

Ora che ci siamo rigenerati un attimo, svolgiamo un lavoro abbastanza semplice: l’implementazione di VehicleService. In questa classe ci dovrebbe andare tutta la logica di business, ma la logica che ha la chiamata GET è davvero banale: recuperare il veicolo dato il suo id. Non preoccupatevi, nei progetti veri la logica di business diventa sempre complessa a piacere. Noi siamo solo fortunati perché siamo all’inizio. In altre parole, nel nostro caso dobbiamo testare che venga invocato il VehicleRepository per recuperare il veicolo, il valore di ritorno deve essere esattamente lo stesso che otteniamo dal VehicleRepository. VehicleRepository non esiste ancora e quindi dobbiamo pensare al metodo che fa al caso nostro. Non reinventiamo niente e quindi immaginiamo di utilizzare il metodo VehicleRepository.findById(Long id) che ci fornice gratis JpaRepository.

Scriviamo i test nel nuovo file src/test/java/it/mattianatali/tddspringbootapi/vehicle/VehicleServiceTest.java:

package it.mattianatali.tddspringbootapi.vehicle;

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;

import java.util.Optional;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.Mockito.when;

@ExtendWith(MockitoExtension.class)
class VehicleServiceTest {
    @Mock
    private VehicleRepository vehicleRepository;

    @InjectMocks
    private VehicleService vehicleService;

    @Test
    void get_shouldReturnVehicle() {
        var vehicleId = 1L;
        var returnedVehicle = Optional.of(
                Vehicle.builder()
                        .id(vehicleId)
                        .brand("Ferrari")
                        .model("488 GTB")
                        .year(2019)
                        .build()
        );
        when(vehicleRepository.findById(vehicleId))
                .thenReturn(returnedVehicle);

        assertEquals(
                returnedVehicle,
                vehicleService.get(vehicleId)
        );

    }

    @Test
    void get_shouldReturnOptionalEmptyIfNotFound() {
        var vehicleId = 1L;
        when(vehicleRepository.findById(vehicleId))
                .thenReturn(Optional.empty());

        assertTrue(vehicleService.get(vehicleId).isEmpty());
    }
}

Notiamo però delle diversità nelle annotazioni utilizzate, ci stiamo riferendo a

@ExtendWith(MockitoExtension.class) invece di @ExtendWith(SpringExtension.class).
@Mock invece di @MockBean.
@InjectMocks è nuovo.

Perché abbiamo queste differenze rispetto al nostro test sul controller? Perché se ci pensiamo bene non abbiamo bisogno di caricare nessun componente di Spring Boot (nel controller avevamo bisogno di MockMvc di Spring Boot per simulare delle chiamate HTTP), quindi possiamo utilizzare solo la libreria Mockito per testare il nostro servizio. Questo significa avere dei test più veloci ad avviarsi perché non dobbiamo caricare il contesto di Spring Boot. Le annotazioni per usare Mockito sono appunto

@ExtendWith(MockitoExtension.class) per avviare il contesto di Mockito e le sue annotazioni durante il test.
@Mock per creare un’istanza mockata che possiamo decidere le risposte da dare, attraverso il metodo when(...).thenReturn(...) durante i test.
@InjectMocks per iniettare le istanze mockate nel nostro servizio sotto test (nel nostro caso VehicleService).

Il resto non dovrebbe sorprendervi più di tanto, normalissimi test organizzati in setup, call, assertions.

Siccome il compilatore si sta lamentando che VehicleRepository non esiste, andiamo a crearlo senza implementare il metodo. In modo tale da poter eseguire il test del VehicleService. In src/main/java/it/mattianatali/tddspringbootapi/vehicle/VehicleRepository.java scriviamo:

package it.mattianatali.tddspringbootapi.vehicle;

import org.springframework.stereotype.Repository;

import java.util.Optional;

@Repository
public class VehicleRepository {
    public Optional<Vehicle> findById(long vehicleId) {
        return null;
    }
}

Ora compila! Facciamo girare i test del nostro servizio ed ovviamente falliscono. Andiamo ad implementare il servizio che sarà molto semplice, non fa nient’altro che fare da “proxy” al nostro futuro VehicleRepository.

package it.mattianatali.tddspringbootapi.vehicle;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.Optional;

@Service
public class VehicleService {
    private VehicleRepository vehicleRepository;

    @Autowired
    public VehicleService(VehicleRepository vehicleRepository) {
        this.vehicleRepository = vehicleRepository;
    }

    public Optional<Vehicle> get(long vehicleId) {
        return vehicleRepository.findById(vehicleId);
    }
}

Anche qui niente di eccezionale. Prendiamo VehicleRepository tramite DI nel costruttore e lo utilizziamo per fornire il veicolo nella chiamata get. Facciamo girare i test e sono verdi!

Implementiamo il VehicleRepository

Siamo quasi giunti al termine, ci manca solo il VehicleRepository per ultimare la chiamata GET. Qui abbiamo bisogno di testare il metodo findById per recuperare il veicolo, per fare un test completo dobbiamo anche poter salvare un veicolo prima di recuperarlo.

Scriviamo il test in src/test/java/it/mattianatali/tddspringbootapi/vehicle/VehicleRepositoryTest.java

package it.mattianatali.tddspringbootapi.vehicle;

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
import org.springframework.test.context.junit.jupiter.SpringExtension;

import java.util.Optional;

import static org.junit.jupiter.api.Assertions.assertEquals;

@ExtendWith(SpringExtension.class)
@DataJpaTest
class VehicleRepositoryTest {
    @Autowired
    private VehicleRepository vehicleRepository;

    @Test
    void findById_shouldGetVehicle() {
        var vehicleToSave =
                Vehicle.builder()
                        .brand("Ferrari")
                        .model("488 GTB")
                        .year(2019)
                        .build();
        var expectedVehicle = vehicleRepository.save(vehicleToSave);
        assertEquals(
                Optional.of(expectedVehicle),
                vehicleRepository.findById(expectedVehicle.getId())
        );
    }
}

Con questo test salviamo un veicolo, poi lo recuperiamo con l’id che ci viene restituito nella save e poi verifichiamo che il findById ci restituisca il veicolo. Ma vediamo le annotazioni che abbiamo utilizzato: sono praticamente le stesse che abbiamo utilizzato per il controller, ma stavolta invece di @WebMvcTest abbiamo utilizzato @DataJpaTest che serve per testare la persistenza dei dati. Abbiamo bisogno di usare il contesto di Spring Boot perché JPA lo richiede, di conseguenza non possiamo usare solamente Mockito come abbiamo fatto con VehicleService.

Anche in questo caso non compila, perché non abbiamo il metodo save dichiarato in VehicleRepository. Andiamo a sistemare in modo intelligente la questione. Trasformiamo VehicleRepository in questo modo:

package it.mattianatali.tddspringbootapi.vehicle;

import org.springframework.data.repository.CrudRepository;
import org.springframework.stereotype.Repository;

@Repository
public interface VehicleRepository extends CrudRepository<Vehicle, Long> {
}

Abbiamo trasformato il VehicleRepository in un’interfaccia che estende CrudRepository, in questo caso utilizziamo un po’ di magia offerta da JPA. CrudRepository ci offre gratis i metodi save e findById che stiamo utilizzando.

Ora compila! Proviamo ad avviare il test del Repository, ma purtroppo fallisce in questo modo:

java.lang.IllegalStateException: Failed to load ApplicationContext
	...
	at com.intellij.rt.execution.junit.JUnitStarter.main(JUnitStarter.java:70)
Caused by: org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'vehicleRepository': Invocation of init method failed; nested exception is java.lang.IllegalArgumentException: Not a managed type: class it.mattianatali.tddspringbootapi.vehicle.Vehicle
	...
Caused by: java.lang.IllegalArgumentException: Not a managed type: class it.mattianatali.tddspringbootapi.vehicle.Vehicle
	...

Quello che Spring Boot sta cercando di dirci è che sul modello Vehicle mancano le annotazioni per poterlo utilizzare insieme al CrudRepository, infatti se ci pensiamo bene nessuno ha detto qual’è il campo id del nostro veicolo e come generarlo. Il povero JPA sa solo che esiste il modello Vehicle e nient’altro.

Andiamo a risolvere il problema modificando il nostro file Vehicle:

package it.mattianatali.tddspringbootapi.vehicle;

import lombok.Builder;
import lombok.Data;

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder(toBuilder = true)
@Entity
public class Vehicle {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String brand;
    private String model;
    private Integer year;
}

Abbiamo aggiunto tre annotazioni:

@Entity serve a JPA per capire che la classe Vehicle può essere utilizzata come modello per la persistenza del dato sul DB.
@Id stiamo indicando come id della nostra tabella sul DB il campo Long id.
@GeneratedValue(strategy = GenerationType.IDENTITY) stiamo dicendo a JPA di delegare al DB la generazione dell’id qualora non fosse indicato.

Facciamo partire il test e stavolta funziona!

Test in caso di mancato veicolo

Aggiungiamo un semplice test per verificare che venga restituito un Optional.empty() qualora non esistesse il veicolo.

@Test
void findById_shouldReturnEmptyIfVehicleNotFound() {
    assertEquals(
            Optional.empty(),
            vehicleRepository.findById(999999L)
    );
}

Possiamo andare tranquilli che durante il test non esiste un valore con quell’id perché l’annotazione @DataJpaTest ci garantisce che, ogni volta che eseguiamo il test, il DB è pulito. Eseguendolo vediamo che il test passa come ci aspettavamo, non dobbiamo implementare nient’altro.

Dobbiamo ricordarci che il setup del DB solitamente è molto più impegnativo: ci sono migrazioni, creazioni di tabelle in modo esplicito, chiamate ad un DB remoto ecc. Noi ce la stiamo cavando facilmente con il DB H2 che abbiamo inserito durante la creazione del progetto. Purtroppo non tratteremo insieme queste tematiche per non perdere il focus dal TDD.

Test sui repository

Nel nostro caso, a causa di questa semplificazione, stiamo testando su un DB in memory creato ad hoc per i test, tutto questo grazie con l’annotazione @DataJpaTest. Purtroppo, cosi facendo, i test sui repository perdono la maggior parte dell’efficacia. Ma ora proviamo ad immaginare di usare questo modus operandi su un progetto vero.

Noi in Pirelli testiamo i repository su un DB molto simile a quello reale. In questo caso i vantaggi di testare i repo sono tanti, anche se l’implementazione viene fatta “magicamente” da Spring. Per esempio testando un banale .save() autogenerato:

Possiamo testare che tutte le proprietà proprietà del modello siano mappate a DB.
Possiamo verificare che le migrazioni rispecchino veramente il codice.
Possiamo verificare che non ci siano dei typo negli enum che si mappano nel DB, o che tutti gli enum siano presenti anche lato DB.
Possiamo verificare che il driver JDBC sia in grado di mappare tutte le proprietà presenti sul modello (e.g. driver vecchi potrebbero non mappare correttamente le classi Date di Java 8).
Possiamo verificare che le relazioni vengano salvate come ci aspettiamo.

Poi il repository può crescere e possiamo creare nuovi metodi autogenerati da Spring ma anche qui:

Possiamo testare che le relazioni siano recuperate in modo corretto.
Possiamo verifiare che non ci siano errori logici nel metodo autogenerato (basta un attimo a confondere un id con un altro o dimenticarti un Not nel metodo).

Infine non dobbiamo trarci in inganno pensando che l’implementazione è semplice (il metodo .save() è autogenerato!) e quindi è inutile il test: i test guidano il nostro sviluppo in TDD. Quindi prima testiamo che la funzionalità non esista, poi la implementiamo, infine il test verifica che esista e rimanga tale per tutti i prossimi sviluppi: il metodo .save() può complicarsi, magari non sarà più autogenerato perchè sono state aggiunte logiche ad hoc. Il nostro test sarà sempre lì a darci questa garanzia. Se non lo facciamo all’inizio, ci perdiamo questa opportunità e potremmo avere dei dispiaceri più avanti.

Chiamata GET completata!

Finalmente ora abbiamo la chiamata GET completamente sviluppata in TDD! Abbiamo 3 componenti ben isolati, facili da testare, con una coverage del 100%. Sembra che sia stato lungo e difficile, ma solamente perché abbiamo spiegato ogni singola riga di codice e anche perché abbiamo spiegato ogni singolo passo che abbiamo svolto. La buona notizia è che tramite questo processo possiamo creare qualsiasi endpoint che ci venga in mente: possiamo complicare la logica di business quanto vogliamo, ma il procedimento in TDD rimarrà sempre il medesimo.

Ora andiamo ad implementare la chiamata POST, ma spiegheremo con lo stesso livello di dettaglio solo il controller dove posso condividere con voi alcuni trucchetti che non ho ancora trattato. Lo sviluppo dei metodi nel service e del repository sarà molto simile a quello che abbiamo fatto per la chiamata GET, quindi sarebbe poco utile ripetere le stesse cose.

Implementiamo il controller per la chiamata POST

Passiamo ora allo sviluppo della chiamata POST per creare dei nuovi veicoli. Come sempre iniziamo con i test. La prima cosa che verifichiamo è che il nostro veicolo passato nel body venga digerito correttamente da Spring Boot e che venga passato al metodo VehicleService.save(vehicle) per salvarlo.

...

@ExtendWith(SpringExtension.class)
@WebMvcTest(VehicleController.class)
class VehicleControllerTest {
    @Autowired
    private MockMvc mvc;

    @Autowired
    private ObjectMapper objectMapper;

    @MockBean
    private VehicleService vehicleService;

    ...

    @Test
    void create_shouldSaveTheVehicle() throws Exception {
        var vehicleId = 1L;
        var vehicleToSave = aValidVehicle();

        when(vehicleService.save(vehicleToSave))
                .thenReturn(
                        vehicleToSave
                                .toBuilder()
                                .id(vehicleId)
                                .build()
                );

        mvc.perform(
                post("/api/v1/vehicles")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsBytes(vehicleToSave))
        )
                .andExpect(status().isCreated())
                .andExpect(jsonPath("$.id", is((int) vehicleId)))
                .andExpect(jsonPath("$.brand", is(vehicleToSave.getBrand())))
                .andExpect(jsonPath("$.model", is(vehicleToSave.getModel())))
                .andExpect(jsonPath("$.year", is(vehicleToSave.getYear())));
    }

    private static Vehicle aValidVehicle() {
        return Vehicle.builder()
                .brand("Ferrari")
                .model("488 GTB")
                .year(2019)
                .build();
    }
}

Come possiamo leggere, stiamo emulando una chiamata POST, settiamo correttamente il contentType della chiamata tramite .contentType(MediaType.APPLICATION_JSON) e inseriamo nel body il nostro veicolo da salvare tramite .content(objectMapper.writeValueAsBytes(vehicleToSave)).

Con

when(vehicleService.save(vehicleToSave))
    .thenReturn(
            vehicleToSave
                    .toBuilder()
                    .id(vehicleId)
                    .build()
    );

emuliamo il fatto che il nostro servizio ci restituisca lo stesso oggetto passato in input ma con l’id popolato. Per questo caso abbiamo usato il metodo toBuilder che ci viene gentilmente offerto dall’annotazione @Builder(toBuilder = true) che avevamo aggiunto sulla classe Vehicle.

Infine testiamo che la chiamata HTTP risponda con lo statusCode 201 - Created e che nel body abbiamo tutti i campi popolati.

objectMapper è il serializzatore di default di Spring Boot Jackson. Chiediamo una sua istanza a Spring Boot tramite @Autowired.

Il compilatore si sta lamentando che non esiste il metodo save sul VehicleService, andiamo ad aggiungerlo senza implementare la logica corretta.

@Service
public class VehicleService {
    private VehicleRepository vehicleRepository;

    @Autowired
    public VehicleService(VehicleRepository vehicleRepository) {
        this.vehicleRepository = vehicleRepository;
    }

    ...

    public Vehicle save(Vehicle vehicleToSave) {
        return null;
    }
}

Avviamo il test e fallisce per questo motivo

...
java.lang.AssertionError: Status expected:<201> but was:<404>
Expected :201
Actual   :404
<Click to see difference>
...

Giustamente l’endpoint non esiste ancora, quindi andiamo ad aggiungerlo sul VehicleController.

package it.mattianatali.tddspringbootapi.vehicle;

import it.mattianatali.tddspringbootapi.vehicle.errors.VehicleNotFoundException;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;

@RestController
public class VehicleController {
    private VehicleService vehicleService;

    @Autowired
    public VehicleController(VehicleService vehicleService) {
        this.vehicleService = vehicleService;
    }

    ...

    @PostMapping("/api/v1/vehicles")
    @ResponseStatus(HttpStatus.CREATED)
    Vehicle saveVehicle(@RequestBody Vehicle vehicle) {
        return vehicleService.save(vehicle);
    }
}

@PostMapping è l’annotazione che ci permette di definire un’endpoint POST.
@ResponseStatus(HttpStatus.CREATED) possiamo definire lo status code di risposta, di default è 200 - Ok, noi invece vogliamo 201 - Created.
@RequestBody è l’annotazione che ci permette di prendere il valore passato nel body e di deserializzarlo a Vehicle.

In questo caso ci basta invocare il metodo vehicleService.save e di ritornare il suo valore.

Facendo girare i test è tutto ok!

Abbiamo quasi finito, ma dobbiamo ancora implementare la regola che ci è stata data quando salviamo un veicolo. La ripropongo qui:

Il brand, model e year sono obbligatori, l’anno di produzione del veicolo non può essere antecedente al 1950 per ragioni di business.

Andiamo a creare il test che verifica queste condizioni.

package it.mattianatali.tddspringbootapi.vehicle;

import com.fasterxml.jackson.databind.ObjectMapper;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.MethodSource;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.http.MediaType;
import org.springframework.test.context.junit.jupiter.SpringExtension;
import org.springframework.test.web.servlet.MockMvc;

import java.util.Optional;
import java.util.stream.Stream;

import static org.hamcrest.Matchers.is;
import static org.mockito.Mockito.when;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@ExtendWith(SpringExtension.class)
@WebMvcTest(VehicleController.class)
class VehicleControllerTest {
    ...
    @ParameterizedTest
    @MethodSource("getInvalidVehicles")
    void create_shouldReturnBadRequestIfBodyIsInvalid(Vehicle invalidVehicle) throws Exception {
        mvc.perform(
                post("/api/v1/vehicles")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content(objectMapper.writeValueAsBytes(invalidVehicle))
        )
                .andExpect(status().isBadRequest());
    }

    private static Stream<Vehicle> getInvalidVehicles() {
        var validVehicle = aValidVehicle();

        return Stream.of(
                validVehicle.toBuilder().brand(null).build(),
                validVehicle.toBuilder().brand("").build(),
                validVehicle.toBuilder().model(null).build(),
                validVehicle.toBuilder().model("").build(),
                validVehicle.toBuilder().year(null).build(),
                validVehicle.toBuilder().year(1949).build()
        );
    }
}

Qui possiamo vedere una bellissima funzionalità di JUnit 5: i test parametrici!

Attraverso l’annotazione @ParametrizedTest definiamo un test che in input vuole un parametro.
@MethodSource("getInvalidVehicles") definiamo il metodo che ci fornirà i veicoli che sono invalidi e che dobbiamo testare.
Il medodo getInvalidVehicles() ci ritorna uno stream di veicoli invalidi, per creare questo stream partiamo da un veicolo valido che abbiamo già testato nell’altro test (aValidVehicle()), poi da questo creiamo un veicolo invalido modificando i parametri. In questo modo creiamo 6 test che testa rispettivamente tutte le regole che il business ci ha imposto ossia:
- Il parametro brand non può essere nullo o stringa vuota.
- Il parametro model non può essere nullo o stringa vuota.
- Il parametro year non può essere nullo.
- Il parametro year non può essere inferiore al 1950.

Facciamo partire il test ed effettivamente vediamo che abbiamo 6 test che falliscono.

java.lang.AssertionError: Status expected:<400> but was:<201>
Expected :400
Actual   :201

Per implementare la validazione dei veicoli possiamo sfruttare la validazione di Spring Boot. Quindi andiamo ad inserire le regole di validazione sul modello Vehicle.

package it.mattianatali.tddspringbootapi.vehicle;

...

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotEmpty;
import javax.validation.constraints.NotNull;

...
public class Vehicle {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    @NotNull
    @NotEmpty
    private String brand;
    @NotNull
    @NotEmpty
    private String model;
    @NotNull
    @Min(1950)
    private Integer year;
}

@NotNull diciamo che il campo non può essere null.
@NotEmpty diciamo che il campo non può essere stringa vuota.
@Min(1950) significa che il campo deve essere almeno 1950.

Infine, per abilitare la validazione, dobbiamo modificare il controller mettendo l’annotazione @Valid nel VehicleController:

...
@PostMapping("/api/v1/vehicles")
@ResponseStatus(HttpStatus.CREATED)
Vehicle saveVehicle(@RequestBody @Valid Vehicle vehicle) {
    return vehicleService.save(vehicle);
}
...

Facciamo girare i test e ora sono tutti verdi! In questo modo abbiamo fatto in un colpo ben 6 test senza duplicare il codice.

Ora che abbiamo implementato il controller, manca il metodo vehicleService.save da implementare, questo lo lascio come compito a casa dato che non darebbe nessun valore aggiunto a questo articolo: dobbiamo praticamente fare la stessa cosa che abbiamo fatto con la chiamata GET. E il metodo del VehicleRepository.save, lo abbiamo già testato quando abbiamo implementato la chiamata GET. In ogni caso nel mio repository potete trovare il progetto completo.

Conclusioni

È stata una lunga chiacchierata, spero proprio che dopo questa lettura abbiate imparato un po’ di funzionalità offerte da JUnit 5, Spring Boot, Lombok, ma soprattutto sia entrato in voi la filosofia del TDD.

La cosa che deve essere chiara è questa: prima ci preoccupiamo di cosa vogliamo raggiungere, poi ci preoccupiamo di come raggiungerlo. Il cosa vogliamo raggiungere si traduce in test, il come si traduce nell’implementazione.

In questo modo abbiamo un codice ben testato, ben organizzato in classi isolate (se una classe è facile da testare, significa che è ben isolata dal resto dei componenti) e soprattutto facile da mantenere (i refactor sono semplici perché ogni singola funzionalità è testata, le regressioni sono pressochè azzerate).

All’inizio può essere difficile, ma poi una volta internalizzato esce naturale e si ha un valore aggiunto che non si può capire fino a che si ha in produzione un progetto sviluppato in TDD. Provare per credere!

Alla prossima!

Come creare una pipeline di Continuous Integration e Continuous Deployment (CI/CD) · DevOps

Sat, 16 Mar 2019 07:03:47 GMT

Introduzione

Una cosa che ho imparato in Pirelli è l’implementazione delle pipeline per avere la Continuous Integration (CI) e Continuous Deployment (CD), d’ora in poi lo chiamerò semplicemente CI/CD. Nascono sempre numerosi progetti con architettura a microservizi: il tempo al lavoro è sempre poco e i lavori ripetitivi mi annoiano facilmente… Cosa c’è di più ripetitivo di una messa in produzione di tutti questi microservizi? Queste pipeline automatiche quindi diventano essenziali per non passare la giornata a fare solo questo noioso mestiere.

Non voglio annoiarvi troppo parlando sui vari vantaggi che CI/CD comporta, se siete giunti su questo post significa che lo sapete già, quindi inizio subito con un esempio pratico.

Creazione della pipeline per GasLow Backend

Come esempio utilizzerò il backend di un mio progetto che ho creato nel mio tempo libero: GasLow. Sostanzialmente è un backend che è in grado di recuperare gli open data che riguardano i prezzi dei carburanti in Italia e di fornire queste informazioni in base alla propria posizione. L’app Android, basata su Flutter, che utilizza questo backend è disponibile gratuitamente sul Play Store.

La cosa importante per noi sono queste:

Il backend è scritto in Node.js + TypeScript, il database è MongoDB.
Il file di configurazione con i dati per connettersi al DB si trova nel file .env, nella root del progetto. Ovviamente il file non è pubblicato su Git per evitare che il mondo intero sappia le credenziali del DB. Potete vedere un esempio di dati contenuti in questo file leggendo .env.example.
Il server di “produzione” si trova su Heroku su una macchina gratuita. In questa guida saremo in grado di automatizzare il deploy su Heroku.
Sto implementando anche la versione AWS serverless, dove viene deployata usando CloudFormation. Purtroppo questa parte è un po’ troppo da spiegare in questa guida introduttiva sulla CI/CD. Magari farò una guida dedicata su questo argomento in futuro.

Prerequisiti

Per capire a pieno questa guida abbiamo bisogno di queste conoscenze:

Un minimo di conoscenza di Git.
Com’è strutturato un progetto in Node.js e i comandi base del suo package manager npm. Questa parte in realtà non è obbligatoria per capire la pipeline come concetto, serve solamente per capire la pipeline di questo esempio specifico.

Scegliamo il servizio di CI/CD

Il primo passo importante per automatizzare il tutto è scegliere il servizio che vogliamo utilizzare. La scelta è veramente ampia. Quelli che conosco ed ho utilizzato sono questi:

CircleCI: molto potente e flessibile. È hostato da loro e quindi non abbiamo bisogno di una nostra macchina per farlo girare. Offre un piano gratuito di 1000 minuti/mese sia per i vostri progetti pubblici che privati, non è male per un uso hobbista. Per ora è la mia prima scelta per i miei progetti privati ed era quello che usavo in Pirelli fino ad un mese fa.
GitLab: anche questo è potente quanto CircleCI. Si può utilizzare la versione hostata da loro come installarlo sulla vostra macchina. È un po’ diverso dagli altri perché offre un pacchetto completo per il vostro progetto (ha Git integrato quindi lo potete usare anche come repository). Per ora è la nostra prima scelta in Pirelli e stiamo infatti facendo una bella migrazione da CircleCI.
Travis CI: forse è un pelino più indietro rispetto ai primi due. Per esempio non è possibile fare ancora un deploy di tipo manuale, a meno di non inventarsi hack come questo. Per manuale intendo avere un bottone che ci permetta di eseguire un deploy solo dopo una conferma. Questa funzione per me è molto utile per avere pieno controllo di quando vogliamo fare il deploy in produzione. A parte questo piccolo neo ha un grossissimo vantaggio: è gratis per tutti i progetti pubblici! Proprio per questo motivo lo uso per i miei progetti pubblici (come GasLow). La nostra guida si baserà su Travis CI.
Jenkins: è una pietra miliare e il più antico di tutti. Io l’ho usato solo poche volte e sinceramente non mi ha mai entusiasmato più di tanto, soprattutto per quanto riguarda la UX. Ma questa è una mia opinione personale e quindi parecchio soggettiva.

Obiettivo della guida

In questa guida vorrei vivere con voi la creazione di una pipeline avendo un progetto già avviato e che è già in produzione. Perché farlo con un progetto già avviato? Perché è un caso d’uso tipico che si incontra al lavoro e probabilmente è la vostra situazione attuale, infine perché di “hello world” per la creazione della pipeline c’è già pieno il web. Ma solitamente sono esempi focalizzati sull’apprendimento del servizio che offre le pipeline, e non tanto per apprendere i concetti e le difficoltà che si incontrano nella vita reale.

Mettiamo in chiaro cosa vogliamo raggiungere: immaginiamo di essere al lavoro e come task della settimana ci è stato proposto di creare la pipeline CI/CD per il progetto GasLow. Alla fine della guida avremo una pipeline composta da due fasi:

Esecuzione dei test: passo fondamentale per ottenere la Continuous Integration (CI).
Deploy in produzione sulla macchina di Heroku: passo per ottenere il Continuous Deployment (CD).

Questo è il minimo indispensabile per ottenere una pipeline completa di CI/CD e per non allungare troppo la guida ci limiteremo a questi due passi. Una volta preso dimestichezza con l’argomento si può complicare la pipeline a piacere. Per esempio una tipica pipeline che utilizzo al lavoro è composta dai seguenti passi:

Build e unit tests dell’applicazione.
Creazione dell’immagine Docker attraverso il Dockerfile, push dell’immagine sul repository AWS ECR.
Migrazione del database e deploy dell’immagine Docker in ambiente di DEV.
Integration tests sull’ambiente di DEV.
Migrazione del database e deploy con conferma manuale in ambiente di QLT utilizzato dal nostro QA Team.
Migrazione del database e deploy con conferma manuale in ambiente di Produzione.

Registrazione a Travis CI

Questo passo è semplicissimo, vi basta andare sulla loro home page e premere sul bottone “SignUp”, inserite le vostre credenziali di GitHub, e a questo punto avete di fatto collegato Travis CI al vostro GitHub. Una volta fatto questo entrerete nella pagina principale di Travis CI.

sulla sinistra vi compariranno i vostri progetti GitHub che utilizzano Travis CI come servizio di CI/CD. All’inizio sarà vuoto ovviamente. Per ora non ci serve sapere altro.

Fork del progetto

Se volete provare con mano anche voi, potete fare il fork del mio progetto e buttare via il file .travis.yml perché lo ricreeremo insieme per formare la pipeline che abbiamo in mente. Il commit di riferimento ha come hash d09f1068a14ddcdb857f1ced90b532680b050917, quindi per essere perfettamente allineati a questa guida dovremo fare il checkout di questo specifico commit, non escludo che il progetto possa avere profonde modifiche nel corso del tempo.

git checkout d09f1068a14ddcdb857f1ced90b532680b050917

Una volta forkato e rimosso il file possiamo andare sui settaggi di Travis CI (menu utente in alto a destra -> Settings). In questa pagina dovrebbero comparire tutti i nostri repo, compreso questo appena forkato. Se non vedete nulla cliccate sul bottone Sync Account, per sincronizzare Travis CI. Poi possiamo vedere il repo gaslow come in figura, abilitiamo il toggle. Ora abbiamo la repo forkata, Travis CI pronto e connesso ad esso. Ora inizia la parte divertente: mettiamo in piedi il primo step della nostra pipeline.

Implementazione della pipeline di Continuous Integration (fase di testing)

Testing in locale

Prima di andare a creare la pipeline poniamoci questa domanda: come si eseguono i test in locale? Il modo migliore per creare una pipeline automatica è di pensare tutti i vari step che dobbiamo fare in locale per raggiungere lo stesso obiettivo. Qui do per scontato che abbiamo un minimo di esperienza in Node.js e come funziona il package manager npm.

Uno che mastica Node.js da mattina a sera ha già pensato a come si fa: c’è il comando npm test… Ma siamo sicuri che basta solo questo? In questo caso stiamo dando per scontato un po’ di cose che per Travis CI non lo saranno affatto.

Per eseguire i test con npm test stiamo dando per scontato i seguenti punti:

Sulla propria macchina c’è installato Node.js v8.
Sulla propria macchina abbiamo MongoDB installato e attivo sulla porta standard :27017.
Abbiamo installato tutte le dipendenze (tramite il comando npm install) e che quindi abbiamo la cartella node_modules correttamente popolata.

Quindi i passaggi corretti per eseguire i test su una macchina pulita sono i seguenti:

Installa Node.js v8.
Installa MongoDB e attivalo sulla porta di default :27017.
npm install per installare le dipendenze presenti nel file package.json e quindi popolare la cartella node_modules.
npm test per eseguire i test.

Testing usando Travis CI

Ora che abbiamo capito i passaggi in locale, proviamo a tradurli in passaggi che possono essere digeriti da Travis CI.

Per far eseguire automaticamente i test a Travis CI abbiamo bisogno di un mezzo per comunicare. Il modo di comunicare con questo servizio è il file .travis.yml, proprio il file che vi ho fatto cancellare durante il fork del progetto. L’estensione del file magari vi può essere sconosciuta. yml viene usato per il formato YAML che sta per (YAML Ain’t Markup Language). È diventato lo standard de-facto nel mondo DevOps perché da un lato è “espressivamente” molto potente, dall’altro è molto semplice da leggere per un umano. Questo formato, per quanto possa essere semplice da leggere, ha molte regole che ci vuole un po’ di tempo per padroneggiarle e conoscerle tutte. Comunque non dobbiamo preoccuparci più di tanto: noi useremo solo il minimo indispensabile e dei concetti molto di base. Io di solito utilizzo Learn yaml in Y minutes come cheatsheet per lo yaml: questo sito è molto conciso ed allo stesso tempo ricco di informazioni; dateci un’occhiata anche per altri linguaggi, non ve ne pentirete.

Iniziamo con il creare il file .travis.yml nella root di progetto. Al suo interno inseriamo questo contenuto:

language: node_js

node_js: '8'

services:
  - mongodb

install: npm install
script: npm test

In questo modo, Travis CI è in grado di far girare i nostri test. Proviamo a committare il file, effettivamente vediamo che Travis CI ha iniziato a lavorare e che ha eseguito i test.

Ora proviamo a vedere le similitudini con i passaggi che avevamo bisogno in locale:

Abbiamo detto a Travis CI di installare Node.js v8? Sì attraverso la direttiva
```
language: node_js

node_js: '8'
```
Abbiamo detto a Travis CI di installare MongoDB e di aprire la porta standard di Mongo? Sì attravers la direttiva
```
services:
  - mongodb
```
Abbiamo installato le dipendenze del progetto prima di eseguire i test? Sì attraverso l’esecuzione dello script npm install durante la fase di installazione del nostro job, attraverso la direttiva
```
install: npm install
```
Abbiamo fatto girare i test? Sì attraverso l’esecuzione dello script npm test durante la fase principale del job, tramite la direttiva
```
script: npm test
```

Quindi possiamo dire di aver eseguito gli stessi passaggi che facevamo in locale usando un linguaggio che Travis CI capisce. Non voglio dilungarmi troppo sul linguaggio che utilizza Travis CI perché è molto specifico al servizio che stiamo utilizzando: CircleCI, GitLab avrebbero usato un linguaggio leggermente diverso. Quello che deve passare qui è questo: Travis CI è come se fosse un foglio di carta bianco, siamo noi che dobbiamo istruirlo come eseguire i nostri test. Il modo migliore di istruirlo è di pensare prima ai passaggi che facciamo in locale, poi li rifacciamo nel linguaggio della piattaforma che noi utilizziamo.

Per chi volesse saperne di più sul linguaggio specifico di Travis CI, lascio qui dei link che approfondiscono gli argomenti appena trattati:

Per conoscere i linguaggi supportati, nello specifico JavaScript.
Per sapere come aggiungere dei nuovi servizi come MongoDB.
Per conoscere le varie fasi di un job.

Deployment usando Travis CI

Ora che abbiamo eseguito i test vogliamo deployare il nostro codice su Heroku. Heroku, per chi non lo conoscesse, permette di deployare il proprio codice sulla loro piattaforma PaaS.

Prima di creare la pipeline, abbiamo bisogno di creare un’applicazione su Heroku, fortunatamente danno la possibilità di ospitare il nostro progetto gratuitamente.

Ci registriamo e creiamo una nuova app.

Ora torniamo sul file .travis.yml e aggiungiamo alla fine:

before_deploy:
  - <STEP_MISTERIOSO>
  - npm run build
deploy:
  provider: heroku
  api_key:
    secure: '<API_KEY>'
  app: <HEROKU_APP>
  on:
    branch: master
  env:
    - NODE_ENV=production
  skip_cleanup: true

Una piccola spiegazione di quello che abbiamo aggiunto:

before_deploy è la keyword per definire cosa bisogna fare appena prima della fase di deploy. La fase di deploy è il passo all’interno di un job che è adibito a deployare il nostro codice su Heroku. Il job, per Travis CI, si compone essenzialmente di tre fasi: install, script e deploy. Se volete approfondire, potete leggere direttamente dalla documentazione di Travis CI le varie fasi che compongono un job.
<STEP_MISTERIOSO> è un passo essenziale per il deploy che non vi ho ancora detto, ne parlo più avanti.
npm run build è lo script che dobbiamo eseguire prima del deploy. Questo script è legato strettamente al nostro progetto. Se siete curiosi potete andare nel file package.json e vedere che lo script build esegue il comando parcel build src/server.ts --target node. Esso non fa altro che chiamare Parcel.js transpilare il codice TypeScript in JavaScript, fare il bundling, minificarlo e inserirlo nella cartella /dist. Alla fine di questo progetto abbiamo quindi il file /dist/server.js pronto per essere eseguito in produzione.
deploy è la keyword per definire cosa bisogna fare durante la fase di deploy.
Con provider definiamo che stiamo usando Heroku come piattaforma.
api_key serve per definire le credenziali per poter effettivamente deployare con Heroku. Il prossimo passo sarà di sostituire '<API_KEY>' con le vere chiavi (criptate).
app: <HEROKU_APP> indichiamo a Travis CI su quale app di Heroku vogliamo fare il deploy. Dobbiamo sostituire <HEROKU_APP> con il nome dell’applicazione Heroku che abbiamo creato nel passo precedente.
Con on: branch: master possiamo fare il deploy solo quando pushiamo sul branch master. Senza questa direttiva ogni singolo push su un qualsiasi branch git farebbe scatenare il deploy automatico.
Con env: possiamo definire le variabili d’ambiente che il nostro progetto avrà a disposizione su Heroku. Nel nostro caso abbiamo aggiunto la variabile NODE_ENV=production che è uno standard nel mondo Node.js per definire che siamo su un ambiente di produzione.
skip_cleanup: true ci permette di evitare la cancellazione dei file generati nel passo precedente. Durante la fase di test abbiamo eseguito il comando npm install che popola la cartella node_modules che è essenziale per il corretto funzionamento del sistema. In questo modo possiamo evitare di rifarlo e quindi risparmiamo del tempo nella fase di deploy. Dobbiamo immaginare che la fase di deploy è separata dalla fase di script, quindi avremmo solo il codice sorgente senza questa direttiva.

Se vogliamo conoscere tutti i vari parametri che possiamo utilizzare per fare un deploy su Heroku possiamo leggere la documentazione ufficiale.

Ricapitolando ci sono ancora due cose da fare:

Capire cosa dobbiamo fare nello STEP_MISTERIOSO: ha a che fare con la configurazione del nostro progetto in produzione. Vi do un indizio: andate a leggere il file src/util/secrets.ts.
Recuperare l’API_KEY di Heroku criptata per far sì che Travis CI possa autenticarsi ed eseguire il deploy.

Capire lo step misterioso

C’è una parte che ho tenuto nascosto fin dall’inizio e che ora è giunto il momento di parlarne. Abbiamo detto che il progetto si basa su MongoDB, ma dove prende le credenziali per collegarsi? Abbiamo eseguito dei test precedentemente, eppure pare che si sia connesso senza problemi. Anche Travis CI, durante i test, si è connesso. Il recupero delle informazioni sulla connessione possiamo leggerlo nel file src/util/secrets.ts che riporto qui per semplicità:

import logger from "./logger";
import dotenv from "dotenv";
import fs from "fs";

if (fs.existsSync(".env")) {
    logger.debug("Using .env file to supply config environment variables");
    dotenv.config({ path: ".env" });
} else {
    logger.debug("Using .env.example file to supply config environment variables");
    dotenv.config({ path: ".env.example" });  // you can delete this after you create your own .env file!
}
export const ENVIRONMENT = process.env.NODE_ENV;
const prod = ENVIRONMENT === "production"; // Anything else is treated as 'dev'

export const SESSION_SECRET = process.env["SESSION_SECRET"];
export const MONGODB_URI = prod ? process.env["MONGODB_URI"] : process.env["MONGODB_URI_LOCAL"];

if (!SESSION_SECRET) {
    logger.error("No client secret. Set SESSION_SECRET environment variable.");
    process.exit(1);
}

if (!MONGODB_URI) {
    logger.error("No mongo connection string. Set MONGODB_URI environment variable.");
    process.exit(1);
}

In pratica il codice si comporta in questo modo:

Recupera il file .env, se non c’è fai il fallback sul file .env.example.
Recupera il valore SESSION_SECRET da questo file.
Recupera il valore MONGODB_URI se sei in produzione, altrimenti MONGODB_URI_LOCAL.

Finalmente possiamo capire come facevano i test a collegarsi a MongoDB senza che noi facessimo nulla: in pratica faceva il fallback sul file .env.example che è versionato su Git, andava a leggete il valore MONGODB_URI_LOCAL=mongodb://localhost:27017 e quindi si collegava al nostro MongoDB locale, mentre Travis CI si collegava al servizio MongoDB che abbiamo instanziato nella pipeline.

Il nostro compito è quello di trovare un modo per caricare il file .env in produzione in modo sicuro, versionato, ma allo stesso tempo che non abbia scritto in chiaro tutte le credenziali per accedere al nostro MongoDB.

Caricare in modo sicuro il file .env

Una soluzione al problema precedente ci è data direttamente da Travis CI. Per questo step abbiamo bisogno di Travis CI Command Line Client che su Mac possiamo installare in questo modo:

sudo gem install travis
travis login

Grazie ad esso possiamo criptare i file in modo sicuro e salvare nella repo il file criptato senza aver paura che qualcuno possa rubarci le credenziali.

Il primo passo è quello di creare il file di configurazione .env pronto per la produzione, dobbiamo stare attenti a non caricarlo per nessun motivo su Git, non è criptato e se lo versioniamo chiunque è in grado di accedere al nostro DB! Se state lavorando sul mio progetto ci ho già pensato io. Se andiamo infatti nel file .gitignore notiamo che il file .env è nella blacklist dei file da non tenere in considerazione con Git.

Allora creiamo il file .env con gli stessi dati che trovate nel file .env.example

# Get this from https://mlab.com/home after you've logged in and created a database
MONGODB_URI=mongodb://<mlab_user>:<mlab_password>@<mlab_connection_url>

# This is standard running mongodb locally
MONGODB_URI_LOCAL=mongodb://localhost:27017

SESSION_SECRET=<session_secret>

Dobbiamo modificare due parti:

In MONGODB_URI, sostituiamo <mlab_user>, <mlab_password>, <mlab_connection_url> con le nostre credenziali del DB che vogliamo usare in produzione. Io utilizzo il servizio mLab.
Sostituiamo <session_secret> con una stringa alfanumerica casuale.

Ora cancelliamo il file .env.enc, dove ci sono le mie chiavi criptate, perché ora andremo a creare il nostro file criptato. Con i valori che abbiamo appena inserito nel file .env. Per questo passo usiamo le linea di comando di Travis CI.

travis encrypt-file .env

Il terminale vi dirà di inserire nel file .travis.yml una stringa del genere

openssl aes-256-cbc -K $encrypted_0a6446eb3ae3_key -iv $encrypted_0a6446eb3ae3_iv -in .env.enc -out .env -d

questo è esattamente quello che dobbiamo scrivere nello step misterioso! Andiamo allora ad aggiornare il file .travis.yml, la fase before_deploy sarà così

before_deploy:
  - openssl aes-256-cbc -K $encrypted_0a6446eb3ae3_key -iv $encrypted_0a6446eb3ae3_iv -in .env.enc -out .env -d
  - npm run build

Il comando che abbiamo appena aggiunto non fa altro che decodificare il file criptato prima di fare il deploy.

Ottenere l’API key criptata di Heroku

Siamo quasi alla fine, ora ci manca solo di inserire nella nostra pipeline l’API key criptata per permettere a Travis CI di poter fare il deploy tramite Heroku.

Per questo passo abbiamo bisogno di Heroku CLI installato sul nostro PC. Se avete Mac vi basta scrivere nel terminale (se avete installato brew)

brew tap heroku/brew && brew install heroku

Ci autentichiamo con Heroku usando il comando

heroku login

ed infine scriviamo questo comando per ottenere l’API Key

travis encrypt $(heroku auth:token)

Il comando ci ritornerà l’API Key, dobbiamo inserirla al posto di '<API_KEY>' nel file .travis.yml. Fatto questo avremo quindi concluso il lavoro e possiamo goderci la nostra pipeline di Continuous Integration e Continuous Deployment!

Consigli sulla creazione delle pipeline

Ora che abbiamo visto un caso d’uso reale voglio condividere con voi qualche consiglio. Spero che vi faranno evitare un po’ di mal di testa che invece mi sono beccato:

Prima la creiamo più è semplice

L’implementazione della CI/CD prima la si crea, più si risparmia tempo, ma soprattutto più è semplice! Idealmente è meglio farla durante la creazione del progetto. Le motivazioni sono tante:

Durante la creazione del progetto stiamo già lavorando sulla questione configurazione e dipendenze del progetto. Quindi tutto quello che stiamo facendo localmente per impostare il nostro ambiente locale, ci basta fare il corrispettivo nella pipeline. Inoltre se sappiamo che stiamo implementando una pipeline fin dall’inizio, evitiamo di creare dei test o delle configurazioni che sono troppo legate alla nostra macchina locale, evitiamo di scrivere configurazioni strane che ci complicano la pipeline proprio perché ci è difficile replicarlo in Travis CI (come per esempio il recupero di file che si trovano in cartelle al di fuori del nostro progetto Git).
Non dobbiamo fare Reverse Engineering sul progetto per capire come configurarlo: nessuno ci avvertirà di trovare “lo step misterioso” nella vita reale e nessuno ci dirà di guardare il file src/util/secrets.ts per avere qualche indizio. In questa guida l’ho fatto per evitare di perdere troppo tempo. Senza questo aiuto avremmo dovuto sbattere la testa numerose volte e fare un minimo di Reverse Engineering del progetto per capire effettivamente come funzionava il recupero delle credenziali. Tutto questo poteva essere evitato se chi ha ideato questo recupero delle credenziali, avesse mantenuto aggiornata la pipeline. E chi è nuovo sul progetto, gli basta vedere il file .travis.yml per capire esattamente il procedimento per ottenere una versione locale funzionante.
Si evita l’errore umano nei deploy: averlo automatizzato è un vantaggio perché non si hanno errori grossolani nel deploy. Immaginate che voi dobbiate eseguire numerosi deploy al giorno… Dopo un po’ abbasserete la guardia e la concentrazione, l’errore per disattenzione è dietro l’angolo e fare errori nel deploy può costare molto caro!
Si risparmia tempo: banalmente prima creiamo una pipeline più ore uomo risparmiamo. Nessuno in azienda è responsabile del deploy, chiunque può farlo. Sono stato in aziende dove il deploy era manuale, e ho visto una persona che era occupata tempo pieno solo per i deploy nei momenti più frenetici. Secondo me è inaccettabile. Gli strumenti per automatizzare ci sono e sono alla portata di tutti. Usiamoli!

Pensiamo ad impostare la pipeline in locale

Provare direttamente su Travis CI può portare via molto tempo. Per esempio se abbiamo problemi nel deploy, dobbiamo pushare le nuove modifiche, attendere tutti i passi precedenti e poi magari ritrovarsi un bell’errore dopo 15 minuti. In questo caso tentiamo di fixare il problema caricando le nuove modifiche e il ciclo ricomincia… Tutto questo porta via ore. Il modo migliore per evitare tutto questo è provare localmente i passaggi. Un po’ come abbiamo fatto in questa guida durante la creazione della pipeline di Continuous Integration. Per raggiungere questo obiettivo dobbiamo creare degli step che siano agnostici rispetto al servizio di CI/CD che utilizziamo. Solitamente io creo una cartella con tutti gli script utili per il deploy. In questo modo posso invocare questi script anche in locale e testare più velocemente la corretta esecuzione. Inoltre se teniamo in mente questo punto sarà più facile anche raggiungere il prossimo.

Non focalizziamoci troppo sul singolo servizio di CI/CD

In questa guida abbiamo usato Travis CI, nel lavoro precedentemente usavamo Jenkins. Nel lavoro attuale usavamo CircleCI, ora invece usiamo GitLab CI. Insomma vi capiterà di usare di tutto che però tutti risolvono lo stesso problema: automatizzare l’integrazione ed il deploy. Cerchiamo quindi di focalizzarci sui concetti di base e non tanto su come farlo su uno specifico servizio. Quest’ultima parte è semplice se abbiamo chiaro cosa dobbiamo raggiungere: basta leggere la guida del servizio specifico. Questo modo di lavorare ci dà parecchia flessibilità sia al lavoro che nei nostri progetti hobbisti. Infine questa flessibilità ci rende liberi di usare un servizio in base ai vantaggi che esso porta: in questa guida abbiamo usato appunto Travis CI perché è gratuito per i progetti open source, ma non è di certo il migliore sulla piazza. Questo non sarebbe possibile se usassimo solo ed esclusivamente un servizio.

Leggiamo delle pipeline già fatte

Dobbiamo ricordarci che non siamo gli unici sulla faccia della terra che stanno pensando di creare una pipeline. Non sottovalutiamo quindi la possibilità di vedere le pipeline dei progetti open source! Ci sono numerosi progetti su GitHub che mostrano degli esempi pratici di pipeline che molto probabilmente risolvono tutto o in parte i nostri problemi. Così facendo possiamo vedere anche dei modi diversi di ragionare che è sempre utile per migliorare il proprio bagaglio culturale. Ricordo infine che Travis CI è gratis per i progetti open source, è il motivo principale per cui ho deciso di scrivere questa guida. Quindi GitHub è pieno di pipeline fatte con Travis CI!

Non cerchiamo la perfezione

Ricordiamoci che il nostro lavoro non è di passare giorni a fare pipeline. È sempre possibile ottimizzarla per velocizzarla, ma come tutte le ottimizzazioni richiedono tempo. Il mio consiglio è di raggiungere il minimo indispensabile per raggiungere l’obiettivo, anche se magari non è la soluzione più elegante possibile. Poi ricordiamoci che col tempo impariamo nuovi concetti, come per esempio il caching e la possibilità di eseguire più job in parallelo, conosciamo meglio il sistema e quindi sarà più semplice per noi ottimizzarla impiegandoci meno tempo. Quindi teniamo sempre a mente che la pipeline è uno strumento che velocizza e automatizza il nostro lavoro… Ma se impiega 5 minuti o 10 minuti cambia davvero poco lato nostro, quindi non spendiamo ore o giorni per queste ottimizzazioni, soprattutto nei primi stadi dove le sfide sono già tante.

Conclusioni

Spero che con questa guida abbiate toccato con mano cosa significhi implementare una pipeline di Continuous Integration e Continuous Delivery su un progetto già esistente. Le difficoltà, come abbiamo visto, sono maggiori se il progetto è già avviato. Quindi, la prossima volta che inizierete a costruire una vostra idea, ricordatevi di pensare subito alla pipeline CI/CD; non ve ne pentirete. In questo modo potrete delegare questi task ad una macchina e voi potrete concentrarvi esclusivamente a ciò che porta realmente valore al vostro progetto: lo sviluppo del codice.

Alla prossima!

Come programmare in Test-Driven Development (TDD) partendo da zero

Fri, 28 Dec 2018 07:03:47 GMT

TDD di qui, TDD di là, tutti ne parlano. Molti ne elogiano i pregi, altri dicono che è una perdita di tempo… Ma alla fine come si procede a sviluppare in TDD?

In questa guida potrai vedere un esempio reale sviluppato in Test-Driven Development. Questa tecnica di programmazione la sto adottando da oltre un anno per i backend che sviluppo in Java, Python e TypeScript. I benefici nel codice che ho scritto sono visibili e molti. Spero di riuscire a convincerti che questa tecnica:

Migliora la qualità del codice.
Diminuisce il tempo speso in debugging e la ricerca di eventuali regressioni del software.
Diminuisce il numero di bug che riescono a raggiungere la produzione.
Semplifica lo sviluppo di applicativi complessi.
È più semplice di quanto sembri.

Come posso convincerti di tutte queste cose? Spero di farcela attraverso un esempio pratico partendo completamente da zero.

Obiettivo

In questa guida svilupperemo una classe che prende in input un’URL e una parola da cercare nella pagina che abbiamo inserito. In questa ricerca ci risponderà dicendo quante volte ha trovato la parola.

Faremo questo semplice applicativo in Node.Js + TypeScript, interamente in TDD. Durante questo sviluppo spiegherò tutti i passaggi e espliciterò tutti i vantaggi che sta introducendo il TDD.

Prerequisiti

Per seguire la guida dovresti avere:

Installato Node.js.
Un minimo di esperienza con Node.js. TypeScript, se non lo hai mai usato, è JavaScript con i tipi, per ora è tutto quello che devi sapere.
Per la seconda parte c’è bisogno di sapere il concetto di programmazione asincrona in JavaScript: andremo ad utilizzare le Promise e le keyword async e await.
Un sistema UNIX (Linux o Mac). Oppure aver abilitato il WSL su Windows.

Se per caso ti stai perdendo, in questa repo su GitHub puoi trovare il prodotto finito. Ma ti consiglio di non “sbirciare” la soluzione perché introdurremo molti concetti nel corso dell’articolo. Vedere il progetto finito senza sapere come ci siamo arrivati non apporta alcun beneficio nell’apprendimento.

Creazione del progetto

Il primo passo è ovviamente creare il progetto. Per questo apriamo il terminale in una cartella su cui lavoreremo. La mia cartella si chiamerà word-counter.

mkdir word-counter
cd word-counter

Creiamo il file package.json dove inseriremo le varie dipendenze Node.js e gli scripts.

npm init

Inseriamo i vari dati che ci chiede. Per ora possiamo anche solo premere Enter e mantenere i valori di default.

Aggiunta delle dipendenze

Ora possiamo inserire il minimo indispensabile per poter iniziare a sviluppare in TDD. Le dipendenze che ci servono sono:

TypeScript: per sviluppare con questo linguaggio.
TSLint: il linter di TypeScript che ci aiuterà nello sviluppo per scrivere codice pulito. Questo è opzionale, ma io solitamente lo aggiungo sempre per avere un ottimo aiuto durante lo sviluppo. Inoltre è integrato molto bene con Visual Studio Code, che è il mio Text Editor preferito per quanto riguarda il mondo Node.js.
Jest: la nostra piattaforma di testing.

Per installare tutto questo scriviamo

npm install --save-dev typescript tslint jest ts-jest @types/jest

Possiamo verificare che in package.json sono state aggiunte queste cinque dipendenze in devDependencies, ossia sono dipendenze che servono per lo sviluppo e non al programma vero e proprio. Inoltre possiamo notare che queste dipendenze sono state scaricare nella cartella node_modules.

Il comando dovrebbe essere chiaro, l’unica parte che forse ha bisogno di spiegazione sono le librerie per Jest. Infatti abbiamo installato tre dipendenze per far girar il tutto.

jest è la nostra piattaforma di testing.
ts-jest è il transpilatore che transforma TypeScript in JavaScript prima di far girare i test. Senza di esso dovremmo ogni volta transpilare manualmente il codice, cosa che vogliamo assolutamente evitare per non perdere tempo.
@types/jest serve a TypeScript per sapere i tipi che sono dentro la libreria di Jest. Immagina che molte volte le librerie sono scritte in JavaScript, quindi TypeScript non avrebbe idea di cosa le funzioni accettano in input o restituiscono in output. Fortunatamente ci sono degli sviluppatori che creano delle librerie che mappano le funzioni JavaScript in TypeScript. Solitamente per installare questi mapping si installa la dipendenza @types/<LIBRERIA_DA_MAPPARE>. Se volete sapere di più per quanto riguarda queste dichiarazione dei tipi in TypeScript potete leggervi direttamente dal sito di DefinitelyTyped, ma per questa guida non è necessario approfondire oltre.

Inizializzazione

Ora che abbiamo scaricato le librerie, dobbiamo configurarle per farle funzionare al meglio. Iniziamo con TypeScript

npx typescript --init

Il comando significa:

npx: avvia un programma che puoi trovare nella cartella node_modules.
typescript --init: il comando di inizializzazione di TypeScript.

Dovrebbe aver creato il file tsconfig.json con i vari parametri di configurazione. Entriamo in questo file e dovremmo vedere commentato la parte // "lib": [],, decommentiamola e scriviamo:

"lib": [
  "es2015"
]

Così facendo possiamo usare le keyword async e await quando avremo a che fare con le Promise.

Ora passiamo a TSLint

npx tslint --init

Possiamo effettivamente vedere che è stato creato un file nella root con il nome tslin.json. Per ora va benissimo così, non lo tocchiamo.

Ora inizializziamo Jest, la nostra piattaforma di test, più o meno come abbiamo fatto con TSLint

npx jest --init

Dovrebbe riconoscere in automatico che c’è TypeScript, creare il file jest.config.js con all’interno la configurazione di default di Jest, ed infine ha inserito in package.json lo script test. In questo modo quando scriviamo in console npm test, Jest si avvia ed esegue tutti i test.

Qui dobbiamo fare una piccola modifica al file jest.config.js: dobbiamo rinominare il campo da globals.ts-jest.tsConfigFile a globals.ts-jest.tsConfig per evitare un messaggio di warning durante i test. Quindi dovremo rinominare quella parte di configurazione in questo modo:

globals: {
  "ts-jest": {
    "tsConfig": "tsconfig.json"
  }
}

Per essere sicuri di aver fatto tutto proviamo a scrivere finalmente un test: lo inseriremo nella cartella src/__tests__ e lo chiamiamo hello-test.ts.

Quindi scriviamo nel file src/__tests__/hello-test.ts:

test("should work", () => {
  expect(true).toBe(true);
});

Il test appena scritto non fa altro che verificare che true sia effettivamente true. A che serve? Nella vita reale a niente, ma nel nostro caso specifico serve a noi per capire che Jest sia configurato correttamente.

Avviamo i test con npm test e dovresti avere un risultato simile al mio.

$ npm test

> word-counter@1.0.0 test /Users/mattia/Repositories/word-counter
> jest

 PASS  src/__tests__/hello-test.ts
  ✓ should work (5ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        1.553s
Ran all test suites.

Perfetto! Il nostro primo test in TypeScript ha funzionato.

Analisi del progetto

Ora si inizia a fare sul serio: riprendiamo il nostro obiettivo e cominciamo a pensare come creare l’architettura.

Per raggiungere l’obiettivo abbiamo bisogno di tre parti:

Raccolta dei valori di input (URL e parola da cercare).
Scaricamento della pagina web.
Conteggio della parola nella pagina web appena scaricata.

Test-Driven Development: si inizia!

Da dove iniziamo? Ovviamente con un test! Alla fine siamo qui per questo no? Imparare il Test-Driven Development. Come si fa ad iniziare con un test? Bisogna pensare a come creare un’architettura che possa essere facilmente testabile, dove ogni test controlla solo un unico aspetto del progetto.

Utilizzeremo un approccio bottom-up per creare il progetto, ossia inizieremo dalla parte più semplice, autocontenuta che non ha bisogno di nessuna dipendenza per funzionare. In questo caso è il punto 3.

Classe WordCounter

WordCounter è la nostra classe che serve per il “Conteggio della parola nella pagina web appena scaricata”. Possiamo tradurlo anche in questo modo: “Data una stringa in input text e una parola da cercare wordToFind, restituisce il numero di volte che wordToFind è contenuta in text“.

Iniziamo allora dal test: senza avere in mano questa classe WordCounter, che non esiste ancora, mi immagino di utilizzarla in questo modo:

const text = "testo scaricato";
const wordToFind = "testo";

const wordCounter = new WordCounter();

wordCounter.count(text, wordToFind); // Output 1

Vediamo di tradurre questo ipotetico utilizzo in un test. Nel nuovo file src/__tests__/word-counter.ts scriviamo:

import WordCounter from "../word-counter";

describe("WordCounter", () => {
  const wordCounter = new WordCounter();

  it("should count the word inside text", () => {
    expect(
      wordCounter.count("testo scaricato", "testo"),
    ).toBe(1);
  });
});

Qui ci serve sapere un minimo come funziona Jest. In poche parole, useremo la convenzione di inglobare i test che sono riferiti ad una classe usando la funzione describe, e poi ogni test della classe userà la funzione it che è il nostro test vero e proprio. La funziona it si compone di una stringa che spiega brevemente cosa andiamo a testare e una funzione che ha al suo interno la logica del test. Per maggiori approfondimenti ti consiglio la loro documentazione ufficiale.

Ora che abbiamo scritto il nostro primo test, possiamo notare un vantaggio nello scrivere in TDD: ci preoccupiamo solamente dell’interfaccia e non dell’implementazione. Alla fine, l’utilizzatore finale delle nostre classi, interessa solo come invocare una determinata funzione, e non come è stata fatta. Capita spesso in programmazione di buttarsi a capofitto nell’implementazione per poi avere un’interfaccia convoluta e poco chiara, proprio perché nella programmazione tradizionale lo sforzo cognitivo va tutto nell’implementazione e l’interfaccia è una cosa secondaria. Qui invece si ribalta il tutto.

Una regola molto importante nel TDD è di procedere a piccoli passi. Non dobbiamo scrivere mille test per poi passare all’implementazione. Si scrive un solo test, che fallisce, e poi il nostro obiettivo è di far funzionare il test implementando il codice necessario. Perché tutto questo? Essenzialmente per due motivi:

Sappiamo perfettamente qual è il nostro obiettivo, far passare l’unico test che fallisce. In questo modo il progetto può essere complesso a piacere, ma mettendoci solo un piccolo obiettivo il tutto diventa semplice, divide et impera funziona sempre!
Scriviamo il minimo indispensabile per far passare il test. Quanti di noi si sono messi a scrivere montagne di codice perché “Non si sa mai”, o perché la nostra mente ha pensato a mille casistiche che nessuno ha mai chiesto? Nel TDD non succede, ogni singola riga di codice è stata scritta per far passare un test. Se scriviamo altro stiamo sbagliando.

Ora che ci siamo detti che dobbiamo procedere a piccoli passi, andiamo effettivamente a scrivere il codice che renderà verde il nostro test. Prima di tutto verifichiamo che fallisca.

In console scriviamo npm test.

Come output abbiamo una cosa del genere.


> word-counter@1.0.0 test /Users/mattia/Repositories/word-counter
> jest

 PASS  src/__tests__/hello-test.ts
 FAIL  src/__tests__/word-counter.ts
  ● Test suite failed to run

    TypeScript diagnostics (customize using `[jest-config].globals.ts-jest.diagnostics` option):
    src/__tests__/word-counter.ts:1:25 - error TS2307: Cannot find module '../word-counter'.

    1 import WordCounter from "../word-counter";
                              ~~~~~~~~~~~~~~~~~

Test Suites: 1 failed, 1 passed, 2 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        1.557s
Ran all test suites.
npm ERR! Test failed.  See above for more details.

Il transpilatore di TypeScript si lamenta giustamente che la classe word-counter non esiste.

Ora scriviamo il minimo indispensabile per far passare il test. Andiamo a creare la classe e il metodo in src/word-counter.ts.

export default class WordCounter {
  public count(text: string, wordToFind: string): number {
    return 1;
  }
}

Facciamo girare il test con npm test. E questo è il risultato:


> word-counter@1.0.0 test /Users/mattia/Repositories/word-counter
> jest

 PASS  src/__tests__/hello-test.ts
 PASS  src/__tests__/word-counter.ts

Test Suites: 2 passed, 2 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        1.669s
Ran all test suites.

Ce l’abbiamo fatta! Ma immagino che ti sei accorto che ho barato. Il metodo che ho scritto restituisce sempre 1, indipendentemente dal testo passato. Ma questo non è sbagliato nel TDD perché il nostro obiettivo è far passare i test il prima possibile con il minimo indispensabile. Se sono riuscito a barare significa che il test non è abbastanza approfondito per verificare il corretto funzionamento del programma. Ora risolviamo scrivendo un test che ci obbliga a considerare l’input text. Nel file src/__tests__/word-counter.ts aggiungiamo

it("should count the word inside text (multiple)", () => {
  expect(wordCounter.count("pippo pippo ciao pippo", "pippo")).toBe(3);
  expect(wordCounter.count("ciao ciao", "ciao")).toBe(2);
  expect(wordCounter.count("ciao", "nonesistequestaparola")).toBe(0);
});

Facendo girare i test effettivamente questo test fallisce

> word-counter@1.0.0 test /Users/mattia/Repositories/word-counter
> jest

 FAIL  src/__tests__/word-counter.ts
  ● WordCounter › should count the word inside text (multiple)

    expect(received).toBe(expected) // Object.is equality

    Expected: 3
    Received: 1

      11 |
      12 |   it("should count the word inside text (multiple)", () => {
    > 13 |     expect(wordCounter.count("pippo pippo ciao pippo", "pippo")).toBe(3);
         |                                                                  ^
      14 |     expect(wordCounter.count("ciao ciao", "ciao")).toBe(2);
      15 |     expect(wordCounter.count("ciao", "nonesistequestaparola")).toBe(0);
      16 |   });

      at Object.<anonymous> (src/__tests__/word-counter.ts:13:66)

 PASS  src/__tests__/hello-test.ts

Test Suites: 1 failed, 1 passed, 2 total
Tests:       1 failed, 2 passed, 3 total
Snapshots:   0 total
Time:        1.612s
Ran all test suites.
npm ERR! Test failed.  See above for more details.

Ora cambiamo l’implementazione di WordCounter.count in src/word-counter.ts in modo tale da far passare il test

public count(text: string, wordToFind: string): number {
  return text
    .split(" ")
    .filter((word) => word === wordToFind)
    .length;
}

I test sono entrambi OK! …Ma c’è una cosa che non abbiamo testato, cosa succede se il testo da cercare è tutto minuscolo ma il testo è maiuscolo? Non lo sappiamo e non ci preoccupiamo nemmeno di scoprilo, ci basta scrivere un test per essere sicuri!

Aggiungiamo il test

it("should count the word case insensitive", () => {
  expect(wordCounter.count("Ciao ciao CIAO", "ciao")).toBe(3);
});

Facendo girare i test fallisce… Allora risolviamo!

public count(text: string, wordToFind: string): number {
  const wordToFindLower = wordToFind.toLowerCase();
  return text.toLowerCase()
    .split(" ")
    .filter((word) => word === wordToFindLower)
    .length;
}

Tutto ok, di nuovo. Ma non abbiamo considerato il testo dove la parola finisce con una virgola o un qualsiasi segno di interpunzione. Nuovo test

it("should count word that have signs nearby", () => {
  expect(wordCounter.count("ciao, ciao! ", "ciao")).toBe(2);
});

Nuova implementazione per gestire questo test che fallisce

public count(text: string, wordToFind: string): number {
    const wordToFindLower = wordToFind.toLowerCase();
    return text.toLowerCase()
      .split(/[^a-zA-Z\d]/)
      .filter((word) => word === wordToFindLower)
      .length;
  }

Tutto verde! Insomma ora è abbastanza chiaro come creare una classe in TDD. Abbiamo visto che è un continuo ping pong di test che falliscono e implementazione che risolve il fail.

Ma questo ping pong, oltre ai benefici che avevamo scritto in precedenza, ne porta anche altri:

Itera lo sviluppo di app complesse attraverso semplici passaggi, in modo incrementale: è palese che abbiamo iniziato con un’implementazione molto semplice, e poi, tramite piccoli passi, siamo arrivati ad avere un metodo che gestisce numerose casistiche che magari non avevamo neppure pensato inizialmente.
I test scritti in precedenza rimangono, l’implementazione cambia continuamente: forse tramite questo esempio non si nota molto, ma ogni volta che abbiamo aggiunto un nuovo test, e abbiamo cambiato l’implementazione, eravamo certi che anche i test precedentemente scritti continuano a funzionare. Questa certezza è fondamentale quando dobbiamo fare pesanti refactor dei metodi, senza il TDD questa certezza, il più delle volte, non esiste. Quindi si tende a non modificare il codice già esistente, si aggiunge il codice “attorno” per evitare di toccare una cosa “che funziona già” e quindi di evitare delle regressioni nel software. Questo comportamento funziona ma per un breve periodo, il codice perde facilmente di leggibilità, diventa confuso e oscuro, ed ecco a voi il famoso debito tecnico! Sono certo che vi è già capitato un codice del genere sottomano e non è divertente.
Tutte le funzionalità che ci servono sono testate: questo è gratis con il TDD. Scriviamo prima il test e poi l’implementazione, per forza di cose è vero.

Ormai ci sentiamo soddisfatti con la nostra classe WordCounter. In realtà ci sarebbe un’altra altra casistica da testare. Per esempio

Cosa succede se passiamo null ai due parametri?

Dobbiamo inserire il test anche per questo caso? La risposta è dipende. Se sappiamo che il nostro codice non deve gestire i null possiamo anche farne a meno. Molti potrebbero ribattere che così il codice non è robusto, ma in realtà il nostro obiettivo non è gestire tutti i casi del mondo, dobbiamo creare una classe che sia ok per il nostro progetto. Quindi bisogna cercare di rimanere focalizzati sull’obiettivo iniziale, in questo modo non complichiamo il codice con casi che non accadono mai e non perdiamo tempo a scrivere codice e test inutili.

Ora che siamo soddisfatti del nostro WordCounter passiamo alla classe successiva.

Classe TextFetcher

Questa classe risolve il punto 2 del nostro obiettivo. Ossia scarica una pagina web e recupera il testo da esso. Ormai sappiamo come funziona e, carichi come una molla, usiamo lo stesso procedimento usato con WordCounter:

Pensiamo all’interfaccia di TextFetcher: io mi immagino di utilizzarlo così new TextFetcher().getContent(url) e ci resituisce una Promise<string>, insomma ci restituisce una stringa in modo asincrono (non possiamo averlo sincrono perché la chiamata HTTP per recuperare il contenuto da un URL è lenta). Qui entra in gioco un prerequisito che avevo scritto in precedenza: la programmazione asincrona in JavaScript/TypeScript. Se volete capire fino in fondo gli esempi che andrò a scrivere vi consiglio le letture che ho inserito nella sezione prerequisiti.
Scriviamo il test per testare la futura implementazione.

import TextFetcher from "../text-fetcher"

describe("TextFetcher", () => {
  const textFetcher = new TextFetcher();

  it("should get the content as text", async () => {
    expect(
      await textFetcher.getContent("https://raw.githubusercontent.com/matitalatina/word-counter/master/README.md")
    ).toContain("WordCounter");
  });
});

Se apriamo l’URL che ho inserito nel test possiamo vedere che è il README.md della repository che sto utilizzando per creare questa app.

Al suo interno c’è la parola WordCounter. Il nostro test verifica che effettivamente l’istanza WordCounter scarica il README e ci restituisce il suo contenuto. Nel test cerco solo la parola WordCounter e non esattamente il contenuto perché il README potrebbe cambiare, ma almeno il nome del progetto spero che rimanga sempre!

Ora proviamo a far passare il test (senza barare per non appesantire troppo il discorso). Per fare la chiamata HTTP che scarica il file, utilizzo una libreria famosissima in Node.js che è Axios. Per questo motivo la installiamo tra le nostre dipendenze

npm install --save axios

Scriviamo una possibile implementazione in src/text-fetcher.ts

import axios from "axios";

export default class TextFetcher {
  public async getContent(url: string): Promise<string> {
    return (await axios.get(url)).data;
  }
}

Abbiamo sostanzialmente creato ed esportato la classe TextFetcher, creato il metodo asincrono async getContent, nell’implementazione usiamo axios per scaricare il contenuto dell’url, aspettiamo in modo asincrono che scarichi il contenuto usando la keyword await, infine prendiamo il contenuto della risposta usando la proprietà data.

Facciamo girare i test con npm test ed ecco che tutto funziona!

Però non so se senti anche tu un piccolo odore di “bruciato”… Se hai notato ho messo nel test un’URL che va a prendere una risorsa esterna al nostro programma, che potrebbe cambiare, potrebbe non essere accessibile perché abbiamo il PC offline. Tutto questo influenzerebbe il nostro test facendolo fallire anche se in realtà il codice è giusto.

Ricorda che gli unit tests devono essere veloci e non devono dipendere da fattori esterni. La chiamata HTTP può essere lenta per via della connessione se non addirittura fallire per possibili cambiamenti o disconnessioni.

Come possiamo risolvere questo problema? Andremo a mockare la chiamata HTTP.

Per fare questo abbiamo bisogno di un’altra libreria esterna: axios-mock-adapter.

npm install --save-dev axios-mock-adapter

Andiamo a modificare il test in src/__tests__/text-fetcher.ts

import axios from "axios";
import MockAdapter from "axios-mock-adapter";
import TextFetcher from "../text-fetcher";

describe("TextFetcher", () => {
  const textFetcher = new TextFetcher();

  const mock = new MockAdapter(axios);

  it("should get the content as text", async () => {
    const content = "Questo è il contenuto della pagina web";

    mock.onGet("/fake-url").reply(200, content);

    expect(
      await textFetcher.getContent("/fake-url"),
    ).toBe(content);
  });
});

Attraverso MockAdapter andiamo ad agganciarci alla libreria axios, in modo tale da creare delle chiamate HTTP false. Con mock.onGet("/fake-url").reply(200, content); andiamo a creare una finta risposta HTTP tramite l’indirizzo /fake-url con il valore della variabile content come contenuto. Infine andiamo a testare che la risposta sia effettivamente content.

Facendo girare i test funziona tutto e stavolta possiamo testare anche offline.

Mockare le chiamate HTTP esterne ai vari URL oppure ai microservizi esterni è fondamentale per avere una buona suite di test unitari. Non possiamo chiamare delle risorse reali durante i test unitari anche perché probabilmente queste risorse esistono sono nell’ambiente di produzione e noi non vogliamo sporcare il contenuto di produzione con dei test.

Classe CounterApp

Questa è l’ultima classe che andremo a costruire. Il suo obiettivo è quello di:

Invocare il TextFetcher per recuperare il testo dall’URL.
Invocare il WordCounter per contare quante volte la parola da cercare è contenuta nel testo scaricato.
Restituire il numero ritornato da WordCounter.

Negli unit tests di una classe non vogliamo testare l’implementazione anche delle sue dipendenze. Nel nostro caso non vogliamo testare di nuovo TextFetcher e WordCounter. Queste classi le abbiamo testate già bene. Per questo motivo andremo a mockare queste dipendenze un po’ come abbiamo fatto per le chiamate HTTP.

Mockando le dipendenze esterne da una classe porta i seguenti vantaggi:

Evitiamo che un errore nella dipendenza faccia fallire anche i test della classe che stiamo testando. Idealmente un errore nel codice dovrebbe far fallire un solo test, e non anche tutte le parti che dipendono da esso.

Abbiamo quindi bisogno di una libreria che si chiama ts-mockito che si ispira alla famosa libreria di Mock su Java chiamata Mockito.

Rende semplice creare dei casi speciali: immaginate che dobbiamo testare correttamente la gestione di un eccezione, la generazione di questa eccezione richiede una situazione molto particolare. Se mockiamo possiamo iniettare un mock che generi questa eccezione senza dover ricreare questa situazione speciale.

Mettiamo in pratica ciò che ci siamo detti. Primo passo è installare ts-mockito.

npm install --save-dev ts-mockito

Andiamo a scrivere il test nel nuovo file src/__tests__/counter-app.ts

import { instance, mock, when } from "ts-mockito";
import CounterApp from "../counter-app";
import TextFetcher from "../text-fetcher";
import WordCounter from "../word-counter";

describe("CounterApp", () => {
  // Initialization
  const mockWordCounter: WordCounter = mock(WordCounter);
  const mockTextFetcher: TextFetcher = mock(TextFetcher);
  const counterApp = new CounterApp(instance(mockTextFetcher), instance(mockWordCounter));

  it("should get parameters and return the count", async () => {
    const providedUrl = "url";
    const providedWordToFind = "word";
    const fakeContent = "Testo recuperato";
    const expectedCount = 1;

    when(mockTextFetcher.getContent(providedUrl))
      .thenReturn(Promise.resolve(fakeContent));
    when(mockWordCounter.count(fakeContent, providedWordToFind))
      .thenReturn(expectedCount);

    expect(await counterApp.countWordFromUrl(providedUrl, providedWordToFind))
      .toBe(expectedCount);
  });
});

Nell’inizializzazione andiamo a creare i mock delle nostre due classi WordCounter e TextFetcher, con la riga new CounterApp(instance(mockTextFetcher), instance(mockWordCounter)) andiamo ad inserire le istanze dei nostri mock nel costruttore della classe CounterApp. Questa tecnica di “iniettare” le dipendenze utilizzate direttamente nel suo costruttore si sposa bene con i frameworks che utilizzano la dependency injection. Se quest’ultima frase che ho scritto è puro arabo, non preoccuparti. Il messaggio che deve passare è questo: è buona prassi richiedere nel costruttore le dipendenze esterne che la classe ha bisogno per funzionare correttamente. Questo è vero per due motivi:

Indica chiaramente al programmatore che utilizza la vostra classe, quali dipendenze ha bisogno per svolgere la propria funzione.
Rende facile i test della classe in questione, perché nel costruttori possiamo iniettare delle istanze mockate, come nel nostro caso.

La parte all’interno del test it("should get parameters and return the count", ...) dovrebbe essere abbastanza autoesplicativa: creo le variabili che mi aspetto di utilizzare e poi utilizzo ts-mockito per fare le dovute asserzioni. Per esempio con when(mockTextFetcher.getContent(providedUrl)).thenReturn(Promise.resolve(fakeContent)); significa: “quando la classe chiama textFetcher utilizzando il metodo getContent con il parametro providedUrl, ritorna una Promise risolta con il valore fakeContent”. La funzionalità when(...).thenReturn(...) serve a noi per bypassare la vera implementazione delle classi mockate e ritornare un valore che decidiamo noi.

Così facendo stiamo testando:

Che la classe CounterApp chiami i metodi delle classi WordCounter e TextFetcher con i parametri corretti, tramite i vari when(...).thenReturn(...).
Che la classe CounterApp ritorni il numero corretto tramite expect(...).toBe(...).

Facciamo girare i test con npm test. Chiaramente fallisce, ora andiamo ad implementare la classe nel nuovo file src/counter-app.ts;

import TextFetcher from "./text-fetcher";
import WordCounter from "./word-counter";

export default class CounterApp {
  constructor(private textFetcher: TextFetcher, private wordCounter: WordCounter) {

  }

  public async countWordFromUrl(url: string, wordToFind: string): Promise<number> {
    const text = await this.textFetcher.getContent(url);
    return this.wordCounter.count(text, wordToFind);
  }
}

Abbiamo creato un costruttore che inserisce nelle variabili private textFetcher e wordCounter le istanze di TextFetcher e WordCounter (il costruttore è vuoto, sembra che non faccia niente, ma il lavoro sporco lo sta facendo la keyword private). Poi abbiamo implementato il metodo asincrono countWordFromUrl che non fa altro che scaricare il contenuto dall’URL e poi conteggia il numero delle volte che compare la parola che stiamo cercando e lo ritorna.

Proviamo con npm test ed effettivamente è tutto ok!

Prova reale

Ora che finalmente abbiamo raggiunto il nostro obiettivo, programmando completamente in TDD, proviamo a fare una prova reale.

Creiamo il file src/index.ts dove inserirò un piccolo script per provare il tutto.

import CounterApp from "./counter-app";
import TextFetcher from "./text-fetcher";
import WordCounter from "./word-counter";

async function testApp() {
  const url = "https://raw.githubusercontent.com/matitalatina/word-counter/master/README.md";
  const wordToFind = "WordCounter";

  const count = await new CounterApp(new TextFetcher(), new WordCounter())
    .countWordFromUrl(url, wordToFind);

  console.log(`The word "${wordToFind}", in ${url}, appears ${count} times`);
}

testApp();

Ho creato una piccola funzione testApp dove crea la mia classe CounterApp con le dovute dipendenze, e provo a contare quante volte compare la parola WordCounter dalla pagina README.md della mia repository per questo progetto. Per avviare il programma, ho bisogno di transpilare TypeScript in JavaScript, perché come sappiamo Node.js non sa leggere direttamente TypeScript. Per risolvere utilizzerò la libreria ts-node.

npm install --save-dev ts-node

Ora che è installato, avviamo il nostro script in questo modo

npx ts-node src/index.ts

Il risultato è questo:

The word "WordCounter", in https://raw.githubusercontent.com/matitalatina/word-counter/master/README.md, appears 1 times

Funziona!!!

Mantenimento del progetto

Abbiamo finito il nostro piccolo progettino in TDD. Ma un vero progetto che si rispetti non è mai “finito”, bisogna mantenerlo e migliorarlo ogni giorno. Un altro vantaggio che ho apprezzato dopo qualche mese di sviluppo in TDD è il tempo drasticamente calato in termini di debugging o di bug in produzione. Quindi il tempo speso a scrivere test è di gran lunga ricompensato dal tempo risparmiato dal debugging del prodotto. Provare per credere! Però non pensare che i bug non esistano più utilizzando il TDD. Sono molto di meno ma ogni tanto capitano. Quando capitano dobbiamo sempre ricordarci di scrivere il test che manifesta il bug prima di fixare il bug. In questo modo continuiamo ad usare il TDD, ma soprattutto abbiamo la garanzia che il bug non si manifesterà più anche se noi andiamo a modificare pesantemente il codice in futuro.

Quando utilizzare il TDD

Ora che abbiamo visto cosa è il TDD, una domanda può sorgere spontanea: quando si dovrebbe utilizzare il TDD? Qui meglio fare una distinzione: se devo scegliere tra il TDD e i test unitari classici, per esperienza personale sceglierei sempre il TDD. L’approccio classico non mi ha mai portato nessun giovamento rispetto al TDD. L’unico “vantaggio” che ho visto è che l’approccio classico permette di non testare tutto, ma sinceramente non lo reputo un vantaggio proprio perché crea dei buchi pericolosi che vanificano gran parte dei vantaggi che abbiamo trovato in questa guida.

Se invece la scelta è tra il TDD e solamente l’implementazione senza test unitari il discorso cambia. Sicuramente queste sono le casistiche dove si dovrebbe utilizzare il TDD (o almeno test unitari).

Sistemi di backend: quando si hanno dei clienti (mobile app, microservizi etc.) che si appoggiano al nostro sistema è fondamentale che il backend funzioni perfettamente.
Parti “mission critical”: se abbiamo delle componenti che devono funzionare e sono cruciali per erogare il nostro servizio, non possiamo permetterci di avere dei bug o andare sulla fiducia.
Componenti che sono difficili da testare “live”: se ci impiego 5 minuti solo per testare una singola volta una casistica speciale, meglio spenderli per creare un test che poi almeno ce l’ho sempre e mi basta un npm test per ricontrollare.

Quando invece non serve il TDD e si può andare solamente con l’implementazione? Sembra un’eresia ma io ho trovato alcuni casi in cui solo l’implementazione basta e avanza:

Quando la nostra implementazione è facilmente testabile “live”: mai sentito parlare di live-reloading? Con le web-app o anche nello sviluppo di app ibride con Flutter, Ionic o React Native, è possibile implementare e visionare subito l’output. Questo è uno strumento potentissimo che velocizza enormemente lo sviluppo, ma soprattutto il tempo tra l’implementazione e il risultato finale è pari a zero. Che serve scrivere i test se mi basta salvare il codice e subito vedo il risultato finale e posso provarlo?
Quando ci possiamo permettere qualche libertà, le specifiche sono ancora fumose ed il nostro cliente è a stretto contatto con lo sviluppo: mi è capitato di sviluppare letteralmente con il cliente che poteva darmi i feedback quasi in tempo reale. Se l’ambiente è molto informale/colloquiale è possibile creare un intero progetto senza scrivere una riga di test ed il cliente è contento comunque anche se magari di tanto in tanto ti chiama per segnalare un bug. L’importante è che possiate risolverlo velocemente così che il cliente possa apprezzare la vostra rapidità nel fix.
Quando il progetto è un esperimento: certe volte capita di creare un progetto solo per capire se una determinata cosa possa funzionare. Oppure si implementa una piccola variazione per fare A/B testing, o ancora si sviluppa una cosa temporanea per ovviare ad un problema altrettanto temporaneo. In questi casi non apprezzeremo mai i vantaggi del TDD, perché il tempo speso nei test non verrà compensato dal tempo risparmiato dal debugging o fix di bug.

Il messaggio che deve passare è questo: valutate il vostro caso e agite di conseguenza. Il TDD è la soluzione a molti problemi, ma non a tutti.

Conclusioni

Prima di tutto mi scuso se leggendo questa guida magari non è passato molto il concetto del “è più semplice di quanto si creda”. Ma non dimenticare che qui hai visto numerosi concetti che, se è la prima volta che li vedi, ci vuole un po’ di tempo per digerirli. Se magari ti sei perso i concetti che hai imparato in questo articolo ti faccio un piccolo sommario:

Inizializzazione di un progetto in Node.js, utilizzo del packet manager npm.
Inserimento di TypeScript con Linter integrato.
Utilizzo di Jest per il testing.
Programmazione asincrona con con le keyword async e await introdotte in ECMAScript 2017.
Utilizzo di librerie di Mocking, quando e perché usarle.
Test Driven Development.

All’inizio il TDD sembra un freno, come tutte le cose nuove, ma una volta preso dimestichezza, tutto diventa più veloce e anche più divertente! Fa sempre piacere arrivare a fine giornata e vedere il proprio progetto che cresce insieme ai test che aumentano e sono tutti verdi… tranne uno! Ebbene sì: a fine giornata, se il progetto non è concluso, scriviamo un test che fallisce prima di andare via. Questo è un consiglio che è molto efficace per riprendere i lavori. In questo modo ci ricordiamo perfettamente cosa stavamo facendo quando ritorneremo a lavorare. Il test fallito ci dirà esattamente cosa abbiamo lasciato indietro.

Spero che questo articolo ti abbia fatto venire voglia di provare questa affascinante tecnica che, a primo impatto, può sembrare quasi assurda, ma una volta adottata, aumenta enormemente la qualità del codice e di conseguenza anche la qualità del prodotto finale.

Se volete vedere il TDD in azione con Spring Boot potete leggere il mio articolo che parla di come sviluppare delle API RESTful in TDD con Spring Boot.

Alla prossima!

11 lezioni che ho imparato lavorando nelle startup

Sat, 21 Apr 2018 07:03:47 GMT

Sono quasi 4 anni che ormai lavoro in startup. Sono convinto che la startup sia un’ottima scelta per uno studente fresco fresco di laurea, perchè sono ambienti molto dinamici: data la loro natura instabile si è “costretti” ad adattarsi, si impara ogni giorno qualcosa di nuovo e quindi è un’ottima opportunità per crescere personalmente insieme all’azienda.

Siccome ora sto cambiando ambiente lavorativo è giunta l’ora di tirare le somme. In questo post racconterò ciò che ho imparato a lavorare nelle startup, nel mio caso wavein.ch e Cloud Academy.

Il tuo capo vuole soluzioni, non problemi

Nelle startup, i propri superiori sono spesso le stesse persone che hanno scritto il codice prima di te, quindi la tentazione di chiedere aiuto a loro è molto alta. Ma ricorda che ora il loro ruolo è cambiato, quindi hanno mille altre faccende per la testa. Infatti contano su di te per portare a termine il compito che ti è stato affidato. Invece di chiedere aiuto, bisogna chiedere a loro che decisione prendere. Il flusso corretto è che loro ti chiedano di fare X, tu analizzi il problema e porti le soluzioni con pro e contro di ognuna, infine il superiore deciderà la soluzione da intraprendere assumendosi la responsabilità. In questo modo tutti sono felici: tu sai perfettamente cosa fare, il superiore ha perso poco tempo e ha ricevuto solo le informazioni che gli interessavano.

Tieni traccia di ciò che stai facendo

La trasparenza nelle startup è fondamentale: tu ovviamente sai benissimo su cosa stai lavorando, quale bug ti sta facendo impazzire… Ma tutto questo non è così scontato per il resto del mondo. Io usavo YouTrack e Jira come issue tracking system, non c’è niente di peggio che avere giornate di fuoco al lavoro ed avere la board vuota. Questo può essere un problema per te che non sei in grado di mostrare agli altri su cosa stai lavorando, ma sopratutto è un problema per il Product Manager che non potrà mai schedulare correttamente i lavori, non avrà nessuna visibilità sui possibili ritardi e infine non può prioritizzare correttamente i lavori. Stesso discorso vale per i task che sono bloccati: metti sempre nero su bianco su cosa stai lavorando.

Ognuno di noi è diverso

Noi abbiamo un carattere, la propria personalità: per questo motivo ci comportiamo spesso con tutti in egual modo. Ma ci dimenticano che anche gli altri sono tutti diversi: c’è chi è più espansivo, chi si offende facilmente, chi è timido, chi si inalbera per il nulla ecc. Non possiamo comportarci allo stesso modo con tutti indiscriminatamente. E peggio ancora non possiamo pretendere che gli altri debbano adattarsi al nostro carattere, non funzionerà mai!

Secondo me è nostro compito tirar fuori il meglio da ognuno facendo leva sulle qualità di ognuno:

La persona ama aiutare il prossimo: fatti aiutare! Sicuramente può insegnarti sempre qualcosa.
Si offende facilmente: cerca di non fare battute inutili, mantieni un profilo più professionale / distaccato.
La persona si infiamma facilmente e odia “non aver ragione”: se hai già in mente la soluzione ad un problema e vuoi solo una conferma, non spiegargli subito il macro problema. Altrimenti ti darà la sua soluzione e non vorrà più discuterne. Invece cerca di spezzettarlo in piccoli problemi dove le soluzioni sono ovvie e sono quelle che hai adottato tu. Infine tutte queste soluzioni porteranno alla tua soluzione definitiva per logica conseguenza.

Se questa persona comincia a scaldarsi, non cominciare a mimare il suo tono… Altrimenti è solo un crescere di toni che finirà solo male. Non aver paura di interrompere la discussione senza una soluzione se vedi che non sta portando a niente.
Ama fare battutacce e piace “insultare amichevolmente” gli altri: stai al gioco! Non prenderti troppo sul serio. Molto spesso se ti prendono in giro apertamente è solo perchè vogliono farsi una risata insieme a te. Se non si è abituati è veramente difficile da digerire inizialmente, ma poi non ci si fa più caso e anzi ci si diverte. Alla fine si capisce quando qualcuno lo fa solo per divertirsi oppure perchè prova rancone nei tuoi confronti.
Una persona non gli vai a genio: la cosa peggiore che si possa fare è fare terra bruciata intorno a lui. Devi passare la quotidianità con lui e quindi non serve a nessuno. Invece cerca di evitare il comportamento che gli dà fastidio se qualcuno te lo dice. Altrimenti cerca di comportarti sempre bene con lui: aiutalo e non stargli troppo attaccato, così piano piano capirà che non dovrebbe avere nulla contro di te. Se non funziona… Beh pace, cerca sempre di non dargli dei buoni motivi per odiarti, è l’unica cosa che si può fare in questi casi.
È timida: non verrà mai a chiederti aiuto o consiglio. Ogni tanto fatti sentire, così che poi si sblocchi anche lui. In questo modo entrambi potete lavorare.
È uno scaricabarile: “Scusa, potresti farmi questo? So che tu ci hai lavorato poco tempo fa.”, “Io non so niente di sta roba, puoi farmelo tu che so che ne sai?“. Un conto è aiutare, un’altro è fare il lavoro di altri al posto loro. Anche tu hai i tuoi obiettivi, cerca di rimanere focalizzato sui tuoi.

Insomma questi sono solo dei piccoli esempi e comportarsi in modo diverso con persone diverse non significa essere falsi. È secondo me l’unico modo per poter vivere in modo pacifico con numerose persone nella quotidianità lavorativa.

È lecito dire di No

Il lavoro è come l’acqua: fluisce dove viene fatto. Quindi bisogna stare attenti a dire troppi sì, altrimenti finisce che tutto il lavoro si riversa su di te e poi hai due problemi molto seri: rischi il burnout perchè non hai un attimo di respiro ed in più ti accusano di essere il collo di bottiglia! È importante aiutare gli altri, fare del lavoro extra, ma lo è di più finire i propri task assegnati. Per l’azienda è importante rispettare il proprio piano, se fallisci nel rispettare le tempistiche originarie, tutto ciò avrà ripercussioni sul planning e questo avrà una ripercussione negativa su tutta l’azienda. Più si è in pochi e più le conseguenze sono visibili. Quindi non bisogna avere paura a dire ‘No’ a chi ci chiede di fare altro lavoro in più. Prima fai il tuo poi, se avanza tempo, accetta del lavoro extra. Altri ‘No’ che sono portanti sono quelli dal punto di vista tecnico. Non è raro che vengano calati dall’alto dei task che da un punto di vista tecnico o di usabilità non stanno né in cielo né in terra. In questi casi è nostro dovere dire ‘No’ e dare le proprie motivazioni: è lo sviluppatore che può capire le conseguenze di requirement esotici (debito tecnico, logiche fumose già dall’inizio, eccessiva complessità della UX ecc).

Un fallimento è realmente tale se non si impara nulla

Ora dico una cosa che non fa piacere a nessuno. Tutti falliscono in qualcosa: io ho fatto sbagli e ne farò ancora, è impossibile fare tutto perfetto nella propria carriera lavorativa. Diffida da chi ti dice “Io non ho mai fatto errori / Non ho mai fallito / Sinceramente non mi ricordo di miei errori commessi nel passato”. Ti sta solo prendendo in giro oppure sta mentendo a se stesso, perchè noi, soprattutto italiani, odiamo fallire e soprattutto odiamo ammetterlo.

Ma sbagliare è parte integrante dell’apprendimento. L’esperienza non è altro che un insieme di errori che ti sei portato a casa e che sei pronto a non ripetere. È per questo che chi dice di non aver mai sbagliato sta mentendo, significa che o non ha mai fatto niente oppure non ha mai avuto un compito veramente sfidante.

Prima si riconosce un errore, prima è possibile porvi rimedio. Prima si pone rimedio e meno danni si fanno. Se una strada sta portando ad un niente di fatto, oppure sta diventando più difficile del previsto, fermati… Fai un bel respiro, analizza la situazione e vedi se ne vale la pena continuare. Altrimenti è giunto il momento di chiedere un parere ad un collega e poi annunciare il problema al proprio superiore (possibilmente con qualche soluzione in mano). Poi si fanno le dovute correzioni.

Vedrai che così facendo nessuno può dirti niente, apprezzeranno la tua capacità di prevedere un possibile danno ancora maggiore, si prende nota di cosa è andato storto così da non ripetere lo stesso errore in futuro e si continua felici di aver evitato un possibile disastro.

L’alternativa a tutto questo? Dire a tutti che è tutto ok, andare avanti sulla propria strada, cercare di tirar fuori il meno peggio, prendere tempo per cercare di tenere in piedi una cosa che è morta, prendere ancora tempo, disperarsi, gettare la spugna e dire che stai lavorando su una cavolata, che non può funzionare, incolpando la donna delle pulizie pur di non assumersi la propria responsabilità… Nessuno lo apprezzerà, anzi capiranno che non possono fare affidamento su di te, quindi evita.

Fallire non è bello, ma succede. Quindi se deve succedere fallo il prima possibile.

Chiedere aiuto è un’arma, non una debolezza

Purtroppo per molti chiedere aiuto è quasi una sconfitta personale, altri non lo fanno per non rubare troppo tempo alla persona che si rende disponibile ad aiutare. Ma chiedere una mano a chi ne sa di più su un determinato prodotto, parte di codice, tecnologia è fondamentale:

Si raggiunge prima l’obiettivo. Chiedere una domanda e ottenere una risposta richiede pochi minuti. Cercare di capire una parte di codice scritta da altri, cercare una risposta online per un caso molto specifico ci si impiega ore.
Si capisce realmente il funzionamento della piattaforma. Purtroppo nelle startup la documentazione lascia un po’ a desiderare, quindi molto spesso si finisce a leggere direttamente il codice. Alcune parti possono essere oscure da capire semplicemente perchè non è esplicitata la reale motivazione. Non è raro trovare orribili hack in mezzo al codice per risolvere dei casi specifici che solo una persona conosce… E non è detto che quella persona sia ancora in azienda! Se c’è ti consiglio una cosa, vai a chiedere.
Si evita di scrivere strafalcioni: ho visto persone che pur di non chiedere o capire il funzionamento di una parte di prodotto, “bypassava” completamente quella parte scrivendone un’altra molto simile. Questo è il male, perchè si creando due parti di codice che coesistono, non si capisce bene il perchè e ovviamente rende il codice non manutenibile. Oppure altri che risolvevano un problema solo in superficie perchè “hey, non tocco il codice scritto da altri!“… Anche questo è il male assoluto: in questo modo si può distruggere l’architettura in poche settimane. Piuttosto si chiede a chi ha scritto il codice e poi si risolve.
Si impara più velocemente! Anche da un punto di vista personale è molto meglio chiedere aiuto: si impara molto più velocemente e sentire come ragionano altri sviluppatori è il miglior modo per migliorare se stessi…
Anche tu hai bisogno di aiuto… Cosa? Stai pensando che tu sei il migliore e che non hai niente da imparare soprattutto dai tuoi colleghi? Beh, tutti quelli che la pensano così sono quelli che crescono di meno e rimangono indietro, perchè pensano che non hanno più nulla da imparare e rimangono fermi con la loro conoscenza. Letteralmente chiunque può insegnarci qualcosa, anche la persona più junior in azienda, perchè semplicemente ogni persona ha un proprio, unico, background personale.

Il codice perfetto non interessa a nessuno

Ecco qui una lezione che può fare male a chi esce fresco fresco dall’università. Nel mondo accademico la cosa più importante è scrivere il codice perfetto, avere il codice più astratto possibile per avere un codice che si adatta facilmente a qualsiasi caso d’uso. Nessuno guarda il tuo codice fino all’esame finale e quindi si può lavorare in tutta tranquillità. C’è solo un piccolo particolare… Nel mondo universitario si ha un sacco di tempo a disposizione, nelle startup no. La feature che ti è stata richiesta è bloccante per altri sviluppatori, gli stakeholder vogliono la tua parte pronta e deployata ieri. Quindi non viene valutata la bontà del tuo codice, ma la tua execution. La velocità con cui porti a termine il tuo compito.

Quindi come si fa a far coesistere il buon codice con velocità di esecuzione? Tramite iterazioni: scrivi il minimo indispensabile per raggiungere l’obiettivo, non complicare le cose con costrutti strani. Scrivere il minimo indispensabile è ben diverso dallo scrivere un brutto codice: continua a seguire le best practice, mantieni il codice più pulito possibile, continua a valutare che più scorciatoie prendi più bisogna sacrificare la manutenibilità. Ma non fasciarti la testa prima del problema, perchè magari quel problema non arriverà mai… E se mai arrivasse, si itera, ma almeno la tua feature originale è già arrivata sul mercato e può essere validata dal cliente.

Raggiungi i tuoi obiettivi, punto

Altra lezione che ho imparato a mie spese e che l’ho ricevuto come un calcio rotante sulle gengive. Appena entrato a Cloud Academy era tutto un mondo nuovo, avevo voglia di fare ed ero veramente carico. Uno dei primi compiti che mi era stato assegnato era l’automatizzazione della generazione dei file statici lato frontend. Mentre lo stavo facendo ho avuto la brillante idea di fare anche una miglioria extra che purtroppo ora non mi ricordo. Ero andato dal mio superiore per mostrargli i miei progressi: dopo aver detto a che punto ero arrivato, gli spiego anche la mia miglioria e cosa potevamo fare in più grazie ad essa. Mentre spiegavo mi ha interrotto bruscamente con un “Ma a me che ca@@o me ne frega?“… Imbarazzo totale, 5 secondi di silenzio… Tutto quello che sono riuscito a dire è stato un “Ah…“.

Io ero abituato a wavein.ch ad avere molto più margine di manovra, ma semplicemente perchè eravamo più piccoli e io ero quasi capo di me stesso. Quindi tutto quello che facevo bene o male andava nella direzione che reputavo giusta. Ma in una startup si hanno dei task “ben definiti”. Se si hanno dei task assegnati bisogna fare quelli e fare il minimo per raggiungere quell’obiettivo. Tutto il resto non è visto di buon occhio, viene visto come tempo perso. Ricorda che il tempo è la risorsa più scarsa in una startup. Quindi occhio con le funzionalità non richieste, anche se per te possono essere un grande miglioramento, per altri potrebbe non interessare “un ca@@o di niente”.

La startup non è una famiglia

La startup non è una famiglia. Bisogna tenerlo bene in mente. Ci piace la meritocrazia, la vogliamo ovunque, ma dobbiamo anche essere in grado di accettare il rovescio della medaglia.

Ora spiego cosa è per me un rapporto lavorativo, nella versione più meritocratica e cinica possibile: io vengo stipendiato per offrire un determinato servizio all’azienda. Tramite il mio servizio, l’azienda acquista del valore. Se il valore generato dal mio servizio è più alto rispetto al mio stipendio, l’azienda ha tutti gli interessi a mantenermi. Più questo delta è alto più l’azienda “mi vuole bene”, se questo delta è troppo marcato io posso chiedere un aumento e l’azienda dovrebbe riconoscermelo. Se non me lo da, ho tutto il diritto di guardarmi in giro per vedere se qualcun’altro riconosce il mio valore. Se invece il delta è negativo significa che all’azienda non gli conviene più darmi lo stipendio e quindi ha tutto il diritto di lasciarmi a casa. C’è infine un’ultima opzione: l’azienda non ha più fondi, quindi comincia a licenziare le persone che hanno un delta meno marcato, ossia sono quelli che generano meno valore all’azienda.

Usando questa versione pulita pulita, meritocratica, cinica quanto vuoi, non si può rimanere “scottati” da un possibile licenziamento. Son cose puramente logiche e razionali.

Però noi non siamo delle macchine e quindi ci sono un sacco di altre variabili in gioco che possono colpire a fondo la sensibilità delle persone: va bene tutta sta storia del delta, ma è meglio licenziare una persona giovane senza figli a carico oppure licenziare una persona con famiglia e 3 figli anche se mi genera meno valore all’azienda? Meglio continuare a lavorare per l’azienda in cui lavoro anche se mi pagano poco, dove mi sono fatto un sacco di amici e mi ci trovo bene oppure cambio lavoro e vado dove mi pagano di più?

Ho conosciuto persone che hanno vissuto malissimo il licenziamento perchè si sentivano “traditi” dall’azienda. Ma secondo me c’è poco da arrabbiarsi: a nessuno piace licenziare persone, la scelta su chi poi bisogna licenziare penso sia una cosa che angoscerebbe chiunque.

Io ho vissuto sulla mia pelle cosa vuol dire essere licenziati dall’oggi al domani. Ciononostante sono rimasto in ottimi rapporti con chi mi ha licenziato perchè, essendo in una startup, sapevo benissimo che i soldi non crescono sugli alberi: ho capito le reali motivazioni e quindi sono riuscito efficacemente a dividere il rapporto lavorativo dall’amicizia. Sono due cose che insieme coesistono, ma non sono certo la stessa cosa.

Con questo non sto dicendo che non si possono fare amici al lavoro. Anzi al lavoro si conoscono persone stupende e nascono delle amicizie che vanno avanti anni anche fuori dal lavoro. Sto solo dicendo che io non ho un posto di lavoro perché sono amico di qualcuno, ma perché sto generando valore all’azienda ed essa è in grado di riconoscermi questo valore generato. Se si tiene in mente questo aspetto secondo me è più facile accettare un licenziamento.

Non esasperare l’ambiente lavorativo

“Possibile Natali che tu non ti arrabbi mai?“. In realtà mi arrabbio anche io, ma semplicemente cerco di non mostrarlo. Passiamo una buona parte della giornata al lavoro e quindi è importante che manteniamo l’ambiente il più calmo possibile, anche se l’incazzatura è sempre dietro l’angolo. In questi anni ho imparato fondamentalmente queste due cose:

Arrabbiarsi è inutile. Purtroppo capita di vedere persone che pretendono di aver ragione solamente urlando o mostrandosi visibilmente irritati. La cosa importante è mantenere comunque la calma, attendere qualche secondo prima di rispondere e, se proprio la situazione non si calma, è meglio concludere la conversazione e rinviarla quando i toni sono più calmi… Anche perchè il problema non si risolve in queste situazioni.
Con la forza non si ottiene niente: nessuno ti farà un favore/task sotto costrizione, bisogna motivare le persone, non obbligarle. Ho avuto la fortuna di vedere tre tipologie di leadership: chi ti costringe, chi ti “minaccia” e chi invece ti motiva a farle. I risultati migliori ovviamente di ottengono con l’ultima. Esasperare l’ambiente lavorativo per ottenere qualcosa non è mai una soluzione, magari può funzionare nel breve termine, ma nel lungo periodo può solo far nascere un problema ben più grave: far schizzare il turnover alle stelle. Il problema è che costringere o minacciare una persona è semplice, motivare non lo è affatto. Ed è per questo che è importante scegliere bene i vari leader in azienda… Non tutti sono in grado di farlo.

La formazione personale è fondamentale

Pensavi che una volta finito gli studi potessi dire addio allo studio? Beh, nell’informatica è solo l’inizio! L’IT è una continua evoluzione, se si rimane fermi anche solo due anni si è tagliati automaticamente fuori. Per molti questa è una condanna, ma per me è la parte più interessante del lavoro. Non si smette mai di imparare e si può vedere in modo tangibile una continua evoluzione nel proprio lavoro e in noi stessi… Il lavoro ripetitivo alla fine annoia! Per formarsi c’è solo l’imbarazzo della scelta: dalle piattaforme e-learning, piccoli progetti, ai meetup organizzati da gente appassionata che veramente ci mette l’anima in ciò che fa.

Conclusioni

Spero che questo post possa essere d’aiuto a chi ha paura di iniziare una carriera lavorativa, specialmente in una startup. È sicuramente una buona palestra per apprendere velocemente, ma sono certo che può un po’ spaventare a chi non ci ha mai lavorato.

Se siete giovani non vi posso consigliare altro che lavorare in questi ambienti: ci si diverte, si conoscono persone veramente stupende che condividono la tua stessa passione e non ci si annoia mai!

Alla prossima!

Come risolvere le regressioni del software usando git bisect

Mon, 15 Jan 2018 07:03:47 GMT

Avete aggiunto una funzionalità al software ed è andata in produzione. Dopo qualche settimana il Product Owner vi comunica che non funziona più. Don’t panic. Usando solamente Git si può risolvere tutto in pochi minuti!

A tutti può capitare una regressione del software e non è mai piacevole. Ho visto molti sviluppatori che, in un caso come questo, cominciano a tentare di riprodurre il bug in locale e a rileggere furiosamente il codice nella speranza di risolvere il bug. Se nel codice ci lavorano molte mani, la ricerca del bug può essere tutt’altro che semplice.

Usando quest’approccio naive non stiamo sfruttando tutte le nostre informazioni in possesso: noi siamo certi che la funzionalità prima funzionava correttamente. Quindi è successo qualcosa nel mentre che ha sicuramente rotto la nostra parte di codice. Quindi perchè cercare questa modifica manualmente quando Git può fare il lavoro sporco per noi in pochissimi passaggi? Git può dirci puntualmente cosa è successo, quando, chi è stato e perchè (se lo sviluppatore che ha introdotto il bug ha scritto un testo decente nel commit).

git bisect

Ebbene sì, Git offre proprio questa funzionalità. Non tutti la sfruttano ma in casi come questi è potentissima. È il comando git bisect.

Per farla breve, si definiscono due commit: il primo è un commit “buggato”, ossia che presenta il problema, il secondo è un commit sano, dove il problema non esisteva ancora. Git poi mostra un commit che sta nel mezzo e sta a noi a dire a Git se funziona o no. Git a questo punto mostra un altro commit che sta sempre nel mezzo tra il commit buggato e quello sano. Si va avanti così finchè Git ci mostra il commit che ha introdotto il bug.

Sembra un procedimento lunghissimo ma non lo è: infatti, ad ogni nostra verifica, dimezziamo il numero di commit tra quello buono e quello buggato. Per esempio se abbiamo 1000 commit che separano i nostri due commit di riferimento, noi troviamo quello che ha introdotto il problema in log_2(1000) ~ 10 passi!

Esempio pratico

Come esempio ho usato un mio piccolo progetto che avevo creato per imparare un po’ di concetti su React. Supponiamo che vogliamo sapere chi ha aggiunto l’effetto particellare alla pagina. Durante il procedimento di git bisect etichettiamo come bad tutte le volte che il progetto ha la cartella src/components/atoms/ParticlesBackground. Mentre tutti i commit che non la possiedono saranno good.

Iniziamo! Per prima cosa cloniamo il progetto ed entriamoci dentro con il terminale.

git clone https://github.com/matitalatina/8ball
cd 8ball

Ora iniziamo la ricerca

git bisect start

Avviando il programma notiamo che il branch master ha la cartella src/components/atoms/ParticlesBackground. Quindi etichettiamo il commit come bad.

git bisect bad

Poi torniamo indietro nella storia di Git abbastanza da non trovare più la cartella in questione. Nel nostro caso tornare indietro di 10 commit è sufficiente.

git checkout HEAD~10

Ok! Ora la cartella è sparita! Quindi possiamo etichettarlo come good.

git bisect good

Ora Git cambierà commit e si porterà esattamente in un punto a metà tra i commit etichettati come good e bad. Ve lo notifica con la seguente dicitura.

Bisecting: 5 revisions left to test after this (roughly 3 steps)
[5e2a30980acb38d3d3958359c56fd0a8d0325136] Improve particles system

Andate avanti a scrivere git bisect good o git bisect bad finchè avrete analizzato circa 4 passi.

Nel nostro caso specifico sarà:

git bisect bad
git bisect good
git bisect bad
git bisect good

Alla fine, quando Git ha individuato il commit che stavamo cercando, ve lo comunica in questo modo:

b7b5d042a8cba637c56cc52401dcd61ec785d9b4 is the first bad commit
commit b7b5d042a8cba637c56cc52401dcd61ec785d9b4
Author: Mattia Natali <***@***.***>
Date:   Mon Nov 6 22:24:32 2017 +0100

    Add particles

:100644 100644 d93738e6743c2460699030cfe8df000e1bc7ecd7 570e0890ece45c8d4ef6640a3ea7a386fd63f7da M	package-lock.json
:100644 100644 994aebed4cf0ebfb0dd56e2bebf2a6e411e44e1c 0dc0290897d7082dadda14595739b80b07766603 M	package.json
:040000 040000 9f912726175c5d9794d00deffdb422136555846f a934e7f36f14c1ec38058bfbfbf403d3fb8043b3 M	src

Già il messaggio del commit ci fa intuire che Git ha fatto centro (“Add particles”)! Ma noi non ci fidiamo e allora vediamo effettivamente cosa è stato fatto in questo commit: prendiamo l’id del commit (b7b5d042a8cba637c56cc52401dcd61ec785d9b4) e scriviamo:

git show b7b5d042a8cba637c56cc52401dcd61ec785d9b4

scorrendo il commit notiamo la parte

diff --git a/src/components/atoms/ParticlesBackground/index.js b/src/components/atoms/ParticlesBackground/index.js
new file mode 100644
index 0000000..748f50d
--- /dev/null
+++ b/src/components/atoms/ParticlesBackground/index.js
@@ -0,0 +1,129 @@
+import Particles from 'react-particles-js'
+import styled from 'styled-components'
+import React from 'react'
+
+const Wrapper = styled.div`
+  pointer-events: none;
+  position: fixed;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  right: 0;
...

che è proprio la parte che stavamo cercando! Quindi in definitiva ora sappiamo che Mattia Natali ha aggiunto questa parte il Lunedì 6 Novembre 2017 alle 22:24.

Conclusioni

Immaginate ora di farlo per un bug che vi sta facendo impazzire, è molto potente perchè vi indica esattamente chi è stato e cosa è stato cambiato. In questo modo potete chiedere chiarimenti all’autore del commit e sapere esattamente la modifica che ha creato il bug.

Magari git bisect non vi servirà tutti i giorni, ma è giusto tenerlo a mente perchè è sicuro che prima o poi vi tornerà utile e vi farà risparmiare un sacco di tempo.

Alla prossima!

Come essere produttivi con il terminale

Fri, 06 Oct 2017 07:03:47 GMT

Se state leggendo questo blog post immagino che siate più o meno nella mia stessa situazione. Siete uno sviluppatore e avete a disposizione 8 ore al giorno per lavorare: in questo lasso di tempo dovete revisionare il codice di altri, fare meeting, gestire le vostre milioni di issue e magari anche quelle di altri, aiutare chi vi chiede aiuto, pensare a come raggiungere i propri obiettivi e infine programmare quello che avete pensato.

Fare tutte queste cose e rientrare nelle 8 ore giornaliere prefissate è difficile senza deludere le aspettative di nessuno. Quindi da bravi ingegneri/sviluppatori state cercando di ottimizzare qualsiasi cosa.

In questo blog post vi spiegherò come ho cercato di ottimizzare il mio tempo passato davanti al terminale. Mi concentrerò soprattutto sul sistema operativo Mac, che è quello su cui lavoro attualmente.

In questa guida non voglio spiegare come si utilizza il terminale. Quello per me è un prerequisito. Il mio fine è di condividere con voi tanti piccoli trucchetti che vi faranno risparmiare tempo nella vostra quotidianità lavorativa in modo tale da concentrarvi maggiormente sull’attività che effettivamente porta valore: la programmazione.

Le basi

Velocizziamo il cursore

Iniziamo con una piccola ottimizzazione tanto semplice quanto efficace, ancora prima di aprire il terminale. Molte volte nel terminale o nel proprio IDE occorre spostare il cursore. Tenendo premuto le frecce direzionali il cursore si sposta finchè non rilasciamo il tasto. Bene, fin qui nulla di nuovo. La cosa esasperante è la lentezza con cui questo cursore si sposta! Molte persone che vedo, per fare veloce, cominciano a premere compulsivamente le frecce oppure semplicemente attendono secondi preziosi finchè il cursore si sposta nella posizione desiderata.

Una semplice ottimizzazione che tutti dovrebbero fare è di diminuire il tempo in cui inizia la ripetizione del tasto e l’intervallo di tempo tra una ripetizione e l’altra.

Per farlo è molto semplice. Andiamo nel Mac in Settings -> Keyboard -> Tab Keyboard. Impostate Key Repeat a Fast e Delay Until Repeat a Short. Ora provate e la differenza sarà enorme. So che all’inizio sembra troppo veloce il cursore, ma poi ci si abitua e non si torna più indietro!

Shortcuts

Questo consiglio vale in generale in ogni programma. Se utilizzate spesso la stessa funzione, cercate di imparare la sua scorciatoria da tastiera. È sicuramente più veloce non staccare le dita dalla tastiera. Capita che la scorciatoia non possa esistere per la vostra funzione, fortunatamente il più delle volte nelle impostazioni si può creare. Vi consiglio di spendere un po’ del vostro tempo nella creazione di queste shortcuts: risparmierete tempo prezioso nel lungo periodo.

iTerm

Il terminale del Mac è buono, ma se volete ancora di più potete utilizzare iTerm. Sostanzialmente è come il terminale nativo ma ha le seguenti funzionalità aggiuntive che aumenteranno la vostra produttività:

Ricerca migliorata: premete cmd + F e aprite la modalità ricerca. Scrivete la parola chiave da cercare e subito vi evidenzierà la vostra parola nel terminale. Usando cmd + G e cmd + shift + G potete cercare la parola successiva o precedente.
Split panels: è possibile suddividere sia verticalmente (cmd + D) che orizzontalmente (cmd + shift + D) la vista in modo da avere più terminali in un’unica pagina. Molto utile se avete più programmi avviati e avete bisogno di monitorarli contemporaneamente.
Profili personalizzabili: con un profilo è possibile customizzare completamente il terminale come colori, shortcuts. Se passate tanto tempo collegati a macchine remote è facile confondersi tra le varie tab aperte. Un ottimo modo per evitare di fare pasticci è di utilizzare profili diversi per macchine con finalità diverse. Il nostro buon DevOp utilizza quotidianamente questa tecnica: per la macchina di produzione ha un bellissimo sfondo rosso vivo, così capisce chiaramente di stare attento e di non starci per troppo tempo. Per l’environment di stage è blu, il resto sfondo nero.
Se siete curiosi per iTerm vi consiglio di leggere le altre feature degne di nota, ma soprattutto di provarlo!

Ordinaria amministrazione

Ecco qui una lista di trucchetti che utilizzo quotidianamente nel terminale. Ho scritto tutti quelli che mi vengono in mente, alcuni saranno ovvi per chi vive tutto il giorno davanti al terminale, altri spero di no ?.

tab: Bastano poche lettere di ciò che volete scrivere, poi premete tab per l’autocompletamento. Questo è molto utile per esempio nella navigazione tra tab.
sudo !!: quante volte avete scritto apt-get install senza dare i permessi di root? Molti, dopo aver letto il messaggio di errore premono freccia su e poi spostano in cursore all’inizio del comando e finalmente inseriscono la parola sudo per diventare root… Quando tempo perso! Basta scrivere sudo !! e boom! Fatto. In sostanza !! viene sostituito con il comando precedente ed è proprio quello che volevamo.
cd: ritorna nella propria home. Perchè scrivere cd ~ o peggio ancora cd ../../../../../ per tornare alla home se basta cd?
cd -: ritorna nella directory precedente. Molto simile è il comando git checkout -: fa il checkout del branch su cui lavoravamo in precedenza.
lsof -i :<PORT>: solo per Mac. Questo comando serve per identificare il programma che sta usando la porta <PORT>. Molto utile quando un programma si blocca in background e voi avete bisogno disperatamente della porta libera. Una volta eseguito il programma vi basta prendere nota del PID del programma e poi kill <PID>. Ora la porta è libera!
Concatenare i comandi: perchè stare a fissare un comando che finisca per poi eseguire il prossimo? Usando && e ; è possibile concatenare più comandi. && esegue il secondo comando solo se il primo si è concluso correttamente, mentre ; lo esegue a prescindere.
ctrl + c: serve per chiudere le applicazioni ma anche per cancellare velocemente quello che stiamo scrivendo.
ctrl + a e ctrl + e: porta rispettivamente all’inizio e alla fine il cursore nel comando che stiamo scrivendo.
ctrl+l: pulisce il terminale, molto più veloce rispetto a scrivere clear!
!$: riprende l’ultimo argomento del comando precedente. Molto utile in casi come questi mkdir -p creo/una/nuova/cartella/ && cd !$ Come avrete intuito sto creando una cartella, ed una volta creata ci entro senza dover scrivere tutto il path di nuovo.
man <APPLICAZIONE>: quante volte vi è capitato di non ricordarvi le opzioni di un comando e siete andati online a cercare la documentazione? Non serve andare online! Basta scrivere man seguito dall’applicazione e avrete tutta la documentazione a portata di mano senza googlare.

cmd + t e cmd + w: rispettivamente apre e chiude una nuova tab del terminale. Se ci fate caso questi comandi sono “universali”, ossia funzionano anche con le tab del browser, del finder, del vostro text editor preferito ecc.
open .: apre nel Finder la cartella in cui ci troviamo.

Navigazione tra i comandi ed auditing

last: mostra chi è connesso con il terminale alla macchina o chi si è connesso in precedenza.
w: molto simile a last. Mostra le persone correntemente connesse alla macchina.
freccia su: inserisce il comando eseguito precedentemente. Molto utile per revisionare il comando o per modificarlo in caso di typo. Se si continua a premere freccia su si torna indietro nella history.
history: mostra tutti i comandi eseguiti. Insieme al comando grep è molto facile ricercare un comando. Per esempio avevate avviato un’app utilizzando runserver ma non vi ricordate tutte le opzioni a memoria? Vi basterà scrivere un pezzo del comando, nel nostro caso scriviamo history | grep runserver.
ctrl + r <TEXT_SEARCH>: si chiama reverse-i-search e significa “cerca nel passato un comando simile a questo”. Insomma è come il comando precedente solo che è ancora più veloce. Per esempio possiamo premere ctrl + r e poi scrivere runserver per avere nel terminale il comando che stavamo cercando. Se il comando che stavate cercando non è l’ultimo ma uno precedente, continuate a premere ctrl + r finchè non ritrovate il comando desiderato!

Spingiamoci oltre!

Fuck!

Capita a tutti di sbagliare a scrivere qualche comando: quando scriviamo un typo e vediamo che il terminale ci risponde picche la prima cosa che pensiamo è “fuck”. Con thefuck possiamo esternare la nostra rabbia in modo produttivo! Questa app è tanto semplice quanto geniale. Se sbagliamo a scrivere un comando, ci basta scrivere fuck nel terminale, in questo modo questa app ci ripropone il comando precedente scritto correttamente. Vedetelo come un correttore automatico del terminale.

L’installazione e molto semplice: avendo installato Homebrew ci basta scrivere

brew install thefuck
eval $(thefuck --alias)

Bene! Ora se sbagliate a scrivere qualche comando arrabbiatevi e scrivete fuck che sarete più produttivi!

Zsh

Spesso ci ritroviamo bash come shell installata di default. Se volete avere quella marcia in più vi consiglio di usare Zsh insieme al plugin Oh My Zsh! Questa combo vi permetterà di essere più produttivi per i seguenti motivi:

Autocompletamento delle cartelle migliorato: una migliore navigazione tra le scelte proposte.
Autocompletamento per i programmi più utilizzati: Git, Docker, npm, Django sono i plugin di Oh My Zsh che utilizzo, ma ce ne sono molti altri!
Temi completamente configurabili: ci sono moltissimi temi pronti all’uso, sicuramente ne troverete uno che soddisferà i vostri gusti personali. Il mio preferito è eastwood.
Maggiore integrazione con Git: appena entriamo in una cartella che contiene un progetto versionato con Git, possiamo notare che viene mostrato il branch su cui siamo e anche un piccolo alert quando non abbiamo committato e pushato tutto il nostro codice. Grazie a questi piccoli aiuti risparmieremo molti git status.
Ricerca di comandi precedenti migliorata: scrivete solo l’inizio di un comando, poi premendo freccia su vi mostra il comando precedentemente utilizzato che inizia proprio nello stesso modo.

Installazione

Se volete installare Zsh con Oh My Zsh! questi sono i passi da seguire:

brew install zsh zsh-completions
sh -c "$(curl -fsSL https://raw.github.com/robbyrussell/oh-my-zsh/master/tools/install.sh)"

Ora riavviate la shell, per utilizzare Zsh vi basta scrivere zsh.

Se volete che Zsh diventi la vostra shell di default allora scrivete

chsh -s $(which zsh)

Cambio del tema

I file di configurazione di Zsh si trovano nel file ~/.zshrc. Con il vostro editor preferito andate a modificare la variabile ZSH_THEME. Se non sapete quale tema scegliere, potete utilizzare la modalità random: così ogni volta che aprite una shell avrete un tema diverso. Quando ne individuate uno che vi piace, prendete il nome del tema che vi appare all’avvio e andate a scriverlo nella variabile sopra citata.

Io, come ho già detto in precedenza, sto utilizzando eastwood. Ha dei colori molto rilassanti e non distrae troppo l’attenzione rispetto ad altri temi.

Modifica dei plugin

Sempre nel file ~/.zshrc possiamo trovare la variabile plugins. I plugins potete vederli come dei miglioramenti nell’autocompletamento per delle applicazioni che utilizzate spesso nel terminale.

Io attualmente uso questa configurazione.

plugins=(django npm docker)

Vi ricordo di separare i plugin con lo spazio e non con la virgola. Ovviamente Zsh offre molti altri plugins, sceglietene il minimo indispensabile perchè potrebbero rallentare l’avvio del terminale.

Alias, alias ovunque!

Nel terminale si possono aggiungere degli alias per velocizzare l’esecuzione di uno o più comandi. Se vi accorgete di scrivere sempre lo stesso comando (o addirittura una serie di comandi) allora significa che è giunta l’ora di dover aggiungere un alias.

Per aggiungere un alias è semplice: bisogna aggiungerli nel file ~/.bash_profile se usate bash oppure ~/.zshrc se usate Zsh. La sintassi per aggiungerne uno è la seguente:

alias <ALIAS>="<COMMAND>"

Ecco qui alcuni miei alias come esempio:

alias gbd="git branch | grep -v '*' | xargs git branch -D": eseguendo gbd (Git Branch Delete) verranno cancellati tutti i branch locali di Git del progetto contenuto nella cartella. Avviatelo solo se siete sicuri di quello che fate!
alias pycc='find . -name "*.pyc" -exec rm -f {} \;': eseguendo pycc (pyc clean) cancellerete ricorsivamente tutti i file compilati python presenti nella cartella. Molto utile se si fa refactoring in Python e abbiamo il timore che i file compilati non rispettino più il codice sorgente.
alias yda='youtube-dl -x --audio-format m4a --audio-quality 160k': eseguendo yda <YOUTUBE_URL> (YouTube Download Audio) scaricherete il file audio di un video di YouTube. Questo comando funziona solo se avete seguito la mia guida su come scaricare un video da YouTube.
alias ddev='docker-compose -f <ABSOLUTE_PATH_DOCKER_YAML_FILE>': eseguendo ddev <DOCKER_COMPOSE_COMMAND> (Docker dev) potete impartire qualsiasi al vostro Docker Compose senza preoccuparvi della cartella in cui vi trovate. Senza questo comando ero sempre costretto ad andare nella cartella del mio progetto Docker Compose cd <PATH_TO_DOCKER_COMPOSE_PROJECT> e poi scrivere docker-compose -f <DOCKER_YAML_FILE> <DOCKER_COMPOSE_COMMAND>… Tutto tempo buttato!
alias c<PROJECT_NAME>='cd <PROJECT_NAME_ABSOLUTE_PATH>': se avete un progetto su cui ci lavorate quotidianamente vi consiglio di creare un alias per raggiungerlo velocemente. Io come convenzione utilizzo la lettera c iniziale che ricorda il comando cd e poi il nome del progetto.

Git

Anche Git supporta un suo meccanismo di alias interno. Aprite o create il file ~/.gitconfig. Al suo interno aggiungiamo

[alias]
    st = status -sbu
    lg = log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit

Come si può intuire abbiamo aggiunto la sezione alias e abbiamo aggiunto due nuovi alias git. Una volta riavvito il terminale possiamo usare:

git st: una versione modificata di git status.
git lg: mostra l’albero dei commit.

Ovviamente questi sono due miei comandi ma nessuno vi vieta di crearne dei vostri!

SSH

Anche l’accesso ad una macchina remota può essere velocizzato. Immagino che le macchine a cui vi connettete da remoto siano sempre le stesse, ed ogni volta scrivere nel temrinale ssh <USERNAME>@<REMOTE_ADDRESS> -i <PRIVATE_KEY_PATH> è lungo, tedioso e difficile da ricordare. È tutta un’altra storia se noi potessimo connetterci semplicemente scrivendo ssh <ALIAS> dove <ALIAS> è il nome che noi abbiamo dato alla macchina remota. Tutto questo è possibile grazie al file di configurazione ~/.ssh/config. Se il file non è presente, potete crearlo scrivendo touch ~/.ssh/config. Tramite questo file possiamo salvare delle connessioni remote e richiamarle tramite un’alias, senza necessariamente riscrivere tutti i parametri ogni volta.

Il file ~/.ssh/config ha la seguente sintassi:

Host <ALIAS>
    HostName <REMOTE_ADDRESS>
    Port <PORT>
    User <USERNAME>
    IdentityFile <PRIVATE_KEY_FILE>

Sostituite le variabili scritte tra le parentesi angolate con i vostri parametri: in questo modo invece di scrivere

ssh <USERNAME>@<REMOTE_ADDRESS>:<PORT> -i <PRIVATE_KEY_FILE>

ora vi basta scrivere

ssh <ALIAS>

molto ma molto più veloce ed immediato. Nel file di configurazione sono obbligatori i campi HostName ed User, il resto sono opzionali. Si possono aggiungere più Host qualora abbiate diverse macchine a cui accedete da remoto.

I parametri SSH disponibili non sono solamente questi, se avete bisogno di funzionalità avanzate come il tunnelling vi consiglio di leggere la guida ufficiale su SSH Config File.

Curiosità

Questi comandi non sono legati alla produttività, ma sono pur sempre degni di nota.

say '<TEXT>': lo sapevate che il Mac può parlare e lo si può far parlare tramite il terminale? Combinando questo comando con ssh possiamo far parlare un Mac anche da remoto. Quindi nessuno ci vieta di mandare un messaggio d’amore alla propria ragazza attraverso il comando ssh girlfriend@<IP_ADDRESS> say 'I love you!', provate a farlo e osservate la sua reazione! (Spoiler: non apprezzerà ve lo posso assicurare ?).
yes: se avete un gelone temporaneo e avete bisogno di una fonte di calore, allora vi consiglio di avviare yes da terminale. Questo comando non fa altro che mandare la CPU al 100%!

Conclusioni

Spero che tutti questi miei trucchetti vi aiutino nel vostro quotidiano a raggiungere i vostri obiettivi lavoritivi nel minor tempo possibile. Sicuramente ci saranno altri milioni tips and tricks che non ne sono a conoscenza: se ne imparo degli altri cercherò di aggiungerli qui in modo da condividerli con voi.

A presto, buon lavoro e alla prossima!

Come scaricare i video da YouTube con il terminale

Sun, 17 Sep 2017 15:10:47 GMT

Avete appena trovato un video bellissimo su YouTube e volete a tutti i costi scaricarlo, oppure volete scaricare solo la parte audio del video per inserirlo nella vostra playlist musicale? Il terminale non vi spaventa? Bene, allora questa guida fa per voi!

Ci sono un sacco di siti online che fanno queste cose: pieni di pubblicità, a volte non funzionano neanche e solitamente danno pochissima possibilità di personalizzazione su cosa scaricare. Io mi sono stancato di appoggiarmi a questi programmi esterni e ho deciso di fare tutto “in casa”.

Questa guida si basa sul sistema operativo Mac OS. Ma con piccoli accorgimenti è possibile seguirla anche per Windows e Linux dato che i programmi che utilizzerò sono multi piattaforma.

Preparazione

Sostanzialmente per raggiungere lo scopo servono 3 programmi:

Homebrew: il miglior gestore di applicazioni per il Mac. Con questo software sarà una passeggiata installare gli altri due.
Ffmpeg: quando si parla di conversione audio/video lui è il punto di riferimento. Gratis, open source, cross platform, potente… Cosa chiedere di più?
Youtube-dl: il programma che fa il lavoro sporco di scaricare il video da YouTube.

Installazione

Ora che sappiamo cosa ci serve procediamo con le installazioni di questi software!

Apriamo il terminale del Mac.

Installiamo Homebrew

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Installiamo Ffmpeg

brew install ffmpeg --with-fdk-aac --with-tools --with-freetype --with-libass --with-libvorbis --with-libvpx --with-x265

Installiamo Youtube-dl
```
brew install youtube-dl
```

Bene! Ora abbiamo tutto l’occorrente per scaricare tutti i video di YouTube che vogliamo!

Si inizia!

Come esempio utilizzerò il video di Gigi D’Agostino che ha appena caricato online. Vi consiglio di vederlo ed ascoltarlo: la sobrietà delle sue pellicole non ha eguali :D!

Modalità automatica

Partiamo dalla cosa più semplice: scaricare il video senza perdere troppo tempo!

Andiamo su YouTube, apriamo il video e copiamo l’URL. Nel nostro caso è https://www.youtube.com/watch?v=UyyxYha4j6o.
Apriamo il terminale e scriviamo youtube-dl e incolliamo l’url del punto precedente. Quindi
```
youtube-dl https://www.youtube.com/watch\?v\=UyyxYha4j6o
```
noterete che copiando vengono aggiunti dei \ prima di ? e =. Non preoccupatevi, sono dei caratteri di escaping che sono necessari e che il terminale aggiunge automaticamente.
Attendiamo ed è fatta! Nella cartella in cui ci troviamo avremo il video!

Scegliere il formato video

Ok Ok, forse il formato scaricato non vi aggrada o ne volete uno con minor qualità… Per far questo scrivete:

Aggiungiamo l’opzione -F che ci mostra tutti i formati disponibili
```
youtube-dl -F https://www.youtube.com/watch\?v\=UyyxYha4j6o
```
Avremo una bella lista di formati disponibili. Scegliamo quello che più ci aggrada e prendiamo nota del format code.
Per scaricare la versione scelta ci basterà aggiungere -f <format_code> dove <format_code> è il codice scelto nel punto precedente. Quindi, per esempio, se volessimo scaricare la versione
```
299          mp4        1920x1080  DASH video 5820k , avc1.64002a, 50fps, video only, 274.09MiB
```
ci basterà scrivere.
```
youtube-dl -f 299 https://www.youtube.com/watch\?v\=UyyxYha4j6o
```

Estrarre la traccia audio

Per avere solo la traccia audio ci basta scegliere il format code che ha nella colonna resolution audio only. Nel nostro video se mostriamo la lista dei formati disponibili possiamo notare che ci sono queste tracce audio

format code  extension  resolution note
139          m4a        audio only DASH audio   48k , m4a_dash container, mp4a.40.5@ 48k (22050Hz), 2.26MiB
249          webm       audio only DASH audio   62k , opus @ 50k, 2.39MiB
250          webm       audio only DASH audio   79k , opus @ 70k, 3.16MiB
140          m4a        audio only DASH audio  128k , m4a_dash container, mp4a.40.2@128k (44100Hz), 6.03MiB
171          webm       audio only DASH audio  152k , vorbis@128k, 6.18MiB
251          webm       audio only DASH audio  153k , opus @160k, 6.24MiB

Molto probabilmente il formato audio non è quello che vogliamo. Quindi abbiamo bisogno una conversione audio. Youtube-dl utilizza ffmpeg per effettuare la conversione. Per esempio se volessivo avere un file audio con formato .m4a con un bitrate di 160k ci basterà scrivere

youtube-dl -x --audio-format m4a --audio-quality 160k https://www.youtube.com/watch\?v\=UyyxYha4j6o

Dove le opzioni significano

-x: estrai la traccia audio dal video.
—audio-format m4a: il formato da scaricare, o da convertire se non presente nella lista, è m4a. I formati disponibili sono "best", "aac", "flac", "mp3", "m4a", "opus", "vorbis", "wav".
—audio-quality 160k: bitrate della traccia audio desiderato.

Scaricare più video o una playlist

Ora che sappiamo come scaricare un video nel formato perfetto per noi, perchè non applicare le stesse impostazioni per più video in un colpo? È semplicissimo! Basta aggiungere più url nel nostro terminale separati da uno spazio. Per esempio possiamo scrivere

youtube-dl -x --audio-format m4a --audio-quality 160k https://www.youtube.com/watch\?v\=UyyxYha4j6o https://www.youtube.com/watch\?v\=6L5a3Qt7cvg

per avere entrambi i video trasformati in traccia audio.

Se invece volessimo scaricare una playlist invece di un singolo video ci basta inserire l’URL della playlist!

Semplifichiamoci la vita con gli alias

Quando voglio scaricare le canzoni da YouTube, di solito uso sempre le stesse impostazioni. E scrivere ogni volta youtube-dl -x --audio-format m4a --audio-quality <URL> è una rottura oltre che difficile da ricordare. Sarebbe molto meglio se si potesse scrivere solamente yda <URL> (yda sta per Youtube Download Audio). La buona notizia è che si può fare!

Apriamo il terminale e inseriamo

echo "alias yda='youtube-dl -x --audio-format m4a --audio-quality 160k'" | tee -a ~/.bash_profile && source !$

Cosa fa questo comando?

echo "alias yda='youtube-dl -x --audio-format m4a --audio-quality 160k'" | tee -a ~/.bash_profile: scrivi il nuovo alias in fondo al file ~/.bash_profile. In questo modo, ogni volta che apririamo un nuovo terminale avremo questo alias pronto all’uso.
&& source !$: dopo aver scritto il nuovo alias ricarica il file ~/.bash_profile nel terminale, in modo da avere il nuovo alias disponibile anche nel terminale corrente.

Ora, se vogliamo scaricare una qualsiasi canzone da YouTube sarà semplicissimo.

Cerchiamo il video su YouTube, copiate l’url.
Apriamo il terminale e scriviamo yda <URL>.
Fine!

Voglio saperne di più!

Youtube-dl non ha solo queste impostazioni, queste sono solamente quelle che utilizzo io. Se volete saperne di più vi basta scrivere youtube-dl --help. In questo modo avrete tutte, ma proprio tutte, le impostazioni di questo programma e vi assicuro che sono tantissime!

Conclusioni

Spero che questa guida vi abbia dato uno strumento in più per poter scaricare i video di YouTube a voi più cari, senza aver bisogno di siti online pieni di pubblicità che funzionano una volta sì e dieci no. Inoltre spero che ora abbiate intuito le potenzialità del terminale, applicazione usata giornalmente dagli sviluppatori, ma snobbata ingiustamente da molti!

Alla prossima!

Come giocare ai videogiochi di due o tre ere fa

Mon, 02 Jan 2017 07:03:47 GMT

In questi giorni di vacanza mi è venuto un momento nostalgia dei vecchi, vecchissimi videogiochi degli anni ‘90 che giocavo sul mio primo PC, un vetusto Compaq Presario con 133MHz di CPU.

Sembra impossibile ma è ancora possibile giocare a questi videogiochi senza aver troppi problemi di compatibilità grazie a DOSBox. Questo programma non è altro che un emulatore del sistema operativo DOS: negli anni ‘90 moltissimi giochi supportavano questo sistema operativo e quindi possiamo sfruttare a nostro vantaggio questa cosa.

In questa guida spiegherò come poter giocare a qualche videogioco che ha segnato la mia infanzia.

Installiamo DOSBox

Per prima cosa bisogna installare DOSBox, io vi consiglio di utilizzare come sistema operativo Windows… Su Mac ho qualche problema di performance… Sembra assurdo ma è così :D. L’installazione non è niente di che: basta andare nella sezione download del sito e scaricare il pacchetto ed installarlo come un comune software. Una volta ultimato questo passo siamo pronti a tuffarci nel passato!

Grand Prix Circuit

Cominciamo ad avviare un gioco semplice semplice. Grand Prix Circuit!

Download

Per prima cosa dobbiamo scaricare il gioco. Scarichiamo il pacchetto ed estraiamo i file dall’archivio .zip in una cartella, per esempio in C:\giochi\gp\.

Mounting del volume

Ora avviamo DOSBox. Ci compare un prompt dei comandi che non è altro che la classica shell di DOS. La prima cosa è montare il volume dove risiede il nostro gioco. In parole più semplici dobbiamo dare a DOSBox un volume C:\, una parte di memoria, che abbia accesso al gioco. DOSBox, senza questa operazione, non può leggere nessun dato del nostro hard disk proprio perchè i volumi (C:\, D:\ ecc) che utilizza Windows sono completamenti differenti rispetto a quelli che usa DOSBox. Per fare questa operazione basta scrivere in DOSBox

mount c c:\giochi\

Ora che abbiamo montato la nostra cartella giochi come volume C, possiamo accederci tramite DOS.

c:

Potete vedere che ora DOSBox mostra C:\> invece di Z:\> proprio perchè è all’interno del nostro volume appena creato. Sostanzialmente ora in DOSBox siamo nella cartella C:\giochi\ del nostro PC.

Avvio del gioco

Ora utilizziamo un’altro comando DOS:

dir

questo comando mostra tutti i file e le cartelle contenute nel path in cui ci troviamo. Dovrebbe comparire la nostra cartella gp. Per accederci utilizziamo il comando

cd gp

Ora siamo nella cartella dove è presente Grand Prix Circuit appena scaricato. Per avviare il gioco con ci resta che eseguire il comando

GP.EXE

Complimenti! Ora potete divertirvi a giocare ad un super gioco che ha fatto la storia!

Riassunto

Bene, fin qui abbiamo imparato a fare le seguenti cose:

Download del gioco e avvio di DOSBox.
Mounting della directory giochi per offrire a DOSBox una parte di memoria del nostro PC.
Navigazione tra le cartelle in DOS tramite i comandi cd dir. Questa guida non vuole insegnare ad utilizzare questo sistema operativo e quindi sono stato abbastanza sbrigativo. Se volete saperne di più potete documentarvi tramite questo link.
Avvio del gioco.

Questi passi vanno bene per buona parte dei vecchi videogiochi, ma ce ne sono altri che richiedono l’installazione oppure l’inserimento del CD-ROM per poter giocare. Il prossimo gioco rientra proprio in questa casistica.

Ignition

Questo gioco mi piace davvero parecchio! Mi ricorda le ore passate insieme a mio cugino parecchi anni fa!

La modalità di avvio è simile alla precedente, solo che in questo caso dobbiamo installare il gioco come se avessimo un CD-ROM.

Download

Scarichiamo il gioco ed estraiamo l’archivio in C:\giochi\ign\.

Mounting dei volumi

Montiamo il volume C: con lo stesso comando usato in precedenza

mount c: c:\giochi\

Ora inseriamo il CD-ROM di Ignition! In che modo? Più o meno come si monta un classico volume.

mount d: c:\giochi\ign\ -t cdrom

In questo caso stiamo dicendo a DOSBox di mostrare la nostra cartella c:\giochi\ign\, dove c’è dentro il gioco scaricato, come se fosse un CD-ROM.

Installazione

Ora entriamo nel CD e avviamo l’installazione

d:
DOS_INST.EXE

A questo punto partirà l’installazione. Scegliete italiano e premete sempre avanti.

Avvio del gioco

Ora siamo pronti per giocare. Scrivete questi tre comandi e buon divertimento!

c:
cd IGNITION
IGN_DOS.BAT

Come scaricare le canzoni da Soundcloud in pochi semplici click

Sun, 13 Nov 2016 07:03:47 GMT

Soundcloud, per chi non lo conoscesse, è un ottimo sito web che permette ai musicisti di collaborare, promuovere e distribuire la loro musica.

Purtroppo non permette lo scaricamento delle canzoni, ma utilizzando gli strumenti per sviluppatori di Google Chrome è molto semplice bypassare questa restrizione.

Istruzioni

Accedete a Soundcloud usando Google Chrome, e andate sulla pagina della canzone che volete scaricare.
Aprite gli strumenti per sviluppatori premendo F12 su Windows oppure cmd + opt + I su Mac. Cliccate sul tab Network. In questa sezione, cliccate sulla sesta icona a partire da sinistra. In questo modo vi si aprirà la linea del tempo dei vari scaricamenti che effettua il browser.
Ora siete pronti per intercettare il file .mp3 da scaricare! Avviate la canzone dal browser. Appena avviata la canzone vedrete degli scaricamenti avviarsi sulla timeline, una linea sicuramente attirerà la vostra attenzione perchè sarà molto più lunga delle altre. Questa linea rappresenta proprio la canzone in formato .mp3.
Selezionate la canzone dalla timeline. Per farlo basta trascinare il mouse su un pezzettino della linea, vi consiglio di prendere una parte in cui questa linea è isolata così da non sbagliare la selezione.
Una volta selezionato lo scaricamento nella timeline, in basso vi comparirà la voce della vostra traccia. Premete con il tasto destro del mouse e cliccate su “Apri il link in una nuova tab”.
Ecco fatto! Ora avete la vostra traccia in .mp3! Cliccate su File->Salva con nome... e godetevi la canzone dove volete e quando volete!

Video tutorial

6 passi vi sembrano troppi? Vi assicuro che dopo averci preso la mano potete scaricare quello che volete in meno di 2 secondi. Ecco qui i 6 passaggi racchiusi in un piccolo video.

Alla prossima!

Come migliorare le foto con Nik Collection

Thu, 11 Aug 2016 07:03:47 GMT

Il digitale ha rivoluzionato parecchi settori, incluso quello della fotografia. Io mi sono affacciato a questo mondo proprio nel momento di transizione… e devo dire che il vecchio rullino non mi manca proprio.

Un grande vantaggio della fotografia digitale è sicuramente l’affascinante mondo della post produzione. I puristi della fotografia lo detestano, i veterani del vecchio rullino pensano che sia un abominio. Per me invece è diventata una fase importante quasi quanto lo scatto: con la post produzione si può completamente modificare una foto mediocre e renderla in uno scatto unico, aggiungere dinamicità, dare carattere ad una foto insipida.

Questa piccola guida vi insegnerà proprio questo (o si spera): la fotografia che utilizzerò l’ho scattata in Francia e si tratta della famosissima Notre Dame de Paris.

Prima di iniziare

Per seguire questa guida servono software professionali: io ho utilizzato Adobe Photoshop. Potete utilizzare anche Aperture oppure Lightroom. Questi software costano e non poco: la prima cosa da fare è acquistarli o sperare che la vostra azienda abbia una licenza per voi, oppure che qualche vostro amico sia particolarmente gentile e vi passi uno slot della loro licenza (Photoshop può essere utilizzato fino a 3 PC con una singola licenza).

Questa guida non vuole insegnarvi ad utilizzare questi software, diciamo che è un prerequisito averne almeno una conoscenza base.

Il software principe di questa guida è invece questa collezione di plugin che si appoggiano ad essi: Nik Collection.

Fino all’anno scorso questa suite costava circa $500, e secondo me li valeva tutti. Ora invece Google ha deciso di renderla gratuita!

Scelta della fotografia

Prima cosa da fare è scegliere quale scatto si intende migliorare / modificare. Una cosa deve essere chiara: la post produzione può fare miracoli ma c’è un limite a tutto. Se la foto iniziale fa pena, è facile che anche sotto un pesante ritocco farà pena uguale. La post produzione valorizza il contenuto, ma se il valore iniziale è zero difficile che esca qualcosa di sensazionale. Quindi cercate sempre di scattare il miglior scatto possibile per avere una buona base di partenza. La mia fotografia è questa: l’ho scattata con il mio LG G3, non una reflex, semplicemente uno smartphone vecchio di 3 anni. Durante il mio soggiorno a Parigi non avevo di meglio, ma comunque ha un ottimo potenziale.

Scelta la fotografia bisogna decidere che fare: magari se non sapete cosa può fare Nik Collection questo passo vi sarà un po’ difficile. Il mio obiettivo in questa foto è di valorizzare la cattedrale, far risaltare i dettagli e di dare un tono drammatico, tipico delle cattedrali, a tutta la scena.

Conosciamo Nik Collection

Ora che abbiamo deciso il nostro punto di partenza e il nostro obiettivo è giunta l’ora di conoscere gli strumenti a nostra disposizione.

Se non lo avete ancora fatto scaricate Nik Collection e installatelo. Sul vostro PC deve essere già presente Photoshop.

Una volta installato, se avviate Photoshop, potete vedere un piccolo nuovo riquadrino dove potete scegliere i vari plugin che compongono questa suite:

Dfine: è il primo plugin da avviare. Il suo compito è di rimuovere il rumore dalle fotografie.
Analog Efex Pro: simula l’effetto delle vecchie pellicole e delle antiche macchine fotografiche che hanno fatto la storia con i loro particolari effetti. Avete presente i filtri Instagram? Ecco avete colto cosa può fare questo plugin.
Color Efex Pro: se volete correggere qualche tinta, creare effetti che hanno a che fare con i colori, questo plugin è perfetto.
Silver Efex Pro: utilissimo se volete creare un’immagine monocromatica.
Viveza: ottimo se volete modificare solo dei particolari della foto, dare risalto a dei soggetti.
HDR Efex Pro: per creare un’immagine HDR. Senza entrare troppo in tecnicismi, per creare una reale immagine HDR c’è bisogno di più scatti dello stesso soggetto usando esposizioni diverse. Ma questo plugin riesce ad ottenere lo stesso risultato anche da una singola immagine.
Sharpener Pro: il suo compito è quello di far risaltare i dettagli e di rendere meno sfuocata l’immagine.

Se per caso non vi compare il riquadro di Nik Collection, potete trovare tutti questi software nel menu in alto alla voce Filtri > Nik Collection.

Rimuoviamo il rumore

Ora è il momento di iniziare! Il primo passo che eseguo sempre è quello di rimuovere il rumore dalla fotografia. Se lo scatto è stato eseguito da una fotocamera non particolarmente performante, come il mio smartphone, questo passaggio è praticamente obbligatorio. Il rumore, anche se impercettibile, viene amplificato durante i passaggi di modifica. Quindi pulire l’immagine da questi disturbi è molto importante.

Questo passaggio è molto semplice. Caricate l’immagine in Photoshop, avviate Dfine. Come lo aprire potete notare che fa qualche magia e rimuovere il rumore automaticamente. Potrebbe sembrare che non sia cambiato nulla, in realtà per apprezzare il lavoro di Dfine è utile ingrandire l’immagine al 100%. Per far ciò fate doppio click sull’immagine, infine, in alto a sinistra, dove c’è scritto Views, avete tre modalità di visualizzazione:

Single image view: la vista di default. Vedete solo l’output finale.
Split view: potete vedere contemporaneamente l’immagine prima e dopo l’applicazione del filtro. Potete spostare anche la linea rossa per avere un rapido confronto tra le due versioni.
Side by side preview: sostanzialmente avrete le due immagini, prima e dopo l’applicazione del filtro affiancate.

Una volta che avete potuto apprezzare i cambiamenti premete OK. Così da poter passare al passo successivo.

HDR Efex Pro, tocca a te!

Ora è giunto il momento di aggiungere un tocco di HDR all’immagine. HDR sta per High Dynamic Range ed è una tecnica fotografica che permette di mostrare più dettagli rispetto ad una fotografia normale. Avete presente quelle situazioni in cui scattate una fotografia ad un’ambiente che presenta sia punti particolarmente illuminati che bui? Capita che la parte molto illuminata viene solo una bella chiazza bianca e la parte scura una chiazza nera. L’HDR riesce a superare queste problematiche. Questa è solo per darvi una idea di cosa sia l’HDR, ci sarebbe da scrivere una guida solo su questo… Ma è meglio tornare alla nostra immagine!

Sempre dal riquadro di Nik Collection, nella sezione HDR Efex Pro scegliete Tone Mapping (Single Image).

Sulla parte sinistra potete trovare il Preset Library, in esso ci sono già degli ottimi punti di partenza. Io ho scelto Deep 1 che si trova nella libreria Realistic.

Una volta scelto il punto di partenza potete focalizzarvi sulla parte che si trova a destra della finestra. Qui potete trovare una marea di configurazioni per modificare ogni singolo aspetto del filtro. Le macro aree sono queste:

Tone Compression: ci sono tutte le impostazioni che riguardano solamente l’effetto HDR. Sicuramente è qui che trovate le impostazioni che cambiano radicalmente l’aspetto della vostra immagine.
Tonality: qui potete trovare le impostazioni classiche dell’immagine come esposizione, ombre, luci, contrasto ecc. Un’opzione che a me piace particolarmente è structure. Aumentandola potete notare come l’immagine diventi particolarmente definita. Occhio a non esagerare perchè oltre ad esaltare i dettagli esalta anche il rumore. Ecco perchè vi avevo caldamente consigliato di rimuoverlo con Dfine… Ora i nodi vengono al pettine!
Finishing: è la post produzione dell’effetto di post produzione! Nel senso sono gli ultimi ritocchi che potete fare prima di abbandonare questo plugin. Io da questa area ho aggiunto un piccolo effetto di vignettatura. Vicino alla scritta Vignette c’è un piccolo menu di scelta. Io ho scelto Lens 2. L’effetto vignettatura non fa altro che scurire i bordi dell’immagine (o schiarire). È un ottimo modo per guidare l’attenzione dell’osservatore. In questo caso il mio intento è di esaltare la cattedrale.

Anche in questo caso non sono andato troppo in dettaglio. Il mio consiglio è di giocare e provare da soli tutte le varie funzionalità. Solo così si può padroneggiare questa suite… Usandola!

Ecco qui il risultato finale dopo questo passaggio.

Correggiamo i colori

Ora l’immagine ha un tono molto più drammatico rispetto all’originale, si addice molto ad una cattedrale. I dettagli della struttura sono stati messi in risalto, possiamo essere soddisfatti del nostro lavoro! C’è solo un piccolo problema… La cattedrale è diventata un canarino! È troppo satura e quindi abbiamo bisogno di rimuovere un po’ di saturazione alla cattedrale.

Per far questo avviamo Color Efex Pro. La finestra che si apre ormai dovrebbe essere familiare: cambiano solo i filtri di partenza sulla sinistra e le impostazioni sulla destra.

Il filtro che andremo ad utilizzare per desaturare l’immagine si chiama Bleach Bypass. Selezioniamolo dai filtri disponibili e notiamo subito i cambiamenti sull’immagine.

Fino ad ora abbiamo applicato i filtri sull’immagine intera, in questo caso noi vogliamo applicarlo solo sulla cattedrale senza intaccare il resto.

Dite ciao ai control points!

Per risolvere questo problema è necessario imparare un’importantissima feature che fino adesso vi ho tenuto nascosto. I control points.

Questi “punti di controllo” vi permettono di applicare il filtro solo su aree specifiche. Proviamo subito ad utilizzarne uno. Sulla parte destra cercate la funzione Control Points, qui potete notare due pulsanti: il primo raffigura un cerchio con accanto il ”+” e l’altro un ”-“. La differenza tra i due è che il primo aggiunge un punto con opacità 100%, il secondo con 0%. In altre parole il primo applica il filtro nel punto selezionato, il secondo lo rimuove.

A noi serve applicare il filtro nel punto in cui selezioniamo. Quindi abbiamo bisogno di premere sul bottone con il ”+“. Una volta premuto spostiamo il cursore sulla cattedrale, noterete che il simbolo del cursore è diventato una sorta di mirino, clicchiamo sulla cattedrale. Nik Collection è abbastanza intelligente da capire che volete applicare il filtro solo sul punto selezionato, quindi rimuove il filtro dal resto dell’immagine e lo lascia solo sul control point.

Una volta posizionato il control point si può notare che c’è un cerchiolino sull’immagine con due sliders. Il primo determina il raggio d’azione del control point, il secondo la sua opacità. Ovviamente più il raggio d’azione è grande più il nostro filtro influenzerà una porzione più grande dell’immagine e più aumentiamo l’opacità più si nota la differenza (nel nostro caso è già al 100%).

Siccome il control point ha un raggio d’azione circolare, vi consiglio di aggiungere tanti punti di piccole dimensioni piuttosto che averne uno grande per avere un maggiore controllo su di esso.

Ma come facciamo a capire il vero raggio d’azione di un control point? Effettivamente Nik collection applica il filtro in modo intelligente: nonostante il raggio d’azione sia circolare, non si nota il punto in cui smette di applicare queste correzioni. Perchè appunto il punto di forza di Nik sono i suoi algoritmi di creazione delle maschere di applicazione. Probabilmente questa frase può essere arabo per chi non non è ferrato con Photoshop, ma sarà chiaro a breve. Per capire cosa ho scritto torniamo su Color Efex Pro; nella sezione Control Points possiamo notare la lista dei nostri punti aggiunti. Ogni voce di questa lista è composta da 4 punti:

Checkbox per abilitare il control point.
Il suo nome.
La percentuale di immagine influenzata.
Checkbox per visualizzare il punto di applicazione (la sua maschera).

Mettiamo la spunta a quest’ultima checkbox di un qualsiasi control point inserito. L’immagine diventa monocroma e da qui possiamo vedere effettivamente il vero punto di applicazione del filtro del control point selezionato. Il nero indica che non è stato applicato il filtro, il bianco dove è stato applicato, le varie gradazioni intermedie indicano una diversa opacità dell’applicazione.

Aggiungete tutti i punti di controllo necessari per “rendere bianca” la cattedrale, in questo modo applicherete il filtro solo sulla cattedrale. Ecco qui la mia cattedrale bianca, indice che sto applicando il filtro bleach bypass solo su di essa.

I control points secondo me sono il vero punto di forza di Nik Collection. Per creare la stessa maschera utilizzando solo Photoshop, invece di impiegarci 5 minuti, ci avremmo impiegato ore!

Una volta che ci siamo accertati che il filtro viene applicato solo alla cattedrale, possiamo rimuovere le spunte alla checkbox della maschere dei punti di controllo e tornare a visualizzare l’immagine normale.

Finalmente ci siamo!

Conclusioni

Ecco qui il risultato finale affiancato alla nostra immagine originale:

Spero che questa guida vi abbia dato una vaga idea delle potenzialità di questa suite di plugin. Ovviamente questa è solo la punta della punta dell’iceberg: il mio intento non è di spiegare la suite e tutti i suoi comandi, ma di applicarlo in un vero caso d’uso.

Se avete voglia di saperne di più vi consiglio caldamente questo video tutorial introduttivo… È in inglese e dura un’ora… Ma ne vale veramente la pena!

Alla prossima!

Come rimuovere i virus dal computer

Sun, 07 Aug 2016 07:03:47 GMT

“Ciao! Tutto bene? Senti penso di avere un virus nel PC, puoi darci un’occhiata?”

Le varianti di questa frase sono infinite, ma più o meno quasi la totalità delle persone che mi chiamano per avere una mano per questo problema esordiscono così.

Oggi vi spiego cosa si può fare per risolvere questo problema da soli, senza spendere un centesimo e senza neppure aver bisogno di chissà quali competenze.

Ci sono virus e virus

Prima di iniziare è meglio sapere un minimo le varie tipologie di virus che potreste imbattervi. Secondo me è utile per capire i messaggi di errore che il vostro antivirus vi propone se trova qualcosa di insolito.

Malware: è qualsiasi cosa che può recare danno al vostro pc. Quindi è la macrocategoria che contiene tutte le voci sottostranti… Infatti avrei dovuto scrivere “Ci sono malware e malware”, ma vabbè ci siamo capiti!
Virus: malware che è in grado di autoreplicarsi e di infettare altri utenti tramite le chiavette usb o supporti removibili.
Worm: simile al virus ma infetta gli altri PC attraverso la rete.
Trojan: si mostra come un software utile, in realtà apre letteralmente una porta ad un attaccante per poter rubare i vostri dati sensibili oppure prendere il possesso del vostro PC. È appunto un cavallo di Troia!
Spyware: spiano ciò che fate sul PC e vendono queste informazioni sul mercato nero.
Adware: vi insozzano il PC di pubblicità indesiderata.
Keylogger: registrano i tasti che premete nella speranza che digitiate qualche credenziale o meglio ancora il codice della carta di credito.
Backdoor: se l’attaccante riesce ad installare questa roba può utilizzare il vostro PC per fare parecchie cose in rete: per esempio inviare email o connettere il vostro PC ad un sito per sovraccaricarlo e provocare un disservizio.
Rootkit: sono molto diffici da scovare, se ne avete uno è come se l’attaccante avesse il vostro pc in casa loro. Semplicemente possono fare quello che vogliono a distanza.
Scareware: sono malware che vi spaventano, vi dicono che il vostro PC ha milioni di problemi e di pagare loro per sistemare tutto. Peccato che invece il vero problema è il programma stesso che finge di aiutarvi. Il più delle volte le persone si beccano questo tipo di malware.
Cryptolocker: nell’ultimo periodo è stato molto in voga. In pratica, una volta avviato, comincia a criptare tutti i vostri documenti e quando ha finito vi chiede un riscatto. Se rivolete i vostri documenti dovete pagare!

La prevenzione prima di tutto!

Premessa: io non uso antivirus, secondo me è possibile vivere anche senza. L’importante è stare attenti e sapere ciò che si avvia… Sempre! Se invece non vi sentite sicuri allora è meglio installare qualche antivirus che possa colmare le vostre disattenzioni in tempo reale. Infine se avete già un malware nel vostro PC allora installatelo immediatamente. Io di solito installo Bitdefender sui PC che sistemo. Ci sono davvero pochissime opzioni e fa il suo lavoro. Una volta installato eseguite una scansione completa del PC e sperate che riesca a risolvere il vostro problema.

Disinstallazione del malware

L’antivirus fa bene due cose: mantenere i virus alla larga prima che possano fare danni e rimuoverli se per caso sono già all’interno del vostro PC. Il problema è che sono molto bravi solo su una categoria, i virus appunto. Ma come avete letto poco tempo fa esistono una miriade di malware che non rientrano in questa categoria. Qualora il vostro malware fosse ancora lì a darvi fastidio avete bisogno di altro… Forse anche di poco altro… Alcune volte basta veramente solo disinstallare l’app che vi da fastidio senza aver bisogno di chissà quali software.

Eseguire questo passo è molto semplice:

Leggete il nome dell’app che si apre e che vi da fastidio.
Andate in Pannello di Controllo > Programmi e Funzionalità > cercate il nome dell’app e disinstallatela.
Se per caso vi dice che l’app è in uso, chiudetela. Se non riuscite a chiuderla aprite il task manager premendo ctrl+shift+esc. Andate nella tab processi e terminate l’app in questione.

Questi passi possono variare sensibilmente in base alla versione di Windows che possedete.

Antibiotici ad ampio spettro

Immagino che se state leggendo qui significa che il vostro bel malware vi vuole molte bene ed è ancora lì nel vostro PC a rendervi la giornata un inferno. Bene! Ora è tempo di utilizzare due software: Malwarebytes e AdwCleaner. Questi due software io li chiamo antibiotici ad ampio spettro proprio perchè fanno questo lavoro: cercano di togliere qualsiasi malware e quindi riescono a togliere più schifezze rispetto ad un antivirus normale.

Io vi consiglio di iniziare con Malwarebytes. Scaricatelo, installatelo (non c’è bisogno della versione premium), aggiornate il suo database e infine fate partire una scansione completa. Tutti questi passi dovrebbero essere semplici e quindi non mi dilungo troppo.

Finita la scansione, probabilmente avrà trovato qualcosa, seguite i passi e rimuovete ciò che ha trovato. Infine vi chiederà di riavviare il PC. Fatelo.

Ora è il momento del secondo software: AdwCleaner. Anche qui i passi sono semplici. Scaricatelo, installatelo e infine avviatelo. La schermata è molto semplice: premete per prima cosa su Scan per avviare la scansione. Poi, una volta concluso, premete su Clean per avviare la pulizia. Infine vi chiederà di riavviare il PC. Anche in questo caso fate come vi dice.

Un po’ di esperienza non guasta mai

A questo punto spero che i vostri problemi siano finiti. Se invece il vostro malware è ancora lì allora è il caso di chiamare un tecnico perchè i tool semplici da utilizzare sono finiti e c’è bisogno di una mano esperta. Tutto quello che potete fare è salvare il salvabile e alzare la cornetta per chiedere assistenza.

Extrema ratio

In realtà c’è ancora una piccola cosa che potete fare da soli, anche se è abbastanza pericolosa: potete tentare il ripristino completo del vostro PC. Nel corso degli anni il ripristino del PC è diventato un processo molto semplice e secondo me è un passo che è diventato alla portata di tutti.

La cosa che dovete fare prima di tutto è salvare i vostri dati, e per salvare intendo su un Hard Disk esterno, unità rimovibile come una chiavetta USB. Insomma salvateli fuori dal PC per essere sicuri di non fare danni.

Se avete Windows 10 i passi sono semplici: andate in Impostazioni > Aggiornamento e sicurezza > Reimposta il PC > Per iniziare e puoi scegliere tra queste opzioni:

Mantieni i miei file: magari provate per prima cosa questa opzione. In questo modo i vostri dati sono al sicuro, ma Windows 10 verrà ripristinato e verranno cancellate le vostre applicazioni.
Ripristina le impostazioni del produttore: questa opzione è la più efficace perchè rende il vostro PC come nuovo.
Rimuovi tutto: scegliete questa opzione nel caso non trovaste la voce precedente.

Conclusioni

Spero che questa guida vi abbia aiutato a risolvere il vostro problemino da soli… Alla fine c’è anche una bella soddisfazione a risolvere i problemi senza l’aiuto di nessuno, no :)? Alla prossima!

Benvenuti!

Wed, 03 Aug 2016 07:03:47 GMT

Eccomi qui, sull’Eurocity diretto per la Svizzera, ovviamente fermo a causa dei lavori alla stazione di Monza.

Proprio per questo motivo ho deciso di impiegare il mio tempo che passo sui treni a scrivere questo mio piccolo blog (e anche a crearlo).

Non ho ancora ben deciso cosa e quanto scriverò. Probabilmente molti articoli saranno delle guide per risolvere i milioni di problemi che ogni tanto risolvo a chi mi “ingaggia” come tecnico informatico. Oppure altro, davvero non lo so ancora. Per ora mi sono divertito a creare questo piccolo blog. Ora mancano solo i contenuti! :)