Заглушка XHR и сервер

Заглушка XMLHttpRequest

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

Также подменяет родные XMLHttpRequest и ActiveXObject (если доступны, и только для XMLHTTP progids). Помогает при тестировании запросов, выполненных с помощью XHR.

Заглушенный сервер и XHR могут быть использованы автономно, загрузив sinon-server.js.

{
    setUp: function () {
        this.xhr = sinon.useFakeXMLHttpRequest();
        var requests = this.requests = [];

        this.xhr.onCreate = function (xhr) {
            requests.push(xhr);
        };
    },

    tearDown: function () {
        this.xhr.restore();
    },

    "test should fetch comments from server" : function () {
        var callback = sinon.spy();
        myLib.getCommentsFor("/some/article", callback);
        assertEquals(1, this.requests.length);

        this.requests[0].respond(200, { "Content-Type": "application/json" },
                                 '[{ "id": 12, "comment": "Hey there" }]');
        assert(callback.calledWith([{ id: 12, comment: "Hey there" }]));
    }
}

sinon.useFakeXMLHttpRequest

var xhr = sinon.useFakeXMLHttpRequest();

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

В браузерах, поддерживающих ActiveXObject, этот конструктор заменяется, а заглушенные объекты возвращаются для XMLHTTP progIds. Другие progIds, такие как XMLDOM, остаются без изменений.

Родной объект XMLHttpRequest будет доступен по адресу sinon.xhr.XMLHttpRequest

xhr.onCreate = function (xhr) {};

Присваивая функцию свойству onCreate возвращаемого объекта из useFakeXMLHttpRequest(), вы можете подписываться на новосозданные объекты FakeXMLHttpRequest. См. API заглушенного объекта xhr ниже.

Использование этого наблюдателя позволяет получать доступ к объектам, созданным, например, jQuery.ajax (или другими абстракциями/фреймворками).

xhr.restore();

Восстановить исходную функцию(и).

FakeXMLHttpRequest

String request.url

URL, заданный в объекте запроса.

String request.method

Метод запроса в виде строки.

Object request.requestHeaders

Объект всех заголовков запроса, например:

{
    "Accept": "text/html, */*",
    "Connection": "keep-alive"
}

String request.requestBody

Тело запроса.

int request.status

Код состояния запроса.

undefined если запрос ещё не обработался (см. respond ниже).

String request.statusText

Заполняется только при вызове метода respond (см. ниже).

boolean request.async

Является ли запрос асинхронным.

String request.username

Имя пользователя (если есть).

String request.password

Пароль (если есть).

Document request.responseXML

При использовании respond, это свойство заполняется разобранным документом, если заголовки ответа указывают на это (см. спецификацию)

String request.getResponseHeader(header);

Значение указанного заголовка ответа, если запрос был обработан (см. respond).

Object request.getAllResponseHeaders();

Все заголовки ответа в виде объекта.

Отфильтрованные запросы

При использовании Sinon.JS для эмуляций или частичного интегрирования/функционального тестирования, вы можете захотеть заглушить некоторые запросы, в то время как другие будут передаваться на сервер. С фильтрованными FakeXMLHttpRequest (нововведение в v1.3.0), вы можете это сделать.

FakeXMLHttpRequest.useFilters

По умолчанию false.

Если установлено значение true, Sinon будет проверять добавленные фильтры, чтобы определить, следует ли «разблокировать» определённые запросы.

FakeXMLHttpRequest.addFilter(fn)

Добавить фильтр, который будет определять, следует ли заглушать запрос.

Фильтр вызывается при вызове xhr.open, с теми же аргументами (method, url, async, username, password). Если фильтр возвращает true, запрос не будет заглушен.

Имитация ответов сервера

request.setStatus(status);

Устанавливает код состояния ответа (свойства status и statusText).

Код состояния должен быть числом, текст состояния берётся из sinon.FakeXMLHttpRequest.statusCodes.

request.setResponseHeaders(object);

Устанавливает заголовки ответа (например, { "Content-Type": "text/html", /* ... */ }, обновляет свойство readyState и вызывает onreadystatechange).

request.setResponseBody(body);

Устанавливает тело ответа, обновляет свойство readyState и вызывает onreadystatechange.

Кроме того, заполняет responseXML разобранным документом, если заголовки ответа об этом указывают (см. спецификацию).

request.respond(status, headers, body);

Вызывает три вышеперечисленных метода.

request.error();

Имитирует ошибку сети в запросе. Обработчик события onerror будет вызван, а status будет 0.

Boolean request.autoRespond

При установке в true, заставляет сервер автоматически отвечать на входящие запросы после таймаута.

По умолчанию таймаут составляет 10 мс, но вы можете настроить его через свойство autoRespondAfter.

Обратите внимание, что эта функция предназначена для помощи при разработке эмуляций и не подходит для использования в тестах.

Number request.autoRespondAfter

При установке в autoRespond сервер будет отвечать на запросы после этого количества миллисекунд. По умолчанию 10.

Заглушенный сервер

Высокоуровневый API для управления экземплярами FakeXMLHttpRequest.

Для работы с JSON-P, обратитесь к нижеприведенным примечаниям.

{
    setUp: function () {
        this.server = sinon.createFakeServer();
    },

    tearDown: function () {
        this.server.restore();
    },

    "test should fetch comments from server" : function () {
        this.server.respondWith("GET", "/some/article/comments.json",
            [200, { "Content-Type": "application/json" },
             '[{ "id": 12, "comment": "Hey there" }]']);

        var callback = sinon.spy();
        myLib.getCommentsFor("/some/article", callback);
        this.server.respond();

        sinon.assert.calledWith(callback, [{ id: 12, comment: "Hey there" }]);

        assert(server.requests.length > 0)
    }
}

var server = sinon.createFakeServer([config]);

Создаёт новый сервер.

Эта функция также вызывает sinon.useFakeXMLHttpRequest().

createFakeServer принимает необязательные свойства для настройки заглушенного сервера. См. параметры настроек ниже для параметров конфигурации.

var server = sinon.createFakeServerWithClock();

Создаёт сервер, который также управляет заглушенными таймерами.

Это полезно при тестировании объектов XHR созданных, например, с помощью jQuery 1.3.x, которые используют таймер для опроса объекта на завершение, вместо обычного onreadystatechange.

server.configure(config);

Настраивает заглушенный сервер.

См. параметры настроек ниже для параметров конфигурации.

server.respondWith(response);

Принуждает сервер отвечать на любой запрос, не сопоставленный с другим ответом, с предоставленными данными. По умолчанию, все несопоставленные запросы получают [404, {}, ""].

response может быть тремя вещами:

1. Строка, представляющая тело ответа
2. Объект с кодом состояния, заголовками и телом ответа, например, [200, { "Content-Type": "text/html", "Content-Length": 2 }, "OK"]
3. Функция.

По умолчанию код состояния 200, а заголовки — пустые.

Если ответ — функция, она получит объект запроса. Вам необходимо вручную вызвать respond на ней для завершения запроса.

server.respondWith(url, response);

Отвечает на все запросы по указанному URL, например, /posts/1.

server.respondWith(method, url, response);

Отвечает на все запросы method по указанному URL с предоставленным ответом.

method — HTTP-метод.

server.respondWith(urlRegExp, response);

URL может быть регулярным выражением, например, /\\/post\\//\\d+

Если ответ — функция, она получит любые группы захвата из регулярного выражения вместе с объектом XMLHttpRequest:

server.respondWith(/\/todo-items\/(\d+)/, function (xhr, id) {
    xhr.respond(200, { "Content-Type": "application/json" }, '[{ "id": ' + id + " }]");
});

server.respondWith(method, urlRegExp, response);

Отвечает на все method запросы по URL, соответствующим регулярному выражению.

server.respond();

Вызывает обработку всех очереди асинхронных запросов для получения ответа.

Если ни один из ответов, добавленных через respondWith, не соответствует, используется ответ по умолчанию [404, {}, ""].

Синхронные запросы обрабатываются немедленно, поэтому убедитесь, что вы вызвали respondWith заранее.

Если вызов сопровождается аргументами, respondWith будет вызван с этими аргументами до обработки запросов.

server.autoRespond = true;

Если установлено, автоматически отвечает на каждый запрос после таймаута.

По умолчанию таймаут составляет 10 мс, но вы можете настроить его через свойство autoRespondAfter.

Обратите внимание, что эта функция предназначена для помощи при разработке эмуляций и не подходит для использования в тестах. Для синхронного немедленного ответа используйте respondImmediately вместо этого.

server.autoRespondAfter = ms;

Заставляет сервер автоматически отвечать на входящие запросы после таймаута.

server.respondImmediately = true;

Если установлено, сервер ответит на каждый запрос немедленно и синхронно.

Это идеально подходит для заглушения сервера изнутри теста без необходимости вызова server.respond() после каждого запроса, сделанного в этом тесте.

Поскольку это синхронно и немедленно, это не подходит для имитации реальной задержки сети в тестах или эмуляциях. Для имитации задержки сети с автоматическими ответами см. server.autoRespond и server.autoRespondAfter.

массив server.requests

Вы можете проверить server.requests для проверки порядка запросов, поиска несопоставленных запросов или проверки того, что не было сделано никаких запросов. server.requests — массив всех созданных объектов FakeXMLHttpRequest.

Boolean server.fakeHTTPMethods

Если установлено в true, сервер будет искать параметр _method в теле POST-запроса и интерпретировать его как фактический метод.

Поддерживает распространённый в приложениях Ruby on Rails паттерн. Для кастомизации имитации HTTP-методов, переопределите server.getHTTPMethod(request).

server.getHTTPMethod(request)

Используется внутри для определения HTTP-метода, используемого с предоставленным запросом.

По умолчанию этот метод просто возвращает request.method. Когда server.fakeHTTPMethods установлено в true, метод возвращает значение параметра _method если метод равен “POST”.

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

server.restore();

Восстанавливает родной конструктор XHR.

Параметры заглушенного сервера

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

server.autoRespond = true

Вы также можете передать параметры в виде объекта в createFakeServer и .configure.

Boolean autoRespond

Если установлено, автоматически отвечает на каждый запрос после таймаута.

По умолчанию таймаут составляет 10 мс, но вы можете настроить его через свойство autoRespondAfter.

Обратите внимание, что эта функция предназначена для помощи при разработке эмуляций и не подходит для использования в тестах.

Для синхронного немедленного ответа используйте respondImmediately вместо этого.

Number autoRespondAfter (ms)

Заставляет сервер автоматически отвечать на входящие запросы после таймаута.

Boolean respondImmediately

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

Это идеально подходит для имитации сервера внутри теста без необходимости вызывать server.respond() после каждого запроса, сделанного в этом тесте.

Поскольку это синхронно и немедленно, это не подходит для моделирования реальной задержки сети в тестах или макетах. Для моделирования задержки сети с автоматическими ответами см. server.autoRespond и server.autoRespondAfter.

boolean fakeHTTPMethods

Если установлено значение true, сервер найдёт параметр _method в теле POST и распознает его как фактический метод.

Поддерживает распространённый шаблон в приложениях Ruby on Rails.

Для имитации пользовательских HTTP-методов переопределите server.getHTTPMethod(request)