PKG-INFO 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387
  1. Metadata-Version: 1.1
  2. Name: django-nose
  3. Version: 1.3
  4. Summary: Makes your Django tests simple and snappy
  5. Home-page: http://github.com/django-nose/django-nose
  6. Author: Erik Rose
  7. Author-email: erikrose@grinchcentral.com
  8. License: BSD
  9. Description: ===========
  10. django-nose
  11. ===========
  12. .. image:: https://travis-ci.org/django-nose/django-nose.png
  13. :target: https://travis-ci.org/django-nose/django-nose
  14. Features
  15. --------
  16. * All the goodness of `nose`_ in your Django tests, like...
  17. * Testing just your apps by default, not all the standard ones that happen to
  18. be in ``INSTALLED_APPS``
  19. * Running the tests in one or more specific modules (or apps, or classes, or
  20. folders, or just running a specific test)
  21. * Obviating the need to import all your tests into ``tests/__init__.py``.
  22. This not only saves busy-work but also eliminates the possibility of
  23. accidentally shadowing test classes.
  24. * Taking advantage of all the useful `nose plugins`_
  25. * Fixture bundling, an optional feature which speeds up your fixture-based
  26. tests by a factor of 4
  27. * Reuse of previously created test DBs, cutting 10 seconds off startup time
  28. * Hygienic TransactionTestCases, which can save you a DB flush per test
  29. * Support for various databases. Tested with MySQL, PostgreSQL, and SQLite.
  30. Others should work as well.
  31. .. _nose: http://somethingaboutorange.com/mrl/projects/nose/
  32. .. _nose plugins: http://nose-plugins.jottit.com/
  33. Installation
  34. ------------
  35. You can get django-nose from PyPI with... ::
  36. pip install django-nose
  37. The development version can be installed with... ::
  38. pip install -e git://github.com/django-nose/django-nose.git#egg=django-nose
  39. Since django-nose extends Django's built-in test command, you should add it to
  40. your ``INSTALLED_APPS`` in ``settings.py``::
  41. INSTALLED_APPS = (
  42. ...
  43. 'django_nose',
  44. ...
  45. )
  46. Then set ``TEST_RUNNER`` in ``settings.py``::
  47. TEST_RUNNER = 'django_nose.NoseTestSuiteRunner'
  48. Use
  49. ---
  50. The day-to-day use of django-nose is mostly transparent; just run ``./manage.py
  51. test`` as usual.
  52. See ``./manage.py help test`` for all the options nose provides, and look to
  53. the `nose docs`_ for more help with nose.
  54. .. _nose docs: http://somethingaboutorange.com/mrl/projects/nose/
  55. Enabling Database Reuse
  56. -----------------------
  57. You can save several seconds at the beginning and end of your test suite by
  58. reusing the test database from the last run. To do this, set the environment
  59. variable ``REUSE_DB`` to 1::
  60. REUSE_DB=1 ./manage.py test
  61. The one new wrinkle is that, whenever your DB schema changes, you should leave
  62. the flag off the next time you run tests. This will cue the test runner to
  63. reinitialize the test database.
  64. Also, REUSE_DB is not compatible with TransactionTestCases that leave junk in
  65. the DB, so be sure to make your TransactionTestCases hygienic (see below) if
  66. you want to use it.
  67. Enabling Fast Fixtures
  68. ----------------------
  69. django-nose includes a fixture bundler which drastically speeds up your tests
  70. by eliminating redundant setup of Django test fixtures. To use it...
  71. 1. Subclass ``django_nose.FastFixtureTestCase`` instead of
  72. ``django.test.TestCase``. (I like to import it ``as TestCase`` in my
  73. project's ``tests/__init__.py`` and then import it from there into my actual
  74. tests. Then it's easy to sub the base class in and out.) This alone will
  75. cause fixtures to load once per class rather than once per test.
  76. 2. Activate fixture bundling by passing the ``--with-fixture-bundling`` option
  77. to ``./manage.py test``. This loads each unique set of fixtures only once,
  78. even across class, module, and app boundaries.
  79. How Fixture Bundling Works
  80. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  81. The fixture bundler reorders your test classes so that ones with identical sets
  82. of fixtures run adjacently. It then advises the first of each series to load
  83. the fixtures once for all of them (and the remaining ones not to bother). It
  84. also advises the last to tear them down. Depending on the size and repetition
  85. of your fixtures, you can expect a 25% to 50% speed increase.
  86. Incidentally, the author prefers to avoid Django fixtures, as they encourage
  87. irrelevant coupling between tests and make tests harder to comprehend and
  88. modify. For future tests, it is better to use the "model maker" pattern,
  89. creating DB objects programmatically. This way, tests avoid setup they don't
  90. need, and there is a clearer tie between a test and the exact state it
  91. requires. The fixture bundler is intended to make existing tests, which have
  92. already committed to fixtures, more tolerable.
  93. Troubleshooting
  94. ~~~~~~~~~~~~~~~
  95. If using ``--with-fixture-bundling`` causes test failures, it likely indicates
  96. an order dependency between some of your tests. Here are the most frequent
  97. sources of state leakage we have encountered:
  98. * Locale activation, which is maintained in a threadlocal variable. Be sure to
  99. reset your locale selection between tests.
  100. * memcached contents. Be sure to flush between tests. Many test superclasses do
  101. this automatically.
  102. It's also possible that you have ``post_save`` signal handlers which create
  103. additional database rows while loading the fixtures. ``FastFixtureTestCase``
  104. isn't yet smart enough to notice this and clean up after it, so you'll have to
  105. go back to plain old ``TestCase`` for now.
  106. Exempting A Class From Bundling
  107. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  108. In some unusual cases, it is desirable to exempt a test class from fixture
  109. bundling, forcing it to set up and tear down its fixtures at the class
  110. boundaries. For example, we might have a ``TestCase`` subclass which sets up
  111. some state outside the DB in ``setUpClass`` and tears it down in
  112. ``tearDownClass``, and it might not be possible to adapt those routines to heed
  113. the advice of the fixture bundler. In such a case, simply set the
  114. ``exempt_from_fixture_bundling`` attribute of the test class to ``True``.
  115. Speedy Hygienic TransactionTestCases
  116. ------------------------------------
  117. Unlike the stock Django test runner, django-nose lets you write custom
  118. TransactionTestCase subclasses which expect to start with an unmarred DB,
  119. saving an entire DB flush per test.
  120. Background
  121. ~~~~~~~~~~
  122. The default Django TransactionTestCase class `can leave the DB in an unclean
  123. state`_ when it's done. To compensate, TransactionTestCase does a
  124. time-consuming flush of the DB *before* each test to ensure it begins with a
  125. clean slate. Django's stock test runner then runs TransactionTestCases last so
  126. they don't wreck the environment for better-behaved tests. django-nose
  127. replicates this behavior.
  128. Escaping the Grime
  129. ~~~~~~~~~~~~~~~~~~
  130. Some people, however, have made subclasses of TransactionTestCase that clean up
  131. after themselves (and can do so efficiently, since they know what they've
  132. changed). Like TestCase, these may assume they start with a clean DB. However,
  133. any TransactionTestCases that run before them and leave a mess could cause them
  134. to fail spuriously.
  135. django-nose offers to fix this. If you include a special attribute on your
  136. well-behaved TransactionTestCase... ::
  137. class MyNiceTestCase(TransactionTestCase):
  138. cleans_up_after_itself = True
  139. ...django-nose will run it before any of those nasty, trash-spewing test cases.
  140. You can thus enjoy a big speed boost any time you make a TransactionTestCase
  141. clean up after itself: skipping a whole DB flush before every test. With a
  142. large schema, this can save minutes of IO.
  143. django-nose's own FastFixtureTestCase uses this feature, even though it
  144. ultimately acts more like a TestCase than a TransactionTestCase.
  145. .. _can leave the DB in an unclean state: https://docs.djangoproject.com/en/1.4/topics/testing/#django.test.TransactionTestCase
  146. Test-Only Models
  147. ----------------
  148. If you have a model that is used only by tests (for example, to test an
  149. abstract model base class), you can put it in any file that's imported in the
  150. course of loading tests. For example, if the tests that need it are in
  151. ``test_models.py``, you can put the model in there, too. django-nose will make
  152. sure its DB table gets created.
  153. Assertions
  154. ----------
  155. ``django-nose.tools`` provides pep8 versions of Django's TestCase asserts
  156. and some of its own as functions. ::
  157. assert_redirects(response, expected_url, status_code=302, target_status_code=200, host=None, msg_prefix='')
  158. assert_contains(response, text, count=None, status_code=200, msg_prefix='')
  159. assert_not_contains(response, text, count=None, status_code=200, msg_prefix='')
  160. assert_form_error(response, form, field, errors, msg_prefix='')
  161. assert_template_used(response, template_name, msg_prefix='')
  162. assert_template_not_used(response, template_name, msg_prefix='')
  163. assert_queryset_equal(qs, values, transform=repr)
  164. assert_num_queries(num, func=None, *args, **kwargs)
  165. assert_code(response, status_code, msg_prefix='')
  166. assert_ok(response, msg_prefix='')
  167. assert_mail_count(count, msg=None)
  168. Using With South
  169. ----------------
  170. `South`_ installs its own test command that turns off migrations during
  171. testing. Make sure that django-nose comes *after* ``south`` in
  172. ``INSTALLED_APPS`` so that django_nose's test command is used.
  173. .. _South: http://south.aeracode.org/
  174. Always Passing The Same Options
  175. -------------------------------
  176. To always set the same command line options you can use a `nose.cfg or
  177. setup.cfg`_ (as usual) or you can specify them in settings.py like this::
  178. NOSE_ARGS = ['--failed', '--stop']
  179. .. _nose.cfg or setup.cfg: http://somethingaboutorange.com/mrl/projects/nose/0.11.2/usage.html#configuration
  180. Custom Plugins
  181. --------------
  182. If you need to `make custom plugins`_, you can define each plugin class
  183. somewhere within your app and load them from settings.py like this::
  184. NOSE_PLUGINS = [
  185. 'yourapp.tests.plugins.SystematicDysfunctioner',
  186. # ...
  187. ]
  188. Just like middleware or anything else, each string must be a dot-separated,
  189. importable path to an actual class. Each plugin class will be instantiated and
  190. added to the Nose test runner.
  191. .. _make custom plugins: http://somethingaboutorange.com/mrl/projects/nose/0.11.2/plugins.html#writing-plugins
  192. Older Versions of Django
  193. ------------------------
  194. Upgrading from Django <= 1.3 to Django 1.4
  195. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  196. In versions of Django < 1.4 the project folder was in fact a python package as
  197. well (note the __init__.py in your project root). In Django 1.4, there is no
  198. such file and thus the project is not a python module.
  199. **When you upgrade your Django project to the Django 1.4 layout, you need to
  200. remove the __init__.py file in the root of your project (and move any python
  201. files that reside there other than the manage.py) otherwise you will get a
  202. `ImportError: No module named urls` exception.**
  203. This happens because Nose will intelligently try to populate your sys.path, and
  204. in this particular case includes your parent directory if your project has a
  205. __init__.py file (see: https://github.com/nose-devs/nose/blob/release_1.1.2/nose/importer.py#L134).
  206. This means that even though you have set up your directory structure properly and
  207. set your `ROOT_URLCONF='my_project.urls'` to match the new structure, when running
  208. django-nose's test runner it will try to find your urls.py file in `'my_project.my_project.urls'`.
  209. Upgrading from Django < 1.2
  210. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  211. Django 1.2 switches to a `class-based test runner`_. To use django-nose
  212. with Django 1.2, change your ``TEST_RUNNER`` from ``django_nose.run_tests`` to
  213. ``django_nose.NoseTestSuiteRunner``.
  214. ``django_nose.run_tests`` will continue to work in Django 1.2 but will raise a
  215. warning. In Django 1.3, it will stop working.
  216. If you were using ``django_nose.run_gis_tests``, you should also switch to
  217. ``django_nose.NoseTestSuiteRunner`` and use one of the `spatial backends`_ in
  218. your ``DATABASES`` settings.
  219. .. _class-based test runner: http://docs.djangoproject.com/en/dev/releases/1.2/#function-based-test-runners
  220. .. _spatial backends: http://docs.djangoproject.com/en/dev/ref/contrib/gis/db-api/#id1
  221. Django 1.1
  222. ~~~~~~~~~~
  223. If you want to use django-nose with Django 1.1, use
  224. https://github.com/django-nose/django-nose/tree/django-1.1 or
  225. http://pypi.python.org/pypi/django-nose/0.0.3.
  226. Django 1.0
  227. ~~~~~~~~~~
  228. django-nose does not support Django 1.0.
  229. Recent Version History
  230. ----------------------
  231. 1.3 (2014-12-05)
  232. * Django 1.6 and 1.7 support (conrado, co3k, Nepherhotep, mbertheau)
  233. * Python 3.3 and 3.4 testing and support (frewsxcv, jsocol)
  234. 1.2 (2013-07-23)
  235. * Python 3 support (melinath and jonashaag)
  236. * Django 1.5 compat (fabiosantoscode)
  237. 1.1 (2012-05-19)
  238. * Django TransactionTestCases don't clean up after themselves; they leave
  239. junk in the DB and clean it up only on ``_pre_setup``. Thus, Django makes
  240. sure these tests run last. Now django-nose does, too. This means one fewer
  241. source of failures on existing projects. (Erik Rose)
  242. * Add support for hygienic TransactionTestCases. (Erik Rose)
  243. * Support models that are used only for tests. Just put them in any file
  244. imported in the course of loading tests. No more crazy hacks necessary.
  245. (Erik Rose)
  246. * Make the fixture bundler more conservative, fixing some conceivable
  247. situations in which fixtures would not appear as intended if a
  248. TransactionTestCase found its way into the middle of a bundle. (Erik Rose)
  249. * Fix an error that would surface when using SQLAlchemy with connection
  250. pooling. (Roger Hu)
  251. * Gracefully ignore the new ``--liveserver`` option introduced in Django 1.4;
  252. don't let it through to nose. (Adam DePue)
  253. 1.0 (2012-03-12)
  254. * New fixture-bundling plugin for avoiding needless fixture setup (Erik Rose)
  255. * Moved FastFixtureTestCase in from test-utils, so now all the
  256. fixture-bundling stuff is in one library. (Erik Rose)
  257. * Added the REUSE_DB setting for faster startup and shutdown. (Erik Rose)
  258. * Fixed a crash when printing options with certain verbosities. (Daniel Abel)
  259. * Broke hard dependency on MySQL. Support PostgreSQL. (Roger Hu)
  260. * Support SQLite, both memory- and disk-based. (Roger Hu and Erik Rose)
  261. * Nail down versions of the package requirements. (Daniel Mizyrycki)
  262. 0.1.3 (2010-04-15)
  263. * Even better coverage support (rozza)
  264. * README fixes (carljm and ionelmc)
  265. * optparse OptionGroups are handled better (outofculture)
  266. * nose plugins are loaded before listing options
  267. See more in changelog.txt.
  268. Platform: UNKNOWN
  269. Classifier: Development Status :: 5 - Production/Stable
  270. Classifier: Environment :: Web Environment
  271. Classifier: Framework :: Django
  272. Classifier: Intended Audience :: Developers
  273. Classifier: License :: OSI Approved :: BSD License
  274. Classifier: Operating System :: OS Independent
  275. Classifier: Programming Language :: Python
  276. Classifier: Programming Language :: Python :: 2
  277. Classifier: Programming Language :: Python :: 2.6
  278. Classifier: Programming Language :: Python :: 2.7
  279. Classifier: Programming Language :: Python :: 3
  280. Classifier: Programming Language :: Python :: 3.3
  281. Classifier: Programming Language :: Python :: 3.4
  282. Classifier: Topic :: Software Development :: Testing