sandiegopython / test-driven-django-development

This repository contains materials for a San Diego Python workshop on learning Django with test inspired development

Test-Driven Django Development

This repository contains code and tutorials used to lead a Test-driven Django workshop. These were developed by San Diego Python and used for a full day event where anyone interested can come and learn Django.

The code is not meant as a replacement for the (excellent) Django tutorials but rather intended to provide additional insight and knowledge. It is best if users go through the tutorials and understand the absolute basics of Django before the workshop.

Tutorials

The latest version of the tutorials is available at http://test-driven-django-development.readthedocs.org

Building

The tutorials are built using Sphinx:

cd tutorials
make html

Contribute

Contributions to these materials are welcome. Please send us a pull request with your changes. If you want to discuss changes before submitting them, feel free to join us on IRC at #sandiegopython on freenode.

License

This material is provided under a Creative Commons (CC BY-SA 3.0) license. Please see the LICENSE file for details.

test-driven-django-development's Issues

First blog post in admin should be titled "Entry Object" in screenshot

The screenshot stating The entry "First Entry" was added successfully. on this page is wrong.

The entry should be titled "Entry Object" until the __unicode__ model method is created.

Make it clear that the Meta inner class is an inner class

Test virtualenv on Windows

For user friendly, have a windows savvy person test and make recommendations

Change 'name' to 'title'

Suggestion: change the wording in the following:
"In the admin change list our entries all have the unhelpful name Entry object."

to:

"In the admin change list our entries all have the unhelpful title Entry object."

First entry screen capture should display Entry Object

Screen capture should show Entry Object until after the First Test is added.

http://test-driven-django-development.readthedocs.org/en/latest/02-models.html

Rename "Post" model to "Entry"

There's some confusion between our "Post" model and HTTP POST.

Add related resources links

For example http://www.tdd-django-tutorial.com/

Explain "Site" table that appears in the admin interface?

In / tutorials / 02-models.rst
paragraph: Creating entries from the admin site

A "Site" table is visible in the screnshot below. Should we explain what it is and how it appeared there ?

First click the "Add" link next to Entries in the admin site.
https://github.com/pythonsd/test-driven-django-development/blob/master/tutorials/_static/02-01_add_entry.png

Comments on tutorial: 02-models.rst

Comments on tutorial: 02-models.rst

At the transition from previous paragraph to this one:
Our first test: __ unicode __ method
In the admin change list our entries all have the unhelpful name Entry object.

• Create more than just one entries so we can actually see that " all entries have... "

In following paragraph:
Tip
There are lots of resources on unit testing but a great place to start is the official Python documentation on the unittest module and the Testing Django applications docs.

• Both links start with importing this module: import unittest
• In our test.py we import this moduel : import TestCase
• So what is the connection between these modules and the package that were installed at the beginning webtest and Django-webtest ?
• What is included in what ? what are we already using / not using yet ?

Since students might have different versions of python (we said: For this workshop you should have a 2.6.x or 2.7.x version of Python) the unittest module might be different for 2.6 users and 2.7 users.

• Is that an issue?
• Instead should everybody do: import unittest2 ?

In following paragraph:
Hint
__ unicode __ may seem like a strange name, but Unicode is a standard for representing and encoding most of the world's writing systems. All strings that Django passes around are Unicode strings so that Django can be used for applications designed for different languages.

• What sound strange to me is not the unicode name but the underscore underscore before and after the unicode name. The test is written with this function call unicode(entry) and not __ unicode __(entry). Should an explanation be given about this here ?
• Also this paragraph may benefit from being placed either at the very beginning of the "Our first test: __ unicode __ method" paragraph when __ unicode __ is mention for the first time, or further below when the method is emplemented:
  Let's add a __ unicode __ method to our model that returns the entry title.

In following paragraph:
Let's write our test to ensure that a blog entry's unicode representation is equal to its title. We need to modify our tests file like so:
from django.test import TestCase
from .models import Entry

• Importing Entry was not done until now. It was not there in the previous dummy test
• Should we point out that each model being tested by this test file will need to be imported ?
• What about doing the import ahead of time, ie even before creating the dummy test ?
• Is this line: "from .models import Entry" an explicit relative import ? I read about this in 2 scoops of Django. The books say this is only available as a backport for 2.7 ? (and not 2.6?) and for it to work you need to use "from __ future __ import absolute_import". Really? I am confused. Do we need to mention anything about all that ?

Clarify distinction between myblog/views.py and blog/views.py

As noted in #53, this may be confusing.

Demonstrate custom model managers with `draft/published` filter

Just an idea.

Add a Note Explaining TestCase

Suggestion: After the paragraph,

"If we read the output carefully, the manage.py test command did a few things. First, it created a test database. ...",

add a Note that encourages folks to read more about:
from django.test import TestCase
at https://docs.djangoproject.com/en/1.6/topics/testing/tools/#django.test.TestCase

Add docstrings for every test class

I think test classes should be described. We could update the tutorial and code to add descriptive docstrings to encourage this behavior (while explaining what they are).

Thoughts on this?

Rename `Post` to `BlogPost` (to avoid confusion with HTTP POST)

Assigning self.post to be a model instance in a class-based view is not a good idea.

Walk through using empty template tag the first time

We the {% empty %} template tag twice throughout the tutorial and we leave it as an exercise to the reader to figure it out both times.

First time in: http://test-driven-django-development.readthedocs.org/en/latest/03-views.html#updating-our-views

Second time in: http://test-driven-django-development.readthedocs.org/en/latest/07-templatetags.html#making-it-a-bit-more-robust

I think we should walk through how to use it one of these times (probably the first?).

limit # of posts on homepage

This should be some kind of user configurable setting. Probably makes the most sense in settings.py

Later on for testing perhaps we should use factory_boy to assert that the n+1 post does NOT show up on the page?

Use consistent pronouns

Sometimes we say "your app" and sometimes we say "our app".

We need to make this consistent. Thoughts?

I propose we say "our" everywhere. That's the tense I've been using for some reason.

Note recommended tutorial prerequisites

Add requirements.txt file?

Should we add a requirements.txt file which has the versions of Django and django-webtest?

Unecessary Django installation instructions in Getting Started

Noted by @alaindomissy in #10:

The second sentence of this paragraph should be changed or removed:

For this workshop, a 1.6.x version is required. If instead you see a "No module named django" message, please follow the Django installation instructions.

4 - More Views. Picky rewordings

[Editorial note: IMO, when it says "Let's" do something, that implies to me that the instructions are going to be shown. As opposed to the imperative, where I know I have to do it myself. This is part of my ".editorconfig" for tutorials or reference manuals :-) ]

The pp:
"Let’s write a unicode_ method for our Comment model like we did for our Entry model earlier."

Would read better as:
"Add a unicode_ method for our Comment model, similar to the one we previously added for our Entry model."
...

The pp"
"First we should create a test in blog/tests.py. Our test should look very similar to the unicode test we wrote for entries earlier. This should suffice:"

would make more sense [to me] as:
"Now we need to create a test in blog/tests.py. It will look very similar to the unicode test we wrote for EntryModelTest earlier. This should suffice:"

Updating tutorial for Django 1.6

All tutorial code worked with Django 1.6.

Differences identified from 1.5 to 1.6:

• Update requirements.txt for 1.6
• Database defaults to SQLite in settings.py
• Admin is automatically added to INSTALLED_APPS in settings.py

Assemble final code and check it into Git

Once the tutorials are done, let's check in the final code at the top level. We will need an explanation in the README that explains what is in the directory.

Pip is a requirement

Make pip a proper prerequisite and/or have a good explanation on how to install it and our tutorial's dependencies.

Show how to verify test coverage

pip install coverage

.coveragerc:

[run]
include = ./*
branch = 1

Then run:

coverage run manage.py test blog
coverage report

Note how databases work during testing

@riseriyo and I noticed that this explanation is missing from the workshop tutorials.

1. Tests create a new test database (so there must be access to create this)
2. Tests won't interact with the real database and can't rely on any data in it

Add 'tree' command to note box for new developers

http://test-driven-django-development.readthedocs.org/en/latest/02-models.html

In Note box where you check directory structure, mentioning tree command will help new users.

Add to "We should add a test for that..."

Suggestion: add to "We should add a test for that... " under section, Updating our views,

Change to:
"We should add a test for that in our class HomePageTests"

Mention South

Add an image showing Admin UI with Entrys

Suggestion: Add an image to document after this paragraph:

'Did you notice that the pluralization of entry is mispelled in the admin interface? “Entrys” should instead read “Entries”.'

Reference views by strings in urls.py files

Currently we recommend import views from myblog and then reference views.home. Django's example uses a string 'blog.views.home' instead. I think we should do that too.

Suggest/make additional changes at the end of the tutorial

Ideas:

• Allow posts to be drafted and only visible once they're "published"
• Limit the number of posts on the homepage (#11)
• Use friendly slug-based URLs (#12)
• Show post history in sidebar (#10)

Use static files template tags

Foundation 4 download link is broken - use new version Foundation 5 ?

The link to download Foundation 4 is broken; it should be replaced with :
http://foundation5.zurb.com/cdn/releases/foundation-4.3.2.zip

Also: the current version is Foundation 5. Should we use the new version?
Download link would be: http://foundation.zurb.com/cdn/releases/foundation-5.2.0.zip
Miration guide is here : http://foundation.zurb.com/docs/upgrading.html

Test for zero blog posts and use an empty block in our for loop

Remove project-level views file

The URL example given in the default Django project includes:

# url(r'^$', 'myblog.views.home', name='home'),

I think that's how we should setup or homepage. As a "home" view in the blog/views.py file, instead of creating a second project-level views file.

Walk through South command output

When creating the schema migration the user is prompted. We don't show this in the example.

Split tests.py module into tests package

We could do this in a later tutorial to split up our tests file for clarity.

Suggested files in the tests package:

• test_models.py
• test_views.py
• test_forms.py

Mention how to use pdb to debug tests and code

Comments on tutorial: 03-views-and-templates.rst

Comments on tutorial: 03-views-and-templates.rst

We don't have a home page (/) but... we have an admin page (/admin/) !

In the Home page test paragraph, after this sentence:
If we run our tests now this test should fail because we haven't created a homepage yet.
Since we saw we already have a page up aand running, the admin, show how a similar test succeeds for an existing page, by adding this test:
def test_adminpage(self):
response = self.client.get('/admin/')
self.assertEqual(response.status_code, 200)

Distinction between myblog and blog:

In the following paragraph we explain (do we really explain?) that we are creating a view in the myblog project directory as opposed to the blog app dirctory:
Important
We are making this views file in the myblog project directory (next to the myblog/urls.py file we are about to change). We are not changing the blog/views.py file yet. We will use that file later.

But when time comes for testing, we run a test that was previously setup in the blog app directory:
Great! Now let's make sure our new test passes:
$ python manage.py test blog

Should we be consistent and have a testfile at the myblog project level ?
Would the following command then work ?
$ python manage.py test myblog
Well I guess not!:
ImproperlyConfigured: App with label myblog could not be found

Just to create a very simple home page we need all of the following:

• Foundation
• Static directory
• static/css/foundation.css file .............................. from Foundation
• Templates directory
• templates/index.html ........................................ using {% load %} and {% static %} tags
• myblog/views.py with a class-based view defined at the project level
• a new pattern in /myblog/urls.py ........................ url( r'^$', views.home), )

That's a lot of copy-pasting before seeing anything new!
Could we break this down into incremental steps ?

The home page does not need to be called index.html. Right?
Name it home1.html and change:
template_name = 'index.html' to template_name = 'home1.html'
This might help show there is no webserver convention here to look for and serve a specific file in the / directory. But the combination of url pattern and the view settings end up picking the right file.
Also: change the settings for template_name successively to:
home1.html, base.html and index.html to see how things build up

Add a model field for published/draft state

This involves adding two tutorials:

• Setting up South
• Adding this new model field and changing our code to use it

This will demonstrate:

• Setting up South
• Making a South migration to add a column
• Changing our tests and code to iterate based on a new feature

I think this is a high priority feature. Thoughts on this? Ideas for implementation? Who wants to take on this task?

Rename RTD URL

@davidfischer are we planning to rename the RTD URL to test-driven-django-development?

Add testing for 404/500 pages

We should test different server responses like 404 or 500

Use friendly URLs: year-month-day/blog-title-slug

Use named 'endblock' tags

Example:

{% block "content" %}
<p>my content</p>
{% endblock "content" %}

I can't seem to find the docs on this.

"Entrys" in the admin

This should be pluralized into "entries": https://docs.djangoproject.com/en/1.6/ref/models/options/#verbose-name-plural

Add tutorial explaining ways to structure tests

Ideas:

• Mention the different names for tests and ways tests are divided: unit, integration, functional, etc.
• Split tests module into a package so not all tests are in one file
• Move full-site tests (the tests that use HTTP requests) into a separate module

Wording tweak on 03-views about putting new code inside content block

The last change needed then is just to update our index.html to actually put those blog posts in there.

Might be good to specify that this goes inside the {% block content %}, so people don't overwrite the whole file.

Step 3 (Views and Templates) inconsistent code snippets

We have conflicting view declarations in the code snippets.

from django.http import HttpResponse

def entry_detail(request, pk):
    return HttpResponse('empty')

And then later:

from django.views.generic import DetailView
from .models import Entry

class EntryDetail(DetailView):
    model = Entry
entry_detail = EntryDetail.as_view()

Add comments count and link to homepage

Example: 5 comments