Quartz 4

FIRE DD-REMOTE-DEBUGGING-WEBENGINE {QC}

5 min read

QC DD-REMOTE-DEBUGGING-WEBENGINE.md

Versione: 1.0 Data: 2025-11-13 Progetto: quantum-core Scopo: Fornire una guida completa per neofiti su come utilizzare Chrome DevTools per ispezionare e debuggare i componenti QWebEngineView nelle applicazioni quantum-core.

1. Il Problema: La “Scatola Nera” della WebView

Nelle nostre applicazioni, usiamo QWebEngineView per renderizzare interfacce web complesse, come i grafici Plotly. Questo componente è incredibilmente potente, ma può sembrare una “scatola nera”: quando qualcosa non funziona al suo interno (es. un grafico non appare o è distorto), i log di Python non ci dicono nulla.

Questo accade perché QWebEngineView è un’istanza completa del browser Chromium. Al suo interno, viene eseguito codice HTML, CSS e JavaScript in un processo separato. Se si verifica un errore in questo ambiente, Python non può vederlo.

Per risolvere questo problema, dobbiamo “aprire” questa scatola nera e guardare dentro, usando gli stessi strumenti che un web developer userebbe per un sito web.

2. La Soluzione quantum-core: Debugging Remoto “Latente”

Il framework quantum-core include una funzionalità “latente” (disattivata di default, ma sempre pronta) per attivare il debugging remoto di QWebEngineView. Quando attivata, espone un’interfaccia web che permette a un browser standard (come Chrome o Edge) di connettersi e ispezionare il contenuto della nostra applicazione in tempo reale.

Come Attivarla

L’attivazione avviene impostando una variabile d’ambiente prima di lanciare l’applicazione. Questo metodo è pulito e non richiede modifiche al codice.

  1. Apri il tuo terminale (PowerShell, Bash, etc.).

  2. Imposta la variabile d’ambiente QC_REMOTE_DEBUGGING_PORT sulla porta che desideri usare (es. 9222).

    • Esempio in PowerShell (Windows): 
      $env:QC_REMOTE_DEBUGGING_PORT="9222"
    • Esempio in Bash (Linux/macOS): 
      export QC_REMOTE_DEBUGGING_PORT=9222

  3. Avvia l’applicazione dallo stesso terminale:

    python run.py

  4. Verifica la Console: All’avvio, dovresti vedere un messaggio di conferma stampato dal framework:

    --- QUANTUM-CORE: Remote Debugging per QWebEngine ATTIVATO sulla porta 9222 ---

3. Guida Passo-Passo all’Ispezione (per Neofiti)

Una volta che l’applicazione è in esecuzione con il debugging remoto attivo:

  1. Apri Chrome o Edge (o un altro browser basato su Chromium).
  2. Vai all’indirizzo: http://localhost:9222 (sostituisci 9222 con la porta che hai scelto).
  3. Trova il Tuo Target: Vedrai una pagina intitolata “Inspectable WebContents”. Ogni QWebEngineView attivo nella tua applicazione apparirà come una riga in questa pagina. Clicca sul link inspect corrispondente alla pagina che vuoi debuggare (spesso avrà un titolo come “Plotly Chart”). Screenshot della pagina di ispezione
  4. Benvenuto in DevTools: Si aprirà una nuova finestra, i Chrome DevTools, connessa in tempo reale al tuo QWebEngineView. Screenshot di DevTools

Le tab più importanti per noi sono:

  • Elements: Ti permette di navigare la struttura HTML e vedere gli stili CSS applicati, proprio come su un sito web.
  • Console: Il nostro strumento principale. Qui puoi vedere tutti i messaggi console.log e gli errori JavaScript, e puoi eseguire comandi JavaScript per ispezionare le variabili.
  • Sources: Qui puoi vedere il codice sorgente (l’HTML e il JS che il tuo codice Python ha generato) e persino impostare breakpoint per fermare l’esecuzione del JavaScript passo dopo passo.

4. Tecniche di Debug Essenziali nella Console

Una volta nella tab Console, puoi interagire direttamente con la tua pagina.

  • Ispezionare una Variabile: Se il tuo JavaScript ha una variabile globale myVar, puoi semplicemente digitare myVar e premere Invio per vederne il contenuto.
  • Verificare i Tipi: Il comando typeof è fondamentale. typeof myVar ti dirà se è un "number", "string", "object", etc.
  • Chiamare Funzioni: Puoi eseguire qualsiasi funzione JavaScript disponibile. Ad esempio, per ritestare il rendering con dati diversi: window.renderPlotly(nuovoJson, nuovoTema).
  • Monitorare le Chiamate: Per vedere se e quando una funzione viene chiamata, usa monitor(nomeFunzione), ad esempio: monitor(window.renderPlotly). La console ti mostrerà ogni chiamata con i relativi argomenti. Per smettere di monitorare, usa unmonitor(nomeFunzione).

5. Caso di Studio: Risolvere la “Linea Piatta Diagonale”

Il nostro recente debug è il caso d’uso perfetto. Eravamo bloccati perché i log Python erano perfetti, ma il grafico era sbagliato. Ecco come DevTools ha risolto il mistero:

  1. L’ipotesi: Pensavamo che i dati dell’asse Y fossero corretti.
  2. Il Test in Console: Abbiamo reso la variabile figure globale nel nostro JS. Poi, nella console di DevTools, abbiamo eseguito: 
    console.log(figure.data[0].y)
  3. La Scoperta: Invece di un array di numeri come [7.17, 7.18, ...], la console ha mostrato questo: 
    {dtype: 'f8', bdata: 'rkfhehQuIEC4HoXrUTggQD0K16NwPSBA...'}
    Questa è stata la “pistola fumante”: la prova inconfutabile che i dati arrivavano a JavaScript in un formato NumPy serializzato che Plotly.js non poteva capire. Questo ci ha permesso di implementare il fix corretto in Python (.tolist()).

6. Risoluzione dei Problemi Comuni

  • “La pagina localhost:9222 non si carica.”
    • Hai impostato la variabile d’ambiente prima di lanciare python run.py?
    • L’hai impostata nello stesso terminale da cui hai lanciato l’app?
    • Controlla che non ci siano firewall che bloccano la porta 9222.
  • “Non vedo la mia pagina nella lista dei target.”
    • Assicurati che il widget che contiene il QWebEngineView sia stato creato e sia visibile nella tua applicazione.
  • “La console mi chiede di digitare allow pasting.”
    • È una misura di sicurezza. Digita allow pasting e premi Invio per sbloccare la console. Se commetti un errore, ricarica la pagina di DevTools (Ctrl+R) per far riapparire il prompt.

Graph View