Python/Справочник по библиотеке Python 2.6

Материал из Викиучебника — открытых книг для открытого мира
Перейти к: навигация, поиск
Python logo and wordmark.svg Документация Python
Эта статья — часть Документации по языку Python

Введение[править]

«Библиотека Python» содержит несколько различных видов компонентов.

В ней содержатся данные типов, которые обычно считаются частью «ядра» в языке, такие как числа или списки. Для этих типов ядро Python’a разделенно на основные формы и места некоторых ограничений на их семантику, но семантику определяет не полностью. (С другой стороны, ядро языка определяет синтаксические правила, такие как написание и приоритеты операторов). Библиотека также содержит встроенные функции и исключения — объекты могут быть использованы в любом месте кода Python’а без необходимости вызова import. Некоторые из них определены в ядре языка, но большинство не имеют большого значения для семантики ядра и только описаны здесь.

Однако, большая часть библиотеки состоит из других модулей. Есть много способов разбирать эту коллекцию. Некоторые модули написаны на С и встроены в интерпретатор Python’a; другие написаны на Питоне и импортированы в форме исходников. Некоторые модули обеспечивают доступ к высокоориентированным возможностям Питона, как печать трассировки стека; доступ к специфичным функциям операционной системы, такие как доступ к определенному оборудованию; другие специфичные для определённых областей применения, таких как мировая паутина. Некоторые модули доступны во всех версиях Питона; другие доступны только когда основные системы поддерживают или нуждаются в них; другие же доступны только исходя из вариантов конфигурации, при которых Питон был скомпилирован и установлен. Это руководство организовано «изнутри»: сначала описание встроенных типов данных, затем встроенных функций и исключений, и наконец модулей, сгрупированных в главы. Порядок следование глав, а также порядок расположения модулей в каждой главе таков, что идёт от наибольнее актуальных до наиболее важных.

Это значит, что если вы начинаете читать это руководство сначала и перейдете на другую главу, когда вам скучно, вы будете получать разумный обзор доступных модулей и областей применения поддерживаемых библиотекой Питона. Конечно, вам не следует это читать как роман — вы также можете просматривать оглавление (в верхней части руководства), или искать конкретные функции, модули или по индексу. И последнее, если вы любите изучать языки не по порядку, выберите случайную страницу (смотрите модуль random) и читайте секцию или две. Независимо от того, в каком порядке вы будете читать это руководство, это поможет начать с главы о встроенных типах, а остальная часть руководства предполагает ознакомление с этим материалом.

Встроенные[править]

Интерпретатор питона имеет некоторое число встроенных математических функций, которые доступны всегда. Они перечислены ниже в алфавитном порядке:

abs(x)

Возвращает модуль числа. Аргумент может быть простой или длинной целочисленной величиной или числом с плавающей точкой. Если аргумент комплексное число, то возвращается его величина.

all(последовательность)

Возвращает True если все значения последовательности правдивые (или последовательность пуста). Эквивалентно:

def all(iterable):
    for element in iterable:
        if not element:
            return False
    return True

Появилось в версии 2.5

any(последовательность)

Возвращает True если хоть один из элементов правдив. Если последовательность пуста возврощает False. Эквивалентно:

def any(iterable):
        for element in iterable:
            if element:
                return True
        return False

Появилось в версии 2.5

basestring()

Это абстрактный тип является суперклассом для str (строка) и unicode(строка Unicode) Он не может быть вызван или обработан, но он может быть использован для тестирования является ли объект экземпляром str или unicode.

isinstance(объект, basestring) <==> isinstance(объект, (str, unicode)). Появилось в версии 2.3.

bin(x)

Конвертирование целого числа в бинарную строку. Результат является действительным выражением Питона Если х не является объектом Питона int, то для него может быть вызван метод __index__(), который вернет целое число.

Появилось в версии 2.6.

bool([x])

Конвертирует значение в булево, используя стандартную процедуру тестирования истинности. Если значение х ложно или отсутствует, то возвращает False(ложь); в другом случае True(истина) bool также является классом, который является подклассом int. У класса bool не может быть подкласса. Он может принимать значение только False(ложь) или True(истина)

Появилось в версии 2.2.1
Изменение в версии 2.3: если аргумент не передается эта функция возвращает False.

callable(объект)

Возвращает True, если объект может быть вызван, False если нет. Если возвращено True, то вызов все ещё может быть неудачным, но если возвращено False, вызов никогда не будет успешным. Отметим, что вызов класса возвращает новый экземпляр; экземпляр класса вызываем, если он имеет метод __call__().

chr(i)

Возвращает строку из одного символа ASCII, код которого равен целому числу. Для примера, chr(97) возвращает строку 'a'. Возвращает ASCII код символа строки. (обратная функция ord()) Число должно быть в пределе [0..255], включительно; ValueError (ошибка значения) генерируется, в случае если значение выходит из этих границ.

unichr(i)

Возвращает строку-unicode с кодом, соответствующим целому числу.
Работает аналогично chr()

classmethod(функция)

Возвращает класс-метод для функции.

Класс-метод получает класс с неявным первым аргументом, например метод получает экземпляр объекта. Декларация класса-метода такова:

class C:
    @classmethod
    def f(cls, arg1, arg2, ...): ...

@classmethod это функция-декоратор

Он может быть вызван как класс (например C.f()) или как экземпляр (например С().f()). Исключения класса игнорируются в его экземпляре. Если класс-метод вызывается как класс, то объект производного класса передается в качестве первого аргумента. Класс-метод отличается от статических методов в C++ и Java. Если все же требуется, то посмотрите staticmethod() в этой главе. Для большей информации по классу-методу, обратитесь к документации в «стандартной иерархии типов»

Появилось в версии 2.2
Изменения в версии 2.4: Добавлен синтаксис для функции-декоратора

cmp(x, y)

Сравнение двух объектов и возвращает целое число в зависимости от результата. Возвращаемое значение отрицательное, если х < y , 0 если x==y и положительное если x > y.

compile(source, filename, mode[, flags[, dont_inherit]])

В процессе…

Non-essential Built-in Functions[править]

Built-in Constants[править]

Constants added by the site module[править]

Средства для разработки [*][править]

unittest — Каркас для модульного тестирования[править]

Появилось в версии 2.1

Каркас модульного тестирования Python, иногда называемый «PyUnit», является Python-версией JUnit Кента Бека и Эрика Гамма. JUnit, в свою очередь, — Java версия каркаса тестирования Smalltalk написанного Кентом. Все перечисленные каркасы являются де-факто стандартными каркасами модульного тестирования для соответствующих языков.

unittest поддерживает автоматизацию тестов, общее использование кода инициализации и завершения тестов, объединение тестов в коллекции и независимость тестов от каркаса выводящего результаты тестирования. Классы модуля unittest упрощают соблюдение перечисленных требований для серии тестов.

Для достижения таких целей в unittest реализуются следующие понятия:


Окружение теста (test fixture)

Под окружением теста подразумевается установка начальных данных, необходимая для выполнения одного или нескольких тестов, а также действия по сбросу начальных данных к исходному положению по завершении теста. Эти процессы могут включать, например, создание временных или промежуточных БД, каталогов, или запуск серверного процесса;

Тестовый вариант (test case)

Тестовый вариант является наименьшим элементом тестирования. Он проверяет соответствие отклика объекта определенным входным данным. В unittest тестовые варианты создаются с помощью базового класса TestCase;

Набор тестов (test suite)

Набор тестов это коллекция тестовых вариантов, наборов тестов, или и того и другого сразу. Набор используется для объединения тестов которые должны выполняться вместе;

Исполнитель тестов

Исполнитель тестов это компонент управляющий выполнением тестов и сообщающий пользователю результаты выполнения. Исполнитель может использовать графический, или текстовый интерфейс, либо возвращать определенное значение, соответствующее результату выполнения тестов.


Понятия тестового варианта и окружения теста реализуются классами TestCase и FunctionTestCase; первый следует использовать при создании новых тестов, а второй используется при интеграции кода уже написанных тестов с каркасом модульных тестов. При создании тестового окружения с помощью TestCase, методы setUp() и tearDown() могут замещаться для обеспечения инициализации и сброса окружения. При использовании FunctionTestCase, для этих целей в конструктор могут передаваться уже существующие функции. При выполнении теста сначала запускается инициализация окружения, если она проходит успешно, то после завершения теста запускается функция сброса окружения, вне зависимости от результатов теста. Для каждого экземпляра TestCase выполняется только единственный тестовый метод, поэтому для каждого теста создается новое окружение.

Наборы тестов реализуются с помощью класса TestSuite. Данный класс позволяет объединять отдельный тесты и наборы тестов. При выполнении набора, выполняются все тесты добавленные непосредственно в набор и в дочерние тестовые наборы.

Исполнитель теста это объект предоставляющий единственный метод run(), принимающий экземпляр класса TestCase или TestSuite как параметр и возвращающий результирующий объект. Результирующим объектом является экземпляр класса TestResult. В комплект unittest входит пример исполнителя теста – класс TextTestRunner, возвращающий результаты тестов в потоке сообщений об ошибках по умолчанию. Альтернативные исполнители тестов могут реализовываться для других сред (таких как графическая среда) без необходимости наследования от определенного класса

Смотрите также:

Модуль doctest – еще один модуль поддержки тестирования с совершенно другим «ароматом».

Простое тестирование SmallTalk: С шаблонами – Оригинальная статья Кента Бека по тестовым каркасам использующим шаблоны, которые использует и unittest

Nose и py.test – Сторонние каркасы для модульного тестирования с более простым синтаксисом написания тестов.

Например func(10) == 42.

python-mock и minimock – Инструменты для создания тестовых квази-объектов (объектов имитирующих внешние ресурсы)

Простой пример[править]

Модуль unittest содержит богатый набор средств для создания и выполнения тестов. В данном разделе демонстрируется, что даже малая часть этих средств достаточна для удовлетворения нужд большинства пользователей.

Вот короткий сценарий для тестирования трех функций из модуля random:

import random
import unittest
class TestSequenceFunctions(unittest.TestCase):

    def setUp(self):
        self.seq = range(10)

    def test_shuffle(self):
        # проверяем, что в перемешанной последовательности 
        #не потерялись элементы
        random.shuffle(self.seq)
        self.seq.sort()
        self.assertEqual(self.seq, range(10))

    def test_choice(self):
        element = random.choice(self.seq)
        self.assertTrue(element in self.seq)

    def test_sample(self):
        self.assertRaises(ValueError, random.sample, self.seq, 20)
        for element in random.sample(self.seq, 5):
            self.assertTrue(element in self.seq)

if __name__ == '__main__':
    unittest.main()

Тестовый вариант создан как подкласс unittest.TestCase. Три отдельных теста заданы с помощью методов, названия которых начинаются с последовательности 'test'. Такое соглашение об наименовании сообщает исполнитель тестов о том, какие методы представляют тесты.

Главной частью всех тестов является вызов assertEqual() для проверки ожидаемого результата, assertTrue() для проверки условия, либо assertRaises() для проверки возбуждения требуемого исключения. Эти методы используются вместо выражения assert, для того чтобы исполнитель тестов мог собрать результаты всех тестов и сформировать отчет.

Если задан метод setUp(), исполнитель тестов вызовет этот метод перед выполнением каждого теста. Аналогично, если задан метод tearDown(), этот метод будет выполняться после каждого теста. В рассмотренном примере setUp() использовался для создания свежей последовательности для каждого теста.

В последнем блоке демонстрируется простой способ выполнения тестов. unittest.main() предоставляет командно-строчный интерфейс к тестовому сценарию. При запуске из командной строки, представленный выше сценарий формирует вывод следующего вида:

...
----------------------------------------------------------------------
Ran 3 tests in 0.000s

OK

Существуют и другие способы выполнение тестов, кроме unittest.main(), причем с большей степенью контроля, не таким скупым выводом и не обязательно запускаемые из командной строки. Например, последние две строки могут быть заменены следующими:

suite = unittest.TestLoader().loadTestsFromTestCase(TestSequenceFunctions)
unittest.TextTestRunner(verbosity=2).run(suite)

Результатом выполнения измененного сценария из интерпретатора, либо из другого сценария, будет следующий вывод:

test_choice (__main__.TestSequenceFunctions) ... ok
test_sample (__main__.TestSequenceFunctions) ... ok
test_shuffle (__main__.TestSequenceFunctions) ... ok

----------------------------------------------------------------------
Ran 3 tests in 0.110s

OK

Приведенные выше примеры демонстрируют наиболее часто используемые функции unittest, достаточные для многих каждодневных задач тестирования. Далее рассматривается полный набор функций, начиная с основных принципов

Организация тестового кода[править]

Основными строительными блоками модульного тестирования являются тестовые варианты – отдельные сценарии, для которые должны устанавливаться начальные значения и проводиться проверка на правильность. В модуле unittest, тестовые варианты представлены экземплярами класса TestCase. Для написания своего тестового сценария Вам требуется написать подкласс класса TestCase, либо использовать FunctionTestCase.

Экземпляр класса производного от TestCase является объектом выполняющим единственный тестовый метод вместе с необязательным кодом настройки и сброса.

Тестовый код экземпляра TestCase должен быть полностью самодостаточным, так, чтобы он мог выполняться изолированно, либо в произвольной комбинации с любым количеством других тестовых вариантов. Простейший подкласс TestCase просто замещает метод runTest() для выполнения определенного тестового кода:

import unittest

class DefaultWidgetSizeTestCase(unittest.TestCase):
    def runTest(self)
        widget = Widget('The widget')
        self.assertEqual(widget.size(), (50, 50), 'incorrect default size')

Обратите внимание, что для того чтобы протестировать что-либо, используется один из методов assert*() или fail*() базового класса TestCase(). Если тест проваливается, поднимается исключение, и unittest идентифицирует тестовый вариант как «провалившийся» (failure). Любые иные исключения воспринимаются как ошибки (errors). Такое разделение позволяет определить место проблемы: failure вызываются неправильными результатами – 5 в том месте, в котором ожидается 6. Errors вызываются некорректным кодом – например, причинойTypeError является неправильный вызов функции

Способ выполнения тестовых вариантов будет описан чуть позже. Сейчас же, отметьте что для того чтобы создать экземпляр такого тестового варианта вызывается его конструктор без аргументов:

testCase = DefaultWidgetSizeTestCase()

Подобные тестовые варианты могут быть многочисленными и установка начальных значений для них может повторяться многократно. В примере выше, создание виджета для каждого из 100 тестовых вариантов для виджетов, означает некрасивое повторение кода.

К счастью, можно избежать таких проблем с кодом установки начальных значений, используя метод setUp(), автоматически вызываемый тестовым каркасом при выполнении теста:

import unittest

class SimpleWidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget('The widget')

class DefaultWidgetSizeTestCase(SimpleWidgetTestCase):
    def runTest(self):
        self.assertEqual(self.widget.size(), (50,50),
                         'incorrect default size')

class WidgetResizeTestCase(SimpleWidgetTestCase):
    def runTest(self):
        self.widget.resize(100,150)
        self.assertEqual(self.widget.size(), (100,150),
                         'wrong size after resize')

Если метод setUp() поднимает исключение во время выполнения теста, каркас полагает что в тесте есть ошибка и метод runTest() не выполняется. Аналогичными образом можно добавить метод tearDown() который сбрасывает изменения в начальных установках после выполнения метода runTest()

class SimpleWidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget('The widget')

    def tearDown(self):
        self.widget.dispose()
        self.widget = None

Если метод setUp() был успешно выполнен, метод tearDown() будет выполнятся вне зависимости от успешности выполнения runtTest().

Описанная рабочая среда для тестового кода называется окружением (fixture). Часто множество небольших тестовых вариантов используют одинаковое окружение. В таких случаях, для класса SimpleWidgetTestCase может создаваться куча подклассов с одним методом, типа DefaultWidgetSizeTestCase. Эта операция отнимает много времени и отбивает всякое желание ей заниматься, поэтому, аналогично с JUnit, unittest предоставляет более простой механизм:

import unittest

class WidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget('The widget')

    def tearDown(self):
        self.widget.dispose()
        self.widget = None

    def test_default_size(self):
        self.assertEqual(self.widget.size(), (50,50),
                         'incorrect default size')

    def test_resize(self):
        self.widget.resize(100,150)
        self.assertEqual(self.widget.size(), (100,150),
                         'wrong size after resize')

В приведенном примере нет метода runTest(), вместо этого есть два разных тестовых метода. Каждый экземпляр класса будут выполнять один из методов test_*() с созданием и уничтожением self.widget при запуске тестового метода. При создании экземпляра требуется указать какой тестовый метод следует выполнять. Это достигается передачей названия метода в конструктор.

defaultSizeTestCase = WidgetTestCase('test_default_size')
resizeTestCase = WidgetTestCase('test_resize')

Экземпляры тестовых вариантов группируются в соответствии с функциями, которые они тестируют. unittest предоставляет механизм такой группировки: тестовые наборы, представляемые классом TestSuite модуля unittest:

widgetTestSuite = unittest.TestSuite()
widgetTestSuite.addTest(WidgetTestCase('test_default_size'))
widgetTestSuite.addTest(WidgetTestCase('test_resize'))

Для упрощения выполнения тестов, как мы убедимся чуть позже, рекомендуется создать в каждом тестовом модуле вызываемый объект, возвращающий предварительно созданный тестовый набор:

def suite():
    suite = unittest.TestSuite()
    suite.addTest(WidgetTestCase('test_default_size'))
    suite.addTest(WidgetTestCase('test_resize'))
    return suite
или даже:
def suite():
    tests = ['test_default_size', 'test_resize']

    return unittest.TestSuite(map(WidgetTestCase, tests))

Поскольку создание подкласса TestCase с несколькими тестовыми функциями со сходными названиями является общей практикой, в unittest есть класс TestLoader, который можно использовать для автоматизации процесса создания тестового набора и наполнения его отдельными тестами. Например, строка:

suite = unittest.TestLoader().loadTestsFromTestCase(WidgetTestCase)

создаст тестовый набор выполняющий методы WidgetTestCase.test_default_size() и WidgetTestCase.test_resize(). TestLoader автоматически находит тестовые методы по префиксу 'test' в названии метода. Обратите внимание, что порядок в котором будут выполняться тесты определяется сортировкой названий тестовых функций с помощью встроенной функции cmp(). Часто возникает необходимость группировать тестовые наборы, например для выполнения тестов для целой системы сразу. С этим нет никаких сложностей, поскольку экземпляры TestSuite могут добавляться в TestSuite, так же как и экземпляры TestCase.

suite1 = module1.TheTestSuite()
suite2 = module2.TheTestSuite()
alltests = unittest.TestSuite([suite1, suite2])

Код тестовых вариантов и тестовых наборов может размещаться в тех же модулях, что и код, который они тестируют (таких как widget.py), но размещение тестового кода в отдельном модуле (таком как test_widget.py) дает ряд преимуществ:

  • Тестовый модуль может выполняться отдельно, из командной строки;
  • Тестовый код проще отделять от поставляемого кода;
  • Меньше искушение изменять тестовый код для большего соответствия тестируемому коду, без веских оснований;
  • Тестовый код следует изменять значительно реже, чем тестируемый код;
  • Проще проводить рефакторинг тестового кода;
  • Тесты для модулей написанных на C должен быть отдельных модулях в любом случае, так почему бы не быть последовательным?
  • При изменении тестовой стратегии, не требуется изменять исходный код.

Повторное использование старого тестового кода[править]

У некоторых пользователей может оказаться тестовый код, который они хотели бы выполнять из unittest без преобразования всех старых тестовых функций в подклассы TestCase. По этой причине, в unittest включен класс FunctionTestCase. Этот подкласс TestCase может использоваться для оборачивания уже существующих тестовых функций. Также обеспечивается поддержка функций установки начальных значений и сброса. Для следующей тестовой функции:

def testSomething():
    something = makeSomething()
    assert something.name is not None
    # ...

возможно создание экземпляра тестового варианта таким образом:

testcase = unittest.FunctionTestCase(testSomething)

При необходимости дополнительного запуска методов установки начального состояния и сброса в ходе выполнения тестового варианта, они должны указываться как в примере:

testcase = unittest.FunctionTestCase(testSomething,
                                     setUp=makeSomethingDB,
                                     tearDown=deleteSomethingDB)

Для упрощения использования уже существующих тестов, unittest поддерживает тесты поднимающие AssertionError для отображения провала теста. Тем не менее, рекомендуется использовать методы TestCase.fail*() и TestCase.assert*(), поскольку в будущих версиях unittest обработка AssertionError может отличаться.

Примечание: Несмотря на то, что с помощью FunctionTestCase можно быстро преобразовать существующую тестовую базу в систему на базе unittest, применение такого подхода не рекомендуется. Затраты времени на создание соответствующих подклассов TestCase многократно окупятся многократным упрощением будущего рефакторинга тестов.

Классы и функции[править]

class unittest.TestCase([methodName])

Экземпляры класса TestCase являются минимальными тестовыми единицами во вселенной unittest. Данный класс предназначен быть базовым классом, с заданием конкретных тестов в его подклассах. Класс реализует интерфейс необходимый исполнителю тестов для выполнения теста, и методы, которые тестовый код может использовать для проверки и сообщения о разных видах провалов тестирования.

Каждый экземпляр TestCase выполняет единственный тестовый метод под названием methodName. Как вы возможно помните, выше приводился пример в котором было что-то вроде этого:

def suite():
    suite = unittest.TestSuite()
    suite.addTest(WidgetTestCase('test_default_size'))
    suite.addTest(WidgetTestCase('test_resize'))
    return suite

В нем создаются два экземпляра WidgetTestCase, каждый из которых выполняет единственный тест. По умолчанию за methodName принимается 'runTest'.

class unittest.FunctionTestCase(testFunc[, setUp[, tearDown[, description]]])

Данный класс реализует часть интерфейса TestCase, позволяющую исполнителю теста выполнить тест, но не предоставляет методов с помощью которых тестовый код может обнаруживать ошибки и сообщать о них. Он используется для создания тестовых вариантов на основе унаследованного тестового кода, позволяя интегрировать его в тестовый каркас на базе unittest.

class unittest.TestSuite([tests])

Класс предоставляет возможность объединения отдельных тестовых вариантов и тестовых наборов. Класс представляет интерфейс необходимый исполнителю тестов для их выполнения, как любых других тестовых вариантов. Выполнение экземпляра TestSuite аналогично итерированию по всему набору тестов, с отдельным запуском каждого теста. Если передается tests, - это должен быть итератор по отдельным тестовым вариантам или другим тестовым наборам которые будут использоваться для начального построения набора. С помощью дополнительных методов класса можно добавлять тестовые варианты и наборы уже после создания экземпляра.

class unittest.TestLoader

Класс отвечает за загрузку тестов в соответствии с различными критериями и их возвращение в обертке TestSuite. Он может проводить загрузку всех тестовых вариантов в заданном модуле или подклассе TestCase.

class unittest.TestResult

Класс используется для сбора информации о тестах которые прошли успешно и провалились.

unittest.defaultTestLoader

Экземпляр класса TestLoader предназначенный для совместного использования. Если нет необходимости в изменении класса TestLoader, вместо постоянного создания новых экземпляров может использоваться этот.

class unittest.TextTestRunner([stream[, descriptions[, verbosity]]])

Базовая реализация тестового исполнителя, выводящая результаты тестов как стандартные ошибки. У класса есть несколько настраиваемых параметров, но в целом он очень прост. Графические приложения выполняющие тестовые наборы должны предоставлять альтернативные реализации.

unittest.main([module[, defaultTest[, argv[, testRunner[, testLoader]]]]])

Командно-строчная программа выполняющая набор тестов, предназначена для реализации простого выполнения тестовых модулей. Простейшим использованием данной функции является включение следующей строки в конец тестового сценария:

if __name__ == '__main__':
    unittest.main()

Аргумент testRunner может быть как классом тестового прогонщика, так и уже созданным экземпляром такого класса. В некоторых случаях, уже существующие тесты могут быть написаны с помощью модуля doctest. Для таких случаев в модуле есть класс DocTestSuite, автоматически создающий экземпляры unittest.TestSuite из уже существующих тестов на базе doctest.

Появилось в версии 2.3.

Объекты TestCase¶[править]

Каждый экземпляр TestCase представляет единственный тест, но в каждом отдельном подклассе может задаваться несколько тестов, но с общим тестовым окружением. Окружение создается и сбрасывается для каждого тестового варианта.

Экземпляры TestCase включают в себя три группы методов: первая используется для запуска теста, вторая используется в реализации теста для проверки условий и сообщении о провалах, и оставшиеся справочные методы позволяют собрать информацию о самом тесте.

В первую группу (выполнения тестов) входят следующие методы:

TestCase.setUp()

Метод вызываемый для подготовки тестового окружения. Он вызывается непосредственно перед вызовом тестового метода. Любые исключения поднятые методом обрабатываются как ошибки, а не как провалы. Реализация по умолчанию не делает ничего.

TestCase.tearDown()

Метод вызываемый сразу после выполнения и записи результата теста. Метод вызывается даже в том случае, если тестовый метод поднял исключение, поэтому при реализации метода в подклассах требуется быть особенно внимательными при проверке внутреннего состояния. Любые исключения поднятые методом обрабатываются как ошибки, а не как провалы. Метод вызывается только в том случае, если метод setUp() был успешно выполнен, вне зависимости от результатов тестового метода. Реализация метода по умолчанию не выполняет ничего.

TestCase.run([result])

Выполняет тест, сохраняет результат в объекте результата теста, переданного в качестве result. Если result не передан, либо None, создается и используется временный объект результата (вызовом метода defaultTestCase()), такой объект результата не возвращается методом.
Аналогичный результат можно получить простым вызовом экземпляра TestCase.

TestCase.debug()

Выполняет тест без сбора результата. Это позволяет исключениям поднятым тестом добраться до вызвавшего объекта и может использоваться для выполнения тестов в отладчике (debugger).

Для проверки и сообщения о провалах, в тестовом коде могут использоваться любые из перечисленных ниже методов:

TestCase.assert_(expr[, msg])
TestCase.failUnless(expr[, msg])
TestCase.assertTrue(expr[, msg]):

Сообщает о провале теста если выражение expr ложно с объяснением ошибки msg, если задано, либо None.

TestCase.assertEqual(first, second[, msg])
TestCase.failUnlessEqual(first, second[, msg])

Проверяет идентичность объектов first и second. Если значения не идентичны, тест проваливается с объяснением msg, либо None.

Обратите внимание, что использование failUnlessEqual() имеет то преимущество, что метод выполняет сравнение, передавая выражение в качестве первого параметра в failUnless(), что позволяет автоматически сформировать значение по умолчанию для msg отображающее одновременно first и second. (На самом деле в 2.6.4 справедливо и для assertEqual, скорее всего описание из старых версий)

TestCase.assertNotEqual(first, second[, msg])
TestCase.failIfEqual(first, second[, msg])

Проверяет неравенство объектов first и second. Если сравниваемые значения равны, тест проваливается с объяснением msg, либо None.

Обратите внимание, что использование failIfEqual() имеет то преимущество, что метод выполняет сравнение, передавая выражение в качестве первого параметра в failUnless(), что позволяет автоматически сформировать значение по умолчанию для msg отображающее одновременно first и second. (На самом деле в 2.6.4 справедливо и для assertNotEqual, скорее всего описание из старых версий)

TestCase.assertAlmostEqual(first, second[, places[, msg]])
TestCase.failUnlessAlmostEqual(first, second[, places[, msg]])

Проверяет примерное равенство объектов first и second вычисляя разницу между значениями, округляя до заданного числа десятичных знаков (по умолчанию 7) и сравнивая с нулем.

Обратите внимание, что сравнение заданного числа десятичных знаков это не то же самое, что сравнение заданного числа значащих цифр. Если значения не признаются равными, тест проваливается с объяснением msg, либо None.

TestCase.assertNotAlmostEqual(first, second[, places[, msg]])
TestCase.failIfAlmostEqual(first, second[, places[, msg]])

Проверяет примерное неравенство first и second вычисляя разницу между значениями, округляя до заданного числа десятичных знаков (по умолчанию 7) и сравнивая с нулем.

Обратите внимание, что сравнение заданного числа десятичных знаков это не то же самое, что сравнение заданного числа значащих цифр. Если значения признаются равными, тест проваливается с объяснением msg, либо None.

TestCase.assertRaises(exception, callable, …)
TestCase.failUnlessRaises(exception, callable, …)

Проверяет поднятие исключения при вызове объекта callable с любыми позиционными либо ключевыми аргументами, также переданными в assertRaises(). Тест проходит если поднимается exception, проваливается если никаких исключений не поднимается, возвращается ошибка, если поднимается исключение отличное от заданного. Для перехвата одного из нескольких типов исключений, в качестве exception может передаваться кортеж с перечисленными классами исключений.

TestCase.failIf(expr[, msg])
TestCase.assertFalse(expr[, msg])

Метод failIf() является инверсией метода failUnless(). Сигнализирует о провале теста если выражение expr истинно с сообщением об ошибке msg либо None.

TestCase.fail([msg])

Безусловно сообщает о провале теста с сообщением msg либо None.

TestCase.failureException

Этот атрибут класса отдает исключение поднимаемое методом test(). Если тестовому каркасу требуется использовать специальное исключение, возможно для передачи дополнительной информации, ему требуется создать подкласс данного исключения для «честной игры» с каркасом. Начальное значение атрибута — AssertionError.

Для сбора информации о тесте тестовый каркас может следующие методы:

TestCase.countTestCases()

Возвращает количество тестов представленных данным тестовым объектом. Для экземпляров TestCase всегда возвращает 1.

TestCase.defaultTestResult()

Возвращает экземпляр класса результатов теста, который следует использовать для данного класса тестового варианта. (если другие экземпляры класса результатов теста не передавались методу run()).

Для экземпляров TestCase метод всегда возвращает экземпляр TestResult; подклассы TestCase могут при необходимости замещать метод.

TestCase.id()

Возвращает строку идентификации конкретного тестового варианта. Обычно строка включает полное название тестового метода, включая названия модуля и класса.

TestCase.shortDescription()

Возвращает однострочное описание теста, либо None если описание не задано. Реализация по умолчанию возвращает первую строку описания (docstring) тестового метода, либо None, если описание не задано.

Объекты TestSuite[править]

Объекты TestSuite ведут себя в основном похоже на объекты TestCase, за тем исключением, что они на самом деле не реализуют тесты. Вместо этого, они используются для объединения тестов в группы тестов которые требуется запускать вместе. В объектах есть ряд дополнительных методов для добавления тестов в экземпляры TestSuite.

TestSuite.addTest(test)

Добавляет экземпляр TestCase либо TestSuite к набору.

TestSuite.addTests(tests)

Добавляет все тесты в итераторе по экземплярам TestCase и TestSuite в данный тестовый набор. Вызов метода эквивалентен итерированию по tests, с вызовом addTest() для каждого элемента.

TestSuite имеет следующие общие методы с TestCase:

TestSuite.run(result)

Выполняет тесты связанные с данным набором, сохраняет результат в объекте результата теста, переданного в качестве result. Обратите внимание, что в отличие от TestCase.run(), TestSuite.run() требует передачи объекта результатов.

TestSuite.debug()

Выполняет тесты, связанные с данным набором без сбора результата. Это позволяет исключениям поднятым тестом добраться до вызвавшего объекта и может использоваться для выполнения тестов в отладчике (debugger).

TestSuite.countTestCases()

Возвращает количество тестов представляемых данным тестовым объектом, включая все отдельные тесты и вложенные наборы.

В типичном сценарии использования объекта TestSuite, метод run() вызывается классом TestRunner, а не пользовательской обвязкой теста.

Объекты TestResult[править]

Объект TestResult хранит результаты выполнения серии тестов. Классы TestCase и TestSuite отвечают за корректную запись результатов тестов. Авторам тестов нет необходимости заниматься записью исходов тестов.

Тестовые каркасы созданные поверх unittest могут требовать доступа к объекту TestResult созданному при выполнении серии тестов, для создания отчетов. Для этих целей экземпляр TestResult возвращается методом TestRunner.run().

При исследовании результатов выполнения серии тестов могут быть интересны следующие атрибуты экземпляров TestResult:

TestResult.errors

Список содержащий двух-элементные кортежи из экземпляров TestCase и строк содержащих отформатированную информацию о состоянии стека (traceback). Каждый кортеж отражает тест поднявший неожиданное исключение.

Изменено в версии 2.2: Содержит отформатированную информацию о состоянии стека вместо результатов sys.exc_info().

TestResult.failures

Список содержащий двух-элементные кортежи из экземпляров TestCase и строк содержащих отформатированную информацию о состоянии стека (traceback). Каждый кортеж отражает тест явно сообщивший о провале теста с помощью методов TestCase.fail*() либо TestCase.assert*().

Изменено в версии 2.2: Содержит отформатированную информацию о состоянии стека вместо результатов sys.exc_info().

TestResult.testsRun

Общее количество уже выполненных тестов.

TestResult.wasSuccessful()

Возвращает True если все уже выполненные тесты прошли успешно, в противном случае возвращает False.

TestResult.stop()

Метод может быть вызван для сигнализации о том, что выполнение серии тестов должна быть прервана установкой атрибута shouldStop класса TestResult в значение True. Объектам TestRunner следует учитывать данный флаг и завершать работу без выполнения каких-либо дополнительных тестов.

Данная функция используется, например, классом TextTestRunner для остановки тестового каркаса когда пользователь с помощью клавиатуры сигнализирует о прерывании проверки. Интерактивные утилиты предоставляющие свою реализацию TestRunner могут использовать эту функцию аналогичным образом.

Следующие методы класса TestResult используются для обслуживания внутренних структур данных, и могут расширяться в подклассах для поддержки дополнительных требований вывода информации. В частности это может быть полезно при создании утилит поддерживающих интерактивное предоставление информации в процессе выполнения тестов.

TestResult.startTest(test)

Вызывается перед выполнением тестового варианта test. Реализация по умолчанию просто увеличивает счетчик testsRun экземпляра.

TestResult.stopTest(test)

Вызывается после завершения тестового варианта test, вне зависимости от исхода теста.

Реализация по умолчанию не делает ничего.

TestResult.addError(test, err)

Вызывается в том случае, если тестовый вариант test поднимает неожиданное исключение. err — кортеж в формате возвращаемого значения sys.exc_info(): (тип, значение, состояние стека).

Реализация по умолчанию добавляет кортеж (test, formatted_err) к атрибуту списка ошибок экземпляра. formatted_err — форматированное состояние стека полученное из err.

TestResult.addFailure(test, err)

Вызывается в том случае, если тестовый вариант test сообщает о провале. err — кортеж в формате возвращаемого значения sys.exc_info(): (тип, значение, состояние стека).

Реализация по умолчанию добавляет кортеж (test, formatted_err) к атрибуту списка провалов экземпляра. formatted_err — форматированное состояние стека полученное из err.

TestResult.addSuccess(test)

Вызывается когда тестовый вариант выполняется успешно. Реализация по умолчанию не делает ничего.

Объекты TestLoader[править]

Класс TestLoader используется для создания тестовых наборов из классов и модулей. Обычно нет необходимости в создании экземпляров данного класса, модуль unittest предоставляет экземпляр доступный для использования как unittest.defaultTestLoader. Тем не менее, использование подклассов или экземпляров позволяет задать значения некоторых настраиваемых параметров класса.

Объекты TestLoader имеют следующие методы:

TestLoader.loadTestsFromTestCase(testCaseClass)

Возвращает набор из всех тестовых вариантов содержащихся в классе testCaseClass производном от класса TestCase.

TestLoader.loadTestsFromModule(module)

Возвращает набор из всех тестовых вариантов заданном модуле. Данный метод просматривает module в поиске классов производных от TestCase и создает по экземпляру каждого класса для каждого тестового метода заданного в классе.

Предупреждение:
При использовании иерархии классов производных от TestCase может оказаться удобным задание тестовых и вспомогательных методов в базовых классах, не предназначенных для непосредственного получения их экземпляров и задание тестового окружения в подклассах. Использование такой техники не очень хорошо совместимо с данным методом, но может оказаться полезным в том случае если необходимо проводить одинаковые тесты в разном тестовом окружении.

TestLoader.loadTestsFromName(name[, module])

Возвращает набор всех тестовых вариантов переданных в строке.

name, — это «имя с точками» которое может указывать на модуль, класс тестового варианта, тестовый метод в классе тестового варианта, экземпляр TestSuite, или на вызываемый объект возвращающий экземпляр TestCase или TestSuite. Проверки на тип объекта на который указывается строка проводятся в том порядке, в котором типы перечислены здесь, то есть метод в классе возможно тестового варианта будет воспринят как «тестовый метод в классе тестового варианта», а не как «вызываемый объект»

Например, для модуля SampleTests содержащего класс SampleTestCase производный от TestCase с тремя тестовыми методами (test_one(), test_two(), и test_three()), по строке 'SampleTests.SampleTestCase' данный метод вернет набор который будет выполнять все три тестовых метода, 'SampleTests.SampleTestCase.test_two' вернет тестовый набор выполняющий только метод test_two().

В строке могут указываться еще не загруженные модули и пакеты, они будут загружены в качестве побочного эффекта. Если в аргументах метода задан модуль module, name обрабатывается относительно указанного модуля.

TestLoader.loadTestsFromNames(names[, module])

Работает аналогично loadTestsFromName(), но принимает поиследовательность строк вместо одной строки. Возвращает тестовый набор поддерживающий все тестовые наборы указанные в строках.

TestLoader.getTestCaseNames(testCaseClass)

Возвращает отсортированную последовательность названий методов обнаруженных в классе testCaseClass, класс должен быть подклассом TestCase.

Следующие атрибуты TestLoader могут настраиваться в подклассах, либо при получении экземпляра класса:

TestLoader.testMethodPrefix

Строка задающая префикс имен методов которые обрабатываются как тестовые методы. Значение по умолчанию — ‘test’ Влияет на getTestCaseNames() и все методы loadTestsFrom*().

TestLoader.sortTestMethodsUsing

Функция используемая для сравнения имен методов при их сортировке в getTestCaseNames() и всех методах loadTestsFrom*(). Значение по умолчанию, встроенная функция cmp(). Для атрибута также может быть установлено значение None для отмены сортировки.

TestLoader.suiteClass Вызываемый объект создающий тестовый набор из списка тестов. В итоговом объекте никакие методы не требуются.

Значение по умолчанию: класс TestSuite.

Влияет на все методы loadTestsFrom*().