Added first stab at model and DB-API unit tests

git-svn-id: http://code.djangoproject.com/svn/django/trunk@336 bcc190cf-cafb-0310-a4f2-bffc1f526a37

tests/runtests.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python
+
+import os, sys, time, traceback
+
+# doctest is included in the same package as this module, because this testing
+# framework uses features only available in the Python 2.4 version of doctest,
+# and Django aims to work with Python 2.3+.
+import doctest
+
+APP_NAME = 'testapp'
+TEST_DATABASE_NAME = 'django_test_db'
+
+error_list = []
+def log_error(model_name, title, description):
+    error_list.append({
+        'title': "%r model: %s" % (model_name, title),
+        'description': description,
+    })
+
+class DjangoDoctestRunner(doctest.DocTestRunner):
+    def __init__(self, verbosity_level, *args, **kwargs):
+        self.verbosity_level = verbosity_level
+        doctest.DocTestRunner.__init__(self, *args, **kwargs)
+
+    def report_start(self, out, test, example):
+        if self.verbosity_level > 1:
+            out("  >>> %s\n" % example.source.strip())
+
+    def report_failure(self, out, test, example, got):
+        log_error(test.name, "API test failed",
+            "Code: %r\nLine: %s\nExpected: %r\nGot: %r" % (example.source.strip(), example.lineno, example.want, got))
+
+    def report_unexpected_exception(self, out, test, example, exc_info):
+        tb = ''.join(traceback.format_exception(*exc_info)[1:])
+        log_error(test.name, "API test raised an exception",
+            "Code: %r\nLine: %s\nException: %s" % (example.source.strip(), example.lineno, tb))
+
+class TestRunner:
+    def __init__(self, verbosity_level=0):
+        self.verbosity_level = verbosity_level
+
+    def output(self, required_level, message):
+        if self.verbosity_level > required_level - 1:
+            print message
+
+    def run_tests(self):
+        from django.conf import settings
+        from django.core.db import db
+        from django.core import management
+
+        # Manually set INSTALLED_APPS to point to the test app.
+        settings.INSTALLED_APPS = (APP_NAME,)
+
+        # Create the test database and connect to it. We need autocommit() because
+        # PostgreSQL doesn't allow CREATE DATABASE statements within transactions.
+        cursor = db.cursor()
+        try:
+            db.connection.autocommit()
+        except AttributeError:
+            pass
+        self.output(1, "Creating test database")
+        try:
+            cursor.execute("CREATE DATABASE %s" % TEST_DATABASE_NAME)
+        except:
+            confirm = raw_input("The test database, %s, already exists. Type 'yes' to delete it, or 'no' to cancel: " % TEST_DATABASE_NAME)
+            if confirm == 'yes':
+                cursor.execute("DROP DATABASE %s" % TEST_DATABASE_NAME)
+                cursor.execute("CREATE DATABASE %s" % TEST_DATABASE_NAME)
+            else:
+                print "Tests cancelled."
+                return
+        db.close()
+        old_database_name = settings.DATABASE_NAME
+        settings.DATABASE_NAME = TEST_DATABASE_NAME
+
+        # Initialize the test database.
+        cursor = db.cursor()
+        self.output(1, "Initializing test database")
+        management.init()
+
+        # Run the tests for each model within APP_NAME/models.
+        model_dir = os.path.join(os.path.dirname(__file__), APP_NAME, 'models')
+        test_models = [f[:-3] for f in os.listdir(model_dir) if f.endswith('.py') and not f.startswith('__init__')]
+        for model_name in test_models:
+            self.output(1, "%s model: Importing" % model_name)
+            try:
+                mod = __import__(APP_NAME + '.models.' + model_name, '', '', [''])
+            except Exception, e:
+                log_error(model_name, "Error while importing", ''.join(traceback.format_exception(*sys.exc_info())[1:]))
+                continue
+            self.output(1, "%s model: Installing" % model_name)
+            management.install(mod)
+
+            # Run the API tests.
+            p = doctest.DocTestParser()
+            test_namespace = dict([(m._meta.module_name, getattr(mod, m._meta.module_name)) for m in mod._MODELS])
+            dtest = p.get_doctest(mod.API_TESTS, test_namespace, model_name, None, None)
+            # Manually set verbose=False, because "-v" command-line parameter
+            # has side effects on doctest TestRunner class.
+            runner = DjangoDoctestRunner(verbosity_level=verbosity_level, verbose=False)
+            self.output(1, "%s model: Running tests" % model_name)
+            runner.run(dtest, clear_globs=True, out=sys.stdout.write)
+
+        # Remove the test database, to clean up after ourselves. Connect to the
+        # previous database (not the test database) to do so, because it's not
+        # allowed to delete a database while being connected to it.
+        db.close()
+        settings.DATABASE_NAME = old_database_name
+        cursor = db.cursor()
+        self.output(1, "Deleting test database")
+        try:
+            db.connection.autocommit()
+        except AttributeError:
+            pass
+        else:
+            time.sleep(1) # To avoid "database is being accessed by other users" errors.
+        cursor.execute("DROP DATABASE %s" % TEST_DATABASE_NAME)
+
+        # Display output.
+        if error_list:
+            print "Got %s error%s:" % (len(error_list), len(error_list) != 1 and 's' or '')
+            for d in error_list:
+                print
+                print d['title']
+                print "=" * len(d['title'])
+                print d['description']
+        else:
+            print "All tests passed."
+
+if __name__ == "__main__":
+    from optparse import OptionParser
+    parser = OptionParser()
+    parser.add_option('-v', help='How verbose should the output be? Choices are 0, 1 and 2, where 2 is most verbose. Default is 0.',
+        type='choice', choices=['0', '1', '2'])
+    options, args = parser.parse_args()
+    verbosity_level = 0
+    if options.v:
+        verbosity_level = int(options.v)
+    t = TestRunner(verbosity_level)
+    t.run_tests()

tests/testapp/models/__init__.py

@@ -0,0 +1 @@
+__all__ = ['basic', 'repr', 'custom_methods', 'many_to_one', 'many_to_many', 'ordering']

tests/testapp/models/basic.py

@@ -0,0 +1,68 @@
+"""
+1. Bare-bones model
+
+This is a basic model with only two non-primary-key fields.
+"""
+
+from django.core import meta
+
+class Article(meta.Model):
+    fields = (
+        meta.CharField('headline', maxlength=100),
+        meta.DateTimeField('pub_date'),
+    )
+
+API_TESTS = """
+# No articles are in the system yet.
+>>> articles.get_list()
+[]
+
+# Create an Article.
+>>> from datetime import datetime
+>>> a = articles.Article(id=None, headline='Area man programs in Python', pub_date=datetime(2005, 7, 28))
+
+# Save it into the database. You have to call save() explicitly.
+>>> a.save()
+
+# Now it has an ID. Note it's a long integer, as designated by the trailing "L".
+>>> a.id
+1L
+
+# Access database columns via Python attributes.
+>>> a.headline
+'Area man programs in Python'
+>>> a.pub_date
+datetime.datetime(2005, 7, 28, 0, 0)
+
+# Change values by changing the attributes, then calling save().
+>>> a.headline = 'Area woman programs in Python'
+>>> a.save()
+
+# get_list() displays all the articles in the database. Note that the article
+# is represented by "<Article object>", because we haven't given the Article
+# model a __repr__() method.
+>>> articles.get_list()
+[<Article object>]
+
+# Django provides a rich database lookup API that's entirely driven by
+# keyword arguments.
+>>> articles.get_object(id__exact=1)
+<Article object>
+>>> articles.get_object(headline__startswith='Area woman')
+<Article object>
+>>> articles.get_object(pub_date__year=2005)
+<Article object>
+
+# Django raises an ArticleDoesNotExist exception for get_object()
+>>> articles.get_object(id__exact=2)
+Traceback (most recent call last):
+    ...
+ArticleDoesNotExist: Article does not exist for {'id__exact': 2}
+
+# Lookup by a primary key is the most common case, so Django provides a
+# shortcut for primary-key exact lookups.
+# The following is identical to articles.get_object(id__exact=1).
+>>> articles.get_object(pk=1)
+<Article object>
+
+"""

tests/testapp/models/custom_methods.py

@@ -0,0 +1,72 @@
+"""
+3. Giving models custom methods and custom module-level functions
+
+Any method you add to a model will be available to instances.
+
+Custom methods have the same namespace as if the model class were defined
+in the dynamically-generated module. That is, methods can access
+``get_list()``, ``get_object()``, ``AddManipulator``, and all other
+module-level objects.
+
+Also, custom methods have access to a few commonly-used objects for
+convenience:
+
+    * The ``datetime`` module from Python's standard library.
+    * The ``db`` object from ``django.core.db``. This represents the database
+      connection, so you can do custom queries via a cursor object.
+
+If your model method starts with "_module_", it'll be a module-level function
+instead of a method. Otherwise, custom module-level functions have the same
+namespace as custom methods.
+"""
+
+from django.core import meta
+
+class Article(meta.Model):
+    fields = (
+        meta.CharField('headline', maxlength=100),
+        meta.DateField('pub_date'),
+    )
+
+    def __repr__(self):
+        return self.headline
+
+    def was_published_today(self):
+        return self.pub_date == datetime.date.today()
+
+    def get_articles_from_same_day_1(self):
+        return get_list(id__ne=self.id, pub_date__exact=self.pub_date)
+
+    def get_articles_from_same_day_2(self):
+        """
+        Verbose version of get_articles_from_same_day_1, which does a custom
+        database query for the sake of demonstration.
+        """
+        cursor = db.cursor()
+        cursor.execute("""
+            SELECT id, headline, pub_date
+            FROM custom_methods_articles
+            WHERE pub_date = %s
+                AND id != %s""", [str(self.pub_date), self.id])
+        return [Article(*row) for row in cursor.fetchall()]
+
+API_TESTS = """
+# Create a couple of Articles.
+>>> from datetime import datetime
+>>> a = articles.Article(id=None, headline='Area man programs in Python', pub_date=datetime(2005, 7, 27))
+>>> a.save()
+>>> b = articles.Article(id=None, headline='Beatles reunite', pub_date=datetime(2005, 7, 27))
+>>> b.save()
+
+# Test the custom methods.
+>>> a.was_published_today()
+False
+>>> a.get_articles_from_same_day_1()
+[Beatles reunite]
+>>> a.get_articles_from_same_day_2()
+[Beatles reunite]
+>>> b.get_articles_from_same_day_1()
+[Area man programs in Python]
+>>> b.get_articles_from_same_day_2()
+[Area man programs in Python]
+"""

tests/testapp/models/many_to_many.py

@@ -0,0 +1,66 @@
+"""
+5. Many-to-many relationships
+
+To define a many-to-many relationship, use ManyToManyField().
+
+In this example, an article can be published in multiple publications,
+and a publication has multiple articles.
+"""
+
+from django.core import meta
+
+class Publication(meta.Model):
+    fields = (
+        meta.CharField('title', maxlength=30),
+    )
+
+    def __repr__(self):
+        return self.title
+
+class Article(meta.Model):
+    fields = (
+        meta.CharField('headline', maxlength=100),
+        meta.ManyToManyField(Publication),
+    )
+
+    def __repr__(self):
+        return self.headline
+
+API_TESTS = """
+# Create a couple of Publications.
+>>> p1 = publications.Publication(id=None, title='The Python Journal')
+>>> p1.save()
+>>> p2 = publications.Publication(id=None, title='Science News')
+>>> p2.save()
+
+# Create an Article.
+>>> a1 = articles.Article(id=None, headline='Django lets you build Web apps easily')
+>>> a1.save()
+
+# Associate the Article with one Publication. set_publications() returns a
+# boolean, representing whether any records were added or deleted.
+>>> a1.set_publications([p1.id])
+True
+
+# If we set it again, it'll return False, because the list of Publications
+# hasn't changed.
+>>> a1.set_publications([p1.id])
+False
+
+# Create another Article, and set it to appear in both Publications.
+>>> a2 = articles.Article(id=None, headline='NASA uses Python')
+>>> a2.save()
+>>> a2.set_publications([p1.id, p2.id])
+True
+>>> a2.set_publications([p1.id])
+True
+>>> a2.set_publications([p1.id, p2.id])
+True
+
+# Article objects have access to their related Publication objects.
+>>> a1.get_publication_list()
+[The Python Journal]
+>>> a2.get_publication_list()
+[The Python Journal, Science News]
+
+"""

tests/testapp/models/many_to_one.py

@@ -0,0 +1,73 @@
+"""
+4. Many-to-one relationships
+
+To define a many-to-one relationship, use ForeignKey().
+"""
+
+from django.core import meta
+
+class Reporter(meta.Model):
+    fields = (
+        meta.CharField('first_name', maxlength=30),
+        meta.CharField('last_name', maxlength=30),
+    )
+
+    def __repr__(self):
+        return "%s %s" % (self.first_name, self.last_name)
+
+class Article(meta.Model):
+    fields = (
+        meta.CharField('headline', maxlength=100),
+        meta.DateField('pub_date'),
+        meta.ForeignKey(Reporter),
+    )
+
+    def __repr__(self):
+        return self.headline
+
+API_TESTS = """
+# Create a Reporter.
+>>> r = reporters.Reporter(id=None, first_name='John', last_name='Smith')
+>>> r.save()
+
+# Create an Article.
+>>> from datetime import datetime
+>>> a = articles.Article(id=None, headline='This is a test', pub_date=datetime(2005, 7, 27), reporter_id=r.id)
+>>> a.save()
+
+>>> a.reporter_id
+1L
+
+>>> a.get_reporter()
+John Smith
+
+# Article objects have access to their related Reporter objects.
+>>> r = a.get_reporter()
+>>> r.first_name, r.last_name
+('John', 'Smith')
+
+# Create an Article via the Reporter object.
+>>> new_article = r.add_article(headline="John's second story", pub_date=datetime(2005, 7, 28))
+>>> new_article
+John's second story
+>>> new_article.reporter_id
+1
+
+# Reporter objects have access to their related Article objects.
+>>> r.get_article_list(order_by=['pub_date'])
+[This is a test, John's second story]
+
+>>> r.get_article(headline__startswith='This')
+This is a test
+
+>>> r.get_article_count()
+2L
+
+# The API automatically follows relationships as far as you need.
+# Use double underscores to separate relationships.
+# This works as many levels deep as you want. There's no limit.
+# Find all Articles for any Reporter whose first name is "John".
+>>> articles.get_list(reporter__first_name__exact='John', order_by=['pub_date'])
+[This is a test, John's second story]
+
+"""

tests/testapp/models/ordering.py

@@ -0,0 +1,51 @@
+"""
+6. Specifying ordering
+
+Specify default ordering for a model using the ``ordering`` attribute, which
+should be a list or tuple of field names. This tells Django how to order the
+results of ``get_list()`` and other similar functions.
+
+If a field name in ``ordering`` starts with a hyphen, that field will be
+ordered in descending order. Otherwise, it'll be ordered in ascending order.
+The special-case field name ``"?"`` specifies random order.
+
+The ordering attribute is not required. If you leave it off, ordering will be
+undefined -- not random, just undefined.
+"""
+
+from django.core import meta
+
+class Article(meta.Model):
+    fields = (
+        meta.CharField('headline', maxlength=100),
+        meta.DateTimeField('pub_date'),
+    )
+    ordering = ('-pub_date', 'headline')
+
+    def __repr__(self):
+        return self.headline
+
+API_TESTS = """
+# Create a couple of Articles.
+>>> from datetime import datetime
+>>> a1 = articles.Article(id=None, headline='Article 1', pub_date=datetime(2005, 7, 26))
+>>> a1.save()
+>>> a2 = articles.Article(id=None, headline='Article 2', pub_date=datetime(2005, 7, 27))
+>>> a2.save()
+>>> a3 = articles.Article(id=None, headline='Article 3', pub_date=datetime(2005, 7, 27))
+>>> a3.save()
+>>> a4 = articles.Article(id=None, headline='Article 4', pub_date=datetime(2005, 7, 28))
+>>> a4.save()
+
+# By default, articles.get_list() orders by pub_date descending, then
+# headline ascending.
+>>> articles.get_list()
+[Article 4, Article 2, Article 3, Article 1]
+
+# Override ordering with order_by, which is in the same format as the ordering
+# attribute in models.
+>>> articles.get_list(order_by=['headline'])
+[Article 1, Article 2, Article 3, Article 4]
+>>> articles.get_list(order_by=['pub_date', '-headline'])
+[Article 1, Article 3, Article 2, Article 4]
+"""

tests/testapp/models/repr.py

@@ -0,0 +1,33 @@
+"""
+2. Adding __repr__() to models
+
+Although it's not a strict requirement, each model should have a ``__repr__()``
+method to return a "human-readable" representation of the object. Do this not
+only for your own sanity when dealing with the interactive prompt, but also
+because objects' representations are used throughout Django's
+automatically-generated admin.
+"""
+
+from django.core import meta
+
+class Article(meta.Model):
+    fields = (
+        meta.CharField('headline', maxlength=100),
+        meta.DateTimeField('pub_date'),
+    )
+
+    def __repr__(self):
+        return self.headline
+
+API_TESTS = """
+# Create an Article.
+>>> from datetime import datetime
+>>> a = articles.Article(id=None, headline='Area man programs in Python', pub_date=datetime(2005, 7, 28))
+>>> a.save()
+
+>>> repr(a)
+'Area man programs in Python'
+
+>>> a
+Area man programs in Python
+"""