Arrêtez d'utiliser datetime.now !

Injection de dépendance en pratique

La meilleure façon de comprendre les avantages de l'ID et sa motivation est d'utiliser un exemple concret.

Recherche IP

Disons que nous voulons essayer de deviner d'où viennent les visiteurs de notre site Django, et nous décidons d'essayer d'utiliser l'adresse IP de la requête pour le faire. Une implémentation initiale peut ressembler à ceci :

from typing import Optional
from django.http import HttpRequest
import requests

def get_country_from_request(request: HttpRequest) -> Optional[str]:
 ip = request.META.get('REMOTE_ADDR', request.META.get('HTTP_X_FORWARDED_FOR'))
 if ip is None or ip == '':
 return None

 response = requests.get(f'https://ip-api.com/json/{ip}')
 if not response.ok:
 return None

 data = response.json()
 if data['status'] != 'success':
 return None

 return data['countryCode']

Cette fonction unique accepte un HttpRequest , essaie d'extraire une adresse IP des en-têtes de requête, puis utilise le requests bibliothèque d'appeler un service externe pour obtenir l'indicatif du pays.

recherche IP

J'utilise le service gratuit https://ip-api.com pour rechercher un pays à partir d'une adresse IP. J'utilise ce service uniquement à des fins de démonstration. Je ne le connais pas, alors ne voyez pas cela comme une recommandation de l'utiliser.

Essayons d'utiliser cette fonction :

>>> from django.test import RequestFactory
>>> rf = RequestFactory()
>>> request = rf.get('/', REMOTE_ADDR='216.58.210.46')
>>> get_country_from_request(request)
'US'

OK, donc ça marche. Notez que pour l'utiliser nous avons créé un HttpRequest objet utilisant le RequestFactory de Django

Essayons d'écrire un test pour un scénario lorsqu'un code pays est trouvé :

import re
import json
import responses

from django.test import RequestFactory

rf = RequestFactory()

with responses.RequestsMock() as rsps:
 url_pattern = re.compile(r'http://ip-api.com/json/[0-9\.]+')
 rsps.add(responses.GET, url_pattern, status=200, content_type='application/json', body=json.dumps({
 'status': 'success',
 'countryCode': 'US'
 }))
 request = rf.get('/', REMOTE_ADDR='216.58.210.46')
 countryCode = get_country_from_request(request)
 assert countryCode == 'US'

La fonction utilise le requests bibliothèque en interne pour faire une requête à l'API externe. Pour simuler la réponse, nous avons utilisé le responses bibliothèque.

Si vous regardez ce test et que vous pensez que c'est très compliqué, vous avez raison. Pour tester la fonction, nous avons dû procéder comme suit :

• Générer une requête Django en utilisant un RequestFactory .
• Moquer un requests réponse en utilisant responses .
• Connaître le fonctionnement interne de la fonction (quelle URL elle utilise).

Ce dernier point est celui où ça devient poilu. Pour tester la fonction, nous avons utilisé nos connaissances sur la façon dont la fonction est implémentée :quel point de terminaison elle utilise, comment l'URL est structurée, quelle méthode elle utilise et à quoi ressemble la réponse. Cela crée une dépendance implicite entre le test et l'implémentation. En d'autres termes, l'implémentation de la fonction ne peut pas changer sans changer également le test . Ce type de dépendance malsaine est à la fois inattendu et nous empêche de traiter la fonction comme une "boîte noire".

Notez également que nous n'avons testé qu'un seul scénario. Si vous regardez la couverture de ce test, vous constaterez qu'elle est très faible. Ensuite, nous essayons de simplifier cette fonction.

Attribuer la responsabilité

L'une des techniques pour rendre les fonctions plus faciles à tester consiste à supprimer les dépendances. Notre fonction IP dépend actuellement du HttpRequest de Django , le requests bibliothèque et implicitement sur le service externe. Commençons par déplacer la partie de la fonction qui gère le service externe vers une fonction distincte :

def get_country_from_ip(ip: str) -> Optional[str]:
 response = requests.get(f'http://ip-api.com/json/{ip}')
 if not response.ok:
 return None

 data = response.json()
 if data['status'] != 'success':
 return None

 return data['countryCode']

def get_country_from_request(request: HttpRequest) -> Optional[str]:
 ip = request.META.get('REMOTE_ADDR', request.META.get('HTTP_X_FORWARDED_FOR'))
 if ip is None or ip == '':
 return None

 return get_country_from_ip(ip)

Nous avons maintenant deux fonctions :

• get_country_from_ip :reçoit une adresse IP et renvoie le code du pays.
• get_country_from_request :accepte un Django HttpRequest , extrayez l'adresse IP de l'en-tête, puis utilisez la première fonction pour trouver le code du pays.

Après avoir divisé la fonction, nous pouvons maintenant rechercher une adresse IP directement, sans créer de requête :

>>> get_country_from_ip('216.58.210.46')
'US'
>>> from django.test import RequestFactory
>>> request = RequestFactory().get('/', REMOTE_ADDR='216.58.210.46')
>>> get_country_from_request(request)
'US'

Maintenant, écrivons un test pour cette fonction :

import re
import json
import responses

with responses.RequestsMock() as rsps:
 url_pattern = re.compile(r'http://ip-api.com/json/[0-9\.]+')
 rsps.add(responses.GET, url_pattern, status=200, content_type='application/json', body=json.dumps({
 'status': 'success',
 'countryCode': 'US'
 }))
 country_code = get_country_from_ip('216.58.210.46')
 assert country_code == 'US'

Ce test ressemble au précédent, mais nous n'avons plus besoin d'utiliser RequestFactory . Parce que nous avons une fonction distincte qui récupère directement le code pays d'une adresse IP, nous n'avons pas besoin de "simuler" un Django HttpRequest .

Cela dit, nous voulons toujours nous assurer que la fonction de niveau supérieur fonctionne et que l'adresse IP est correctement extraite de la requête :

# BAD EXAMPLE!
import re
import json
import responses

from django.test import RequestFactory

rf = RequestFactory()
request_with_no_ip = rf.get('/')
country_code = get_country_from_request(request_with_no_ip)
assert country_code is None

Nous avons créé une requête sans IP et la fonction a renvoyé None . Avec ce résultat, pouvons-nous vraiment dire avec certitude que la fonction fonctionne comme prévu ? Pouvons-nous dire que la fonction a renvoyé None parce qu'il n'a pas pu extraire l'IP de la requête, ou parce que la recherche de pays n'a rien renvoyé ?

Quelqu'un m'a dit un jour que si pour décrire une fonction, vous avez besoin d'utiliser les mots "et" ou "ou", vous pouvez probablement bénéficier de sa division. Il s'agit de la version profane du principe de responsabilité unique qui dicte que chaque classe ou fonction ne devrait avoir qu'une seule raison de changer .

La fonction get_country_from_request extrait l'IP d'une requête et essaie de trouver le code de pays correspondant. Donc, si la règle est correcte, nous devons la scinder :

def get_ip_from_request(request: HttpRequest) -> Optional[str]:
 ip = request.META.get('REMOTE_ADDR', request.META.get('HTTP_X_FORWARDED_FOR'))
 if ip is None or ip == '':
 return None
 return ip


# Maintain backward compatibility
def get_country_from_request(request: HttpRequest) -> Optional[str]:
 ip = get_ip_from_request(request)
 if ip is None:
 return None
 return get_country_from_ip(ip)

Pour pouvoir tester si nous extrayons correctement une adresse IP d'une requête, nous avons transféré cette partie dans une fonction distincte. Nous pouvons maintenant tester cette fonction séparément :

rf = RequestFactory()
assert get_ip_from_request(rf.get('/')) is None
assert get_ip_from_request(rf.get('/', REMOTE_ADDR='0.0.0.0')) == '0.0.0.0'
assert get_ip_from_request(rf.get('/', HTTP_X_FORWARDED_FOR='0.0.0.0')) == '0.0.0.0'
assert get_ip_from_request(rf.get('/', REMOTE_ADDR='0.0.0.0', HTTP_X_FORWARDED_FOR='1.1.1.1')) =='0.0.0.0'

Avec seulement ces 5 lignes de code, nous avons couvert beaucoup plus de scénarios possibles.

Utiliser un service

Jusqu'à présent, nous avons implémenté des tests unitaires pour la fonction qui extrait l'adresse IP de la requête et rendu possible la recherche d'un pays en utilisant uniquement une adresse IP. Les tests pour la fonction de haut niveau sont encore très brouillons. Parce que nous utilisons requests à l'intérieur de la fonction, nous avons été obligés d'utiliser responses aussi pour le tester. Il n'y a rien de mal avec responses , mais moins il y a de dépendances, mieux c'est.

Invoquer une requête à l'intérieur de la fonction crée une dépendance implicite entre cette fonction et le requests bibliothèque. Une façon d'éliminer cette dépendance est d'extraire la partie faisant la demande à un service distinct :

import requests

class IpLookupService:

 def __init__(self, base_url: str) -> None:
 self.base_url = base_url

 def get_country_from_ip(self, ip: str) -> Optional[str]:
 response = requests.get(f'{self.base_url}/json/{ip}')
 if not response.ok:
 return None

 data = response.json()
 if data['status'] != 'success':
 return None

 return data['countryCode']

Le nouveau IpLookupService est instancié avec l'url de base du service, et fournit une fonction unique pour obtenir un pays à partir d'une IP :

>>> ip_lookup_service = IpLookupService('http://ip-api.com')
>>> ip_lookup_service.get_country_from_ip('216.58.210.46')
'US'

Construire des services de cette manière présente de nombreux avantages :

• Encapsuler toute la logique liée à la recherche d'adresses IP
• Fournit une interface unique avec des annotations de type
• Peut être réutilisé
• Peut être testé séparément
• Peut être développé séparément (tant que l'API qu'il fournit reste inchangée)
• Peut être ajusté pour différents environnements (par exemple, utiliser une URL différente pour le test et la production)

La fonction de niveau supérieur devrait également changer. Au lieu de faire des requêtes tout seul, il utilise le service :

def get_country_from_request(
 request: HttpRequest,
 ip_lookup_service: IpLookupService,
) -> Optional[str]:
 ip = get_ip_from_request(request)
 if ip is None:
 return None
 return ip_lookup_service.get_country_from_ip(ip)

Pour utiliser la fonction, nous lui passons une instance du service :

>>> ip_lookup_service = IpLookupService('http://ip-api.com')
>>> request = RequestFactory().get('/', REMOTE_ADDR='216.58.210.46')
>>> get_country_from_request(request, ip_lookup_service)
'US'

Maintenant que nous avons le contrôle total du service, nous pouvons tester la fonction de niveau supérieur sans utiliser responses :

from unittest import mock
from django.test import RequestFactory

fake_ip_lookup_service = mock.create_autospec(IpLookupService)
fake_ip_lookup_service.get_country_from_ip.return_value = 'US'

request = RequestFactory().get('/', REMOTE_ADDR='216.58.210.46')

country_code = get_country_from_request(request, fake_ip_lookup_service)
assert country_code == 'US'

Pour tester la fonction sans faire de requêtes http, nous avons créé une maquette du service. Nous définissons ensuite la valeur de retour de get_country_from_ip , et a transmis le service fictif à la fonction.

Modifier les implémentations

Un autre avantage de DI souvent mentionné est la possibilité de modifier complètement l'implémentation sous-jacente d'un service injecté. Par exemple, un jour, vous découvrez que vous n'avez pas besoin d'utiliser un service distant pour rechercher une adresse IP. Au lieu de cela, vous pouvez utiliser une base de données IP locale.

Parce que notre IpLookupService ne fuit pas son implémentation interne, c'est un changement facile :

from typing import Optional
import GeoIP

class LocalIpLookupService:
 def __init__(self, path_to_db_file: str) -> None:
 self.db = GeoIP.open(path_to_db_file, GeoIP.GEOIP_STANDARD)

 def get_country_from_ip(self, ip: str) -> Optional[str]:
 return self.db.country_code_by_addr(ip)

L'API du service est restée inchangée, vous pouvez donc l'utiliser de la même manière que l'ancien service :

>>> ip_lookup_service = LocalIpLookupService('/usr/share/GeoIP/GeoIP.dat')
>>> ip_lookup_service.get_country_from_ip('216.58.210.46')
'US'
>>> from django.test import RequestFactory
>>> request = RequestFactory().get('/', REMOTE_ADDR='216.58.210.46')
>>> get_country_from_request(request, ip_lookup_service)
'US'

La meilleure partie ici est que les tests ne sont pas affectés. Tous les tests doivent réussir sans apporter de modifications.

GéoIP

Dans l'exemple, j'utilise l'API MaxMind GeoIP Legacy Python Extension car elle utilise des fichiers que j'ai déjà dans mon système d'exploitation dans le cadre de geoiplookup . Si vous avez vraiment besoin de rechercher des adresses IP, consultez GeoIP2 et assurez-vous de vérifier la licence et les restrictions d'utilisation.

De plus, les utilisateurs de Django pourraient être ravis de savoir que Django fournit un wrapper autour de geoip2 .

Services de dactylographie

Dans la dernière section, nous avons un peu triché. Nous avons injecté le nouveau service LocalIpLookupService dans une fonction qui attend une instance de IpLookupService . Nous nous sommes assurés que ces deux éléments sont identiques, mais les annotations de type sont désormais erronées. Nous avons également utilisé un mock pour tester la fonction qui n'est pas non plus de type IpLookupService . Alors, comment pouvons-nous utiliser les annotations de type tout en pouvant injecter différents services ?

from abc import ABCMeta
import GeoIP
import requests

class IpLookupService(metaclass=ABCMeta):
 def get_country_from_ip(self, ip: str) -> Optional[str]:
 raise NotImplementedError()


class RemoteIpLookupService(IpLookupService):
 def __init__(self, base_url: str) -> None:
 self.base_url = base_url

 def get_country_from_ip(self, ip: str) -> Optional[str]:
 response = requests.get(f'{self.base_url}/json/{ip}')
 if not response.ok:
 return None

 data = response.json()
 if data['status'] != 'success':
 return None

 return data['countryCode']


class LocalIpLookupService(IpLookupService):
 def __init__(self, path_to_db_file: str) -> None:
 self.db = GeoIP.open(path_to_db_file, GeoIP.GEOIP_STANDARD)

 def get_country_from_ip(self, ip: str) -> Optional[str]:
 return self.db.country_code_by_addr(ip)

Nous avons défini une classe de base appelée IpLookupService qui fait office d'interface. La classe de base définit l'API publique pour les utilisateurs de IpLookupService . En utilisant la classe de base, nous pouvons fournir deux implémentations :

1. RemoteIpLookupService :utilise le requests bibliothèque pour rechercher l'IP à un externe.
2. LocalIpLookupService :utilise la base de données GeoIP locale.

Désormais, toute fonction nécessitant une instance de IpLookupService peut utiliser ce type, et la fonction pourra accepter n'importe quelle sous-classe de celui-ci.

Avant de conclure, nous devons encore gérer les tests. Auparavant, nous supprimions la dépendance du test sur responses , maintenant nous pouvons abandonner mock aussi bien. Au lieu de cela, nous sous-classons IpLookupService avec une implémentation simple pour les tests :

from typing import Iterable

class FakeIpLookupService(IpLookupService):
 def __init__(self, results: Iterable[Optional[str]]):
 self.results = iter(results)

 def get_country_from_ip(self, ip: str) -> Optional[str]:
 return next(self.results)

Le FakeIpLookupService implémente IpLookupService , et produit des résultats à partir d'une liste de résultats prédéfinis que nous lui fournissons :

from django.test import RequestFactory

fake_ip_lookup_service = FakeIpLookupService(results=['US'])
request = RequestFactory().get('/', REMOTE_ADDR='216.58.210.46')

country_code = get_country_from_request(request, fake_ip_lookup_service)
assert country_code == 'US'

Le test n'utilise plus mock .

Utiliser un protocole

La forme de hiérarchie de classes démontrée dans la section précédente est appelée "sous-typage nominal". Il existe une autre façon d'utiliser le typage sans classes, en utilisant Protocols :

from typing import Iterable, Optional
from typing_extensions import Protocol
import GeoIP
import requests


class IpLookupService(Protocol):
 def get_country_from_ip(self, ip: str) -> Optional[str]:
 pass


class RemoteIpLookupService:
 def __init__(self, base_url: str) -> None:
 self.base_url = base_url

 def get_country_from_ip(self, ip: str) -> Optional[str]:
 response = requests.get(f'{self.base_url}/json/{ip}')
 if not response.ok:
 return None

 data = response.json()
 if data['status'] != 'success':
 return None

 return data['countryCode']


class LocalIpLookupService:
 def __init__(self, path_to_db_file: str) -> None:
 self.db = GeoIP.open(path_to_db_file, GeoIP.GEOIP_STANDARD)

 def get_country_from_ip(self, ip: str) -> Optional[str]:
 return self.db.country_code_by_addr(ip)


class FakeIpLookupService:
 def __init__(self, results: Iterable[Optional[str]]):
 self.results = iter(results)

 def get_country_from_ip(self, ip: str) -> Optional[str]:
 yield from self.results

Le passage des classes aux protocoles est doux. Au lieu de créer IpLookupService comme classe de base, nous la déclarons Protocol . Un protocole est utilisé pour définir une interface et ne peut pas être instancié. Au lieu de cela, un protocole est utilisé uniquement à des fins de typage. Lorsqu'une classe implémente l'interface définie par le protocole, cela signifie que le "Sous-typage structurel" se termine et la vérification de type sera validée.

Dans notre cas, nous utilisons un protocole pour nous assurer qu'un argument de type IpLookupService implémente les fonctions que nous attendons d'un service IP.

sous-typage structurel et nominal

J'ai écrit sur les protocoles, le sous-typage structurel et nominal dans le passé. Découvrez la modélisation du polymorphisme dans Django avec Python.

Alors, lequel utiliser ? Certains langages, comme Java, utilisent exclusivement le typage nominal, tandis que d'autres langages, comme Go, utilisent le typage structurel pour les interfaces. Il y a des avantages et des inconvénients dans les deux sens, mais nous n'aborderons pas cela ici. En Python, le typage nominal est plus facile à utiliser et à comprendre, donc ma recommandation est de s'y tenir, à moins que vous n'ayez besoin de la flexibilité offerte par les protocoles.

Non-déterminisme et effets secondaires

Si vous avez déjà eu un test qui, un jour, a commencé à échouer, sans provocation, ou un test qui échoue une fois par lune bleue sans raison apparente, il est possible que votre code repose sur quelque chose qui n'est pas déterministe. Dans le datetime.date.today exemple, le résultat de datetime.date.today repose sur l'heure actuelle qui change constamment, donc ce n'est pas déterministe.

Il existe de nombreuses sources de non-déterminisme. Les exemples courants incluent :

• Le hasard
• Accès au réseau
• Accès au système de fichiers
• Accès à la base de données
• Variables d'environnement
• Variables globales mutables

L'injection de dépendance fournit un bon moyen de contrôler le non-déterminisme dans les tests. La recette de base est la suivante :

1. Identifier la source du non-déterminisme et l'encapsuler dans un service  :Par exemple, TimeService, RandomnessService, HttpService, FilesystemService et DatabaseService.
2. Utiliser l'injection de dépendances pour accéder à ces services :Ne les contournez jamais en utilisant directement datetime.now() et similaire.
3. Fournir des implémentations déterministes de ces services dans les tests  :Utilisez plutôt une simulation ou une implémentation personnalisée adaptée aux tests.

Si vous suivez la recette avec diligence, vos tests ne seront pas affectés par des circonstances extérieures et vous n'aurez pas de tests feuilletés !