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

Заглушка XMLHttpRequest

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

Также заглушает стандартные XMLHttpRequest и ActiveXObject (если доступны и только для XMLHTTP progid). Помогает при тестировании запросов, выполненных с использованием 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 progId. Другие progId, такие как 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 (новая функция в версии 1.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 установлено в true, отвечать на запросы после этого количества миллисекунд. По умолчанию 10.

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

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

// example.test.js in Mocha TDD
var sinon = require("sinon");

suite("sinon.fakeServer", function () {
  setup(function () {
    this.server = sinon.fakeServer.create();
  });

  teardown(function () {
    this.server.restore();
  });

  test("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.fakeServer.create([config]);

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

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

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

var server = sinon.fakeServerWithClock.create();

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

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

Как и в случае с create() выше, для настройки параметров конфигурации при создании можно предоставить необязательный объект свойств.

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() для настройки ответа сервера перед вызовом respond(). В противном случае вы получите ответ по умолчанию — 404 NOT FOUND.

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

server.getHTTPMethod(request)

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

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

Этот метод можно переопределить для настройки поведения.

server.restore();

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

Свойства

Массив server.requests

server.requests — это массив всех созданных объектов FakeXMLHttpRequest.

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

Свойства конфигурации

Заглушенный сервер предоставляет настраиваемые свойства для изменения поведения сервера по вашему желанию. Эти свойства можно установить напрямую или с помощью объекта литерала, переданного в create(options) и/или server.configure(options).

// Defaults
server.autoRespond = false;
server.autoRespondAfter = 10; // in milliseconds
server.respondImmediately = false;
server.fakeHTTPMethods = false;

// configure fakeServer to autoRespond
server.autoRespond = true;

// Change server now to respondImmediately
server.configure({ respondImmediately: true });

Булево autoRespond

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

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

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

Число autoRespondAfter (ms)

Принуждает сервер автоматически отвечать на входящие запросы после истечения времени ожидания. Требуется server.autoRespond значение true, чтобы это имело эффект. Если server.respondImmediately установлено в значение true, это значение игнорируется.

Булево значение respondImmediately

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

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

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

Булево значение fakeHTTPMethods

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

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