Stetho — che cos'è, debug di Android tramite Chrome DevTools

Cos'è Stetho e come funziona

Stetho è una libreria Java che avvia un server WebSocket locale all'interno dell'applicazione Android. Chrome DevTools si collega a questo server tramite una porta adb, ottenendo l'accesso ai componenti interni dell'applicazione: database, richieste di rete, preferences e la gerarchia delle viste. Tutta la comunicazione passa attraverso il protocollo Chrome DevTools, che consente di utilizzare gli strumenti standard del browser senza installare software aggiuntivo.

Architettura e componenti

La libreria è composta da moduli: stetho (nucleo), stetho-okhttp (intercettazione del traffico tramite OkHttp), stetho-urlconnection (intercettazione tramite HttpURLConnection) e stetho-js-rhino (supporto ai plugin JavaScript). Il nucleo apre un socket UNIX a cui Chrome si collega tramite adb forward. Ogni ispettore è implementato come plugin separato, registrato all'inizializzazione di Stetho.

Requisiti e limitazioni

Stetho supporta Android 4.4+ (API 19) e funziona solo nelle build di debug. Su dispositivi con Android 11+ è richiesto un permesso INTERNET esplicito nel manifest. La libreria non è ufficialmente supportata da Facebook dal 2020, ma il codice resta aperto e viene utilizzato nei progetti legacy. Per i nuovi progetti Google consiglia Android Studio Profiler e Network Inspector.

Collegamento e configurazione di Stetho in un progetto Android

Il collegamento avviene tramite una dipendenza Gradle con il flag debugImplementation affinché Stetho funzioni solo nella build di debug. L'inizializzazione avviene nel metodo Application.onCreate() con una singola chiamata a Stetho.initializeWithDefaults(this). Per Network Inspector è richiesta l'integrazione con OkHttp tramite un Interceptor.

// build.gradle (app) — aggiungere Stetho
dependencies {
    debugImplementation 'com.facebook.stetho:stetho:1.6.0'
    debugImplementation 'com.facebook.stetho:stetho-okhttp3:1.6.0'
}

// Inizializzazione nella classe Application
public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Stetho.initializeWithDefaults(this);
    }
}

Configurazione del Network Interceptor

Per intercettare le richieste di rete tramite OkHttp, aggiungere StethoInterceptor alla catena di interceptor. Stetho registra automaticamente l'URL, le intestazioni di richiesta e risposta, il codice di stato e il tempo di esecuzione. I dati vengono visualizzati nella scheda Network di Chrome DevTools dopo il collegamento al dispositivo tramite chrome://inspect.

Network Inspector: intercettazione del traffico HTTP

Il Network Inspector di Stetho mostra tutte le richieste HTTP dell'applicazione in ordine cronologico. Per ogni richiesta sono disponibili: metodo, URL, codice di stato, intestazioni di richiesta e risposta, corpo della richiesta e della risposta (inclusi JSON e dati binari). La scheda Preview mostra il corpo della risposta in forma formattata.

Filtro e ricerca delle richieste

Chrome DevTools supporta il filtro delle richieste per tipo (XHR, JS, CSS, Doc), codice di stato e dominio. Il campo di ricerca filtra per URL e contenuto. Per lo sviluppo mobile è utile raggruppare le richieste per dominio API e verificare la sequenza delle chiamate durante i test degli schermi dell'applicazione.

// Client OkHttp con interceptor Stetho
OkHttpClient client = new OkHttpClient.Builder()
    .addNetworkInterceptor(new StethoInterceptor())
    .build();

// Esecuzione di una richiesta
Request request = new Request.Builder()
    .url("https://api.example.com/users")
    .build();
client.newCall(request).enqueue(callback);

Database Inspector: lavoro con SQLite

Il Database Inspector di Stetho si collega ai database SQLite dell'applicazione tramite Chrome DevTools. Nella scheda Resources → Web SQL vengono mostrati tutti i database aperti, le loro tabelle e i contenuti. Sono disponibili la visualizzazione della struttura delle tabelle, degli indici e l'esecuzione di query SQL arbitrarie.

Esecuzione di query SQL tramite DevTools

Nella console di Chrome DevTools è possibile eseguire query SQL direttamente sul database dell'applicazione: SELECT, INSERT, UPDATE, DELETE. Questo è utile per pulire i dati prima dei test, verificare la correttezza delle migrazioni e correggere manualmente record errati senza ricompilare l'applicazione. Tutte le modifiche sono immediatamente visibili sul dispositivo.

Dumpapp e plugin personalizzati

Dumpapp è l'interfaccia shell di Stetho che consente di eseguire comandi personalizzati tramite adb. I plugin Dumpapp vengono registrati all'inizializzazione di Stetho e possono esportare qualsiasi stato dell'applicazione: cache, impostazioni, stato del contenitore DI. I comandi vengono eseguiti come adb forward tcp:12345 localabstract:stetho_dumpapp.

Creazione di un plugin Dumpapp personalizzato

Il plugin implementa l'interfaccia DumperContext e viene registrato tramite Stetho.initialize con un InspectorModules personalizzato. L'esempio seguente mostra un plugin per il dump di SharedPreferences: i dati vengono serializzati in JSON e stampati nel terminale tramite un comando adb.

// Plugin Dumpapp personalizzato per SharedPreferences
public class PrefsDumper implements DumperContext {
    @Override
    public String getName() {
        return "prefs";
    }
    @Override
    public void dump(DumperContext ctx) {
        SharedPreferences sp = ctx.getContext()
            .getSharedPreferences("app_prefs", Context.MODE_PRIVATE);
        ctx.getStdout().println(sp.getAll().toString());
    }
}

Stetho vs Android Studio Inspector: confronto

Android Studio fornisce strumenti di profiling integrati: Network Profiler, Database Inspector e View Inspector, introdotti in Android Studio 4.1+. Stetho era popolare prima dell'introduzione di questi strumenti e resta rilevante per i progetti che usano OkHttp e richiedono l'integrazione con Chrome DevTools.

Quando scegliere Stetho

Stetho è giustificato nei progetti legacy dove OkHttp è già utilizzato e il team è abituato a Chrome DevTools. Per i nuovi progetti Android Studio Inspector copre la maggior parte degli scenari di debug. Tuttavia, Chrome DevTools resta più comodo per le query SQLite: la console integrata con autocompletamento SQL è più veloce dei clic sequenziali nell'IDE.

Ispezione della gerarchia delle viste tramite Stetho

La View Hierarchy in Stetho viene mostrata nella scheda Elements di Chrome DevTools come un albero simile al DOM. Ogni View è rappresentata come un elemento HTML con attributi: id, layout_width, layout_height, padding, margin, visibility e testo. Le modifiche nell'albero vengono sincronizzate in tempo reale alla rotazione dello schermo o all'aggiornamento dell'UI.

Visualizzare e modificare le proprietà

Selezionando un elemento nell'albero, è possibile visualizzare le sue proprietà nel pannello Styles, in modo simile all'ispezione delle pagine web. Stetho mostra le dimensioni calcolate, i padding, il colore di sfondo e lo stato (pressed, focused, enabled). La modifica di alcune proprietà in DevTools viene applicata immediatamente all'applicazione, accelerando la scelta dei parametri UI senza ricompilazione.

Ricerca di perdite di memoria tramite View Inspector

Stetho aiuta a individuare perdite di memoria legate alle View: se un'Activity non viene distrutta dopo finish(), la sua View radice rimane nell'albero. Controllando regolarmente la scheda Elements si possono notare Activity fantasma e trovare la fonte della perdita, di solito riferimenti statici a Context o dialoghi non chiusi.

Tecniche pratiche di debug

Stetho è efficace per verificare la serializzazione JSON prima di inviarla al server. Aprire Network Inspector, trovare la richiesta e visualizzare il corpo in modalità Raw per verificare la struttura dei dati e la correttezza dei campi.

Debug di SQLiteOpenHelper

Stetho mostra tutti i database creati tramite SQLiteOpenHelper. Se il database non compare in Chrome DevTools, verificare che getWritableDatabase() sia stato chiamato almeno una volta nel codice dell'applicazione.

Ordine degli Interceptor in OkHttp

Stetho deve essere l'ultimo interceptor nella catena OkHttp per vedere le richieste modificate. L'ordine corretto: prima AuthInterceptor, poi LoggingInterceptor, poi StethoInterceptor per ultimo.

Tecniche pratiche di debug con Stetho

Stetho è efficace per verificare la correttezza della serializzazione JSON prima di inviarla al server. Aprire Network Inspector, trovare la richiesta e visualizzare il corpo della richiesta in modalità Raw per assicurarsi della correttezza della struttura dei campi e dei tipi di dati.

Debug di SQLiteOpenHelper e ContentProvider

Stetho mostra tutti i database creati tramite SQLiteOpenHelper. Se il database non compare in Chrome DevTools, verificare che il metodo getWritableDatabase() sia stato chiamato almeno una volta nel codice dell'applicazione. Per le migrazioni, eseguire ALTER TABLE tramite la console SQL e verificare il risultato con una query SELECT.

Ordine degli Interceptor nella catena OkHttp

Stetho deve essere l'ultimo interceptor nella catena OkHttp per mostrare le richieste modificate finali. La sequenza corretta: AuthInterceptor per primo, poi LoggingInterceptor, poi StethoInterceptor per ultimo per una registrazione corretta.