Re: [GMG-Devel] Help extract documentation from my brain

[Christopher Allan Webber]

More docs, this one on tests.

                            Writing tests
                            =============

Writing tests is not too hard.  Just look at other examples in
mediagoblin/tests/

1 Running tests 
----------------

Simply use:

./runtests.sh

This basically calls ./bin/nosetests and sets a necessary CELERY
environment variable.  Any arguments that you pass in get passed to
the nosetests command itself.

There are some useful arguments you can pass in while debugging... in
particular:

 --pdb: Enter pdb whenever an exception is raised
 --pdb-failures: Enter pdb whenever an assertion failures happens
                     (honestly, I almost always run --pdb and
                     --pdb-failures at the same time)
 --nocapture: Don't capture stdout.  Useful for catching print
                  statements or if you've done a pdb.set_trace() (if
                  you do pdb.set_trace() and *don't* do this, the
                  tests appear to hang, but haven't really... you just
                  can't see the prompt)
                  

2 Writing tests 
----------------

Look at some other examples in the various test modules and read the
docs:

[http://somethingaboutorange.com/mrl/projects/nose/1.0.0/]

But basically you just want to write functions that start with "test_"
(Or classes similarly starting with Test* and methods like test*).

For things where you want access to an "application", use the
setup_fresh_app decorator, eg like:


  from mediagoblin.tests.tools import setup_fresh_app
  
  @setup_fresh_app
  def test_register_views(test_app):
      [...]

This will setup a fresh "application" for you, turn on "testing
bucket" stuff (more on this in a few) in utils.py if it isn't already,
and clear the "testing buckets" if they have stuff in them.  You can
skip the decorator and call these components manually.  So let's
describe those:

 mediagoblin.tests.tools.get_test_app(): get an application for
      testing... same thing as is passed into the function with the
      setup_fresh_app decorator, and wipes the database and session
      and public_storage/queued_storage things.  What's returned is a
      [WebTest] wrapper around the application.
 mediagoblin.util._activate_testing(): sets TESTS_ENABLED, which
      means that various tools wil cache extra information about
      templates visited, context passed in, emails sent, etc.
 mediagoblin.util.clear_test_buckets(): Clears all the types of
      buckets described above.

One of the less obvious of these "buckets" is the
util.TEMPLATE_TEST_CONTEXT bucket.  Assuming you use
util.render_template() or util.render_to_response(),
util.TEMPLATE_TEST_CONTEXT will be populated with the name of the
template as the key and the context supplied as the value.


[WebTest]: http://pythonpaste.org/webtest/