Фейковый 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 установлено в 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).