Django и doctest

Doctests использует стандартный моудль Python doctest, который ищет тесты в строках докуентации. Здесь вкратце описывается как же он работает, за более подробной информацией обращайтесь к официальной документации.

What’s a docstring?

Хорошее объяснение работы можно найти в PEP 257:

Строка документации - строковый литерал, который идёт первым в модуле, функции, методе или классе. К ней можно обратиться через атрибут __doc__.

Например, в строке документации этой функции описано что же она делает:

def add_two(num):
    "Return the result of adding two to the provided number."
    return num + 2

Поскольку тесты зачастую прекрасно документируют код, писать их в строке документации - отличная идея. И код протестирован, и документация написана.

Как и юнит-тесты, doctest`ы ищутся в двух местах:

  • Файл models.py. Вы можете определить doctest`ы на уровне модуля или на уровне конкретной модели. Обычная практика тесты уровня приложения писать в строках документации к модулю, а для модели использовать их собственную.

  • Файл tests.py в каталоге приложения, т.е. там, где лежит models.py. Этот файл – хук для doctest`ов, которые не связаны непосредственно с какой-то моделью.

Этот пример эквивалентен примеру, который был приведён при рассмотрении юнит-тестов:

# models.py

from django.db import models

class Animal(models.Model):
    """
    An animal that knows how to make noise

    # Create some animals
    >>> lion = Animal.objects.create(name="lion", sound="roar")
    >>> cat = Animal.objects.create(name="cat", sound="meow")

    # Make 'em speak
    >>> lion.speak()
    'The lion says "roar"'
    >>> cat.speak()
    'The cat says "meow"'
    """
    name = models.CharField(max_length=20)
    sound = models.CharField(max_length=20)

    def speak(self):
        return 'The %s says "%s"' % (self.name, self.sound)

когда вы run your tests, будет найдены строки документации, которые выглядит как сессия Python в интерпретаторе, и затем выполнены.

При выполнении тестов для моделей создаётся временная база данных. Таким образом, при любом обращении к базе данных (например, создание и сохранение экземпляра) реальные таблицы не пострадают. Однако, состояние БД между выполнением тестов из разных строк документации не сохраняется, так что, если требуются зависимости от других моделей, надо самому позаботиться о дампах или фикстурах. Подробнее про фикстуры - fixtures. Не забудьте дать права пользователю БД на создание баз: CREATE DATABASE.

За более подробной информацией по поводу doctest смотрите документацию Python.