Come aggiungere test per Processing
Questo articolo nasce dopo aver discusso alla scorsa Hack Fest di Padova. Un sentito grazie a tutte le persone che hanno mostrato interesse all'argomento. La guida ufficiale dell'architettura dei test è disponibile qui.
Gli unit test sono una parte di ogni programma (anche se non è proprio la parte più interessante da scrivere) perchè permettono di scovare eventuali errori prima del rilascio di una versione del software. Per intenderci meglio: uno sviluppatore cambia qualcosa in un algoritmo ma scrive male una stringa. Questo algoritmo non funzionerà. Gli unit test servono proprio a prevenire questi errori. La teoria è molto semplice. Un test lancia l'algoritmo e confronta questi output con dei risultati veri e che sono stati verificati. Se l'output è diverso dal risultato attesto il test fallisce e si viene informati dell'errore (quale riga ha causato quale errore).
Nel caso specifico di Processing gli output di un algoritmo (ovvero dei vettori o dei raster) vengono confrontati con layer verificati da chi ha creato il test. Se durante il confronto qualcosa non torna (layer è in una posizione diversa, dovrebbe essere un punto invece è una linea, non c'è proprio un risultato, ecc..) il test fallisce. Il codice di QGIS è ospitato su github. Il motore dei test è invece ospitato su Travis. Detta in parole semplici: quando uno sviluppatore cambia qualcosa nel codice e manda le sue modifiche (chiamate commit) al codice sorgente, Travis inizia una vera e propria compilazione di QGIS in remoto. Durante la compilazione vengono fatti girare i vari test e se qualcosa non va si capisce subito quale modifica ha causato l'errore. Questo sistema di prevenzione ha un valore intrinseco immenso in quanto per tutti gli algoritmi (ma non solo, infatti ogni pezzo di QGIS può essere accompagnato da un test) di cui esiste un test si ha la garanzia che funzionino e che continuino a funzionare.
Tutti (ma proprio tutti) possono aggiungere dei test per Processing. Il processo è un po' macchinoso, ma ne vale la pena.
L'architettura dei test necessita di alcuni software e accorgimenti, in particolare si appoggia interamente al software di controllo versioni git. Oltre a git consiglio l'utilizzo di un editor di testo avanzato (non avanzatissimo però ecco, non un blocco note). Il flusso di lavoro, anche se complesso, è piuttosto lineare:
- creazione account su Github
- fork del repository di QGIS sul proprio account. Questa operazione permette di avere una copia del codice di QGIS ma sul proprio account
- clonazione della copia forkata. Ovvero copiare sulla macchina locale la copia personale di QGIS
- utilizzare l'ultima versione di QGIS master
- scegliere un algoritmo di cui non esiste ancora un test
- lanciare l'algoritmo e verificare che il risultato sia corretto
- copiare il test e i risultati in una particolare cartella di QGIS
- inviare il test e i risultati dal computer locale alla pripria copia su github
- fare una pull request, ovvero chiedere che le modifiche della proprio copia di QGIS vengano incorporate nel codice sorgente vero
Procediamo per punti.
La procedura è semplice anche per chi usa Windows. Rimando al sito ufficiale per tutte le informazioni git
Anche in questo caso non c'è tanto da spiegare, si fa tutto dal sito di github
Questa procedura viene interamente fatta dal sito di github
-
cercare il repository di QGIS
-
cliccare sul pulsante fork
-
a questo punto si avrà la copia forkata di QGIS sul proprio account di github
La procedura cambia a seconda del sistema operativo. Di seguito un esempio su una macchina Linux
-
aprire un terminale e spostarsi nella cartella in cui si vuole clonare il repository forkato. Una volta scelta la cartella bisogna copiare l'url di github del fork...
-
... e incollarlo nel terminale con il seguente comando
git clone [email protected]:ghtmtt/QGIS.git
Basta aspettare un po' (il repository di QGIS pesa poco più di un GB) e si avrà una esatta copia locale su cui si potrà lavorare
Anche se i test possono essere aggiunti per qualunque versione di QGIS il consiglio è quello di utilizzare l'ultima versione di QGIS disponibile.
Ci sono già diversi algoritmi di Processing che sono accompagnati da test. L'elenco di tutti i test già eseguiti è presente in un file qgis_algorithm_tests.yaml. Questo file si trova dentro il repository appena clonato, ovvero nella cartella: QGIS/python/plugins/processing/tests/testdata
Per vedere quali algoritmi hanno già un test si può aprire il file qgis_algorithm_tests.yaml cercare il nome inglese dell'algoritmo. Per esempio l'algoritmo Densify geometries ha già un test e lo si può trovare cercando qgis:densifygeometries.
È quindi fondamentale cercare prima gli algoritmi sprovvisti di test per evitare di creare dei doppioni.
Tutta questa parte si svolge dentro QGIS.
L'architettura dei test è accompagnata da alcuni dati predefiniti da utilizzare. Se i dati forniti non dovessero essere adatti si possono tranquillamente aggiungere altri dati nel repository.
Questi dati (ed eventualmente anche dati creati ad hoc) sono nella cartella: QGIS/QGIS/python/plugins/processing/tests/testdata/custom del repository locale di QGIS.
Affinchè i test funzionino correttamente è fondamentale usare solamente dati presenti in questa cartella. Quindi caricate i dati predefiniti in questa cartella e scegliete l'algoritmo che volete testare, in questo esempio l'algoritmo Difference.
Lanciare l'algoritmo e verificare che il risultato sia corretto.
Se tutto si è svolto correttamente, il risultato deve essere salvato come file gml nella cartella QGIS/QGIS/python/plugins/processing/tests/testdata/expected del repository di QGIS:
Se avete lanciato l'algoritmo con i dati di input dalla cartella corretta e avete salvato il risultato nella cartella coerente, siete pronti per copiare una specifica stringa che l'architettura degli unit test ha creato.
Cliccate su Processing --> Storico e Log e espandete il menu degli algoritmi. Il primo della lista è l'algoritmo più recente che avete lanciato. Facendo click con il tasto denstro compare l'opzione Create Test e
si aprirà una nuova finestra con una stringa di testo:
Questa stringa va copiata e incollata in fondo al file qgis_algorithm_tests.yaml che si trova nella cartella QGIS/python/plugins/processing/tests/testdata.
State attenti all'indentazione, ovvero all'allineamento del testo copiato: deve essere perfettamente coerente con gli altri test.
Il test è pronto: avete infatti creato dei dati nuovi (il layer gml) e avete copiato la stringa dello unit test nel file corretto.
Il prossimo passaggio consiste nel sincronizzare la cartella locale del repository sul vostro computer con il repository forkato ovvero quello presente sull'vostro account di github.
Tutte queste procedure vengono fatte tramite git. Sul sito di QGIS c'è un'ottima spiegazione (anche se riguarda la documentazione) di come utlizzare git. Il procedimento è esattemente lo stesso.
Di seguito un esempio per Linux. Aprite un terminale e spostatevi nella cartella del repository, nel seguente esempio la cartella è QGIS:
cd QGIS
potete verificare i cambiamenti che avete fatto con il comando git status.
Il consiglio è quello di NON usare il branch master ma di crearne uno vostro che potete sempre cancellare e aggiornare, ma di cui siete sicuri che non avrà alcun effetto sul branch principale. Il comando per creare un branch è il seguente:
git checkout -b processing_test_difference
dove processing_test_difference è il nome del branch che potete modificare come volete.
Aggiungete i file con il comando git add . accompagnato in un secondo momento dal comando git commit -m "test for difference algorithm added" dove fra "" dovete specificare il messaggio di cosa avete fatto:
git add .
git commit -m
"test for difference algorithm added"
prova f3fcde1 test for difference algorithm added
2 files changed, 47 insertions(+)
create mode 100644 python/plugins/processing/tests/testdata/expected/difference.gml
create mode 100644 python/plugins/processing/tests/testdata/expected/difference.xsd
a questo punto per sincronizzare il repository locale con quello del vostro account su github lanciate il comando:
git push origin processing_test_difference
Quindi state inviando le modifiche del branch processing_test_difference al branch origin che è il nome predefinito del repository di github.
9. Fare una pull request, ovvero chiedere che le modifiche della proprio copia di QGIS vengano incorporate nel codice sorgente vero
Sul vostro repository di github vedrete un messaggio del genere:
cliccando sul pulsante Compare & pull request potete chiedere che le modifiche del vostro repository vengano mandate anche al repository originale di QGIS. Compilate con cura i vari campi. importante è che le modifiche del vostro branch siano mandate al branch master di QGIS e che il titolo della Pull Request sia esplicativo. Questo permetterà agli sviluppatori di velocizzare la verifica delle modifiche:
Quando siete sicuri cliccate su Create Pull Request. Verrete reindirizzati all'elenco di tutte le Pull Request di QGIS dove potete vedere l'avanzamento della compilazione remota di QGIS e verificare che il procedimento sia stato effettuato correttamente:
Quando gli sviluppatori lo riterranno opportuno uniranno la vostra Pull Request (tecnicamente faranno un merge) e quell'algoritmo di QGIS sarà cosi blindato.