Утилиты тестирования

Очень часто вы хотите протестировать свое приложение или просто проверить вывод из интерактивной сессии Python. Теоретически это довольно просто, потому что вы можете смоделировать среду WSGI и вызвать приложение с фиктивными start_response и итерировать по итератору приложения, но есть, по мнению некоторых, лучшие способы взаимодействия с приложением.

Погружение

Werkzeug предоставляет объект Client, которому вы можете передать приложение WSGI (и необязательно обёртку ответа), что позволяет отправлять виртуальные запросы приложению.

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

>>> from werkzeug.test import Client
>>> from werkzeug.testapp import test_app
>>> from werkzeug.wrappers import BaseResponse
>>> c = Client(test_app, BaseResponse)
>>> resp = c.get('/')
>>> resp.status_code
200
>>> resp.headers
Headers([('Content-Type', 'text/html; charset=utf-8'), ('Content-Length', '8339')])
>>> resp.data.splitlines()[0]
'<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"'

Или без определения обёртки:

>>> c = Client(test_app)
>>> app_iter, status, headers = c.get('/')
>>> status
'200 OK'
>>> headers
[('Content-Type', 'text/html; charset=utf-8'), ('Content-Length', '8339')]
>>> ''.join(app_iter).splitlines()[0]
'<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"'

Создание среды

Новая в версии 0.5.

Самый простой способ интерактивно тестировать приложения — использовать EnvironBuilder. Он может создавать как стандартные среды WSGI, так и объекты запросов.

Следующий пример создаёт среду WSGI с одним загруженным файлом и полем формы:

>>> from werkzeug.test import EnvironBuilder
>>> from StringIO import StringIO
>>> builder = EnvironBuilder(method='POST', data={'foo': 'this is some text',
...      'file': (StringIO('my file contents'), 'test.txt')})
>>> env = builder.get_environ()

Полученная среда — это обычная среда WSGI, которую можно использовать для дальнейшей обработки:

>>> from werkzeug.wrappers import Request
>>> req = Request(env)
>>> req.form['foo']
u'this is some text'
>>> req.files['file']
<FileStorage: u'test.txt' ('text/plain')>
>>> req.files['file'].read()
'my file contents'

EnvironBuilder автоматически определяет тип содержимого, если вы передаёте словарь в конструктор как data. Если вы предоставляете строку или поток ввода, вы должны сделать это сами.

По умолчанию он будет пытаться использовать application/x-www-form-urlencoded и использовать только multipart/form-data если файлы загружаются:

>>> builder = EnvironBuilder(method='POST', data={'foo': 'bar'})
>>> builder.content_type
'application/x-www-form-urlencoded'
>>> builder.files['foo'] = StringIO('contents')
>>> builder.content_type
'multipart/form-data'

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

>>> builder = EnvironBuilder(method='POST', data='{"json": "this is"}')
>>> builder.content_type
>>> builder.content_type = 'application/json'

Тестирование API

class werkzeug.test.EnvironBuilder(path='/', base_url=None, query_string=None, method='GET', input_stream=None, content_type=None, content_length=None, errors_stream=None, multithread=False, multiprocess=False, run_once=False, headers=None, data=None, environ_base=None, environ_overrides=None, charset='utf-8', mimetype=None, json=None)

Этот класс можно использовать для удобного создания WSGI-среды в целях тестирования. Он может использоваться для быстрого создания WSGI-сред или объектов запроса из произвольных данных.

Подпись этого класса также используется в некоторых других местах начиная с Werkzeug 0.5 (create_environ(), BaseResponse.from_values(), Client.open()). По этой причине большая часть функциональности доступна только через конструктор.

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

data может принимать следующие значения:

объект str или bytes: Объект преобразуется в input_stream, устанавливается content_length, и необходимо указать content_type.
строку dict или MultiDict: Ключи должны быть строками. Значения могут быть любыми из следующих объектов, или списком из них:
- объект, подобный file: Такие объекты автоматически преобразуются в объекты FileStorage.
- объект tuple: Метод add_file() вызывается с ключом и распакованными элементами tuple в качестве позиционных аргументов.
- строка str: Строка устанавливается как данные формы для соответствующего ключа.
объект-поток: Содержимое объекта загружается в память и обрабатывается как обычный str или bytes.

Параметры:

Параметры:	path – путь к запросу. В WSGI-среде это отобразится как `PATH_INFO`. Если `query_string` не определено, а в `path` есть знак вопроса, всё после него используется как строка запроса. base_url – базовый URL, используемый для извлечения схемы URL, хоста (имя сервера + порт сервера) и корня скрипта (`SCRIPT_NAME`). query_string – необязательная строка или словарь с параметрами URL. method – HTTP-метод, по умолчанию `GET`. input_stream – необязательный поток ввода. Не указывайте его и `data`. Как только поток ввода установлен, вы не можете изменить `args` и `files`, если не установите `input_stream` в `None` снова. content_type – тип контента запроса. Начиная с версии 0.5, его не нужно указывать при указании файлов и данных формы через `data`. content_length – длина контента запроса. Не нужно указывать, если данные предоставляются через `data`. errors_stream – необязательный поток ошибок, используемый для `wsgi.errors`. По умолчанию `stderr`. multithread – управляет `wsgi.multithread`. По умолчанию `False`. multiprocess – управляет `wsgi.multiprocess`. По умолчанию `False`. run_once – управляет `wsgi.run_once`. По умолчанию `False`. headers – необязательный список или объект `Headers` заголовков. data – строка или словарь данных формы или объект файла. См. объяснение выше. json – объект, который будет сериализован и присвоен `data`. По умолчанию устанавливает тип контента на `"application/json"`. Сериализуется функцией, присвоенной `json_dumps`. environ_base – необязательный словарь со значениями по умолчанию среды. environ_overrides – необязательный словарь с переопределениями среды. charset – кодировка, используемая для кодирования данных Unicode.

path – путь к запросу. В WSGI-среде это отобразится как PATH_INFO. Если query_string не определено, а в path есть знак вопроса, всё после него используется как строка запроса.
base_url – базовый URL, используемый для извлечения схемы URL, хоста (имя сервера + порт сервера) и корня скрипта (SCRIPT_NAME).
query_string – необязательная строка или словарь с параметрами URL.
method – HTTP-метод, по умолчанию GET.
input_stream – необязательный поток ввода. Не указывайте его и data. Как только поток ввода установлен, вы не можете изменить args и files, если не установите input_stream в None снова.
content_type – тип контента запроса. Начиная с версии 0.5, его не нужно указывать при указании файлов и данных формы через data.
content_length – длина контента запроса. Не нужно указывать, если данные предоставляются через data.
errors_stream – необязательный поток ошибок, используемый для wsgi.errors. По умолчанию stderr.
multithread – управляет wsgi.multithread. По умолчанию False.
multiprocess – управляет wsgi.multiprocess. По умолчанию False.
run_once – управляет wsgi.run_once. По умолчанию False.
headers – необязательный список или объект Headers заголовков.
data – строка или словарь данных формы или объект файла. См. объяснение выше.
json – объект, который будет сериализован и присвоен data. По умолчанию устанавливает тип контента на "application/json". Сериализуется функцией, присвоенной json_dumps.
environ_base – необязательный словарь со значениями по умолчанию среды.
environ_overrides – необязательный словарь с переопределениями среды.
charset – кодировка, используемая для кодирования данных Unicode.

Добавлено в версии 0.15: Параметр json и метод json_dumps().

Добавлено в версии 0.15: В среде environ есть ключи REQUEST_URI и RAW_URI, содержащие путь до проценто-декодирования. Это не часть WSGI PEP, но многие WSGI-серверы включают его.

Изменено в версии 0.6: path и base_url теперь могут быть строками Unicode, которые кодируются с использованием iri_to_uri().

path: Путь к приложению. (также известен как PATH_INFO)

charset: Кодировка, используемая для кодирования данных Unicode.

headers: Объект Headers с заголовками запроса.

errors_stream: Поток ошибок, используемый для потока wsgi.errors.

multithread: Значение wsgi.multithread

multiprocess: Значение wsgi.multiprocess

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

environ_overrides: Словарь со значениями, используемыми для переопределения сгенерированной среды.

input_stream: Необязательный поток ввода. Он и form / files взаимоисключающие. Также не предоставляйте этот поток, если метод запроса не POST / PUT или что-то аналогичное.

args: Аргументы URL в формате MultiDict.

base_url: Базовый URL используется для извлечения схемы URL, имени хоста, порта и пути к корню.

close(): Закрывает все файлы. Если вы поместили реальные file объекты в словарь files, вы можете вызвать этот метод, чтобы автоматически закрыть их все одним разом.

content_length: Длина контента как целое число. Отражается из и в headers. Не устанавливайте, если вы устанавливаете files или form для автоматического определения.

content_type: Тип контента запроса. Отражается из и в headers. Не устанавливайте, если вы устанавливаете files или form для автоматического определения.

files: Словарь загруженных файлов. Можно использовать метод add_file() для добавления новых файлов в словарь.

form: Словарь значений формы.

classmethod from_environ(environ, **kwargs): Преобразует словарь environ обратно в билдер. Любые дополнительные kwargs переопределяют аргументы, извлеченные из environ.

Добавлено в версии 0.15.

get_environ(): Возвращает построенную среду environ.

Изменено в версии 0.15: Заголовки типа и длины контента устанавливаются на основе обнаружения потока ввода. Ранее это устанавливало только WSGI-ключи.

END_OF_DOCUMENT_MARKER

get_request(cls=None)

Возвращает запрос с данными. Если класс запроса не указан, используется request_class.

Параметры:	cls – Обёртка запроса для использования.

input_stream: Необязательный входной поток. Если вы его зададите, он очистит form и files.

static json_dumps(obj, *, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False, **kw): Функция сериализации, используемая, когда передаётся json.

mimetype: Тип MIME (тип содержимого без кодировки и т. д.)

Введено в версии 0.14.

mimetype_params: Параметры типа MIME в виде словаря. Например, если тип содержимого text/html; charset=utf-8, параметры будут {'charset': 'utf-8'}.

Введено в версии 0.14.

query_string: Строка запроса. Если вы зададите её как строку, args больше недоступна.

request_class: Псевдоним для werkzeug.wrappers.base_request.BaseRequest

server_name: Имя сервера (только для чтения, используйте host для задания).

server_port: Порт сервера как целое число (только для чтения, используйте host для задания).

server_protocol = 'HTTP/1.1': Протокол сервера для использования. По умолчанию HTTP/1.1

wsgi_version = (1, 0): Версия WSGI для использования. По умолчанию (1, 0)

class werkzeug.test.Client(application, response_wrapper=None, use_cookies=True, allow_subdomain_redirects=False)

Этот класс позволяет отправлять запросы к обернутому приложению.

Обёртка ответа может быть классом или функцией-фабрикой, которая принимает три аргумента: app_iter, status и headers. По умолчанию обёртка ответа просто возвращает кортеж.

Пример:

class ClientResponse(BaseResponse):
    ...

client = Client(MyApplication(), response_wrapper=ClientResponse)

Параметр use_cookies указывает, следует ли хранить и отправлять cookie для последующих запросов. По умолчанию это True, но передача False отключит это поведение.

Если вы хотите запросить какой-либо поддомен вашего приложения, вы можете установить allow_subdomain_redirects на True, как будто нет, внешние перенаправления запрещены.

Введено в версии 0.5: use_cookies появилось в этой версии. Более ранние версии не обеспечивали встроенную поддержку cookie.

Введено в версии 0.14: Параметр mimetype был добавлен.

Введено в версии 0.15: Параметр json.

open(*args, **kwargs)

Принимает те же аргументы, что и класс EnvironBuilder с некоторыми дополнениями: Вы можете предоставить EnvironBuilder или WSGI-среду в качестве единственного аргумента вместо аргументов EnvironBuilder и двух необязательных ключевых аргументов (as_tuple, buffered) которые изменяют тип возвращаемого значения или способ выполнения приложения.

Изменено в версии 0.5: Если в словаре, предоставленном как файл в словаре для параметра data, тип содержимого должен называться content_type теперь, вместо mimetype. Это изменение было внесено для согласованности с werkzeug.FileWrapper.

Параметр follow_redirects был добавлен в open().

Дополнительные параметры:

Параметры:

Параметры:	as_tuple – Возвращает кортеж в форме `(environ, result)` buffered – Установите это значение в True, чтобы буферизировать запуск приложения. Это также автоматически закроет приложение для вас. follow_redirects – Установите это значение в True, если `Client` должен следовать HTTP-перенаправлениям.

as_tuple – Возвращает кортеж в форме (environ, result)
buffered – Установите это значение в True, чтобы буферизировать запуск приложения. Это также автоматически закроет приложение для вас.
follow_redirects – Установите это значение в True, если Client должен следовать HTTP-перенаправлениям.

Доступны сокращенные методы для многих HTTP-методов:

get(*args, **kw): Как open, но метод принудительно устанавливается в GET.

patch(*args, **kw): Как open, но метод принудительно устанавливается в PATCH.

post(*args, **kw): Как open, но метод принудительно устанавливается в POST.

head(*args, **kw): Как open, но метод принудительно устанавливается в HEAD.

put(*args, **kw): Как open, но метод принудительно устанавливается в PUT.

delete(*args, **kw): Как open, но метод принудительно устанавливается в DELETE.

options(*args, **kw): Как open, но метод принудительно устанавливается в OPTIONS.

trace(*args, **kw): Как open, но метод принудительно устанавливается в TRACE.

werkzeug.test.create_environ([options])

Создаёт новый словарь WSGI environ на основе переданных значений. Первый параметр должен быть путём запроса, который по умолчанию равен ‘/’. Второй может быть абсолютным путём (в этом случае хост – localhost:80) или полным путём к запросу со схемой, netloc, портом и путём к скрипту.

Принимает те же аргументы, что и конструктор EnvironBuilder.

Изменено в версии 0.5: Эта функция теперь является тонким оболочкой над EnvironBuilder, которая была добавлена в 0.5. Параметры headers, environ_base, environ_overrides и charset были добавлены.

werkzeug.test.run_wsgi_app(app, environ, buffered=False)

Возвращает кортеж (app_iter, status, headers) вывода приложения. Это лучше всего работает, если вы передаёте приложение, которое всегда возвращает итератор.

Иногда приложения могут использовать вызываемую функцию write(), возвращаемую функцией start_response. Это пытается автоматически разрешить такие крайние случаи. Но если вы не получаете ожидаемый вывод, вы должны установить buffered на True, что обеспечивает буферизацию.

Если передано некорректное WSGI-приложение, поведение этой функции не определено. Никогда не передавайте несоответствующие WSGI-приложения в эту функцию.

Параметры:	app – приложение для выполнения. buffered – установите в `True` для принудительной буферизации.
Возвращает:	кортеж в форме `(app_iter, status, headers)`