Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Refs #2333 - Added more documentation for testing framework, and clar…

…ified some code as a result of trying to describe it.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@3689 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit fc2d5f461f398bf048e8b821142019ddba9a677d 1 parent d9883e1
Russell Keith-Magee authored August 31, 2006
3  django/test/simple.py
@@ -61,7 +61,8 @@ def run_tests(module_list, verbosity=1, extra_tests=[]):
61 61
     for test in extra_tests:
62 62
         suite.addTest(test)
63 63
 
64  
-    old_name = create_test_db(verbosity)
  64
+    old_name = settings.DATABASE_NAME
  65
+    create_test_db(verbosity)
65 66
     management.syncdb(verbosity, interactive=False)
66 67
     unittest.TextTestRunner(verbosity=verbosity).run(suite)
67 68
     destroy_test_db(old_name, verbosity)
3  django/test/utils.py
@@ -50,14 +50,11 @@ def create_test_db(verbosity=1, autoclobber=False):
50 50
                 sys.exit(1)
51 51
                
52 52
     connection.close()
53  
-    old_database_name = settings.DATABASE_NAME
54 53
     settings.DATABASE_NAME = TEST_DATABASE_NAME
55 54
 
56 55
     # Get a cursor (even though we don't need one yet). This has
57 56
     # the side effect of initializing the test database.
58 57
     cursor = connection.cursor()
59  
-            
60  
-    return old_database_name
61 58
 
62 59
 def destroy_test_db(old_database_name, verbosity=1):
63 60
     # Unless we're using SQLite, remove the test database to clean up after
22  docs/django-admin.txt
@@ -345,6 +345,17 @@ setting the Python path for you.
345 345
 Displays a help message that includes a terse list of all available actions and
346 346
 options.
347 347
 
  348
+--noinput
  349
+---------
  350
+
  351
+Inform django-admin that the user should NOT be prompted for any input. Useful if
  352
+the django-admin script will be executed as an unattended, automated script.
  353
+
  354
+--noreload
  355
+----------
  356
+
  357
+Disable the use of the auto-reloader when running the development server.
  358
+
348 359
 --version
349 360
 ---------
350 361
 
@@ -355,6 +366,17 @@ Example output::
355 366
     0.9.1
356 367
     0.9.1 (SVN)
357 368
 
  369
+--verbosity
  370
+-----------
  371
+
  372
+Example usage::
  373
+
  374
+    django-admin.py syncdb --verbosity=2
  375
+
  376
+Verbosity determines the amount of notification and debug information that 
  377
+will be printed to the console. '0' is no output, '1' is normal output,
  378
+and `2` is verbose output.
  379
+
358 380
 Extra niceties
359 381
 ==============
360 382
 
12  docs/settings.txt
@@ -754,6 +754,18 @@ misspelled) variables. See `How invalid variables are handled`_.
754 754
 
755 755
 .. _How invalid variables are handled: http://www.djangoproject.com/documentation/templates_python/#how-invalid-variables-are-handled
756 756
 
  757
+TEST_RUNNER
  758
+-----------
  759
+
  760
+**New in Django development version**
  761
+
  762
+Default: ``'django.test.simple.run_tests'``
  763
+
  764
+The name of the method to use for starting the test suite. See 
  765
+`Testing Django Applications`_.
  766
+
  767
+.. _Testing Django Applications: ../testing/
  768
+
757 769
 TIME_FORMAT
758 770
 -----------
759 771
 
162  docs/testing.txt
@@ -4,13 +4,21 @@ Testing Django applications
4 4
 
5 5
 **New in Django development version**.
6 6
 
7  
-.. XXX insert quick introduction to testing (and why you'd want to do it)
  7
+Automated testing is an extremely useful weapon in the bug-killing arsenal
  8
+of the modern developer. When initially writing code, a test suite can be
  9
+used to validate that code behaves as expected. When refactoring or
  10
+modifying code, tests serve as a guide to ensure that behavior hasn't
  11
+changed as a result of the refactor.
  12
+
  13
+Testing an web application is a complex task, as there are many
  14
+components of a web application that must be validated and tested. To
  15
+help you test your application, Django provides a test execution
  16
+framework, and range of utilities that can be used to stimulate and
  17
+inspect various facets of a web application.
8 18
 
9  
-.. note::
10  
-    
11 19
     This testing framework is currently under development, and may change
12  
-    slightly before the next official Django release.  
13  
-    
  20
+    slightly before the next official Django release.
  21
+
14 22
     (That's *no* excuse not to write tests, though!)
15 23
 
16 24
 Writing tests
@@ -23,17 +31,20 @@ Writing doctests
23 31
 
24 32
 Doctests use Python's standard doctest_ module, which searches for tests in
25 33
 your docstrings. Django's test runner looks for doctests in your ``models.py``
26  
-file, and executes any that it finds.
  34
+file, and executes any that it finds. Django will also search for a file
  35
+called ``tests.py`` in the application directory (i.e., the directory that
  36
+holds ``models.py``). If a ``tests.py`` is found, it will also be searched
  37
+for doctests.
27 38
 
28 39
 .. admonition:: What's a **docstring**?
29 40
 
30 41
     A good explanation of docstrings (and some guidlines for using them
31 42
     effectively) can be found in :PEP:`257`:
32  
-        
33  
-        A docstring is a string literal that occurs as the first statement in 
  43
+
  44
+        A docstring is a string literal that occurs as the first statement in
34 45
         a module, function, class, or method definition.  Such a docstring
35 46
         becomes the ``__doc__`` special attribute of that object.
36  
-        
  47
+
37 48
     Since tests often make great documentation, doctest lets you put your
38 49
     tests directly in your docstrings.
39 50
 
@@ -44,25 +55,25 @@ model-level doctests in the docstring for each model.
44 55
 For example::
45 56
 
46 57
     from django.db import model
47  
-    
  58
+
48 59
     class Animal(models.Model):
49 60
         """
50 61
         An animal that knows how to make noise
51  
-        
  62
+
52 63
         # Create some animals
53 64
         >>> lion = Animal.objects.create(name="lion", sound="roar")
54 65
         >>> cat = Animal.objects.create(name="cat", sound="meow")
55  
-        
  66
+
56 67
         # Make 'em speak
57 68
         >>> lion.speak()
58 69
         'The lion says "roar"'
59 70
         >>> cat.speak()
60 71
         'The cat says "meow"'
61 72
         """
62  
-        
  73
+
63 74
         name = models.CharField(maxlength=20)
64 75
         sound = models.CharField(maxlength=20)
65  
-        
  76
+
66 77
         def speak(self):
67 78
             return 'The %s says "%s"' % (self.name, self.sound)
68 79
 
@@ -80,24 +91,24 @@ Writing unittests
80 91
 -----------------
81 92
 
82 93
 Like doctests, Django's unit tests use a standard library module: unittest_.
83  
-Django's test runner looks for unit test cases in a ``tests.py`` file in your
84  
-app (i.e. in the same directory as your ``models.py`` file).
  94
+As with doctests, Django's test runner looks for any unit test cases defined
  95
+in ``models.py``, or in a ``tests.py`` file in your application directory.
85 96
 
86 97
 An equivalent unittest test case for the above example would look like::
87 98
 
88 99
     import unittest
89 100
     from myapp.models import Animal
90  
-    
  101
+
91 102
     class AnimalTestCase(unittest.TestCase):
92  
-        
  103
+
93 104
         def setUp(self):
94 105
             self.lion = Animal.objects.create(name="lion", sound="roar")
95 106
             self.cat = Animal.objects.create(name="cat", sound="meow")
96  
-        
  107
+
97 108
         def testSpeaking(self):
98 109
             self.assertEquals(self.lion.speak(), 'The lion says "roar"')
99 110
             self.assertEquals(self.cat.speak(), 'The cat says "meow"')
100  
-            
  111
+
101 112
 When you `run your tests`_, the test utility will find all the test cases
102 113
 (that is, subclasses of ``unittest.TestCase``) in ``tests.py``, automatically
103 114
 build a test suite out of those test cases, and run that suite.
@@ -119,7 +130,7 @@ system has different benefits, the best approach is probably to use both
119 130
 together, picking the test system to match the type of tests you need to
120 131
 write.
121 132
 
122  
-For developers new to testing, however, this choice can seem 
  133
+For developers new to testing, however, this choice can seem
123 134
 confusing, so here are a few key differences to help you decide weather
124 135
 doctests or unit tests are right for you.
125 136
 
@@ -136,11 +147,11 @@ get you started faster.
136 147
 The ``unittest`` framework will probably feel very familiar to developers
137 148
 coming from Java.  Since ``unittest`` is inspired by Java's JUnit, if
138 149
 you've used testing frameworks in other languages that similarly were
139  
-inspired by JUnit, ``unittest`` should also feel pretty familiar.  
  150
+inspired by JUnit, ``unittest`` should also feel pretty familiar.
140 151
 
141 152
 Since ``unittest`` is organized around classes and methods, if you need
142 153
 to write a bunch of tests that all share similar code, you can easily use
143  
-subclass to abstract common tasks; this makes test code shorter and cleaner. 
  154
+subclass to abstract common tasks; this makes test code shorter and cleaner.
144 155
 There's also support for explicit setup and/or cleanup routines, which give
145 156
 you a high level of control over the environment your test cases run in.
146 157
 
@@ -148,6 +159,20 @@ Again, remember that you can use both systems side-by-side (even in the same
148 159
 app). In the end, most projects will eventually end up using both; each shines
149 160
 in different circumstances.
150 161
 
  162
+Testing utilities
  163
+=================
  164
+
  165
+Test Client
  166
+-----------
  167
+
  168
+A dummy browser; instruments the template generation process...
  169
+
  170
+Fixtures
  171
+--------
  172
+
  173
+Feature still to come...
  174
+
  175
+
151 176
 Running tests
152 177
 =============
153 178
 
@@ -155,9 +180,22 @@ Run your tests using your project's ``manage.py`` utility::
155 180
 
156 181
     $ ./manage.py test
157 182
 
158  
-You'll see a bunch of text flow by as the test database is created, models are
159  
-initialized, and your tests are run. If everything goes well, at the end
160  
-you'll see::
  183
+If you only want to run tests for a particular application, add the
  184
+application name to the command line. For example, if your
  185
+``INSTALLED_APPS`` contains ``myproject.polls`` and ``myproject.animals``,
  186
+but you only want to run the animals unit tests, run::
  187
+
  188
+    $ ./manage.py test animals
  189
+
  190
+When you run your tests, you'll see a bunch of text flow by as the test
  191
+database is created and models are initialized. This test database is
  192
+created from scratch every time you run your tests. The test database
  193
+gets its name by prepending ``test_`` to the database name specified by
  194
+``settings.DATABASE_NAME``; all other database settings will the same as
  195
+they would be for the project normally.
  196
+
  197
+Once the test database has been established, Django will run your tests.
  198
+If everything goes well, at the end you'll see::
161 199
 
162 200
     ----------------------------------------------------------------------
163 201
     Ran 22 tests in 0.221s
@@ -189,4 +227,74 @@ failed::
189 227
     Ran 2 tests in 0.048s
190 228
 
191 229
     FAILED (failures=1)
192  
-    
  230
+
  231
+When the tests have all been executed, the test database is destroyed.
  232
+
  233
+Using a different testing framework
  234
+===================================
  235
+
  236
+Doctest and Unittest are not the only Python testing frameworks. While
  237
+Django doesn't provide explicit support these alternative frameworks,
  238
+it does provide a mechanism to allow you to invoke tests constructed for
  239
+an alternative framework as if they were normal Django tests.
  240
+
  241
+When you run ``./manage.py test``, Django looks at the ``TEST_RUNNER``
  242
+setting to determine what to do. By default, ``TEST_RUNNER`` points to ``django.test.simple.run_tests``. This method defines the default Django
  243
+testing behaviour. This behaviour involves:
  244
+
  245
+#. Creating the test database
  246
+#. Running ``syncdb`` to install models and initial data into the test database
  247
+#. Looking for Unit Tests and Doctests in ``models.py`` and ``tests.py`` file for each installed application
  248
+#. Running the Unit Tests and Doctests that are found
  249
+#. Destroying the test database.
  250
+
  251
+If you define your own test runner method and point ``TEST_RUNNER``
  252
+at that method, Django will execute your test runner whenever you run
  253
+``./manage.py test``. In this way, it is possible to use any test
  254
+framework that can be executed from Python code.
  255
+
  256
+Defining a test runner
  257
+----------------------
  258
+By convention, a test runner should be called ``run_tests``; however, you
  259
+can call it anything you want. The only requirement is that it accept two
  260
+arguments:
  261
+
  262
+``run_tests(module_list, verbosity=1)``
  263
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  264
+
  265
+The module list is the list of Python modules that contain the models to be
  266
+tested. This is the same format returned by ``django.db.models.get_apps()``
  267
+
  268
+Verbosity determines the amount of debug information that will be
  269
+provided to the console; '0' is no output, '1' is normal output,
  270
+and `2` is verbose output.
  271
+
  272
+Testing utilities
  273
+-----------------
  274
+
  275
+To assist in the creation of your own test runner, Django provides
  276
+a number of utility methods in the ``django.test.utils`` module.
  277
+
  278
+``create_test_db(verbosity=1, autoclobber=False)``:
  279
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  280
+
  281
+Creates a new test database, and run ``syncdb`` against it.
  282
+
  283
+``verbosity`` has the same behaviour as in the test runner.
  284
+
  285
+``Autoclobber`` describes the behavior that will occur if a database with
  286
+the same name as the test database is discovered. If ``autoclobber`` is False,
  287
+the user will be asked to approve destroying the existing database. ``sys.exit``
  288
+is called if the user does not approve. If autoclobber is ``True``, the database
  289
+will be destroyed without consulting the user.
  290
+
  291
+``create_test_db()`` has the side effect of modifying
  292
+``settings.DATABASE_NAME`` to match the name of the test database.
  293
+
  294
+``destroy_test_db(old_database_name, verbosity=1)``:
  295
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  296
+
  297
+Destroys the database with the name ``settings.DATABASE_NAME`` matching,
  298
+and restores the value of ``settings.DATABASE_NAME`` to the provided name.
  299
+
  300
+``verbosity`` has the same behaviour as in the test runner.

0 notes on commit fc2d5f4

Please sign in to comment.
Something went wrong with that request. Please try again.