Test Driven Development (TDD) is an iterative development cycle that emphasizes writing automated tests before writing the actual code.

The process is simple:

1. Write your tests first.

2. Watch them fail.

3. Write just enough code to make those tests pass.

4. Test again.

5. Refactor.

6. Repeat.

Contents

This is a long post, so here's a TOC for your convenience:

1. Why TDD

2. First Test

3. Setup Django

4. Functional Tests

• Admin Login

• Setup the Contacts App

5. Unit Tests

• Main View

• All Contacts View

• Add Contact View

• Views

• Validation

• Create Contact

6. Functional Tests Redux

7. Test Structure

8. Conclusion

Why TDD?

With TDD, you'll learn to break code up into logical, easily understandable pieces, helping ensure the correctness of code.

This is important because it's hard to-

1. Solve complex problems all at once in our heads;

2. Know when and where to start working on a problem;

3. Increase the complexity of a codebase without introducing errors and bugs; and

4. Recognize when code breaks occur.

TDD helps address these issues. It in no way guarantees that your code will be error free; however, you will write better code, which results in a better understanding of the code. This in itself will help with eliminating errors and at the very least, you will be able to address errors much easier.

TDD is practically an industry standard as well.

Enough talk. Let's get to the code.

For this tutorial, we'll be creating an app to store user contacts.

Please note: This tutorial assumes you are running a Unix-based environment - e.g, Mac OSX, straight Linux, or Linux VM through Windows. I will also be using Sublime 2 as my text editor. Also, make sure you you've completed the official Django tutorial and have a basic understanding of the Python language. Also, in this first post, we will not yet get into some of the new tools available in Django 1.6. This post sets the foundation for subsequent posts that deal with different forms of testing.

First Test

Before we do anything we need to first setup a test. For this test we just want to make that Django is properly setup. We're going to be using a functional test for this - which we'll be explained further down.

1. Create a new directory to hold your project:

   $ mkdir django-tdd
   $ cd django-tdd

2. Now setup a new directory to hold your functional tests:

   $ mkdir ft
   $ cd ft

3. Create a new file called "tests.py" and add the following code:

   from selenium import webdriver
   
   browser = webdriver.Firefox()browser.get('http://localhost:8000/')body = browser.find_element_by_tag_name('body')assert 'Django' in body.text
   
   browser.quit()

4. Now run the test:

   $ python tests.py

   Make sure you have selenium installed - pip install selenium

   You should see FireFox pop up and attempt to navigate to http://localhost:8000/. In your terminal you should see:

   Traceback (most recent call last):File "tests.py", line 7, in <module>assert 'Django' in body.textAssertionError

   Congrats! You wrote your first failing test.

   Now let's write just enough code to make it pass, which simply amounts to setting up a Django development environment.

Setup Django

1. Activate a virtualenv:

   $ cd ..$ virtualenv --no-site-packages env
   $ source env/bin/activate

2. Install Django and setup a Project:

   $ pip install django==1.6.1$ django-admin.py startproject contacts

   Your current project structure should look like this:

   ├── contacts│   ├── contacts│   │   ├── __init__.py│   │   ├── settings.py│   │   ├── urls.py│   │   └── wsgi.py│   └── manage.py└── ft    └── tests.py

3. Install Selenium:

   pip install selenium==2.39.0

4. Run the server:

   $ cd contacts
   $ python manage.py runserver

5. Next, open up a new window in your terminal, navigate to the "ft" directory, then run the test again:

   $ python tests.py

   You should see the FireFox window navigate to http://localhost:8000/ again. This time there should be no errors. Nice. You just passed your first test!

   Now, let's finish setting up our dev environment.

6. Version Control

   First, add a ".gitignore" and include the following code in the file:

   .Pythonenv
   bin
   lib
   include.DS_Store.pyc

   Now create a Git repository and commit:

   $ git init
   $ git add .$ git commit -am "initial"

7. With the project setup, let's take a step back and discuss functional tests.

Functional Tests

We approached the first test through Selenium via Functional tests. Such tests let us drive the web browser as if we were the end user, to see how the application actually functions. Since these tests follow the behavior of the end user - also called a User Story - it involves the testing of a number of features, rather than just a single function - which is more appropriate for Unit tests. It's important to note that when testing code you have not written, you should begin with functional tests. Since we are essentially testing Django code, functional tests are the right way to go.

Another way to think about functional vs unit tests is that Functional tests focus on testing the app from the outside, from the user's perspective, while unit tests focus on the app from the inside, from the developer's perspective.

This will make much more sense in practice.

Before moving on, let's restructure our testing environment to make testing easier.

1. First, let's re-write the first test in the "tests.py" file:

   from selenium import webdriverfrom selenium.webdriver.common.keys import Keysfrom django.test import LiveServerTestCaseclass AdminTest(LiveServerTestCase):
   
     def setUp(self):
         self.browser = webdriver.Firefox()
   
     def tearDown(self):
         self.browser.quit()
   
     def test_admin_site(self):    
         # user opens web browser, navigates to admin page
         self.browser.get(self.live_server_url + '/admin/')
         body = self.browser.find_element_by_tag_name('body')
         self.assertIn('Django administration', body.text)

2. Then run it:

   $ python manage.py test ft

   It should pass:

   ----------------------------------------------------------------------Ran 1 test in 3.304sOK

   Congrats!

   Before moving on, let's see what's going on here. If all went well it should pass. You should also see FireFox open and go through the process we indicated in the test with the setUp() and tearDown() functions. The test itself is simply testing whether the "/admin" (self.browser.get(self.live_server_url + '/admin/') page can be found and that the words "Django administration" are present in the body tag.

   Let's confirm this.

3. Run the server:

   $ python manage.py runserver

   Then navigate to http://localhost:8000/admin/ in your browser and you should see:

   

4. We can confirm that the test is working correctly by simply testing for the wrong thing. Update the last line in the test to:

   self.assertIn('administration Django', body.text)

   Run it again. You should see the following error (which is expected, of course):

   AssertionError: 'administration Django' not found in u'Django administration\nUsername:\nPassword:\n '

   Correct the test. Test it again. Commit the code.

   Finally, did you notice that we started the function name for the actual test began with test_. This is so that the Django test runner can find the test. In other words, any function that begins with test_ will be treated as a test by the test runner.

Admin Login

Next, let's test to make sure the user can login to the admin site.

1. Update test_admin_site the function in "tests.py":

   def test_admin_site(self):    
     # user opens web browser, navigates to admin page
     self.browser.get(self.live_server_url + '/admin/')
     body = self.browser.find_element_by_tag_name('body')
     self.assertIn('Django administration', body.text)
     # users types in username and passwords and presses enter
     username_field = self.browser.find_element_by_name('username')
     username_field.send_keys('admin')
     password_field = self.browser.find_element_by_name('password')
     password_field.send_keys('admin')
     password_field.send_keys(Keys.RETURN)
     # login credentials are correct, and the user is redirected to the main admin page
     body = self.browser.find_element_by_tag_name('body')
     self.assertIn('Site administration', body.text)

   So -

• find_element_by_name - is used for locating the input fields

• send_keys - sends keystrokes

1. Run the test. You should see this error:

   AssertionError: 'Site administration' not found in u'Django administration\nPlease enter the correct username and password for a staff account. Note that both fields may be case-sensitive.\nUsername:\nPassword:\n '

   This failed because we don't have an admin user setup. This is an expected failure, which is good. In other words, we knew it would fail - which makes it much easier to fix.

2. Sync the database:

   $ python manage.py syncdb

   Setup an admin user.

   Test again. It should fail again. Why? Django creates a copy of our database when tests are ran so that way tests do not affect the production database.

3. We need to setup a Fixture, which is a file containing data we want loaded into the test database: the login credentials. To do that, run these commands to dump the admin user info from the database to the Fixture:

   $ mkdir ft/fixtures
   $ python manage.py dumpdata auth.User --indent=2 > ft/fixtures/admin.json

   Now update the AdminTest class:

   class AdminTest(LiveServerTestCase):
   
       # load fixtures
     fixtures = ['admin.json']
   
     def setUp(self):
         self.browser = webdriver.Firefox()
   
     def tearDown(self):
         self.browser.quit()
   
     def test_admin_site(self):    
         # user opens web browser, navigates to admin page
         self.browser.get(self.live_server_url + '/admin/')
         body = self.browser.find_element_by_tag_name('body')
         self.assertIn('Django administration', body.text)
         # users types in username and passwords and presses enter
         username_field = self.browser.find_element_by_name('username')
         username_field.send_keys('admin')
         password_field = self.browser.find_element_by_name('password')
         password_field.send_keys('admin')
         password_field.send_keys(Keys.RETURN)
         # login credentials are correct, and the user is redirected to the main admin page
         body = self.browser.find_element_by_tag_name('body')
         self.assertIn('Site administration', body.text)

   Run the test. It should pass.

   Each time a test is ran, Django dumps the test database. Then all the Fixtures specified in the "test.py" file are loaded into the database.

4. Let's add one more assert. Update the test again:

   def test_admin_site(self):    
       # user opens web browser, navigates to admin page
       self.browser.get(self.live_server_url + '/admin/')
       body = self.browser.find_element_by_tag_name('body')
       self.assertIn('Django administration', body.text)
       # users types in username and passwords and presses enter
       username_field = self.browser.find_element_by_name('username')
       username_field.send_keys('admin')
       password_field = self.browser.find_element_by_name('password')
       password_field.send_keys('admin')
       password_field.send_keys(Keys.RETURN)
       # login credentials are correct, and the user is redirected to the main admin page
       body = self.browser.find_element_by_tag_name('body')
       self.assertIn('Site administration', body.text)
       # user clicks on the Users link
       user_link = self.browser.find_elements_by_link_text('Users')
       user_link[0].click()
       # user verifies that user live@forever.com is present
       body = self.browser.find_element_by_tag_name('body')
       self.assertIn('live@forever.com', body.text)

5. Run it. It should fail, because we need to and another user to the fixture file:

   [{"pk": 1, "model": "auth.user", "fields": {
     "username": "admin", 
     "first_name": "", 
     "last_name": "", 
     "is_active": true, 
     "is_superuser": true, 
     "is_staff": true, 
     "last_login": "2013-12-29T03:49:13.545Z", 
     "groups": [], 
     "user_permissions": [], 
     "password": "pbkdf2_sha256$12000$VtsgwjQ1BZ6u$zwnG+5E5cl8zOnghahArLHiMC6wGk06HXrlAijFFpSA=", 
     "email": "ad@min.com", 
     "date_joined": "2013-12-29T03:49:13.545Z"}},{"pk": 2, "model": "auth.user", "fields": {
     "username": "live", 
     "first_name": "", 
     "last_name": "", 
     "is_active": true, 
     "is_superuser": false, 
     "is_staff": false, 
     "last_login": "2013-12-29T03:49:13.545Z", 
     "groups": [], 
     "user_permissions": [], 
     "password": "pbkdf2_sha256$12000$VtsgwjQ1BZ6u$zwnG+5E5cl8zOnghahArLHiMC6wGk06HXrlAijFFpSA=", 
     "email": "live@forever.com", 
     "date_joined": "2013-12-29T03:49:13.545Z"}}]

Run it again. Make sure it passes. Refactor the test if needed. Now think about what else you could test. Perhaps you could test to make sure the admin user can add a user in the Admin panel. Or perhaps a test to ensure that someone without admin access cannot access the Admin panel. Write a few more tests. Update your code. Test again. Refactor if necessary.

Next, we're going to add the app for adding contacts. Don't forget to commit!

Setup the Contacts App

1. Start with a test. Add the following function:

   def test_create_contact_admin(self):    
     self.browser.get(self.live_server_url + '/admin/')
     username_field = self.browser.find_element_by_name('username')
     username_field.send_keys('admin')
     password_field = self.browser.find_element_by_name('password')
     password_field.send_keys('admin')
     password_field.send_keys(Keys.RETURN)
     # user verifies that user_contacts is present
     body = self.browser.find_element_by_tag_name('body')
     self.assertIn('User_Contacts', body.text)

2. Run the test suite again. You should see the following error-

   AssertionError: 'User_Contacts' not found in u'Django administration\nWelcome, admin. Change password / Log out\nSite administration\nAuth\nGroups\nAdd\nChange\nUsers\nAdd\nChange\nRecent Actions\nMy Actions\nNone available'

   -which is expected.

   Now, write just enough code for this to pass.

3. Create the App:

   $ python manage.py startapp user_contacts

4. Add it to the "settings.py" file:

   INSTALLED_APPS = (
     'django.contrib.admin',
     'django.contrib.auth',
     'django.contrib.contenttypes',
     'django.contrib.sessions',
     'django.contrib.messages',
     'django.contrib.staticfiles',
     'ft',
     'user_contacts',)

5. Within the "admin.py" file in the user_contacts directory add the following code:

   from user_contacts.models import Person, Phonefrom django.contrib import admin
   
   admin.site.register(Person)admin.site.register(Phone)

6. Your project structure should now look like this:

   .├── user_contacts│   ├── __init__.py│   ├── admin.py   
   │   ├── models.py│   ├── tests.py│   └── views.py├── contacts│   ├── __init__.py│   ├── settings.py│   ├── urls.py│   └── wsgi.py├── ft│   ├── __init__.py│   ├── fixtures│   │   └── admin.json│   └── tests.py└── manage.py

7. Update "models.py":

   from django.db import modelsclass Person(models.Model):
     first_name = models.CharField(max_length = 30)
     last_name = models.CharField(max_length = 30)
     email = models.EmailField(null = True, blank = True)
     address = models.TextField(null = True, blank = True)
     city = models.CharField(max_length = 15, null = True,blank = True)
     state = models.CharField(max_length = 15, null = True, blank = True)
     country = models.CharField(max_length = 15, null = True, blank = True)
   
     def __unicode__(self):
         return self.last_name +", "+ self.first_nameclass Phone(models.Model):
     person = models.ForeignKey('Person')
     number = models.CharField(max_length=10)
   
     def __unicode__(self):
         return self.number

8. Run the test again now. You should now see:

   Ran 2 tests in 11.730sOK

9. Let's go ahead and add to the test to make sure the admin can add data:

   # user clicks on the Persons linkpersons_links = self.browser.find_elements_by_link_text('Persons')persons_links[0].click()# user clicks on the Add person linkadd_person_link = self.browser.find_element_by_link_text('Add person')add_person_link.click()# user fills out the formself.browser.find_element_by_name('first_name').send_keys("Michael")self.browser.find_element_by_name('last_name').send_keys("Herman")self.browser.find_element_by_name('email').send_keys("michael@realpython.com")self.browser.find_element_by_name('address').send_keys("2227 Lexington Ave")self.browser.find_element_by_name('city').send_keys("San Francisco")self.browser.find_element_by_name('state').send_keys("CA")self.browser.find_element_by_name('country').send_keys("United States")# user clicks the save buttonself.browser.find_element_by_css_selector("input[value='Save']").click()# the Person has been addedbody = self.browser.find_element_by_tag_name('body')self.assertIn('Herman, Michael', body.text)# user returns to the main admin screenhome_link = self.browser.find_element_by_link_text('Home')home_link.click()# user clicks on the Phones linkpersons_links = self.browser.find_elements_by_link_text('Phones')persons_links[0].click()# user clicks on the Add phone linkadd_person_link = self.browser.find_element_by_link_text('Add phone')add_person_link.click()# user finds the person in the dropdownel = self.browser.find_element_by_name("person")for option in el.find_elements_by_tag_name('option'):
     if option.text == 'Herman, Michael':
         option.click()# user adds the phone numbersself.browser.find_element_by_name('number').send_keys("4158888888")# user clicks the save buttonself.browser.find_element_by_css_selector("input[value='Save']").click()# the Phone has been addedbody = self.browser.find_element_by_tag_name('body')self.assertIn('4158888888', body.text)# user logs outself.browser.find_element_by_link_text('Log out').click()body = self.browser.find_element_by_tag_name('body')self.assertIn('Thanks for spending some quality time with the Web site today.', body.text)

That's it for the admin functionality. Let's switch gears and focus on the application, user_contacts, itself. Did you forget to commit? If so, do it now.

Unit Tests

Think about the features we have written thus far. We've just defined our model and allowed admins to alter the model. Based on that, and the overall goal of our Project, focus on the remaining user functionalities.

Users should be able to-

1. View all contacts.

2. Add new contacts.

Try to formulate the remaining Functional test(s) based on those requirements. Before we write the functional tests, though, we should define the behavior of the code through unit tests - which will help you write good, clean code, making it easier to write the Functional tests.

Remember: Functional tests are the ultimate indicator of whether your Project works or not, while Unit tests are the means to help you reach that end. This will all make sense soon.

Let's pause for a minute and talk about some conventions.

Although the basics of TDD (or ends) - test, code, refactor - are universal, many developers approach the means differently. For example, I like to write my unit tests first, to ensure that my code works at a granular level, then write the functional tests. Others write functional tests first, watch them fail, then write unit tests, watch them fail, then write code to first satisfy the unit tests, which should ultimately satisfy the functional tests. There's no right or wrong answer here. Do what feels most comfortable - but continue to test first, then write code, and finally refactor.

Views

First, check to make sure all the views are setup correctly.

Main View

1. As always, start with a test:

   from django.template.loader import render_to_stringfrom django.test import TestCase, Clientfrom user_contacts.models import Person, Phonefrom user_contacts.views import *class ViewTest(TestCase):def setUp(self):
       self.client_stub = Client()def test_view_home_route(self):
       response = self.client_stub.get('/')
       self.assertEquals(response.status_code, 200)

2. Name this test test_views.py and save it in the user_contacts/tests directory. Also add an __init__.py file to the directory and delete the "tests.py" file in the main user_contacts directory.

3. Run it:

   $ python manage.py test user_contacts

   It should fail - AssertionError: 404 != 200 - because the URL, View, and the Template do not exist. If you're unfamiliar with how Django handles the MVC architecture, please read the short article here.

   The test is simple. We first GET the url "/" using the Client, which is part of Django’s TestCase. The response is stored, then we check to make sure the returned status code is equal to 200.

4. Add the following route to "contacts/urls.py":

   url(r'^', include('user_contacts.urls')),

5. Update "user_contacts/urls.py":

   from django.conf.urls import patterns, urlfrom user_contacts.views import *urlpatterns = patterns('',
       url(r'^$', home),)

6. Update "views.py":

   from django.http import HttpResponse, HttpResponseRedirectfrom django.shortcuts import render_to_response, renderfrom django.template import RequestContextfrom user_contacts.models import Phone, Person# from user_contacts.new_contact_form import ContactFormdef home(request):
     return render_to_response('index.html')

7. Add an "index.html" template to the templates directory:

   <!DOCTYPE html><html>
     <head>
       <title>Welcome.</title>
       <meta name="viewport" content="width=device-width, initial-scale=1.0">
       <link href="http://netdna.bootstrapcdn.com/bootstrap/3.0.0/css/bootstrap.min.css" rel="stylesheet" media="screen">
       <style>
           .container {
               padding: 50px;
           }
       </style>
     </head>
     <body>
       <div class="container">
           <h1>What would you like to do?</h1>
           <ul>
               <li><a href="/all">View Contacts</a></li>
               <li><a href="/add">Add Contact</a></li>
           </ul>
       <div>
       <script src="http://code.jquery.com/jquery-1.10.2.min.js"></script>
       <script src="http://netdna.bootstrapcdn.com/bootstrap/3.0.0/js/bootstrap.min.js"></script>
     </body></html>

8. Run the test again. It should pass just fine.

All Contacts View

The test for this view is nearly identical to our last test. Try it on your own before looking at my answer.

1. Write the test first by adding the following function to the ViewTest class:

   def test_view_contacts_route(self):
     response = self.client_stub.get('/all/')
     self.assertEquals(response.status_code, 200)

2. When ran, you should see the same error: AssertionError: 404 != 200.

3. Update "user_contacts/urls.py" with the following route:

   url(r'^all/$', all_contacts),

4. Update "views.py":

   def all_contacts(request):
     contacts = Phone.objects.all()
     return render_to_response('all.html', {'contacts':contacts})

5. Add an "all.html" template to the templates directory:

   <!DOCTYPE html><html><head><title>All Contacts.</title><meta name="viewport" content="width=device-width, initial-scale=1.0"><link href="http://netdna.bootstrapcdn.com/bootstrap/3.0.0/css/bootstrap.min.css" rel="stylesheet" media="screen"><style>
     .container {
       padding: 50px;
     }</style></head><body><div class="container">
     <h1>All Contacts</h1>
     <table border="1" cellpadding="5">
       <tr>
         <th>First Name</th>
         <th>Last Name</th>
         <th>Address</th>
         <th>City</th>
         <th>State</th>
         <th>Country</th>
         <th>Phone Number</th>
         <th>Email</th>
       </tr>
       {% for contact in contacts %}      <tr>
           <td></td>
           <td></td>
           <td></td>
           <td></td>
           <td></td>
           <td></td>
           <td></td>
           <td></td>
         </tr>
       {% endfor %}  </table>
     <br>
     <a href="/">Return Home</a></div><script src="http://code.jquery.com/jquery-1.10.2.min.js"></script><script src="http://netdna.bootstrapcdn.com/bootstrap/3.0.0/js/bootstrap.min.js"></script></body></html>

6. This should pass as well.

Add Contact View

This test is slightly different from the previous two, so please follow along closely.

1. Add the test to the test suite:

   def test_add_contact_route(self):
     response = self.client_stub.get('/add/')
     self.assertEqual(response.status_code, 200)

2. You should see this error when ran: AssertionError: 404 != 200

3. Update "urls.py":

   url(r'^add/$', add),

4. Update "views.py":

   def add(request):person_form = ContactForm()return render(request, 'add.html', {'person_form' : person_form}, context_instance = RequestContext(request))

   Make sure to add the following import:

   from user_contacts.new_contact_form import ContactForm

5. Create a new file called new_contact_form.py and add the following code:

   import refrom django import formsfrom django.core.exceptions import ValidationErrorfrom user_contacts.models import Person, Phoneclass ContactForm(forms.Form):
     first_name = forms.CharField(max_length=30)
     last_name = forms.CharField(max_length=30)
     email = forms.EmailField(required=False)
     address = forms.CharField(widget=forms.Textarea, required=False)
     city = forms.CharField(required=False)
     state = forms.CharField(required=False)
     country = forms.CharField(required=False)
     number = forms.CharField(max_length=10)
   
     def save(self):
         if self.is_valid():
             data = self.cleaned_data
             person = Person.objects.create(first_name=data.get('first_name'), last_name=data.get('last_name'),
                 email=data.get('email'), address=data.get('address'), city=data.get('city'), state=data.get('state'),
                 country=data.get('country'))
             phone = Phone.objects.create(person=person, number=data.get('number'))
             return phone

6. Add "add.html" to the templates directory:

   <!DOCTYPE html><html><head><title>Welcome.</title><meta name="viewport" content="width=device-width, initial-scale=1.0"><link href="http://netdna.bootstrapcdn.com/bootstrap/3.0.0/css/bootstrap.min.css" rel="stylesheet" media="screen"><style>
       .container {
           padding: 50px;
       }</style></head><body>
     <div class="container">
       <h1>Add Contact</h1>
       <br>
       <form action="/create" method ="POST" role="form">
         {% csrf_token %}      <input type ="submit" name ="Submit" class="btn btn-default" value ="Add">
       </form>
       <br>
       <a href="/">Return Home</a>
     </div><script src="http://code.jquery.com/jquery-1.10.2.min.js"></script><script src="http://netdna.bootstrapcdn.com/bootstrap/3.0.0/js/bootstrap.min.js"></script></body></html>

7. Does it pass? It should. If not, refactor.