Guida a GitHub Actions per i docenti: automatizzare i test dei compiti

DIDATTICA · Area Docenti • GitHub Actions

✍ Autore: profgiagnotti | Per docenti che vogliono autograding reale

Guida a GitHub Actions per i docenti: automatizzare i test dei compiti

Come far eseguire i test a GitHub a ogni git push dello studente, e vedere subito chi ha superato la consegna senza scaricare un solo progetto.

⚙️ GitHub Actions🧪 Autograding📦 Kit pronto

📚 Indice

1. L'idea in breve 2. Prerequisiti 3. Due strade possibili 4. Anatomia di un workflow 5. Kit pronto all'uso: i workflow da copiare e incollare 6. Rendere i risultati più leggibili 7. Come il docente vede chi ha superato i test 8. Come lo studente legge l'esito 9. Limiti, sicurezza e imbrogli 10. Problemi frequenti 11. Kit pronto all'uso (scaricabile) 12. Checklist finale

1. L'idea in breve

GitHub Actions è il sistema di automazione di GitHub. Un file di configurazione (workflow, in formato YAML) dice a GitHub: «quando succede X, esegui questi comandi». Per i compiti l'evento è il push dello studente e i comandi sono i test.

FLUSSO ACTIONS

Studente fa git push → GitHub avvia una macchina virtuale → Installa il linguaggio → Esegue i test → Segna il commit con ✓ (superato) o ✗ (fallito)

Cosa ottiene il docente: un colpo d'occhio sullo stato di tutti i repository, senza clonare nulla; cosa ottiene lo studente: un feedback immediato, anche la sera prima della scadenza.

💡 Nota

Colleghi, da ricordare bene: questo è il vero salto di qualità rispetto al semplice GitHub Classroom. Non scaricate più zip. Vedete verde/rosso al volo. Non fate questo errore: correggere tutto a mano la sera prima della scadenza.

2. Prerequisiti

Una classe su GitHub Classroom e un repository modello (vedi la guida precedente).
Test scritti per l'esercizio (PyTest, JUnit, Mocha o altro framework).
Il repository modello contiene già la cartella .github/workflows/: i repository degli studenti la erediteranno automaticamente.

3. Due strade possibili

	A. Autograding di GitHub Classroom	B. Workflow GitHub Actions scritto a mano
Come si configura	Da interfaccia web, nell'assignment	Un file YAML nel repository modello
Punteggio per test	Sì, con punti assegnabili	Solo superato/fallito (il punteggio richiede lavoro in più)
Flessibilità	Media	Alta: qualsiasi linguaggio, più passaggi, report
Ideale per	Voti automatici semplici	Controllo totale, progetti più complessi

In pratica Classroom genera a sua volta un workflow Actions: le due strade usano lo stesso motore. Questa guida segue soprattutto la strada B, perché è quella che permette di capire e personalizzare tutto. Puoi sempre aggiungere il punteggio da Classroom in un secondo momento.

4. Anatomia di un workflow

Il file va salvato in .github/workflows/test.yml (il nome può variare, la cartella no).

WORKFLOW BASE

name: Test automatici       # nome mostrato nella scheda Actions

on:                          # QUANDO parte
  push:                      # a ogni push
  workflow_dispatch:         # e anche manualmente dal pulsante "Run workflow"

jobs:                        # COSA fa
  test:
    runs-on: ubuntu-latest   # su quale macchina
    steps:
      - uses: actions/checkout@v4       # scarica il codice
      - name: Esegui i test
        run: echo "qui vanno i comandi"   # il comando vero e proprio

🚨 Nota - errore più frequente

Attenzione all'indentazione: il YAML usa spazi (mai tabulazioni) e due spazi per livello. È l'errore più frequente. Colleghi, da ricordare bene: se copiate da PDF o Word, l'indentazione salta. Copiate sempre dal kit.

5. Kit pronto all'uso: i workflow da copiare e incollare

Ogni workflow qui sotto va salvato come .github/workflows/test.yml nel repository modello. Gli stessi file sono nel Kit scaricabile (vedi sezione 11).

5.1 Python con PyTest

Struttura attesa: codice in src/, test in tests/, eventuale requirements.txt nella radice.

PYTHON - PYTEST

name: Test automatici (PyTest)

on:
  push:
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Installa le dipendenze
        run: |
          python -m pip install --upgrade pip
          pip install pytest
          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi

      - name: Esegui i test
        run: python -m pytest -v

python -m pytest (invece di pytest) aggiunge la cartella corrente al percorso di ricerca, così import src.modulo funziona senza configurazioni extra.

5.2 Java con JUnit (Maven)

Struttura attesa: progetto Maven standard con pom.xml e test in src/test/java.

JAVA - MAVEN JUNIT

name: Test automatici (JUnit + Maven)

on:
  push:
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '21'
          cache: maven

      - name: Compila ed esegui i test
        run: mvn --batch-mode test

Con Gradle sostituisci cache: maven con cache: gradle e l'ultimo comando con ./gradlew test (il progetto deve contenere il wrapper gradlew; se usi Linux ricorda che il file deve essere eseguibile).

5.3 JavaScript con Mocha (Node.js)

Struttura attesa: package.json con lo script "test": "mocha" e i test in test/.

JS - MOCHA

name: Test automatici (Mocha)

on:
  push:
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Installa le dipendenze
        run: npm ci

      - name: Esegui i test
        run: npm test

npm ci richiede il file package-lock.json nel repository. Se non c'è, usa npm install.

5.4 Altri linguaggi: lo schema è sempre lo stesso

Cambia solo il passaggio di installazione dell'ambiente e il comando di test:

Linguaggio	Azione di setup	Comando di test tipico
C# / .NET	actions/setup-dotnet@v4	dotnet test
Go	actions/setup-go@v5	go test ./...
PHP	shivammathur/setup-php@v2	vendor/bin/phpunit
C / C++	già presente su ubuntu-latest	make test oppure ctest

6. Rendere i risultati più leggibili

6.1 Salvare un report dei test

Aggiungi questo passaggio dopo quello dei test per conservare un file con i risultati (esempio con PyTest):

REPORT XML + ARTIFACT

  - name: Esegui i test e salva il report
    run: python -m pytest -v --junitxml=report.xml

  - name: Conserva il report
    if: always()             # anche se i test falliscono
    uses: actions/upload-artifact@v4
    with:
      name: report-test
      path: report.xml

Senza if: always() il report non verrebbe salvato proprio nel caso più interessante: quando i test falliscono.

6.2 Un riassunto in chiaro nella pagina dell'esecuzione

STEP SUMMARY

  - name: Riassunto
    if: always()
    run: |
      echo "### Esito dei test" >> $GITHUB_STEP_SUMMARY
      echo "Esecuzione per il commit ${GITHUB_SHA::7}" >> $GITHUB_STEP_SUMMARY

7. Come il docente vede chi ha superato i test

Dal pannello di GitHub Classroom: nella pagina dell'assignment compare l'elenco degli studenti con lo stato dei loro repository; se usi l'autograding di Classroom vedi anche i punti.
Dal singolo repository: nella scheda Actions trovi la cronologia delle esecuzioni; accanto a ogni commit compare un segno di spunta o una croce.
Dal log: cliccando un'esecuzione fallita leggi esattamente quale test è fallito e perché.
Notifiche: puoi seguire (Watch) i repository per ricevere avvisi, ma con molte classi conviene consultare il pannello a scadenza.

💡 Suggerimento per colleghi

Suggerimento: definisci con gli studenti una regola chiara, ad esempio «fa fede l'ultimo commit prima della scadenza con test superati». Da ricordare bene: comunicatelo nel README del template.

8. Come lo studente legge l'esito

Va spiegato in classe, una volta sola:

nella pagina del repository, accanto al commit compare un pallino giallo (in corso), verde (superato) o rosso (fallito);
cliccando sul pallino e poi su Details si apre il log con l'errore;
l'errore va letto dal basso verso l'alto: le ultime righe dicono quale test è fallito e cosa ci si aspettava.

💡 Nota

Colleghi, fate una live in classe: mostrate un commit rosso e leggete il log insieme. In 10 minuti i ragazzi capiscono come debuggare da soli. Non fate questo errore: lasciare che scoprano da soli il pallino rosso la sera della consegna.

9. Limiti, sicurezza e imbrogli

Gli studenti possono modificare i file del loro repository, compresi i test e il workflow. Per i compiti valutati: non dare agli studenti permessi di amministrazione, controlla che tests/ e .github/ non siano stati toccati (la cronologia dei commit lo mostra) e, per le verifiche importanti, rilancia i test nel tuo repository con il codice dello studente.
Test «nascosti»: per evitare che lo studente scriva codice solo per superare i test visibili, tieni una seconda batteria di test non pubblicata ed eseguila tu.
Non inserire segreti (password, chiavi) nel repository modello: verrebbe copiato in tutti i repository.
Niente pull_request_target: usa solo push e pull_request, che eseguono il codice con permessi ridotti.
Test = correttezza, non qualità: integra sempre con una lettura del codice.
Quote di utilizzo: i repository privati hanno un monte di minuti di esecuzione mensile gratuito, che dipende dal piano dell'organizzazione. Verifica i limiti attuali su https://docs.github.com/billing e sul programma GitHub Education. Per ridurre i consumi usa la cache (cache: negli step di setup) e test brevi.

🚨 Nota - sicurezza

Da collega a collega, da ricordare bene: mai segreti nel template e mai pull_request_target. Gli studenti hanno accesso al repo, vedrebbero tutto. Se dovete usare segreti, usateli solo nei workflow del docente, non nel modello distribuito.

10. Problemi frequenti

Sintomo	Causa probabile	Soluzione
Il workflow non compare nella scheda Actions	File fuori dalla cartella .github/workflows/ o estensione sbagliata	Controlla percorso ed estensione .yml
Errore «mapping values are not allowed»	Indentazione errata nel YAML	Usa solo spazi, due per livello
ModuleNotFoundError in PyTest	Dipendenza mancante	Aggiungi al requirements.txt
npm ci fallisce	Manca package-lock.json	Aggiungilo oppure usa npm install
Test verdi in locale ma rossi su GitHub	Percorsi con maiuscole/minuscole diverse, o dipendenze non dichiarate	I server sono Linux: i nomi dei file distinguono maiuscole e minuscole
Nessuna esecuzione dopo il push	Actions disattivate nell'organizzazione	Controlla Settings → Actions dell'organizzazione
Il workflow non è nei repository degli studenti	Il modello non era ancora «Template» quando è stato creato l'assignment	Verifica che il file fosse nel modello prima di creare il compito

11. Kit pronto all'uso (scaricabile)

Il kit allegato a questa guida contiene:

pytest.yml, junit-maven.yml, junit-gradle.yml, mocha.yml: i workflow completi, da rinominare in test.yml;
pytest-con-report.yml: la versione di PyTest con report e riassunto;
esempi/python/, esempi/node/: un mini-esercizio con test, per provare subito tutto il flusso;
LEGGIMI.md: le istruzioni di installazione in 5 passi.

Installazione in 5 passi:

Crea il repository modello (o aprine uno esistente).
Crea la cartella .github/workflows/ e copia nel suo interno il workflow del tuo linguaggio, chiamandolo test.yml.
Aggiungi il tuo codice di partenza e i test.
Fai un push e controlla nella scheda Actions che l'esecuzione parta (all'inizio i test falliranno, se l'esercizio è da completare: è normale).
Crea l'assignment da GitHub Classroom scegliendo questo repository come modello.

💡 Nota

Colleghi, se è la prima volta, provate con l'esempio Python del kit. È il più veloce da testare e il report XML vi aiuta a capire subito dove lo studente ha sbagliato. Da ricordare bene: fate partire una Actions sul modello prima di dare il compito.

12. Checklist finale

CHECKLIST FINALE - COPIA

☐ Il workflow è in .github/workflows/test.yml nel repository modello
☐ I test funzionano su una copia di prova del repository
☐ Gli studenti non hanno permessi di amministrazione sul loro repository
☐ La regola di consegna «fa fede l'ultimo commit con test superati» è stata comunicata
☐ Una breve lezione spiega come leggere l'esito delle Actions
☐ Hai pianificato un controllo dei test o dei workflow modificati prima di valutare

🧰 Adesso prova a realizzare ciò che hai letto con il kit che ho preparato per te

Ho preparato un kit scaricabile con i workflow YAML completi, gli esempi Python/Node e il LEGGIMI in 5 passi. Scaricalo e provalo subito nella tua Classroom.

⬇️ Scarica il Kit GitHub Actions per Docenti

File ZIP con pytest.yml, junit-maven.yml, mocha.yml, esempi e report.

🏫 Hub Area Docenti

Torna all'hub con tutte le guide tecniche e normativa per docenti.

← Area Docenti HUB

📚 Il tuo prossimo passo ora

Apri il repository modello che usi già con GitHub Classroom, aggiungi la cartella .github/workflows/ e incolla il workflow del tuo linguaggio. Fai un push di prova e guarda la scheda Actions diventare verde. Se vuoi, scrivi nei commenti che linguaggio usi: ti dico quale workflow è più adatto.