🚧 Warning, this Chapter is freshly updated for Django 4 + Python 3.12.
The code listings should have valid syntax, and I’ve been through and sense-checked the chapter text, but a few things might still be off! So let me know what you think of the chapter, via obeythetestinggoat@gmail.com
In this chapter we’ll start testing the parts of our code that send emails.
In the FT, you saw that Django gives us a way of retrieving
any emails it sends by using the mail.outbox attribute.
But in this chapter, I want to demonstrate a very important testing technique called mocking,
so for the purpose of these unit tests, we’ll pretend that this nice Django shortcut doesn’t exist.
Am I telling you not to use Django’s mail.outbox?
No; use it, it’s a neat shortcut.
But I want to teach mocks because they’re a useful general-purpose tool
for unit testing external dependencies.
You may not always be using Django!
And even if you are, you may not be sending
email—any interaction with a third-party API is a good candidate for testing with mocks.
|
Note
|
I once gave a talk called "Stop Using Mocks!". Have a look for that, and my book on architecture patterns for a deeper look at the trade-offs of mocking, and some alternatives. |
Let’s just get a basic view and URL set up first. We can do so with a simple test that our new URL for sending the login email should eventually redirect back to the home page:
from django.test import TestCase
class SendLoginEmailViewTest(TestCase):
def test_redirects_to_home_page(self):
response = self.client.post(
"/accounts/send_login_email", data={"email": "edith@example.com"}
)
self.assertRedirects(response, "/")Wire up the include in 'superlists/urls.py', plus the url in
accounts/urls.py, and get the test passing with something a bit like this:
from django.core.mail import send_mail
from django.shortcuts import redirect
def send_login_email(request):
return redirect("/")I’ve added the import of the send_mail function as a placeholder for now:
$ python src/manage.py test accounts [...] Ran 4 tests in 0.015s OK
OK, now we have a starting point, so let’s get mocking!
When we call send_mail in real life we expect Django to be making a
connection to our email provider, and sending an actual email across the public
internet. That’s not something we want to happen in our tests. It’s a similar
problem whenever you have code that has external side effects—calling an
API, sending out a tweet or an SMS or whatever it may be. In our unit tests, we
don’t want to be sending out real tweets or API calls across the internet. But
we would still like a way of testing that our code is correct.
Mocks[1]
are the answer.
Actually, one of the great things about Python is that its dynamic nature makes
it very easy to do things like mocking, or what’s sometimes called
monkeypatching. Let’s suppose
that, as a first step, we want to get to some code that invokes send_mail
with the right subject line, from address, and to address. That would look
something like this:
def send_login_email(request):
email = request.POST['email']
# send_mail(
# 'Your login link for Superlists',
# 'body text tbc',
# 'noreply@superlists',
# [email],
# )
return redirect('/')How can we test this, without calling the 'real' send_mail function? The
answer is that our test can ask Python to replace the send_mail function with
a fake version, at runtime, before we invoke the send_login_email view.
Check this out:
from django.test import TestCase
import accounts.views # (2)
class SendLoginEmailViewTest(TestCase):
[...]
def test_sends_mail_to_address_from_post(self):
self.send_mail_called = False
def fake_send_mail(subject, body, from_email, to_list): # (1)
self.send_mail_called = True
self.subject = subject
self.body = body
self.from_email = from_email
self.to_list = to_list
accounts.views.send_mail = fake_send_mail # (2)
self.client.post(
"/accounts/send_login_email", data={"email": "edith@example.com"}
)
self.assertTrue(self.send_mail_called)
self.assertEqual(self.subject, "Your login link for Superlists")
self.assertEqual(self.from_email, "noreply@superlists")
self.assertEqual(self.to_list, ["edith@example.com"])-
We define a
fake_send_mailfunction, which looks like the realsend_mailfunction, but all it does is save some information about how it was called, using some variables onself. -
Then, before we execute the code under test by doing the
self.client.post, we swap out the realaccounts.views.send_mailwith our fake version—it’s as simple as just assigning it.
It’s important to realise that there isn’t really anything magical going on here; we’re just taking advantage of Python’s dynamic nature and scoping rules.
Up until we actually invoke a function, we can modify the variables it has
access to, as long as we get into the right namespace (that’s why we import the
top-level accounts module, to be able to get down to the accounts.views module,
which is the scope that the accounts.views.send_login_email function will run
in).
This isn’t even something that only works inside unit tests. You can do this kind of "monkeypatching" in any kind of Python code!
That may take a little time to sink in. See if you can convince yourself that it’s not all totally crazy, before reading a couple of bits of further detail.
-
Why do we use
selfas a way of passing information around? It’s just a convenient variable that’s available both inside the scope of thefake_send_mailfunction and outside of it. We could use any mutable object, like a list or a dictionary, as long as we are making in-place changes to an existing variable that exists outside our fake function. (Feel free to have a play around with different ways of doing this, if you’re curious, and see what works and doesn’t work.) -
The "before" is critical! I can’t tell you how many times I’ve sat there, wondering why a mock isn’t working, only to realise that I didn’t mock 'before' I called the code under test.
Let’s see if our hand-rolled mock object will let us test-drive some code:
$ python src/manage.py test accounts
[...]
self.assertTrue(self.send_mail_called)
AssertionError: False is not true
So let’s call send_mail, naively:
def send_login_email(request):
send_mail()
return redirect("/")That gives:
TypeError: SendLoginEmailViewTest.test_sends_mail_to_address_from_post.<locals> .fake_send_mail() missing 4 required positional arguments: 'subject', 'body', 'from_email', and 'to_list'
Looks like our monkeypatch is working!
We’ve called send_mail, and it’s gone into our fake_send_mail function,
which wants more arguments.
Let’s try this:
def send_login_email(request):
send_mail("subject", "body", "from_email", ["to email"])
return redirect("/")That gives:
self.assertEqual(self.subject, "Your login link for Superlists") AssertionError: 'subject' != 'Your login link for Superlists'
That’s working pretty well. And now we can work all the way through to something like this:
def send_login_email(request):
email = request.POST["email"]
send_mail(
"Your login link for Superlists",
"body text tbc",
"noreply@superlists",
[email],
)
return redirect("/")and passing tests!
$ python src/manage.py test accounts Ran 5 tests in 0.016s OK
Brilliant! We’ve managed to write tests for some code, that
ordinarily[2] would go out and try to send real emails across the internet,
and by "mocking out" the send_email function, we’re able to write
the tests and code all the same.
The
popular 'mock' package was added to the standard library as part of Python
3.3.[3]
It provides a magical object called a Mock; try this out in a Python shell:
>>> from unittest.mock import Mock
>>> m = Mock()
>>> m.any_attribute
<Mock name='mock.any_attribute' id='140716305179152'>
>>> type(m.any_attribute)
<class 'unittest.mock.Mock'>
>>> m.any_method()
<Mock name='mock.any_method()' id='140716331211856'>
>>> m.foo()
<Mock name='mock.foo()' id='140716331251600'>
>>> m.called
False
>>> m.foo.called
True
>>> m.bar.return_value = 1
>>> m.bar(42, var='thing')
1
>>> m.bar.call_args
call(42, var='thing')A magical object that responds to any request for an attribute or method call with other mocks, that you can configure to return specific values for its calls, and that allows you to inspect what it was called with? Sounds like a useful thing to be able to use in our unit tests!
And
as if that weren’t enough, the mock module also provides a helper
function called patch, which we can use to do the monkeypatching we did
by hand earlier.
I’ll explain how it all works shortly, but let’s see it in action first:
from unittest import mock
from django.test import TestCase
[...]
@mock.patch("accounts.views.send_mail")
def test_sends_mail_to_address_from_post(self, mock_send_mail):
self.client.post(
"/accounts/send_login_email", data={"email": "edith@example.com"}
)
self.assertEqual(mock_send_mail.called, True)
(subject, body, from_email, to_list), kwargs = mock_send_mail.call_args
self.assertEqual(subject, "Your login link for Superlists")
self.assertEqual(from_email, "noreply@superlists")
self.assertEqual(to_list, ["edith@example.com"])If you rerun the tests, you’ll see they still pass. And since we’re always suspicious of any test that still passes after a big change, let’s deliberately break it just to see:
self.assertEqual(to_list, ["schmedith@example.com"])And let’s add a little debug print to our view:
def send_login_email(request):
email = request.POST["email"]
print(type(send_mail))
send_mail(
[...]And run the tests again:
$ python src/manage.py test accounts [...] <class 'function'> <class 'unittest.mock.MagicMock'> [...] AssertionError: Lists differ: ['edith@example.com'] != ['schmedith@example.com'] [...] Ran 5 tests in 0.024s FAILED (failures=1)
Sure enough, the tests fail. And we can see just before the failure
message that when we print the type of the send_mail function,
in the first unit test it’s a normal function, but in the second unit
test we’re seeing a mock object.
Let’s remove the deliberate mistake and dive into exactly what’s going on:
@mock.patch("accounts.views.send_mail") # (1)
def test_sends_mail_to_address_from_post(self, mock_send_mail): # (2)
self.client.post( # (3)
"/accounts/send_login_email", data={"email": "edith@example.com"}
)
self.assertEqual(mock_send_mail.called, True) # (4)
(subject, body, from_email, to_list), kwargs = mock_send_mail.call_args # (5)
self.assertEqual(subject, "Your login link for Superlists")
self.assertEqual(from_email, "noreply@superlists")
self.assertEqual(to_list, ["edith@example.com"])-
The
mock.patch()decorator takes a dot-notation name of an object to monkeypatch. That’s the equivalent of manually replacing thesend_mailinaccounts.views. The advantage of the decorator is that, firstly, it automatically replaces the target with a mock. And secondly, it automatically puts the original object back at the end! (Otherwise, the object stays monkeypatched for the rest of the test run, which might cause problems in other tests.) -
patchthen injects the mocked object into the test as an argument to the test method. We can choose whatever name we want for it, but I usually use a convention ofmock_plus the original name of the object. -
We call our view under test as usual, but everything inside this test method has our mock applied to it, so the view won’t call the real
send_mailobject; it’ll be seeingmock_send_mailinstead. -
And we can now make assertions about what happened to that mock object during the test. We can see it was called…
-
…and we can also unpack its various positional and keyword call arguments, and examine what it was called with. (We’ll discuss
call_argsin a bit more detail later.)
All crystal-clear? No? Don’t worry, we’ll do a couple more tests with mocks, to see if they start to make more sense as we use them more.
First let’s get back to our FT and see where it’s failing:
$ python src/manage.py test functional_tests.test_login [...] AssertionError: 'Check your email' not found in 'Superlists\nEnter your email to log in\nStart a new To-Do list'
Submitting the email address currently has no effect, because the form isn’t sending the data anywhere. Let’s wire it up in base.html:
<form method="POST" action="{% url 'send_login_email' %}">Does that help? Nope, same error. Why? Because we’re not actually displaying a success message after we send the user an email. Let’s add a test for that.
We’ll use Django’s "messages framework", which is often used to display ephemeral "success" or "warning" messages to show the results of an action. Have a look at the django messages docs if you haven’t come across it already.
Testing Django messages is a bit contorted—we have to pass follow=True to
the test client to tell it to get the page after the 302-redirect, and examine
its context for a list of messages (which we have to listify before it’ll
play nicely). Here’s what it looks like:
def test_adds_success_message(self):
response = self.client.post(
"/accounts/send_login_email",
data={"email": "edith@example.com"},
follow=True,
)
message = list(response.context["messages"])[0]
self.assertEqual(
message.message,
"Check your email, we've sent you a link you can use to log in.",
)
self.assertEqual(message.tags, "success")That gives:
$ python src/manage.py test accounts
[...]
message = list(response.context["messages"])[0]
IndexError: list index out of range
And we can get it passing with:
from django.contrib import messages
[...]
def send_login_email(request):
[...]
messages.success(
request,
"Check your email, we've sent you a link you can use to log in.",
)
return redirect("/")What happens next in the functional test? Ah. Still nothing. We need to actually add the messages to the page. Something like this:
[...]
</nav>
{% if messages %}
<div class="row">
<div class="col-md-8">
{% for message in messages %}
{% if message.level_tag == 'success' %}
<div class="alert alert-success">{{ message }}</div>
{% else %}
<div class="alert alert-warning">{{ message }}</div>
{% endif %}
{% endfor %}
</div>
</div>
{% endif %}Now do we get a little further? Yes!
$ python src/manage.py test accounts [...] Ran 6 tests in 0.023s OK $ python src/manage.py test functional_tests.test_login [...] AssertionError: 'Use this link to log in' not found in 'body text tbc'
We need to fill out the body text of the email, with a link that the user can use to log in.
Let’s just cheat for now though, by changing the value in the view:
send_mail(
"Your login link for Superlists",
"Use this link to log in",
"noreply@superlists",
[email],
)That gets the FT a little further:
$ python src/manage.py test functional_tests.test_login [...] AssertionError: Could not find url in email body: Use this link to log in
We’re going to have to build some kind of URL! Let’s build one that, again, just cheats:
class LoginViewTest(TestCase):
def test_redirects_to_home_page(self):
response = self.client.get("/accounts/login?token=abcd123")
self.assertRedirects(response, "/")We’re imagining we’ll pass the token in as a GET parameter, after the ?.
It doesn’t need to do anything for now.
I’m sure you can find your way through to getting the boilerplate in for a basic URL and view, via errors like these:
-
No URL:
AssertionError: 404 != 302 : Response didn't redirect as expected: Response code was 404 (expected 302)
-
No view:
AttributeError: module 'accounts.views' has no attribute 'login'
-
Broken view:
ValueError: The view accounts.views.login didn't return an HttpResponse object. It returned None instead.
-
OK!
$ python src/manage.py test accounts [...] Ran 7 tests in 0.029s OK
And now we can give them a link to use. It still won’t do much though, because we still don’t have a token to give to the user.
Back in our send_login_email view, we’ve tested the email subject, from, and
to fields. The body is the part that will have to include a token or URL they
can use to log in. Let’s spec out two tests for that:
from accounts.models import Token
[...]
def test_creates_token_associated_with_email(self):
self.client.post(
"/accounts/send_login_email", data={"email": "edith@example.com"}
)
token = Token.objects.get()
self.assertEqual(token.email, "edith@example.com")
@mock.patch("accounts.views.send_mail")
def test_sends_link_to_login_using_token_uid(self, mock_send_mail):
self.client.post(
"/accounts/send_login_email", data={"email": "edith@example.com"}
)
token = Token.objects.get()
expected_url = f"http://testserver/accounts/login?token={token.uid}"
(subject, body, from_email, to_list), kwargs = mock_send_mail.call_args
self.assertIn(expected_url, body)The first test is fairly straightforward; it checks that the token we create in the database is associated with the email address from the post request.
The second one is our second test using mocks. We mock out the send_mail
function again using the patch decorator, but this time we’re interested
in the body argument from the call arguments.
Running them now will fail because we’re not creating any kind of token:
$ python src/manage.py test accounts [...] accounts.models.Token.DoesNotExist: Token matching query does not exist. [...] accounts.models.Token.DoesNotExist: Token matching query does not exist.
We can get the first one to pass by creating a token:
from accounts.models import Token
[...]
def send_login_email(request):
email = request.POST["email"]
token = Token.objects.create(email=email)
send_mail(
[...]And now the second test prompts us to actually use the token in the body of our email:
[...] AssertionError: 'http://testserver/accounts/login?token=[...] not found in 'Use this link to log in' FAILED (failures=1)
So we can insert the token into our email like this:
from django.urls import reverse
[...]
def send_login_email(request):
email = request.POST["email"]
token = Token.objects.create(email=email)
url = request.build_absolute_uri( # (1)
reverse("login") + "?token=" + str(token.uid),
)
message_body = f"Use this link to log in:\n\n{url}"
send_mail(
"Your login link for Superlists",
message_body,
"noreply@superlists",
[email],
)
[...]-
request.build_absolute_urideserves a mention—it’s one way to build a "full" URL, including the domain name and the http(s) part, in Django. There are other ways, but they usually involve getting into the "sites" framework, and that gets overcomplicated pretty quickly. You can find lots more discussion on this if you’re curious by doing a bit of googling.
Two more pieces in the puzzle. We need an authentication backend, whose job it will be to examine tokens for validity and then return the corresponding users; then we need to get our login view to actually log users in, if they can authenticate.
Our custom authentication backend is next. Here’s how it looked in the spike:
class PasswordlessAuthenticationBackend(BaseBackend):
def authenticate(self, request, uid):
print("uid", uid, file=sys.stderr)
if not Token.objects.filter(uid=uid).exists():
print("no token found", file=sys.stderr)
return None
token = Token.objects.get(uid=uid)
print("got token", file=sys.stderr)
try:
user = ListUser.objects.get(email=token.email)
print("got user", file=sys.stderr)
return user
except ListUser.DoesNotExist:
print("new user", file=sys.stderr)
return ListUser.objects.create(email=token.email)
def get_user(self, email):
return ListUser.objects.get(email=email)Decoding this:
-
We take a UID and check if it exists in the database.
-
We return
Noneif it doesn’t. -
If it does exist, we extract an email address, and either find an existing user with that address, or create a new one.
A rule of thumb for these sorts of tests: any if means an extra test, and
any try/except means an extra test, so this should be about three tests.
How about something like this?
from django.contrib.auth import get_user_model
from django.http import HttpRequest
from django.test import TestCase
from accounts.authentication import PasswordlessAuthenticationBackend
from accounts.models import Token
User = get_user_model()
class AuthenticateTest(TestCase):
def test_returns_None_if_no_such_token(self):
result = PasswordlessAuthenticationBackend().authenticate(
HttpRequest(), "no-such-token"
)
self.assertIsNone(result)
def test_returns_new_user_with_correct_email_if_token_exists(self):
email = "edith@example.com"
token = Token.objects.create(email=email)
user = PasswordlessAuthenticationBackend().authenticate(
HttpRequest(), token.uid
)
new_user = User.objects.get(email=email)
self.assertEqual(user, new_user)
def test_returns_existing_user_with_correct_email_if_token_exists(self):
email = "edith@example.com"
existing_user = User.objects.create(email=email)
token = Token.objects.create(email=email)
user = PasswordlessAuthenticationBackend().authenticate(
HttpRequest(), token.uid
)
self.assertEqual(user, existing_user)In authenticate.py we’ll just have a little placeholder:
class PasswordlessAuthenticationBackend:
def authenticate(self, request, uid):
passHow do we get on?
$ python src/manage.py test accounts
.FE.........
======================================================================
ERROR: test_returns_new_user_with_correct_email_if_token_exists (accounts.tests
.test_authentication.AuthenticateTest.test_returns_new_user_with_correct_email_
if_token_exists)
---------------------------------------------------------------------
Traceback (most recent call last):
File "...goat-book/src/accounts/tests/test_authentication.py", line 24, in
test_returns_new_user_with_correct_email_if_token_exists
new_user = User.objects.get(email=email)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[...]
accounts.models.User.DoesNotExist: User matching query does not exist.
======================================================================
FAIL: test_returns_existing_user_with_correct_email_if_token_exists (accounts.t
ests.test_authentication.AuthenticateTest.test_returns_existing_user_with_corre
ct_email_if_token_exists)
---------------------------------------------------------------------
Traceback (most recent call last):
File "...goat-book/src/accounts/tests/test_authentication.py", line 34, in
test_returns_existing_user_with_correct_email_if_token_exists
self.assertEqual(user, existing_user)
AssertionError: None != <User: User object (edith@example.com)>
---------------------------------------------------------------------
Ran 12 tests in 0.038s
FAILED (failures=1, errors=1)
Here’s a first cut:
from accounts.models import Token, User
class PasswordlessAuthenticationBackend:
def authenticate(self, request, uid):
token = Token.objects.get(uid=uid)
return User.objects.get(email=token.email)That gets one test passing but breaks another one:
$ python src/manage.py test accounts ERROR: test_returns_None_if_no_such_token (accounts.tests.test_authentication.A uthenticateTest.test_returns_None_if_no_such_token) [...] accounts.models.Token.DoesNotExist: Token matching query does not exist. ERROR: test_returns_new_user_with_correct_email_if_token_exists (accounts.tests .test_authentication.AuthenticateTest.test_returns_new_user_with_correct_email_ if_token_exists) [...] accounts.models.User.DoesNotExist: User matching query does not exist.
Let’s fix each of those in turn:
def authenticate(self, request, uid):
try:
token = Token.objects.get(uid=uid)
return User.objects.get(email=token.email)
except Token.DoesNotExist:
return NoneThat gets us down to one failure:
ERROR: test_returns_new_user_with_correct_email_if_token_exists (accounts.tests .test_authentication.AuthenticateTest.test_returns_new_user_with_correct_email_ if_token_exists) [...] accounts.models.User.DoesNotExist: User matching query does not exist. FAILED (errors=1)
And we can handle the final case like this:
def authenticate(self, request, uid):
try:
token = Token.objects.get(uid=uid)
return User.objects.get(email=token.email)
except User.DoesNotExist:
return User.objects.create(email=token.email)
except Token.DoesNotExist:
return NoneThat’s turned out neater than our spike!
We’ve handled the authenticate function which Django will use to log new users in.q
The second part of the protocol we have to implement is the get_user method,
whose job is to retrieve a user based on their unique identifier (the email address),
or to return None if it can’t find one
(have another look at the spiked code if you need a
reminder).
Here are a couple of tests for those two requirements:
class GetUserTest(TestCase):
def test_gets_user_by_email(self):
User.objects.create(email="another@example.com")
desired_user = User.objects.create(email="edith@example.com")
found_user = PasswordlessAuthenticationBackend().get_user("edith@example.com")
self.assertEqual(found_user, desired_user)
def test_returns_None_if_no_user_with_that_email(self):
self.assertIsNone(
PasswordlessAuthenticationBackend().get_user("edith@example.com")
)And our first failure:
AttributeError: 'PasswordlessAuthenticationBackend' object has no attribute 'get_user'
Let’s create a placeholder one then:
class PasswordlessAuthenticationBackend:
def authenticate(self, request, uid):
[...]
def get_user(self, email):
passNow we get:
self.assertEqual(found_user, desired_user) AssertionError: None != <User: User object (edith@example.com)>
And (step by step, just to see if our test fails the way we think it will):
def get_user(self, email):
return User.objects.first()That gets us past the first assertion, and onto:
self.assertEqual(found_user, desired_user) AssertionError: <User: User object (another@example.com)> != <User: User object (edith@example.com)>
And so we call get with the email as an argument:
def get_user(self, email):
return User.objects.get(email=email)Now our test for the None case fails:
ERROR: test_returns_None_if_no_user_with_that_email (accounts.tests.test_authen tication.GetUserTest.test_returns_None_if_no_user_with_that_email) [...] accounts.models.User.DoesNotExist: User matching query does not exist.
Which prompts us to finish the method like this:
def get_user(self, email):
try:
return User.objects.get(email=email)
except User.DoesNotExist:
return None # (1)-
You could just use
passhere, and the function would returnNoneby default. However, because we specifically need the function to returnNone, the "explicit is better than implicit" rule applies here.
That gets us to passing tests:
OK
And we have a working authentication backend!
The final step is to use the backend in our login view. First we add it to 'settings.py':
AUTH_USER_MODEL = "accounts.User"
AUTHENTICATION_BACKENDS = [
"accounts.authentication.PasswordlessAuthenticationBackend",
]
[...]Next let’s write some tests for what should happen in our view. Looking back at the spike again:
def login(request):
print("login view", file=sys.stderr)
uid = request.GET.get("uid")
user = auth.authenticate(uid=uid)
if user is not None:
auth.login(request, user)
return redirect("/")We need the view to call django.contrib.auth.authenticate, and then,
if it returns a user, we call django.contrib.auth.login.
|
Tip
|
This is a good time to check out the Django docs on authentication for a little more context. |
So far we’ve used mocks to test external dependencies, like Django’s mail-sending function. The main reason to use a mock was to isolate ourselves from external side effects, in this case, to avoid sending out actual emails during our tests.
In this section we’ll look at a different kind of use of mocks. Here we don’t have any side effects we’re worried about, but there are still some reasons you might want to use a mock here.
The nonmocky way of testing this login view would be to see whether it does actually log the user in, by checking whether the user gets assigned an authenticated session cookie in the right circumstances.
But our authentication backend does have a few different code paths:
it returns None for invalid tokens, existing users if they already exist,
and creates new users for valid tokens if they don’t exist yet. So, to fully
test this view, I’d have to write tests for all three of those cases.
|
Tip
|
One possible justification for using mocks is when they will reduce duplication between tests. It’s one way of avoiding combinatorial explosion. |
On top of that, the fact that we’re using the Django
auth.authenticate function rather than calling our own code directly is
relevant: it allows us the option to add further backends in future.
So in this case (in contrast to the example in Mocks Can Leave You Tightly Coupled to the Implementation) the implementation does matter, and using a mock will save us from having duplication in our tests. Let’s see how it looks:
@mock.patch("accounts.views.auth") # (1)
def test_calls_authenticate_with_uid_from_get_request(self, mock_auth): # (2)
self.client.get("/accounts/login?token=abcd123")
self.assertEqual(
mock_auth.authenticate.call_args, # (3)
mock.call(uid="abcd123"), # (4)
)-
We expect to be using the
django.contrib.authmodule in 'views.py', and we mock it out here. Note that this time, we’re not mocking out a function, we’re mocking out a whole module, and thus implicitly mocking out all the functions (and any other objects) that module contains. -
As usual, the mocked object is injected into our test method.
-
This time, we’ve mocked out a module rather than a function. So we examine the
call_argsnot of themock_authmodule, but of themock_auth.authenticatefunction. Because all the attributes of a mock are more mocks, that’s a mock too. You can start to see whyMockobjects are so convenient, compared to trying to build your own. -
Now, instead of "unpacking" the call args, we use the
callfunction for a neater way of saying what it should have been called with—that is, the token from the GET request. (See the following sidebar.)
The
call_args property on a mock represents the positional and keyword
arguments that the mock was called with. It’s a special "call" object type,
which is essentially a tuple of (positional_args, keyword_args).
positional_args is itself a tuple, consisting of the set of positional
arguments. keyword_args is a dictionary.
>>> from unittest.mock import Mock, call
>>> m = Mock()
>>> m(42, 43, 'positional arg 3', key='val', thing=666)
<Mock name='mock()' id='139909729163528'>
>>> m.call_args
call(42, 43, 'positional arg 3', key='val', thing=666)
>>> m.call_args == ((42, 43, 'positional arg 3'), {'key': 'val', 'thing': 666})
True
>>> m.call_args == call(42, 43, 'positional arg 3', key='val', thing=666)
TrueSo in our test, we could have done this instead:
self.assertEqual(
mock_auth.authenticate.call_args,
((,), {'uid': 'abcd123'})
)
# or this
args, kwargs = mock_auth.authenticate.call_args
self.assertEqual(args, (,))
self.assertEqual(kwargs, {'uid': 'abcd123'})But you can see how using the call helper is nicer.
What happens when we run the test? The first error is this:
$ python src/manage.py test accounts [...] AttributeError: <module 'accounts.views' from '...goat-book/src/accounts/views.py'> does not have the attribute 'auth'
|
Tip
|
module foo does not have the attribute bar
is a common first failure in a test that uses mocks.
It’s telling you that you’re trying to mock out something
that doesn’t yet exist (or isn’t yet imported)
in the target module.
|
Once we import django.contrib.auth, the error changes:
from django.contrib import auth, messages
[...]Now we get:
AssertionError: None != call(uid='abcd123')
Now it’s telling us that the view doesn’t call the auth.authenticate
function at all. Let’s fix that, but get it deliberately wrong, just to see:
def login(request):
auth.authenticate("bang!")
return redirect("/")Bang indeed!
$ python src/manage.py test accounts
[...]
AssertionError: call('bang!') != call(uid='abcd123')
[...]
FAILED (failures=1)
Let’s give authenticate the arguments it expects then:
def login(request):
auth.authenticate(uid=request.GET.get("token"))
return redirect("/")That gets us to passing tests:
$ python src/manage.py test accounts [...] Ran 15 tests in 0.041s OK
Next
we want to check that if the authenticate function returns a user,
we pass that into auth.login. Let’s see how that test looks:
@mock.patch("accounts.views.auth") # (1)
def test_calls_auth_login_with_user_if_there_is_one(self, mock_auth):
response = self.client.get("/accounts/login?token=abcd123")
self.assertEqual(
mock_auth.login.call_args, # (2)
mock.call(response.wsgi_request, mock_auth.authenticate.return_value), # (3)
)-
We mock the
contrib.authmodule again. -
This time we examine the call args for the
auth.loginfunction. -
We check that it’s called with the request object that the view sees, and the "user" object that the
authenticatefunction returns. Becauseauthenticateis also mocked out, we can use its special "return_value" attribute.
When you call a mock, you get another mock. But you can also get a copy of that returned mock from the original mock that you called. Boy, it sure is hard to explain this stuff without saying "mock" a lot! Another little console illustration might help here:
>>> m = Mock()
>>> thing = m()
>>> thing
<Mock name='mock()' id='140652722034952'>
>>> m.return_value
<Mock name='mock()' id='140652722034952'>
>>> thing == m.return_value
TrueIn any case, what do we get from running the test?
$ python src/manage.py test accounts [...] AssertionError: None != call(<WSGIRequest: GET '/accounts/login?t[...]
Sure enough, it’s telling us that we’re not calling auth.login at all yet.
Let’s try doing that. Deliberately wrong as usual first!
def login(request):
auth.authenticate(uid=request.GET.get("token"))
auth.login("ack!")
return redirect("/")Ack indeed!
TypeError: login() missing 1 required positional argument: 'user'
[...]
AssertionError: call('ack!') != call(<WSGIRequest: GET
'/accounts/login?token=[...]
Let’s fix that:
def login(request):
user = auth.authenticate(uid=request.GET.get("token"))
auth.login(request, user)
return redirect("/")Now we get this unexpected complaint:
ERROR: test_redirects_to_home_page (accounts.tests.test_views.LoginViewTest.test_redirects_to_home_page) [...] AttributeError: 'AnonymousUser' object has no attribute '_meta'
It’s because we’re still calling auth.login indiscriminately on any kind of user,
and that’s causing problems back in our original test for the redirect,
which isn’t currently mocking out auth.login.
We need to add an if (and therefore another test),
and while we’re at it we’ll learn about patching at the class level.
We want to add another test, with another @patch('accounts.views.auth'),
and that’s starting to get repetitive.
We use the "three strikes" rule,
and we can move the patch decorator to the class level.
This will have the effect of mocking out accounts.views.auth
in every single test method in that class.
That also means our original redirect test will now also
have the mock_auth variable injected:
@mock.patch("accounts.views.auth") # (1)
class LoginViewTest(TestCase):
def test_redirects_to_home_page(self, mock_auth): # (2)
[...]
def test_calls_authenticate_with_uid_from_get_request(self, mock_auth): # (3)
[...]
def test_calls_auth_login_with_user_if_there_is_one(self, mock_auth): # (3)
[...]
def test_does_not_login_if_user_is_not_authenticated(self, mock_auth):
mock_auth.authenticate.return_value = None # (4)
self.client.get("/accounts/login?token=abcd123")
self.assertEqual(mock_auth.login.called, False) # (5)-
We move the patch to the class level…
-
which means we get an extra argument injected into our first test method…
-
And we can remove the decorators from all the other tests.
-
In our new test, we explicitly set the
return_valueon theauth.authenticatemock, 'before' we call theself.client.get. -
We assert that, if
authenticatereturnsNone, we should not callauth.loginat all.
That cleans up the spurious failure, and gives us a specific, expected failure to work on:
self.assertEqual(mock_auth.login.called, False) AssertionError: True != False
And we get it passing like this:
def login(request):
user = auth.authenticate(uid=request.GET.get("token"))
if user:
auth.login(request, user)
return redirect("/")The unit tests pass…
OK
So are we there yet?
If you’ve used unittest.mock before, you may have come across its special
assert_called…
methods, and you may be wondering why I didn’t use them.
For example, instead of doing:
self.assertEqual(a_mock.call_args, call(foo, bar))You can just do:
a_mock.assert_called_with(foo, bar)And the mock library will raise an AssertionError for you if there is a
mismatch.
Why not use that? For me, the problem with these magic methods is that it’s too easy to make a silly typo and end up with a test that always passes:
a_mock.asssert_called_with(foo, bar) # will always passUnless you get the magic method name exactly right, then you will just get a "normal" mock method, which just silently return another mock, and you may not realise that you’ve written a test that tests nothing at all.
That’s why I prefer to always have an explicit unittest method in there.
I think we’re just about ready to try our functional test!
Let’s just make sure our base template shows a different nav bar for logged-in and non–logged-in users (which our FT relies on):
<nav class="navbar">
<div class="container-fluid">
<a class="navbar-brand" href="/">Superlists</a>
{% if user.email %}
<ul>
<span class="navbar-text">Logged in as {{ user.email }}</span>
<a href="#TODO">Log out</a>
</ul>
{% else %}
<form method="POST" action="{% url 'send_login_email' %}">
<div class="input-group">
<label class="navbar-text me-2" for="id_email_input">
Enter your email to log in
</label>
<input
id="id_email_input"
name="email"
class="form-control"
placeholder="your@email.com"
/>
{% csrf_token %}
</div>
</form>
{% endif %}
</div>
</nav>TODO resume updates to chapter from here
How does our FT look now?
$ python src/manage.py test functional_tests.test_login [...] . --------------------------------------------------------------------- Ran 1 test in 3.282s OK
Wow! Can you believe it? I scarcely can!
Time for a manual look around with runserver:
$ python src/manage.py runserver [...] Internal Server Error: /accounts/send_login_email Traceback (most recent call last): File "...goat-book/accounts/views.py", line 20, in send_login_email ConnectionRefusedError: [Errno 111] Connection refused
You’ll probably get an error, like I did, when you try to run things manually. It’s because of two things:
-
Firstly, we need to re-add the email configuration to settings.py.
EMAIL_HOST = "smtp.gmail.com"
EMAIL_HOST_USER = "obeythetestinggoat@gmail.com"
EMAIL_HOST_PASSWORD = os.environ.get("EMAIL_PASSWORD")
EMAIL_PORT = 587
EMAIL_USE_TLS = True-
Secondly, we (probably) need to re-set the
EMAIL_PASSWORDin our shell.
$ export EMAIL_PASSWORD="yoursekritpasswordhere"
Until now we’ve only used the .env file on the server, because all the other settings have sensible defaults for dev, but there’s just no way to get a working login system without this one.
Just as we do on the server, you can also use a .env file to save project-specific environment variables:
$ echo .env >> .gitignore # we don't want to commit our secrets into git! $ echo EMAIL_PASSWORD="yoursekritpasswordhere" >> .env $ set -a; source .env; set +a;
It does mean you have to remember to do that weird set -a; source… dance,
every time you start working on the project, as well as remembering to activate
your virtualenv.
If you search or ask around, you’ll find there are some tools and shell plugins that load virtualenvs and .env files automatically, and/or django plugins that do this stuff too.
-
Django-specific: django-environ or django-dotenv
-
More general Python project management Pipenv
-
Or even roll your own
And now…
$ python src/manage.py runserver
…you should see something like Check your email…..
Woohoo!
I’ve been waiting to do a commit up until this moment, just to make sure everything works. At this point, you could make a series of separate commits—one for the login view, one for the auth backend, one for the user model, one for wiring up the template. Or you could decide that, since they’re all interrelated, and none will work without the others, you may as well just have one big commit:
$ git status $ git add . $ git diff --staged $ git commit -m "Custom passwordless auth backend + custom user model"
The last thing we need to do before we call it a day is to test the logout link
(you may remember the URL just says #TODO at the moment.)
We extend the FT with a couple more steps:
[...]
# she is logged in!
self.wait_for(lambda: self.browser.find_element(By.LINK_TEXT, "Log out"))
navbar = self.browser.find_element(By.CSS_SELECTOR, ".navbar")
self.assertIn(TEST_EMAIL, navbar.text)
# Now she logs out
self.browser.find_element(By.LINK_TEXT, "Log out").click()
# She is logged out
self.wait_for(
lambda: self.browser.find_element(By.CSS_SELECTOR, "input[name=email]")
)
navbar = self.browser.find_element(By.CSS_SELECTOR, ".navbar")
self.assertNotIn(TEST_EMAIL, navbar.text)With that, we can see that the test is failing because the logout button doesn’t actually do anything:
$ python src/manage.py test functional_tests.test_login [...] selenium.common.exceptions.NoSuchElementException: Message: Unable to locate element: input[name=email]; [...]
So let’s tell the base template that we want a new url named "logout":
{% if user.email %}
<ul>
<span class="navbar-text">Logged in as {{ user.email }}</span>
<a href="{% url 'logout' %}">Log out</a>
</ul>
{% else %}If you try the FTs at this point, you’ll see an error saying that URL doesn’t exist yet:
$ python src/manage.py test functional_tests.test_login Internal Server Error: / [...] django.urls.exceptions.NoReverseMatch: Reverse for 'logout' not found. 'logout' is not a valid view function or pattern name. ====================================================================== ERROR: test_can_get_email_link_to_log_in (functional_tests.test_login.LoginTest.test_can_get_email_link_to_log_in) [...] selenium.common.exceptions.NoSuchElementException: Message: Unable to locate element: Log out; [...]
Implementing a logout URL is actually very simple: we can use Django’s built-in logout view, which clears down the user’s session and redirects them to a page of our choice:
from django.contrib.auth import views as auth_views
from django.urls import path
from . import views
urlpatterns = [
path("send_login_email", views.send_login_email, name="send_login_email"),
path("login", views.login, name="login"),
path("logout", auth_views.LogoutView.as_view(next_page="/"), name="logout"),
]And that gets us a fully passing FT—indeed, a fully passing test suite:
$ python src/manage.py test functional_tests.test_login [...] OK $ cd src && python manage.py test [...] Ran 56 tests in 78.124s OK
|
Warning
|
We’re nowhere near a truly secure or acceptable login system here. Since this is just an example app for a book, we’ll leave it at that, but in "real life" you’d want to explore a lot more security and usability issues before calling the job done. We’re dangerously close to "rolling our own crypto" here, and relying on a more established login system would be much safer. |
In the next chapter, we’ll start trying to put our login system to good use. In the meantime, do a commit and enjoy this recap:
mail.outbox for us, but, again, let’s pretend it doesn’t. What if you were using Flask? Or what if this was an API call, not an email?
pip install mock.