← Back to branch summary

~ubuntu-branches/debian/sid/python-django/sid

« back to all changes in this revision

Viewing changes to docs/topics/testing/overview.txt

  • Committer: Package Import Robot
  • Author(s): Raphaël Hertzog
  • Date: 2014-09-17 14:15:11 UTC
  • mfrom: (1.3.17) (6.2.18 experimental)
  • Revision ID: package-import@ubuntu.com-20140917141511-icneokthe9ww5sk4
Tags: 1.7-2
* Release to unstable.
* Add a migrate-south sample script to help users apply their South
  migrations. Thanks to Brian May.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/topics/testing/overview.txt
22
22
 
23
23
.. admonition:: unittest2
24
24
 
 
25
    .. deprecated:: 1.7
 
26
 
25
27
    Python 2.7 introduced some major changes to the ``unittest`` library,
26
 
    adding some extremely useful features. To ensure that every Django
27
 
    project can benefit from these new features, Django ships with a
28
 
    copy of unittest2_, a copy of Python 2.7's ``unittest``, backported for
29
 
    Python 2.6 compatibility.
30
 
 
31
 
    To access this library, Django provides the
32
 
    ``django.utils.unittest`` module alias. If you are using Python
33
 
    2.7, or you have installed ``unittest2`` locally, Django will map the alias
34
 
    to it. Otherwise, Django will use its own bundled version of ``unittest2``.
35
 
 
36
 
    To use this alias, simply use::
37
 
 
38
 
        from django.utils import unittest
39
 
 
40
 
    wherever you would have historically used::
41
 
 
42
 
        import unittest
43
 
 
44
 
    If you want to continue to use the legacy ``unittest`` library, you can --
45
 
    you just won't get any of the nice new ``unittest2`` features.
 
28
    adding some extremely useful features. To ensure that every Django project
 
29
    could benefit from these new features, Django used to ship with a copy of
 
30
    Python 2.7's ``unittest`` backported for Python 2.6 compatibility.
 
31
 
 
32
    Since Django no longer supports Python versions older than 2.7,
 
33
    ``django.utils.unittest`` is deprecated. Simply use ``unittest``.
46
34
 
47
35
.. _unittest2: https://pypi.python.org/pypi/unittest2
48
36
 
182
170
the tests will by default use an in-memory database (i.e., the
183
171
database will be created in memory, bypassing the filesystem
184
172
entirely!). If you want to use a different database name, specify
185
 
:setting:`TEST_NAME` in the dictionary for any given database in
186
 
:setting:`DATABASES`.
 
173
:setting:`NAME <TEST_NAME>` in the :setting:`TEST <DATABASE-TEST>`
 
174
dictionary for any given database in :setting:`DATABASES`.
 
175
 
 
176
.. versionchanged:: 1.7
 
177
 
 
178
    On PostgreSQL, :setting:`USER` will also need read access to the built-in
 
179
    ``postgres`` database.
187
180
 
188
181
Aside from using a separate database, the test runner will otherwise
189
182
use all of the same database settings you have in your settings file:
193
186
create a new database on the system.
194
187
 
195
188
For fine-grained control over the character encoding of your test
196
 
database, use the :setting:`TEST_CHARSET` option. If you're using
197
 
MySQL, you can also use the :setting:`TEST_COLLATION` option to
 
189
database, use the :setting:`CHARSET <TEST_CHARSET>` TEST option. If you're using
 
190
MySQL, you can also use the :setting:`COLLATION <TEST_COLLATION>` option to
198
191
control the particular collation used by the test database. See the
199
192
:doc:`settings documentation </ref/settings>` for details of these
200
 
advanced settings.
 
193
and other advanced settings.
 
194
 
 
195
.. versionchanged:: 1.7
 
196
 
 
197
   The different options in the :setting:`TEST <DATABASE-TEST>` database
 
198
   setting used to be separate options in the database settings dictionary,
 
199
   prefixed with ``TEST_``.
201
200
 
202
201
.. admonition:: Finding data from your production database when running tests?
203
202
 
208
207
    your tests. *It is a bad idea to have such import-time database queries in
209
208
    your code* anyway - rewrite your code so that it doesn't do this.
210
209
 
 
210
    .. versionadded:: 1.7
 
211
 
 
212
        This also applies to customized implementations of
 
213
        :meth:`~django.apps.AppConfig.ready()`.
 
214
 
211
215
.. seealso::
212
216
 
213
217
    The :ref:`advanced multi-db testing topics <topics-testing-advanced-multidb>`.
222
226
 
223
227
* All :class:`~django.test.TestCase` subclasses are run first.
224
228
 
225
 
* Then, all other unittests (including :class:`unittest.TestCase`,
226
 
  :class:`~django.test.SimpleTestCase` and
 
229
* Then, all other Django-based tests (test cases based on
 
230
  :class:`~django.test.SimpleTestCase`, including
227
231
  :class:`~django.test.TransactionTestCase`) are run with no particular
228
232
  ordering guaranteed nor enforced among them.
229
233
 
230
 
* Then any other tests (e.g. doctests) that may alter the database without
231
 
  restoring it to its original state are run.
232
 
 
233
 
.. versionchanged:: 1.5
234
 
 
235
 
    Before Django 1.5, the only guarantee was that
236
 
    :class:`~django.test.TestCase` tests were always ran first, before any other
237
 
    tests.
 
234
* Then any other :class:`unittest.TestCase` tests (including doctests) that may
 
235
  alter the database without restoring it to its original state are run.
238
236
 
239
237
.. note::
240
238
 
243
241
    database by a given :class:`~django.test.TransactionTestCase` test, they
244
242
    must be updated to be able to run independently.
245
243
 
 
244
.. _test-case-serialized-rollback:
 
245
 
 
246
Rollback emulation
 
247
------------------
 
248
 
 
249
Any initial data loaded in migrations will only be available in ``TestCase``
 
250
tests and not in ``TransactionTestCase`` tests, and additionally only on
 
251
backends where transactions are supported (the most important exception being
 
252
MyISAM).
 
253
 
 
254
Django can reload that data for you on a per-testcase basis by
 
255
setting the ``serialized_rollback`` option to ``True`` in the body of the
 
256
``TestCase`` or ``TransactionTestCase``, but note that this will slow down
 
257
that test suite by approximately 3x.
 
258
 
 
259
Third-party apps or those developing against MyISAM will need to set this;
 
260
in general, however, you should be developing your own projects against a
 
261
transactional database and be using ``TestCase`` for most tests, and thus
 
262
not need this setting.
 
263
 
 
264
The initial serialization is usually very quick, but if you wish to exclude
 
265
some apps from this process (and speed up test runs slightly), you may add
 
266
those apps to :setting:`TEST_NON_SERIALIZED_APPS`.
 
267
 
 
268
Apps without migrations are not affected; ``initial_data`` fixtures are
 
269
reloaded as usual.
 
270
 
246
271
Other test conditions
247
272
---------------------
248
273