Gruppo degli utenti italiani di QGIS

Come aggiungere un test per Processing in QGIS

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

Come funzionano gli unit test

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).

Cosa sono gli unit test di Processing

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.

Come si creano test per Processing

Tutti (ma proprio tutti) possono aggiungere dei test per Processing. Il processo è un po' macchinoso, ma ne vale la pena.

Requisiti

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:

Ammetto che il tutto può spaventare, ma è più lineare di quello che si può immaginare. Procediamo per punti.


0. scaricare e installare git sul proprio computer

La procedura è semplice anche per chi usa Windows. Rimando al sito ufficiale per tutte le informazioni git

1. creare un account su github

Anche in questo caso non c'è tanto da spiegare, si fa tutto dal sito di Github

2. Fare un fork di QGIS

Questa procedura viene interamente fatta dal sito di Github

alt text

3. clonare il fork sul proprio computer

La procedura cambia a seconda del sistema operativo. Di seguito un esempio su una macchina Linux

ora 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

4. Usare l'ultima versione di QGIS master

Anche se i test possono essere aggiunti per qualunque versione di QGIS il consiglio è quello di utilizzare l'ultima versione di QGIS disponibile.

5. Scegliere un algoritmo di cui ancora non esiste un test

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.

6. Lanciare l'algoritmo e verificare che il risultato sia corretto

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.

7. Copiare il test e i risultati in una particolare cartella di QGIS

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 string 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.

8. Inviare il test e i risultati dal computer locale alla pripria copia su Github

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 che restituisce: 


          git status
          On branch master
          Your branch is ahead of 'origin/master' by 104 commits.
          (use "git push" to publish your local commits)
          Untracked files:
          (use "git add <file>..." to include in what will be committed)
          python/plugins/processing/tests/testdata/expected/difference.gml
          python/plugins/processing/tests/testdata/expected/difference.xsd
          nothing added to commit but untracked files present (use "git add" to track)

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.