Инструменты для тестирования

Часто нужно протестировать ваше приложение или проверить вывод из интерактивной сессии 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', '6658')])
>>> resp.data.splitlines()[0]
b'<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"'

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

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

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

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

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

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

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

>>> from werkzeug.wrappers import Request
>>> req = Request(env)
>>> req.form['foo']
'this is some text'
>>> req.files['file']
<FileStorage: u'test.txt' ('text/plain')>
>>> req.files['file'].read()
b'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'] = BytesIO('contents'.encode("utf8"))
>>> 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 WSGI, имени хоста (имя сервера + порт сервера) и корня скрипта (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()

Возвращает созданную среду.

Журнал изменений

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

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, статус и заголовки. По умолчанию обёртка ответа просто возвращает кортеж.

Пример:

class ClientResponse(BaseResponse):
    ...

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

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

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

Журнал изменений

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

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

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

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.

Доступны сокращённые методы для многих 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, статус, заголовки) выходных данных приложения. Лучше всего работает, если вы передаёте ему приложение, которое всегда возвращает итератор.

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

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

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