Заглушка 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. Объектом String представляющим тело ответа
2. Объектом Array со статусом, заголовками и телом ответа, например [200, { "Content-Type": "text/html", "Content-Length": 2 }, "OK"]
3. Объектом Function.

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

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

server.respondWith(url, response);

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

server.respondWith(method, url, response);

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

method — это HTTP-метод.

server.respondWith(urlRegExp, response);

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

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

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

server.respondWith(method, urlRegExp, response);

Отвечает на все запросы с указанным методом к 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).