Фейковый 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 (новая функция с версии 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);

Заставляет сервер отвечать на любой запрос, не соответствующий другому ответу, с предоставленными данными. Стандартный ответ «catch-all» — [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).