Фейковый 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 для эмуляций или частичного интегрирования/функционального тестирования вы можете захотеть подменить некоторые запросы, но сохранить другие, которые идут на backend-сервер. С отфильтрованными 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+

Если ответ — функция, она получит все capture groups из регулярного выражения, а также объект 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).