La tua funzione chiama un’API meteo. Il tuo test non dovrebbe dipendere da Internet, da una chiave API o dal tempo di domani. Il built-in di Python unittest.mock ti consente di sostituire quella chiamata con una controfigura che restituisce esattamente ciò che scegli.

Abbiamo scritto un piccolo modulo weather e nove test, tutti eseguiti con lo unittest di Python 3.13. Tutti e nove sono stati superati e i risultati stampati di seguito provengono da quella tiratura.

Perché deridere?

• Velocità: nessuna chiamata di rete o configurazione del database.
• Affidabilità: i test non falliscono perché un servizio di terze parti è inattivo.
• Controllo: puoi simulare timeout, errori e dati dispari su richiesta.
• Isolamento: metti alla prova la tua logica, non il server di qualcun altro.

I mock appartengono principalmente agli unit test. I test di integrazione dovrebbero comunque parlare di dipendenze reali o realistiche.

Nozioni di base finte

from unittest.mock import Mock

api = Mock()
api.get_price.return_value = 499

print(api.get_price("pen"))                # 499
api.get_price.assert_called_once_with("pen")
print(api.get_price.call_args_list)        # [call('pen')]
print(api.anything_at_all())               # <Mock name='mock.anything_at_all()' ...>

A Mock registra ogni chiamata, così puoi verificare come è stata utilizzata. Notate l’ultima riga, però. Un semplice Mock inventa qualsiasi attributo tu chieda. Questa flessibilità è conveniente e anche pericolosa, come vedremo.

MagicMock ha la stessa idea ma supporta anche metodi “magici” come __len__ e __iter__. patch() utilizza MagicMock per impostazione predefinita.

side_effect: errori e sequenze

side_effect controlla cosa succede ad ogni chiamata. Impostalo su un’eccezione per simulare un errore:

api.fetch.side_effect = ConnectionError("down")
api.fetch()   # raises ConnectionError

Impostalo su un elenco per restituire risultati diversi nelle chiamate successive. Questo è perfetto per testare la logica dei tentativi:

def fetch_with_retry(api, attempts=3):
    for _ in range(attempts):
        try:
            return api.fetch()
        except ConnectionError:
            continue
    raise ConnectionError("all attempts failed")

api = Mock()
api.fetch.side_effect = [ConnectionError("busy"), {"ok": True}]
print(fetch_with_retry(api))    # {'ok': True}
print(api.fetch.call_count)     # 2

La prima chiamata non è riuscita, la seconda ha avuto successo e il test ha dimostrato che la funzione ha riprovato esattamente una volta. Simulare questo rispetto a un servizio reale sarebbe quasi impossibile.

patch(): sostituisce qualcosa temporaneamente

Spesso la dipendenza non viene passata. Viene importata all’interno del modulo. patch() lo scambia per la durata di un test e lo ripristina successivamente:

# weather.py
from http_client import get as requests_get

def report(city):
    data = requests_get(f"https://api.example.com/weather?city={city}")
    return f"{city}: {data['temp_c']}°C"

from unittest.mock import patch

with patch("weather.requests_get") as fake_get:
    fake_get.return_value = {"temp_c": 31}
    print(weather.report("Pune"))   # Pune: 31°C
    fake_get.assert_called_once_with(
        "https://api.example.com/weather?city=Pune")

Puoi usare patch come gestore di contesto come questo, o come decoratore, che passa il mock come argomento.

Patch dove viene utilizzata, non dove è definita

Questo è l’errore che quasi tutti commettono una volta. La vera funzione get risiede in http_client, quindi sembra naturale patcharla lì:

with patch("http_client.get") as fake_get:
    fake_get.return_value = {"temp_c": 99}
    weather.report("Pune")

# ConnectionError: no network in tests: https://api.example.com/weather?city=Pune

La vera funzione è stata eseguita. Quando weather.py ha fatto from http_client import get as requests_get, ha creato il proprio nome che punta alla funzione originale. La patch http_client.get ha cambiato un nome diverso, quindi weather non ha mai visto il mock. Il nostro http_client.get rilancia apposta, quindi l’errore è stato clamoroso. In un progetto reale, potrebbe tranquillamente chiamare un’API live.

spec e autospec: rendi i mock rigorosi

Un semplice Mock accetta qualsiasi cosa, compresi gli errori di battitura. Con una specifica, consente solo gli attributi della classe reale:

api = Mock(spec=weather.WeatherClient)
api.get_temprature("Pune")
# AttributeError: Mock object has no attribute 'get_temprature'

loose = Mock()
loose.get_temprature("Pune")    # returns a Mock, no error at all

La versione simulata accettava volentieri il metodo di ortografia errata, quindi un test che lo utilizzava poteva passare anche se il codice reale si bloccava. autospec va oltre e controlla le firme dei metodi:

with patch("weather.WeatherClient", autospec=True) as Fake:
    client = Fake.return_value
    client.get_temperature("Pune", "extra", "args")
# TypeError: too many positional arguments

Preferisci autospec=True o create_autospec() quando deridi le tue stesse lezioni. Mantiene le finte oneste mentre il codice reale cambia.

Date e orari beffardi

Il codice che dipende dalla data odierna è difficile da testare. Avvolgi l’orologio in una piccola funzione e applica la patch che:

def today():
    return datetime.date.today()

def is_weekend():
    return today().weekday() >= 5

@patch("weather.today")
def test_date(self, fake_today):
    fake_today.return_value = datetime.date(2026, 11, 7)
    print(weather.is_weekend())   # True (a Saturday)

Non è possibile applicare facilmente una patch datetime.date.today direttamente, perché i tipi incorporati non consentono l’impostazione dei loro attributi. Biblioteche come Freezegun e Time Machine gestiscono questo problema in modo più completo.

Affermazioni sui mock

Quando un’asserzione fallisce, il messaggio è chiaro. Abbiamo chiamato assert_called_once() su un metodo che non è mai stato eseguito:

AssertionError: Expected 'save' to have been called once. Called 0 times.

Le versioni precedenti di Python consentono il passaggio silenzioso dei metodi di asserzione con errori di ortografia, come assret_called_once. Le versioni moderne sollevano un errore per i nomi che iniziano con assert o per errori di ortografia comuni, ma una specifica è ancora la guardia più forte.

pytest e schernisce

Tutto quanto sopra funziona anche in pytest. Molti utenti pytest utilizzano anche il dispositivo monkeypatch integrato per semplici sostituzioni, o il plugin pytest-mock, che fornisce un dispositivo mocker che annulla automaticamente le patch. Per tutti vale la regola “patch dove viene utilizzata”. Consulta il nostro tutorial pytest per dispositivi e configurazione.

Quando non deridere

• Non deridere ciò che stai testando. Se la derisione fa tutto il lavoro, il test non dimostra nulla.
• Evita di prendere in giro oggetti di valore semplice. Usa oggetti reali.
• Non deridere tutto. I test pieni di simulazioni spesso si interrompono ogni volta che viene effettuato il refactoring del codice, anche quando il comportamento è corretto.
• Esegui alcuni test di integrazione reali. I mock codificano le tue ipotesi su un servizio e tali ipotesi possono essere errate.

Le simulazioni inoltre gonfiano facilmente la copertura del codice, poiché i percorsi simulati vengono eseguiti senza alcun comportamento reale dietro di loro.

Errori comuni di scherno

• Correzione del nome sbagliato. Trattato sopra, e ancora la causa numero uno di “la mia simulazione viene ignorata”.
• Dimenticare di impostare return_value. Il codice in prova riceve quindi un oggetto Mock invece dei dati. Potrebbe passare direttamente attraverso la tua funzione e fare un test superato per sbaglio, ad esempio quando controlli solo che un risultato sia veritiero.
• Affermare sulla finzione invece che sul risultato. Controllare che save() sia stato chiamato è più debole che controllare cosa è stato salvato. Utilizzare assert_called_once_with(...) con argomenti reali o, meglio, affermare il risultato della funzione.
• Patch che perdono. Chiamare patcher.start() senza stop() lascia il falso sul posto per test successivi. Utilizzare il gestore del contesto, il decoratore o addCleanup(patcher.stop).
• Decoratori impilati nell’ordine sbagliato. Con diversi @patch decoratori, quello in basso viene passato come primo argomento. Mescolarli silenziosamente configura la finzione sbagliata.
• Deridere una libreria che non possiedi in molti test. Avvolgilo in una piccola classe tutta tua e prendilo in giro invece. I tuoi test descrivono quindi le tue esigenze, non l’API della biblioteca.

Mock, stub e falsi

Queste parole sono spesso usate in modo approssimativo, ma le differenze aiutano quando si parla di test. Uno stub restituisce semplicemente risposte predefinite. Un mock registra anche le chiamate in modo da poter verificare come è stato utilizzato. Un falso è un’implementazione funzionante e semplificata, come un repository in memoria invece di un database. Python Mock può fungere da stub o mock. I fake sono classi ordinarie che scrivi tu stesso e spesso portano a test che sopravvivono meglio al refactoring, perché controllano il comportamento piuttosto che le chiamate esatte.

Una buona regola pratica è deridere i bordi del proprio sistema: la rete, l’orologio, i numeri casuali, il file system e i servizi di terze parti a pagamento. All’interno di quei bordi, preferisci gli oggetti reali. I test costruiti in questo modo rimangono veloci ed esercitano comunque il codice effettivamente scritto.

Considerazioni finali

Il mocking è uno strumento preciso: sostituisci dipendenze lente o imprevedibili, controlla cosa restituiscono e controlla come il tuo codice le ha utilizzate. Due abitudini prevengono la maggior parte dei problemi. Patch il nome nel modulo sotto test e usa autospec in modo che i tuoi mock rifiutino le chiamate che l’oggetto reale rifiuterebbe.

Domande frequenti

Continua a imparare