This tutorial begins where Tutorial 4 left off.\nWe’ve built a Web-poll application, and we’ll now create some automated tests\nfor it.
\nTests are simple routines that check the operation of your code.
\nTesting operates at different levels. Some tests might apply to a tiny detail\n(does a particular model method return values as expected?) while others\nexamine the overall operation of the software (does a sequence of user inputs\non the site produce the desired result?). That’s no different from the kind of\ntesting you did earlier in Tutorial 2, using the\nshell to examine the behavior of a method, or running the\napplication and entering data to check how it behaves.
What’s different in automated tests is that the testing work is done for\nyou by the system. You create a set of tests once, and then as you make changes\nto your app, you can check that your code still works as you originally\nintended, without having to perform time consuming manual testing.
\nSo why create tests, and why now?
\nYou may feel that you have quite enough on your plate just learning\nPython/Django, and having yet another thing to learn and do may seem\noverwhelming and perhaps unnecessary. After all, our polls application is\nworking quite happily now; going through the trouble of creating automated\ntests is not going to make it work any better. If creating the polls\napplication is the last bit of Django programming you will ever do, then true,\nyou don’t need to know how to create automated tests. But, if that’s not the\ncase, now is an excellent time to learn.
\nUp to a certain point, ‘checking that it seems to work’ will be a satisfactory\ntest. In a more sophisticated application, you might have dozens of complex\ninteractions between components.
\nA change in any of those components could have unexpected consequences on the\napplication’s behavior. Checking that it still ‘seems to work’ could mean\nrunning through your code’s functionality with twenty different variations of\nyour test data just to make sure you haven’t broken something - not a good use\nof your time.
\nThat’s especially true when automated tests could do this for you in seconds.\nIf something’s gone wrong, tests will also assist in identifying the code\nthat’s causing the unexpected behavior.
\nSometimes it may seem a chore to tear yourself away from your productive,\ncreative programming work to face the unglamorous and unexciting business\nof writing tests, particularly when you know your code is working properly.
\nHowever, the task of writing tests is a lot more fulfilling than spending hours\ntesting your application manually or trying to identify the cause of a\nnewly-introduced problem.
\nIt’s a mistake to think of tests merely as a negative aspect of development.
\nWithout tests, the purpose or intended behavior of an application might be\nrather opaque. Even when it’s your own code, you will sometimes find yourself\npoking around in it trying to find out what exactly it’s doing.
\nTests change that; they light up your code from the inside, and when something\ngoes wrong, they focus light on the part that has gone wrong - even if you\nhadn’t even realized it had gone wrong.
\nYou might have created a brilliant piece of software, but you will find that\nmany other developers will simply refuse to look at it because it lacks tests;\nwithout tests, they won’t trust it. Jacob Kaplan-Moss, one of Django’s\noriginal developers, says “Code without tests is broken by design.”
\nThat other developers want to see tests in your software before they take it\nseriously is yet another reason for you to start writing tests.
\nThe previous points are written from the point of view of a single developer\nmaintaining an application. Complex applications will be maintained by teams.\nTests guarantee that colleagues don’t inadvertently break your code (and that\nyou don’t break theirs without knowing). If you want to make a living as a\nDjango programmer, you must be good at writing tests!
\nThere are many ways to approach writing tests.
\nSome programmers follow a discipline called “test-driven development”; they\nactually write their tests before they write their code. This might seem\ncounter-intuitive, but in fact it’s similar to what most people will often do\nanyway: they describe a problem, then create some code to solve it. Test-driven\ndevelopment simply formalizes the problem in a Python test case.
\nMore often, a newcomer to testing will create some code and later decide that\nit should have some tests. Perhaps it would have been better to write some\ntests earlier, but it’s never too late to get started.
\nSometimes it’s difficult to figure out where to get started with writing tests.\nIf you have written several thousand lines of Python, choosing something to\ntest might not be easy. In such a case, it’s fruitful to write your first test\nthe next time you make a change, either when you add a new feature or fix a bug.
\nSo let’s do that right away.
\nFortunately, there’s a little bug in the polls application for us to fix\nright away: the Question.was_published_recently() method returns True if\nthe Question was published within the last day (which is correct) but also if\nthe Question’s pub_date field is in the future (which certainly isn’t).
To check if the bug really exists, using the Admin create a question whose date\nlies in the future and check the method using the shell:
>>> import datetime\n>>> from django.utils import timezone\n>>> from polls.models import Question\n>>> # create a Question instance with pub_date 30 days in the future\n>>> future_question = Question(pub_date=timezone.now() + datetime.timedelta(days=30))\n>>> # was it published recently?\n>>> future_question.was_published_recently()\nTrue\nSince things in the future are not ‘recent’, this is clearly wrong.
\nWhat we’ve just done in the shell to test for the problem is exactly\nwhat we can do in an automated test, so let’s turn that into an automated test.
A conventional place for an application’s tests is in the application’s\ntests.py file; the testing system will automatically find tests in any file\nwhose name begins with test.
Put the following in the tests.py file in the polls application:
polls/tests.pyimport datetime\n\nfrom django.test import TestCase\nfrom django.utils import timezone\n\nfrom .models import Question\n\n\nclass QuestionModelTests(TestCase):\n\n def test_was_published_recently_with_future_question(self):\n """\n was_published_recently() returns False for questions whose pub_date\n is in the future.\n """\n time = timezone.now() + datetime.timedelta(days=30)\n future_question = Question(pub_date=time)\n self.assertIs(future_question.was_published_recently(), False)\nWhat we have done here is created a django.test.TestCase subclass\nwith a method that creates a Question instance with a pub_date in the\nfuture. We then check the output of was_published_recently() - which\nought to be False.
In the terminal, we can run our test:
\n$ python manage.py test polls\nand you’ll see something like:
\nCreating test database for alias 'default'...\nSystem check identified no issues (0 silenced).\nF\n======================================================================\nFAIL: test_was_published_recently_with_future_question (polls.tests.QuestionModelTests)\n----------------------------------------------------------------------\nTraceback (most recent call last):\n File "/path/to/mysite/polls/tests.py", line 16, in test_was_published_recently_with_future_question\n self.assertIs(future_question.was_published_recently(), False)\nAssertionError: True is not False\n\n----------------------------------------------------------------------\nRan 1 test in 0.001s\n\nFAILED (failures=1)\nDestroying test database for alias 'default'...\nWhat happened is this:
\npython manage.py test polls looked for tests in the polls application
it found a subclass of the django.test.TestCase class
it created a special database for the purpose of testing
it looked for test methods - ones whose names begin with test
in test_was_published_recently_with_future_question it created a Question\ninstance whose pub_date field is 30 days in the future
… and using the assertIs() method, it discovered that its\nwas_published_recently() returns True, though we wanted it to return\nFalse
The test informs us which test failed and even the line on which the failure\noccurred.
\nWe already know what the problem is: Question.was_published_recently() should\nreturn False if its pub_date is in the future. Amend the method in\nmodels.py, so that it will only return True if the date is also in the\npast:
polls/models.pydef was_published_recently(self):\n now = timezone.now()\n return now - datetime.timedelta(days=1) <= self.pub_date <= now\nand run the test again:
\nCreating test database for alias 'default'...\nSystem check identified no issues (0 silenced).\n.\n----------------------------------------------------------------------\nRan 1 test in 0.001s\n\nOK\nDestroying test database for alias 'default'...\nAfter identifying a bug, we wrote a test that exposes it and corrected the bug\nin the code so our test passes.
\nMany other things might go wrong with our application in the future, but we can\nbe sure that we won’t inadvertently reintroduce this bug, because simply\nrunning the test will warn us immediately. We can consider this little portion\nof the application pinned down safely forever.
\nWhile we’re here, we can further pin down the was_published_recently()\nmethod; in fact, it would be positively embarrassing if in fixing one bug we had\nintroduced another.
Add two more test methods to the same class, to test the behavior of the method\nmore comprehensively:
\npolls/tests.pydef test_was_published_recently_with_old_question(self):\n """\n was_published_recently() returns False for questions whose pub_date\n is older than 1 day.\n """\n time = timezone.now() - datetime.timedelta(days=1, seconds=1)\n old_question = Question(pub_date=time)\n self.assertIs(old_question.was_published_recently(), False)\n\ndef test_was_published_recently_with_recent_question(self):\n """\n was_published_recently() returns True for questions whose pub_date\n is within the last day.\n """\n time = timezone.now() - datetime.timedelta(hours=23, minutes=59, seconds=59)\n recent_question = Question(pub_date=time)\n self.assertIs(recent_question.was_published_recently(), True)\nAnd now we have three tests that confirm that Question.was_published_recently()\nreturns sensible values for past, recent, and future questions.
Again, polls is a simple application, but however complex it grows in the\nfuture and whatever other code it interacts with, we now have some guarantee\nthat the method we have written tests for will behave in expected ways.
The polls application is fairly undiscriminating: it will publish any question,\nincluding ones whose pub_date field lies in the future. We should improve\nthis. Setting a pub_date in the future should mean that the Question is\npublished at that moment, but invisible until then.
When we fixed the bug above, we wrote the test first and then the code to fix\nit. In fact that was a simple example of test-driven development, but it\ndoesn’t really matter in which order we do the work.
\nIn our first test, we focused closely on the internal behavior of the code. For\nthis test, we want to check its behavior as it would be experienced by a user\nthrough a web browser.
\nBefore we try to fix anything, let’s have a look at the tools at our disposal.
\nDjango provides a test Client to simulate a user\ninteracting with the code at the view level. We can use it in tests.py\nor even in the shell.
We will start again with the shell, where we need to do a couple of\nthings that won’t be necessary in tests.py. The first is to set up the test\nenvironment in the shell:
>>> from django.test.utils import setup_test_environment\n>>> setup_test_environment()\nsetup_test_environment() installs a template renderer\nwhich will allow us to examine some additional attributes on responses such as\nresponse.context that otherwise wouldn’t be available. Note that this\nmethod does not setup a test database, so the following will be run against\nthe existing database and the output may differ slightly depending on what\nquestions you already created. You might get unexpected results if your\nTIME_ZONE in settings.py isn’t correct. If you don’t remember setting\nit earlier, check it before continuing.
Next we need to import the test client class (later in tests.py we will use\nthe django.test.TestCase class, which comes with its own client, so\nthis won’t be required):
>>> from django.test import Client\n>>> # create an instance of the client for our use\n>>> client = Client()\nWith that ready, we can ask the client to do some work for us:
\n>>> # get a response from '/'\n>>> response = client.get('/')\nNot Found: /\n>>> # we should expect a 404 from that address; if you instead see an\n>>> # "Invalid HTTP_HOST header" error and a 400 response, you probably\n>>> # omitted the setup_test_environment() call described earlier.\n>>> response.status_code\n404\n>>> # on the other hand we should expect to find something at '/polls/'\n>>> # we'll use 'reverse()' rather than a hardcoded URL\n>>> from django.urls import reverse\n>>> response = client.get(reverse('polls:index'))\n>>> response.status_code\n200\n>>> response.content\nb'\\n <ul>\\n \\n <li><a href="/polls/1/">What's up?</a></li>\\n \\n </ul>\\n\\n'\n>>> response.context['latest_question_list']\n<QuerySet [<Question: What's up?>]>\nThe list of polls shows polls that aren’t published yet (i.e. those that have a\npub_date in the future). Let’s fix that.
In Tutorial 4 we introduced a class-based view,\nbased on ListView:
polls/views.pyclass IndexView(generic.ListView):\n template_name = 'polls/index.html'\n context_object_name = 'latest_question_list'\n\n def get_queryset(self):\n """Return the last five published questions."""\n return Question.objects.order_by('-pub_date')[:5]\nWe need to amend the get_queryset() method and change it so that it also\nchecks the date by comparing it with timezone.now(). First we need to add\nan import:
polls/views.pyfrom django.utils import timezone\nand then we must amend the get_queryset method like so:
polls/views.pydef get_queryset(self):\n """\n Return the last five published questions (not including those set to be\n published in the future).\n """\n return Question.objects.filter(\n pub_date__lte=timezone.now()\n ).order_by('-pub_date')[:5]\nQuestion.objects.filter(pub_date__lte=timezone.now()) returns a queryset\ncontaining Questions whose pub_date is less than or equal to - that\nis, earlier than or equal to - timezone.now.
Now you can satisfy yourself that this behaves as expected by firing up the\nrunserver, loading the site in your browser, creating Questions with dates\nin the past and future, and checking that only those that have been published\nare listed. You don’t want to have to do that every single time you make any\nchange that might affect this - so let’s also create a test, based on our\nshell session above.
Add the following to polls/tests.py:
polls/tests.pyfrom django.urls import reverse\nand we’ll create a shortcut function to create questions as well as a new test\nclass:
\npolls/tests.pydef create_question(question_text, days):\n """\n Create a question with the given `question_text` and published the\n given number of `days` offset to now (negative for questions published\n in the past, positive for questions that have yet to be published).\n """\n time = timezone.now() + datetime.timedelta(days=days)\n return Question.objects.create(question_text=question_text, pub_date=time)\n\n\nclass QuestionIndexViewTests(TestCase):\n def test_no_questions(self):\n """\n If no questions exist, an appropriate message is displayed.\n """\n response = self.client.get(reverse('polls:index'))\n self.assertEqual(response.status_code, 200)\n self.assertContains(response, "No polls are available.")\n self.assertQuerysetEqual(response.context['latest_question_list'], [])\n\n def test_past_question(self):\n """\n Questions with a pub_date in the past are displayed on the\n index page.\n """\n create_question(question_text="Past question.", days=-30)\n response = self.client.get(reverse('polls:index'))\n self.assertQuerysetEqual(\n response.context['latest_question_list'],\n ['<Question: Past question.>']\n )\n\n def test_future_question(self):\n """\n Questions with a pub_date in the future aren't displayed on\n the index page.\n """\n create_question(question_text="Future question.", days=30)\n response = self.client.get(reverse('polls:index'))\n self.assertContains(response, "No polls are available.")\n self.assertQuerysetEqual(response.context['latest_question_list'], [])\n\n def test_future_question_and_past_question(self):\n """\n Even if both past and future questions exist, only past questions\n are displayed.\n """\n create_question(question_text="Past question.", days=-30)\n create_question(question_text="Future question.", days=30)\n response = self.client.get(reverse('polls:index'))\n self.assertQuerysetEqual(\n response.context['latest_question_list'],\n ['<Question: Past question.>']\n )\n\n def test_two_past_questions(self):\n """\n The questions index page may display multiple questions.\n """\n create_question(question_text="Past question 1.", days=-30)\n create_question(question_text="Past question 2.", days=-5)\n response = self.client.get(reverse('polls:index'))\n self.assertQuerysetEqual(\n response.context['latest_question_list'],\n ['<Question: Past question 2.>', '<Question: Past question 1.>']\n )\nLet’s look at some of these more closely.
\nFirst is a question shortcut function, create_question, to take some\nrepetition out of the process of creating questions.
test_no_questions doesn’t create any questions, but checks the message:\n“No polls are available.” and verifies the latest_question_list is empty.\nNote that the django.test.TestCase class provides some additional\nassertion methods. In these examples, we use\nassertContains() and\nassertQuerysetEqual().
In test_past_question, we create a question and verify that it appears in\nthe list.
In test_future_question, we create a question with a pub_date in the\nfuture. The database is reset for each test method, so the first question is no\nlonger there, and so again the index shouldn’t have any questions in it.
And so on. In effect, we are using the tests to tell a story of admin input\nand user experience on the site, and checking that at every state and for every\nnew change in the state of the system, the expected results are published.
\nDetailViewLink to this heading#What we have works well; however, even though future questions don’t appear in\nthe index, users can still reach them if they know or guess the right URL. So\nwe need to add a similar constraint to DetailView:
polls/views.pyclass DetailView(generic.DetailView):\n ...\n def get_queryset(self):\n """\n Excludes any questions that aren't published yet.\n """\n return Question.objects.filter(pub_date__lte=timezone.now())\nAnd of course, we will add some tests, to check that a Question whose\npub_date is in the past can be displayed, and that one with a pub_date\nin the future is not:
polls/tests.pyclass QuestionDetailViewTests(TestCase):\n def test_future_question(self):\n """\n The detail view of a question with a pub_date in the future\n returns a 404 not found.\n """\n future_question = create_question(question_text='Future question.', days=5)\n url = reverse('polls:detail', args=(future_question.id,))\n response = self.client.get(url)\n self.assertEqual(response.status_code, 404)\n\n def test_past_question(self):\n """\n The detail view of a question with a pub_date in the past\n displays the question's text.\n """\n past_question = create_question(question_text='Past Question.', days=-5)\n url = reverse('polls:detail', args=(past_question.id,))\n response = self.client.get(url)\n self.assertContains(response, past_question.question_text)\nWe ought to add a similar get_queryset method to ResultsView and\ncreate a new test class for that view. It’ll be very similar to what we have\njust created; in fact there will be a lot of repetition.
We could also improve our application in other ways, adding tests along the\nway. For example, it’s silly that Questions can be published on the site\nthat have no Choices. So, our views could check for this, and exclude such\nQuestions. Our tests would create a Question without Choices and\nthen test that it’s not published, as well as create a similar Question\nwith Choices, and test that it is published.
Perhaps logged-in admin users should be allowed to see unpublished\nQuestions, but not ordinary visitors. Again: whatever needs to be added to\nthe software to accomplish this should be accompanied by a test, whether you\nwrite the test first and then make the code pass the test, or work out the\nlogic in your code first and then write a test to prove it.
At a certain point you are bound to look at your tests and wonder whether your\ncode is suffering from test bloat, which brings us to:
\nIt might seem that our tests are growing out of control. At this rate there will\nsoon be more code in our tests than in our application, and the repetition\nis unaesthetic, compared to the elegant conciseness of the rest of our code.
\nIt doesn’t matter. Let them grow. For the most part, you can write a test\nonce and then forget about it. It will continue performing its useful function\nas you continue to develop your program.
\nSometimes tests will need to be updated. Suppose that we amend our views so that\nonly Questions with Choices are published. In that case, many of our\nexisting tests will fail - telling us exactly which tests need to be amended to\nbring them up to date, so to that extent tests help look after themselves.
At worst, as you continue developing, you might find that you have some tests\nthat are now redundant. Even that’s not a problem; in testing redundancy is\na good thing.
\nAs long as your tests are sensibly arranged, they won’t become unmanageable.\nGood rules-of-thumb include having:
\na separate TestClass for each model or view
a separate test method for each set of conditions you want to test
test method names that describe their function
This tutorial only introduces some of the basics of testing. There’s a great\ndeal more you can do, and a number of very useful tools at your disposal to\nachieve some very clever things.
\nFor example, while our tests here have covered some of the internal logic of a\nmodel and the way our views publish information, you can use an “in-browser”\nframework such as Selenium to test the way your HTML actually renders in a\nbrowser. These tools allow you to check not just the behavior of your Django\ncode, but also, for example, of your JavaScript. It’s quite something to see\nthe tests launch a browser, and start interacting with your site, as if a human\nbeing were driving it! Django includes LiveServerTestCase\nto facilitate integration with tools like Selenium.
If you have a complex application, you may want to run tests automatically\nwith every commit for the purposes of continuous integration, so that\nquality control is itself - at least partially - automated.
\nA good way to spot untested parts of your application is to check code\ncoverage. This also helps identify fragile or even dead code. If you can’t test\na piece of code, it usually means that code should be refactored or removed.\nCoverage will help to identify dead code. See\nIntegration with coverage.py for details.
\nTesting in Django has comprehensive\ninformation about testing.
\nFor full details on testing, see Testing in Django.
\nWhen you’re comfortable with testing Django views, read\npart 6 of this tutorial to learn about\nstatic files management.
\n