89 lines
6.0 KiB
Markdown
89 lines
6.0 KiB
Markdown
# Panoramica tecnica del workspace — GrifoAutomaticTestEnv
|
|
|
|
Questo documento fornisce una descrizione tecnica e operativa del progetto, pensata come base per gli sviluppi futuri.
|
|
|
|
1) Scopo generale
|
|
- Ambiente di test automatico Python per il sistema radar GRIFO-F/TH. Fornisce accesso al bus 1553, comunicazione seriale, controllo alimentazione, raccolta/logging dei risultati e generazione di report in PDF.
|
|
|
|
2) Struttura principale (cartelle rilevanti)
|
|
- `PlatformSimulator/` — componenti nativi e binding SWIG per 1553.
|
|
- `PlatformSimulator/bin/interpreter.py` e `_interpreter.pyd` (driver nativo). Questi espongono l'API a basso livello per la comunicazione 1553.
|
|
- `TestEnvironment/env/` — librerie Python condivise tra gli script di test.
|
|
- `leo_grifo_1553.py` — wrapper Python per 1553 (classe `GrifoInstrumentInterface` e singleton `theGrifo1553`).
|
|
- `leo_grifo_terminal.py` — gestione terminale seriale e parsing messaggi (`%%E`, `%%F`, `RECYCLE`).
|
|
- `leo_grifo_io_box.py` — interfaccia BrainBox per controllo alimentazione (`theBrainBox`).
|
|
- `leo_grifo_core.py` — recorder (`theRecorder`) per tracciare step e sessioni.
|
|
- `leo_grifo_test_report.py` / `leo_grifo_pdf2report.py` — generazione PDF a partire da template JSON.
|
|
- `test_common_function.py` — funzioni di alto livello usate dagli script (`check`, `getValue`, `setValue`, `generate_pdf_report`).
|
|
- `site-packages/` — dipendenze locali usate dall'ambiente (fpdf2, pyserial, PIL, ecc.).
|
|
- `TestEnvironment/scripts/` — script utente e test runner.
|
|
- `GRIFO_M_PBIT.py` — test principale (PBIT). Rileva `--simulate` per usare i mock.
|
|
- `GRIFO_M_PBIT_mock.py` — implementazione mock (monkey-patching dei singoli oggetti globali per simulazione).
|
|
- `__init__.py` — bootstrap dei path (aggiunge `../env` e `env/site-packages` a `sys.path`).
|
|
- `TestEnvironment/json/` — template e configurazioni (es. `default_template.json`).
|
|
- `TestEnvironment/pdf_reports/` e `TestEnvironment/LOG/` — output di esecuzione.
|
|
|
|
3) Pattern e convenzioni di progetto (importanti per gli agenti)
|
|
- Singleton globali: `theGrifo1553`, `theBrainBox`, `theRecorder`. Non rinominare questi oggetti senza aggiornare tutti i call-site.
|
|
- Interfaccia comune: classi di livello dispositivo implementano `check(expected, *fields, **kwargs)`, `get(*fields, **kwargs)`, `set(value, *fields, **kwargs)` (vedi `TestCommonInterface` in `leo_grifo_common.py`). Usare le funzioni wrapper in `test_common_function.py` per tracciare i risultati.
|
|
- Recorder: usare `theRecorder.add_step()` / `close_session()` per registrare lo storico del test; i report PDF aggregheranno questi dati.
|
|
- Path precedence: gli script si aspettano che `env/site-packages` sia prioritario rispetto alla Python di sistema. Il bootstrap in `TestEnvironment/scripts/__init__.py` gestisce questo.
|
|
|
|
4) Interazione con il codice nativo 1553
|
|
- `PlatformSimulator/bin/_interpreter.pyd` è la libreria nativa (funziona solo con la versione di Python con cui è stata compilata). Per questo motivo è obbligatorio usare la versione di Python contenuta in `PlatformSimulator/bin` (embedded Python) per eseguire i test in modo affidabile.
|
|
- Evitare di eseguire gli script con la Python di sistema: il binding nativo potrebbe non essere caricabile o provocare errori di ABI.
|
|
|
|
5) Modalità di esecuzione raccomandate
|
|
- Rapida (consigliata per sviluppo):
|
|
```powershell
|
|
cd <repo-root>
|
|
.\run_simulate_simple.bat
|
|
```
|
|
oppure (esplicito):
|
|
```powershell
|
|
PlatformSimulator\bin\python.exe TestEnvironment\scripts\GRIFO_M_PBIT.py --simulate
|
|
```
|
|
- Produzione-like (usa l'ambiente embedded):
|
|
```powershell
|
|
cd <repo-root>
|
|
.\run_simulate.bat
|
|
```
|
|
- Wrapper manuale utile per CI/debug:
|
|
```powershell
|
|
python python_simulate_wrapper.py
|
|
```
|
|
|
|
6) Esecuzione in CI
|
|
- Nel job CI bisogna utilizzare l'interprete Python presente in `PlatformSimulator/bin` o garantire che `_interpreter.pyd` sia compatibile con la Python della runner. Consiglio pratico per GitHub Actions: copiare `PlatformSimulator/bin` nel runner e lanciare `PlatformSimulator/bin/python.exe python_simulate_wrapper.py`.
|
|
|
|
7) Cosa cercare quando si modifica codice critico
|
|
- Non cambiare le firme `check/get/set` né i nomi dei singletons senza aggiornare tutti gli script sotto `TestEnvironment/scripts/`.
|
|
- Se modifichi report PDF o template JSON aggiorna `leo_grifo_test_report.py` e controlla che `generate_pdf_report()` sia ancora invocato con i parametri attesi.
|
|
- Aggiunte a `site-packages` locali devono essere testate con l'interprete embedded.
|
|
|
|
8) Raccomandazioni di sviluppo immediate
|
|
- Usare esclusivamente l'interprete in `PlatformSimulator/bin` per sviluppare e testare.
|
|
- Eseguire `GRIFO_M_PBIT.py --simulate` per validare le modifiche senza hardware reale.
|
|
- Aggiungere test di smoke che: lancino lo script in modalità `--simulate`, verifichino che esca con codice 0 e che venga generato un PDF in `TestEnvironment/pdf_reports/`.
|
|
|
|
9) File chiave per iniziare (ordine suggerito di lettura)
|
|
- `TestEnvironment/scripts/__init__.py` (bootstrap dei path)
|
|
- `TestEnvironment/env/leo_grifo_1553.py` (wrapper 1553)
|
|
- `TestEnvironment/env/leo_grifo_common.py` (interfaccia comune)
|
|
- `TestEnvironment/env/test_common_function.py` (API helper per test)
|
|
- `TestEnvironment/scripts/GRIFO_M_PBIT.py` (flow test principale)
|
|
- `TestEnvironment/scripts/GRIFO_M_PBIT_mock.py` (implementazione simulazione)
|
|
|
|
10) Esempio rapido di comando per sviluppo locale (embedded Python)
|
|
```powershell
|
|
# dalla radice del repository
|
|
PlatformSimulator\bin\python.exe TestEnvironment\scripts\GRIFO_M_PBIT.py --simulate
|
|
```
|
|
|
|
11) Note finali e prossimi passi consigliati
|
|
- Primo passo: aggiungere uno smoke-test script sotto `TestEnvironment/scripts/` che esegua il flusso `--simulate` e verifichi la presenza del PDF; questo renderà immediato il feedback per ogni modifica.
|
|
- Se vuoi, implemento subito lo smoke-test e un esempio di job CI che usa l'interprete embedded.
|
|
|
|
---
|
|
Documento generato automaticamente come base per i futuri sviluppi; chiedimi di espandere sezioni specifiche o di creare gli script di smoke-test e CI.
|