docs: aggiunge guide per emulatore Android e test

Nuovi docs/emulatore.md e docs/testing.md; CLAUDE.md e README.md
aggiornati con i riferimenti.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

CLAUDE.md

@@ -47,6 +47,7 @@ bash docker/build.sh --release              # release → dist/biteplan-release.
 - **Emulatore**: Android SDK in `/home/davide/android-sdk`; accelerazione hardware via `/dev/kvm` (WSL2 con KVM abilitato).
 - **AVD `biteplan`**: dedicato a questo progetto (Pixel 6, Android 14, google_apis/x86_64). Non riutilizzare AVD di altri progetti (es. `palladium_wallet`).
 - **Permessi**: le build Docker girano come root nel volume montato — se `.dart_tool/` o `build/` risultano di proprietà root, serve `sudo chown -R davide:davide .dart_tool build` prima di usare flutter da host.
+- **Setup e uso dell'emulatore Android** (installazione SDK, creazione AVD, comandi `adb`, troubleshooting): [docs/emulatore.md](docs/emulatore.md).
 
 ## Build e firma
 
@@ -55,6 +56,7 @@ bash docker/build.sh --release              # release → dist/biteplan-release.
 - **Keystore**: `docker/biteplan.jks` è in `.gitignore`; da ottenere dall'autore o generare con `keytool`. Password via `BITEPLAN_KEYSTORE_PASS` (mai hardcoded); alias: `biteplan`
 - **applicationId**: `com.davide.biteplan` — non cambiare, garantisce aggiornamento diretto dalla v1.2.1
 - **versionCode**: letto da `pubspec.yaml` (`version: X.Y.Z+BUILD`); BUILD deve essere sempre crescente
+- **kAppVersion**: `lib/core/constants/app_constants.dart` duplica la versione di `pubspec.yaml` a mano (nessuna sincronizzazione automatica) — aggiornarla ad ogni bump di versione, altrimenti l'update checker confronta contro il valore sbagliato
 
 ## Architettura
 
@@ -64,6 +66,7 @@ Feature-first sotto `lib/features/` (meal_planner, converter, shopping_list, gui
 lib/
 ├── app.dart                          # MaterialApp + NavigationBar; in initState chiama UpdateService.checkUpdate() e mostra showUpdateDialog()
 ├── core/constants/app_constants.dart # kDayIds, kMealSlots, kStorageKey*, kAppVersion
+├── core/theme/app_theme.dart          # ThemeData Material 3, seed color 0xFF2d6a4f
 ├── shared/
 │   ├── services/storage_service.dart      # wrapper SharedPreferences (load/save)
 │   ├── services/update_service.dart       # checkUpdate() → GitHub API; isNewer(), parseTagName() (@visibleForTesting)
@@ -86,7 +89,7 @@ lib/
 
 ## Testing
 
-184 test unit + widget in `test/` (rispecchia la struttura di `lib/`), più un integration test in `integration_test/app_test.dart`. I test unit/widget non richiedono device. Coverage ~93% su `lib/` (esclusi per scelta: `main.dart`, il percorso camera di `qr_scan_page`).
+184 test unit + widget in `test/` (rispecchia la struttura di `lib/`), più un integration test in `integration_test/app_test.dart`. I test unit/widget non richiedono device. Coverage ~93% su `lib/` (esclusi per scelta: `main.dart`, il percorso camera di `qr_scan_page`). Dettaglio di cosa è coperto/escluso e come lanciare la suite: [docs/testing.md](docs/testing.md).
 
 - Storage isolato con `SharedPreferences.setMockInitialValues({})`
 - Widget test: estensione `pumpApp` in `test/helpers/pump_app.dart`

README.md

@@ -2,9 +2,29 @@
 
 App Android per la gestione della dieta quotidiana — pianificazione pasti, conversione crudo/cotto e lista della spesa.
 
-## Funzionalità
+> Un'unica app per pianificare la settimana, sapere quanto pesare crudo o cotto e non dimenticare cosa comprare.
 
-### Piano Pasti
+![License](https://img.shields.io/badge/license-EUPL--1.2-blue)
+![Flutter](https://img.shields.io/badge/flutter-3.41.9-02569B?logo=flutter)
+![Platform](https://img.shields.io/badge/platform-Android-3DDC84?logo=android)
+
+## Overview
+
+BitePlan nasce per unire in un'unica app tre attività che di solito richiedono strumenti
+separati: pianificare i pasti della settimana, convertire i pesi degli alimenti tra crudo e
+cotto (utile per chi segue una dieta con quantità espresse in una delle due forme), e tenere
+una lista della spesa sincronizzata con quanto pianificato.
+
+- **Problema risolto**: evitare di ricalcolare a mano le rese di cottura e di dimenticare
+  ingredienti quando si fa la spesa.
+- **Perché esiste**: progetto personale dell'autore, pensato per un uso quotidiano reale.
+- **Limiti noti**: i coefficienti di resa sono medie indicative (vedi
+  [docs/conversioni.md](docs/conversioni.md)); il piano pasti si condivide tra dispositivi
+  solo via QR code, senza account né sincronizzazione cloud; nessuna build iOS.
+
+## Features
+
+### Piano pasti
 - Pianificazione settimanale su 7 giorni × 3 pasti (colazione, pranzo, cena)
 - Card accordion per giorno, giorno corrente aperto di default
 - Aggiunta e rimozione di voci per ogni pasto
@@ -28,7 +48,32 @@ App Android per la gestione della dieta quotidiana — pianificazione pasti, con
 - All'avvio controlla silenziosamente l'ultima release su GitHub
 - Se disponibile una versione più recente, mostra un dialog con link diretto al download dell'APK
 
-## Stack
+## Architecture
+
+Feature-first sotto `lib/features/`, ognuna con modelli, provider (state management) e
+presentation; persistenza su `SharedPreferences`. Dettaglio del flusso dati per feature in
+[docs/architettura.md](docs/architettura.md).
+
+```text
+biteplan/
+├── lib/
+│   ├── app.dart               # MaterialApp + navigazione
+│   ├── core/                  # costanti, tema
+│   ├── shared/                # servizi e widget condivisi
+│   └── features/
+│       ├── meal_planner/
+│       ├── converter/
+│       ├── shopping_list/
+│       └── guide/
+├── assets/data/conversions.json
+├── android/                   # progetto nativo (MethodChannel in Kotlin)
+├── test/                      # unit + widget test
+├── integration_test/
+├── docs/                      # guida utente, architettura, fonti conversioni
+└── docker/                    # build APK headless, test riproducibili
+```
+
+## Requisiti e dipendenze
 
 | Livello | Tecnologia |
 |---|---|
@@ -38,19 +83,7 @@ App Android per la gestione della dieta quotidiana — pianificazione pasti, con
 | QR code | qr_flutter + mobile_scanner |
 | Build APK | Docker (headless) |
 
-## Sviluppo
+Requisiti host per lo sviluppo:
-
-Sviluppo locale con Flutter installato sull'host e un emulatore Android dedicato — no Docker.
-
-```bash
-emulator -avd biteplan &
-flutter run
-# hot reload con "r", hot restart con "R"
-```
-
-Vedi [docker/README.md](docker/README.md) per test e build APK via Docker.
-
-### Requisiti host
 
 - **Linux x86_64** (Ubuntu/Debian o simili; funziona anche su **WSL2** se il kernel espone `/dev/kvm`)
 - **KVM** per l'accelerazione hardware — senza, l'emulatore è inutilizzabile. Verifica con:
@@ -62,7 +95,7 @@ Vedi [docker/README.md](docker/README.md) per test e build APK via Docker.
 - **Java 17+** (`sudo apt install openjdk-21-jdk`)
 - Strumenti di base: `git curl unzip` — e ~15 GB di spazio libero
 
-### Installazione passo passo
+## Installazione
 
 **1. Flutter** (versione pinnata `3.41.9`, la stessa di `.flutter-version`):
 
@@ -116,104 +149,94 @@ flutter run
 > **Nota WSL2**: serve un kernel con KVM abilitato (WSL2 recenti lo hanno di serie —
 > verifica con `ls /dev/kvm`). La finestra dell'emulatore compare tramite WSLg.
 
-### Installare e testare l'APK di debug sull'emulatore
+## Utilizzo
+
+```bash
+emulator -avd biteplan &
+flutter run
+# hot reload con "r", hot restart con "R"
+```
+
+Per l'uso dell'app una volta installata, vedi la [guida utente](docs/guida-utente.md).
+
+### Installare e testare un APK già buildato
 
 Una volta creato l'AVD `biteplan` (vedi sopra), per installare e provare un APK di debug
 già buildato (es. `dist/biteplan-debug.apk` generato da `bash docker/build.sh`) senza
 passare da `flutter run`:
 
-**1. Avvia l'emulatore e attendi il boot completo:**
-
 ```bash
 emulator -avd biteplan &
 adb wait-for-device
-# poi attendi che il boot sia terminato (può richiedere 1-2 min al primo avvio):
 adb shell 'while [ "$(getprop sys.boot_completed)" != "1" ]; do sleep 1; done'
-```
 
-**2. Installa l'APK:**
-
-```bash
 adb install -r dist/biteplan-debug.apk   # -r = reinstalla sovrascrivendo se già presente
-```
-
-**3. Avvia l'app:**
-
-```bash
 adb shell monkey -p com.davide.biteplan -c android.intent.category.LAUNCHER 1
-```
 
-**4. Osserva i log in tempo reale (utile per debug):**
+# log in tempo reale
-
-```bash
 adb logcat --pid=$(adb shell pidof -s com.davide.biteplan)
-```
 
-**5. Disinstalla quando hai finito:**
+# disinstalla quando hai finito
-
-```bash
 adb uninstall com.davide.biteplan
 ```
 
-> Per lo sviluppo iterativo (hot reload) usa invece `flutter run` — questa procedura serve
+> Per lo sviluppo iterativo (hot reload) usa `flutter run` — questa procedura serve a
-> a validare l'APK esatto che verrà distribuito.
+> validare l'APK esatto che verrà distribuito.
 
 ## Test
 
-La suite copre unit test e widget test. Richiede l'immagine Docker `biteplan-build`
+Cosa è coperto, cosa no e insidie note: [docs/testing.md](docs/testing.md).
-(creata automaticamente al primo `bash docker/build.sh`).
 
 ```bash
-# Tutti i test (dalla root del progetto)
+flutter test                                            # tutta la suite (host)
-docker run --rm -v "$(pwd):/workspace" -w /workspace biteplan-build \
+flutter test test/features/meal_planner/qr_test.dart    # singolo file
-  bash -c "flutter pub get && flutter test"
 
-# Un singolo file
+# versione riproducibile via Docker (immagine biteplan-build, creata al primo bash docker/build.sh)
 docker run --rm -v "$(pwd):/workspace" -w /workspace biteplan-build \
-  bash -c "flutter test test/features/meal_planner/qr_test.dart"
+  bash -c "flutter pub get --enforce-lockfile && flutter test"
 ```
 
-### Struttura
+Struttura di `test/` (rispecchia `lib/`):
 
-```
+```text
 test/
-├── helpers/
+├── helpers/pump_app.dart                 # estensione pumpApp per widget test
-│   └── pump_app.dart                     # estensione pumpApp per widget test
 ├── features/
-│   ├── converter/
+│   ├── converter/{models,providers}/
-│   │   ├── models/conversion_entry_test.dart
+│   ├── meal_planner/{models,providers,widgets}/ + qr_test.dart
-│   │   └── providers/converter_provider_test.dart
+│   └── shopping_list/{models,providers,widgets}/
-│   ├── meal_planner/
+└── shared/{services,widgets}/
-│   │   ├── models/meal_plan_test.dart
-│   │   ├── providers/meal_planner_provider_test.dart
-│   │   ├── widgets/meal_card_test.dart
-│   │   └── qr_test.dart
-│   └── shopping_list/
-│       ├── models/shopping_item_test.dart
-│       ├── providers/shopping_list_provider_test.dart
-│       └── widgets/shopping_item_tile_test.dart
-└── shared/
-    ├── services/
-    │   └── update_service_test.dart      # parsing versione e confronto semver
-    └── widgets/
-        └── update_dialog_test.dart       # widget test dialog aggiornamento
 ```
 
 ## Build APK
 
 ```bash
 bash docker/build.sh                        # debug   → dist/biteplan-debug.apk
+export BITEPLAN_KEYSTORE_PASS=password      # richiesto solo per --release
 bash docker/build.sh --release              # release → dist/biteplan-release.apk
 ```
 
-Vedi [docker/README.md](docker/README.md) per i requisiti della firma release.
+Vedi [docker/README.md](docker/README.md) per i requisiti della firma release (keystore).
+
+## Contribuire
+
+Progetto personale mantenuto da un singolo autore, senza processo di contribuzione formale.
+Segnalazioni di bug e proposte sono benvenute via [Issues](https://github.com/davide3011/biteplan/issues);
+per modifiche più ampie apri prima una issue di discussione prima di lavorare a una PR.
 
 ## Documentazione
 
 - [Guida utente](docs/guida-utente.md)
+- [Architettura](docs/architettura.md)
 - [Fonti e documentazione conversioni](docs/conversioni.md)
+- [Emulatore Android — installazione e uso](docs/emulatore.md)
+- [Test — cosa è coperto e come lanciarli](docs/testing.md)
 - [Changelog](CHANGELOG.md)
 
-## Licenza
+## Stato e licenza
 
-[EUPL v1.2](LICENSE) — Davide Grilli
+Versione corrente: vedi [pubspec.yaml](pubspec.yaml) e [CHANGELOG.md](CHANGELOG.md).
+Distribuito come APK firmato tramite le [release GitHub](https://github.com/davide3011/biteplan/releases);
+l'app verifica automaticamente la disponibilità di aggiornamenti all'avvio.
+
+Rilasciato sotto licenza [EUPL v1.2](LICENSE) — Davide Grilli.

docs/architettura.md

@@ -0,0 +1,83 @@
+# Architettura — BitePlan
+
+Documento tecnico per chi sviluppa o mantiene l'app: come sono strutturati i dati e come
+scorrono tra UI, provider e persistenza. Per l'elenco file per file vedi [CLAUDE.md](../CLAUDE.md);
+per l'uso dell'app vedi [guida-utente.md](guida-utente.md).
+
+## Pattern generale
+
+Ogni feature (`meal_planner`, `converter`, `shopping_list`) segue lo stesso schema:
+
+```
+Widget (presentation/) → Provider (ChangeNotifier) → StorageService / asset → SharedPreferences
+        ↑____________________________notifyListeners()____________________________|
+```
+
+Ogni provider espone metodi che mutano lo stato immutabile in memoria, chiamano
+`notifyListeners()` e poi salvano in modo fire-and-forget (senza `await`, l'UI non aspetta
+la scrittura su disco). `load()` va chiamato una volta all'avvio (in `main.dart`) prima di
+usare il provider.
+
+## Piano pasti (`meal_planner`)
+
+- **Modello**: `MealPlan` è una mappa `dayId → DayPlan`; `DayPlan` ha tre liste di stringhe
+  (`colazione`, `pranzo`, `cena`). Entrambi sono immutabili: ogni modifica passa da
+  `copyWith`/`withUpdatedDay` e ricostruisce l'oggetto.
+- **Provider**: `MealPlannerProvider` tiene `_plan` in memoria, la inizializza vuota con
+  `MealPlan.empty(kDayIds)`, la carica da `StorageService` (chiave `meals`, JSON via
+  `toJsonString`/`fromJsonString`). Se il JSON salvato è corrotto, torna a un piano vuoto
+  invece di lanciare un'eccezione.
+- **Condivisione QR** (`qr_codec.dart`): `buildQrPayload` serializza il piano come
+  `{ "v": 1, "meals": {...} }` e restituisce `null` se supera 2953 byte (capienza QR con error
+  correction L) — la UI mostra un errore in quel caso. `parseMealPlanFromQr` valida
+  struttura e versione prima di ricostruire il `MealPlan`, per non far crashare l'app su un
+  QR malformato o generato da una versione futura.
+- **Generazione lista spesa**: la pagina piano pasti legge `plan.allItems` e chiama
+  `ShoppingListProvider.addAll(...)` — l'aggregazione duplicati avviene lì, non nel meal
+  planner.
+
+## Convertitore crudo/cotto (`converter`)
+
+- **Dati**: `assets/data/conversions.json` è una mappa `alimento → metodo → { yield }`,
+  caricata una sola volta in `ConverterProvider.loadDb()` e appiattita in una lista di
+  `ConversionEntry { food, method, yieldFactor }`.
+- **Calcolo**: `rawToCooked = raw * yieldFactor`, `cookedToRaw = cooked / yieldFactor`.
+  Il provider arrotonda il risultato a un decimale (`(v * 10).roundToDouble() / 10`).
+- **Ricerca**: `search(query)` filtra `_db` per sottostringa case-insensitive sul nome
+  alimento; non c'è persistenza, lo stato (`selected`, `grams`, `rawToCooked`) vive solo in
+  memoria e si azzera con `reset()`.
+- I coefficienti e le fonti sono documentati in [conversioni.md](conversioni.md) — per
+  aggiungerne di nuovi si modifica solo il JSON, non serve toccare il provider.
+
+## Lista della spesa (`shopping_list`)
+
+- **Modello**: `ShoppingItem { id, name, checked, quantity }`. `id` è generato come
+  `timestamp_contatore` (non un vero UUID) per garantire unicità anche ad aggiunte multiple
+  nello stesso millisecondo.
+- **Provider**: `ShoppingListProvider` persiste su chiave `shopping_list` come lista JSON.
+  `pendingItems`/`checkedItems` sono getter derivati, non stato separato.
+- **`addAll(names)`**: raggruppa i nomi per confronto case-insensitive, somma le occorrenze
+  in `quantity` e salta quelli già presenti nella lista (case-insensitive anche lì) — è il
+  meccanismo dietro "zucchine (x2)" e dietro il "senza duplicati" della generazione lista
+  dal piano pasti.
+
+## Controllo aggiornamenti
+
+`UpdateService.checkUpdate()` (chiamato da `app.dart` in `initState`) interroga
+`GET /repos/davide3011/biteplan/releases/latest` su GitHub con `dart:io HttpClient`
+(nessun package HTTP aggiuntivo), timeout 5s su connessione e risposta. Confronta il
+`tag_name` (spogliato del prefisso `v`) con `kAppVersion` via confronto semver a tre
+componenti (`isNewer`); qualsiasi errore di rete, parsing o timeout fa fallire silenziosamente
+il controllo (ritorna `null`, nessun dialog). Disabilitato su web (`kIsWeb`).
+
+`kAppVersion` in `app_constants.dart` **non** è sincronizzato automaticamente con
+`pubspec.yaml` — va aggiornato a mano ad ogni release, altrimenti il confronto versione è
+sbagliato.
+
+## MethodChannel nativo
+
+Il bottone "Scarica" del dialog di aggiornamento e altri link esterni passano da
+`UrlLauncherService`, che invoca il canale nativo `com.davide.biteplan/launcher`
+implementato in Kotlin (`android/app/src/main/kotlin/com/davide/biteplan/MainActivity.kt`)
+con un `Intent.ACTION_VIEW` — scelta per evitare di aggiungere il package `url_launcher`
+per un solo caso d'uso.

docs/emulatore.md

@@ -0,0 +1,121 @@
+# Emulatore Android — installazione e uso (Ubuntu)
+
+Guida per chi sviluppa BitePlan su Ubuntu (nativo o WSL2) e deve installare ed usare
+l'emulatore Android in locale. Per i requisiti generali del progetto vedi [README](../README.md);
+per la build via Docker vedi [CLAUDE.md](../CLAUDE.md).
+
+## 1. Prerequisiti
+
+- **KVM** per l'accelerazione hardware: senza, l'emulatore è troppo lento per essere usabile.
+
+  ```bash
+  ls /dev/kvm          # deve esistere
+  groups | grep kvm    # il tuo utente deve essere nel gruppo kvm
+  ```
+
+  Se il gruppo manca:
+
+  ```bash
+  sudo usermod -aG kvm $USER
+  # poi rilogin (o riavvia la sessione) perché il gruppo sia effettivo
+  ```
+
+  Su **WSL2** serve un kernel con KVM abilitato (le versioni recenti lo hanno di serie).
+  La finestra dell'emulatore compare tramite WSLg.
+
+- **Java 17+**: `sudo apt install openjdk-21-jdk`
+- Strumenti di base: `git curl unzip`, e ~15 GB di spazio libero per SDK + system image.
+
+## 2. Installare Android SDK command-line tools
+
+```bash
+mkdir -p ~/android-sdk/cmdline-tools
+cd ~/android-sdk/cmdline-tools
+curl -O https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip
+unzip commandlinetools-linux-11076708_latest.zip && mv cmdline-tools latest
+rm commandlinetools-linux-11076708_latest.zip
+
+cat >> ~/.bashrc <<'EOF'
+export ANDROID_HOME="$HOME/android-sdk"
+export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"
+EOF
+source ~/.bashrc
+```
+
+## 3. Installare i pacchetti SDK e accettare le licenze
+
+```bash
+sdkmanager "platform-tools" "emulator" \
+  "platforms;android-34" "build-tools;34.0.0" \
+  "system-images;android-34;google_apis;x86_64"
+yes | sdkmanager --licenses
+```
+
+## 4. Creare l'AVD `biteplan`
+
+Il progetto usa un AVD dedicato (Pixel 6, Android 14, `google_apis`/x86_64) — non riusare
+AVD di altri progetti.
+
+```bash
+echo "no" | avdmanager create avd -n biteplan \
+  -k "system-images;android-34;google_apis;x86_64" -d pixel_6
+```
+
+Verifica che tutto sia a posto con `flutter doctor` (la voce "Android toolchain" deve
+risultare ✓).
+
+## 5. Avviare l'emulatore
+
+```bash
+emulator -avd biteplan &
+```
+
+Il primo boot richiede 1-2 minuti; quelli successivi sono più veloci grazie allo snapshot
+automatico dello stato. Per lo sviluppo con hot reload, dalla root del progetto:
+
+```bash
+flutter run     # r = hot reload, R = hot restart
+```
+
+### Opzioni utili
+
+```bash
+emulator -list-avds              # elenca gli AVD disponibili
+emulator -avd biteplan -no-snapshot-load   # forza un cold boot (ignora lo stato salvato)
+emulator -avd biteplan -wipe-data          # resetta l'AVD allo stato di fabbrica
+```
+
+## 6. Comandi `adb` quotidiani
+
+```bash
+adb devices                      # emulatori/device collegati
+adb wait-for-device               # attende che l'emulatore sia raggiungibile
+adb shell 'while [ "$(getprop sys.boot_completed)" != "1" ]; do sleep 1; done'  # attende il boot completo
+
+adb install -r dist/biteplan-debug.apk   # installa/reinstalla un APK già buildato
+adb shell monkey -p com.davide.biteplan -c android.intent.category.LAUNCHER 1  # avvia l'app
+
+adb logcat --pid=$(adb shell pidof -s com.davide.biteplan)   # log in tempo reale dell'app
+
+adb uninstall com.davide.biteplan   # disinstalla
+```
+
+> Per lo sviluppo iterativo usa `flutter run` (hot reload); la sequenza `adb install` sopra
+> serve a validare l'APK esatto che verrà distribuito, senza passare da `flutter run`.
+
+## 7. Chiudere l'emulatore
+
+```bash
+adb -s emulator-5554 emu kill    # spegnimento pulito (salva lo snapshot)
+# oppure chiudi la finestra dell'emulatore
+```
+
+## Troubleshooting
+
+| Sintomo | Causa probabile | Soluzione |
+|---|---|---|
+| `emulator: ERROR: x86_64 emulation currently requires hardware acceleration` | KVM non accessibile | Verifica `/dev/kvm` e l'appartenenza al gruppo `kvm` (§1) |
+| Emulatore lentissimo, UI a scatti | KVM non attivo, o system image ARM su host x86_64 | Usa una system image `x86_64` come da §3, verifica KVM |
+| Boot bloccato su logo Android per minuti | Cold boot dopo `-wipe-data`, oppure macchina sotto carico | Attendi, è normale al primo avvio; se persiste prova `-no-snapshot-load` |
+| Finestra emulatore non compare su WSL2 | WSLg non attivo o kernel senza supporto grafico | Aggiorna WSL (`wsl --update`), verifica `echo $DISPLAY` |
+| `adb: no devices/emulators found` | Emulatore non ancora avviato o non ancora bootato | `adb wait-for-device`, poi ricontrolla con `adb devices` |

docs/testing.md

@@ -0,0 +1,78 @@
+# Test — BitePlan
+
+Cosa copre la suite di test, cosa no, e come lanciarla. Per l'architettura del codice
+testato vedi [architettura.md](architettura.md).
+
+## Come lanciare i test
+
+```bash
+flutter test                                            # tutta la suite unit + widget (host)
+flutter test test/features/meal_planner/qr_test.dart    # singolo file
+
+# versione riproducibile via Docker (immagine biteplan-build, creata da bash docker/build.sh)
+docker run --rm -v "$(pwd):/workspace" -w /workspace biteplan-build \
+  bash -c "flutter pub get --enforce-lockfile && flutter test"
+
+# integration test — richiede un emulatore avviato (vedi docs/emulatore.md)
+flutter test integration_test/app_test.dart
+```
+
+## Struttura
+
+```text
+test/
+├── coverage_helper_test.dart             # importa tutta lib/ perché lcov copra anche i file non testati
+├── helpers/pump_app.dart                 # estensione pumpApp per i widget test
+├── features/
+│   ├── converter/{models,pages,providers}/
+│   ├── meal_planner/{models,pages,providers,widgets}/ + qr_test.dart
+│   ├── shopping_list/{models,pages,providers,widgets}/
+│   └── guide/{pages,widgets}/
+└── shared/{services,widgets}/
+```
+
+184 test unit + widget, coverage ~93% su `lib/`, più `integration_test/app_test.dart`
+(navigazione tra tab, flussi end-to-end su un emulatore/device reale).
+
+## Cosa è coperto
+
+- **Modelli**: serializzazione/deserializzazione, `copyWith`, edge case (`MealPlan`,
+  `DayPlan`, `ConversionEntry`, `ShoppingItem`).
+- **Provider**: mutazioni di stato, persistenza (fire-and-forget) tramite
+  `StorageService` con `SharedPreferences.setMockInitialValues({})` isolato per test.
+- **Conversione crudo/cotto**: `rawToCooked`/`cookedToRaw` in `ConversionEntry`.
+- **QR**: `buildQrPayload`/`parseMealPlanFromQr` in `qr_codec.dart` (payload valido,
+  troppo grande, malformato).
+- **Update checker**: `isNewer()`, `parseTagName()` (`@visibleForTesting`), dialog di
+  aggiornamento con `MethodChannel` mockato.
+- **Widget/pagine**: rendering, interazioni utente (tap, form) via `pumpApp`, per tutte
+  le feature (meal_planner, converter, shopping_list, guide).
+- **Integration test**: navigazione fra i tab e flussi che attraversano più feature,
+  su un device/emulatore reale (non richiesto per lo sviluppo quotidiano).
+
+## Cosa NON è coperto (per scelta)
+
+- **`main.dart`**: bootstrap dell'app (setup provider, `runApp`), poco valore nel
+  testarlo isolatamente — è coperto indirettamente dall'integration test.
+- **Percorso camera di `qr_scan_page`**: l'uso reale della fotocamera per scansionare un
+  QR richiede hardware/permessi non simulabili in un widget test; la logica di parsing
+  (`qr_codec.dart`) è invece testata a parte.
+- **`UrlLauncherService`**: wrapper sottile sul `MethodChannel` nativo
+  (`com.davide.biteplan/launcher`) che apre un URL nel browser — l'effetto (apertura
+  browser) non è verificabile senza un device reale.
+
+## Insidie note
+
+- **Non chiamare `loadDb()`/`load()` dei provider nel body di `testWidgets`**: l'async
+  reale eseguito nella zona `FakeAsync` di `flutter_test` può bloccare la suite (timeout
+  10 min). Vanno chiamati nel `setUp()` — vedi
+  [test/features/converter/pages/converter_page_test.dart](../test/features/converter/pages/converter_page_test.dart).
+- **Storage isolato**: ogni test che tocca `StorageService`/i provider deve chiamare
+  `SharedPreferences.setMockInitialValues({})` prima di caricare lo stato, altrimenti i
+  test si influenzano a vicenda.
+- **MethodChannel nei test**: va mockato con
+  `TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger.setMockMethodCallHandler`
+  — vedi [test/shared/widgets/update_dialog_test.dart](../test/shared/widgets/update_dialog_test.dart).
+- **Nuovi file in `lib/`**: aggiungerli all'import di
+  [test/coverage_helper_test.dart](../test/coverage_helper_test.dart), altrimenti lcov
+  li esclude dal report di coverage anche se non hanno bisogno di test dedicati.