Add a tutorial for the testing framework

[Russell Keith-Magee]

Testing is an important part of modern website development. The official Django tutorial should include a section on how to use the testing framework.

[Alexander Lyabah]

​http://docs.djangoproject.com/en/dev/topics/testing/#using-different-testing-frameworks

it's not enough? What section must be added?

[Eric Holscher]

I'd like to see this get into 1.3. Fix the "more tutorials coming later" at the end of the current tut.

If any of the documentation at ​http://djangotesting.com/ is worthwhile for inclusion, I would gladly donate it (It's in restructured text already). Or if anyone wanted to use that as a starting point, that would be awesome.

[Eric Holscher]

Sadly not going to have time to get this in for 1.3. Again.

[holdenweb]

Please note that ​http://djangotesting.com/ is currently unavailable due to expiry of the domain name registration.

[Daniele Procida]

If no-one else has already embarked on the task, I would like to write up and contribute some documentation based on testing the application as it stands in the tutorial.

It's not mentioned in the "coming soon" section (1.4, it's gone from dev), so I assume not.

After writing Django code for more than three years I have only just learned how to do tests, and understood what they are for, despite several abortive previous attempts. It's something I wish I had understood much earlier.

Please let me know whether I should embark on this. I can start immediately, and can demonstrate work-in-progress on GitHub, but I don't want to spend a lot of time on it if someone else already has something ready to drop in.

[anonymous]

Work in progress at ​https://github.com/evildmp/django/blob/testing-tutorial/docs/intro/tutorial05.txt; can I have some feedback please?

[Preston Holmes]

The tone and scope of this is good needs some minor work here and there - I gave some feedback to the author on IRC. Additional review would be great.

[Tim Graham]

Hi Daniele,

This looks like a great start. I'm currently working on trying to finish up a tutorial for contributing (#16779) but after that, I'll be happy to work through this and offer my feedback. Hopefully we should be able to get this committed for the 1.5 release. One quick thing I noticed was a mixture of tabs and spaces for indentation - please replace the tabs with spaces. Thanks for your work on this!

Tim

[Daniele Procida]

timo, I think I have pretty much finished. ​https://github.com/evildmp/django/commit/53d731cbad39f56aa099a5be773b5fd8c84094a7

I think that it's free of tabs now, but I seem to have got into a mess locally with git rebase, and I will have to spend a bit of time undoing it before further work on this.

Regards,

Daniele

[Tim Graham]

This looks quite good to me, bravo! I've made some edits, mostly cosmetic. One material change I did make was to remove override_settings in the tests. As far as I can see, it shouldn't be necessary. What exception was raised when you executed that test?

I'll reply to your thread on django-developers and hopefully we can get a couple more people to run through this.

Here's an HTML version for easy review: ​http://techytim.com/django/9962/intro/tutorial05.html

[Daniele Procida]

Thanks.

I have made a couple of changes and corrections locally based on comments from Mark Jones, but I also made a mess rebasing my local copy, and now I am not sure how (or whether) I can push them to my branch on GitHub, all at <​https://github.com/evildmp/django/blob/tutorial05-test/docs/intro/tutorial05.txt>.

If I want to comment on your version, or note typos etc, what is the best way to do that?

For example:

was_published_recently() returns True, though we wanted it to return False`

If I *don't* override_settings, DEBUG = False causes a TemplateDoesNotExist: 404.html:

Traceback (most recent call last):
  File "/home/daniele/django-testing-tutorial/mysite/polls/tests.py", line 116, in test_detail_view_with_a_future_poll
    response = self.client.get(reverse('polls:detail', args=(self.stones_poll.id,)))
  File "/home/daniele/django-testing-tutorial/local/lib/python2.7/site-packages/django/test/client.py", line 439, in get
    response = super(Client, self).get(path, data=data, **extra)
  File "/home/daniele/django-testing-tutorial/local/lib/python2.7/site-packages/django/test/client.py", line 244, in get
    return self.request(**r)
  File "/home/daniele/django-testing-tutorial/local/lib/python2.7/site-packages/django/core/handlers/base.py", line 150, in get_response
    response = callback(request, **param_dict)
  File "/home/daniele/django-testing-tutorial/local/lib/python2.7/site-packages/django/utils/decorators.py", line 91, in _wrapped_view
    response = view_func(request, *args, **kwargs)
  File "/home/daniele/django-testing-tutorial/local/lib/python2.7/site-packages/django/views/defaults.py", line 20, in page_not_found
    t = loader.get_template(template_name) # You need to create a 404.html template.
  File "/home/daniele/django-testing-tutorial/local/lib/python2.7/site-packages/django/template/loader.py", line 145, in get_template
    template, origin = find_template(template_name)
  File "/home/daniele/django-testing-tutorial/local/lib/python2.7/site-packages/django/template/loader.py", line 138, in find_template
    raise TemplateDoesNotExist(name)
TemplateDoesNotExist: 404.html

Finally, my preference when writing documents like this (on the web, dense, and likely to be read by non-native English speakers) is to break the text up into shorter paragraphs than the Django documentation generally does. What's your feeling on that?

Daniele

[Tim Graham]

1. Hmm, I'm not sure. It may be easiest to port these changes over to my updated patch manually, if that's not too much work. You could try using something like Meld to view changes between my updated version and your local copy.

2. Feel free to download the patch I uploaded, make any changes, and re-upload it. If you have some changes you're not sure about, feel free to leave a comment here and we can discuss. Or if you want to just leave comments here for typos, etc. as well, I'll be happy to update it.

3. Are you perhaps using a version of Django older than 8bd7b598b6de1be1e3f72f3a1ee62803b1c02010 as that commit made the 404 template optional. Even before this commit, tutorial 3 instructed to create a 404.html template: ​https://docs.djangoproject.com/en/1.4/intro/tutorial03/#write-a-404-page-not-found-view

4. I sympathize with that argument. On the other hand, a new paragraph is typically used to indicate a change of subject matter and I had some trouble following sections since the breaks suggested to me that the two sections weren't closely related -- thus, I collapsed a few sections a bit. Let me know if you think anything I did was too extreme.

[Tim Graham]

Daniele, I made a few more edits and opened a pull request which should make it easier to leave comments.

​https://github.com/django/django/pull/548

[Tim Graham <timograham@…>]

In b052e6cc959b540e4d1de8a747689c25c6aeace9:

Fixed #9962 - Added a testing tutorial.

Thank-you Daniele Procida for the first draft
and shaibi, Aymeric, and others for the reviews.

[Tim Graham <timograham@…>]

In c252ed567c9844294bbe7924de62eb747d4cc0d9:

[1.5.X] Fixed #9962 - Added a testing tutorial.

Thank-you Daniele Procida for the first draft
and shaibi, Aymeric, and others for the reviews.

Backport of b052e6cc95 from master