Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[Docs] Update fake-server usage & descriptions #2365

Merged
merged 2 commits into from May 25, 2021
Merged

[Docs] Update fake-server usage & descriptions #2365

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fb0199a
[Docs] Update fake-server usage & descriptions
codejedi365 May 2, 2021
d648886
applied prettier to markdown
codejedi365 May 3, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
144 changes: 66 additions & 78 deletions docs/release-source/release/fake-xhr-and-server.md
View file
Open in desktop
Expand Up @@ -177,53 +177,60 @@ When `autoRespond` is `true`, respond to requests after this number of milliseco

High-level API to manipulate `FakeXMLHttpRequest` instances.

For help with handling JSON-P please refer to our [notes below](#json-p)

```javascript
{
setUp: function () {
this.server = sinon.createFakeServer();
},
// example.test.js in Mocha TDD
var sinon = require("sinon");

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

"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" }]']);
teardown(function () {
this.server.restore();
});

var callback = sinon.spy();
myLib.getCommentsFor("/some/article", callback);
this.server.respond();
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" }]',
]);

sinon.assert.calledWith(callback, [{ id: 12, comment: "Hey there" }]);
var callback = sinon.spy();
myLib.getCommentsFor("/some/article", callback);
this.server.respond();

assert(server.requests.length > 0)
}
}
sinon.assert.calledWith(callback, [{ id: 12, comment: "Hey there" }]);

assert(server.requests.length > 0);
});
});
```

#### `var server = sinon.createFakeServer([config]);`
### Methods

#### `var server = sinon.fakeServer.create([config]);`

Creates a new server.

This function also calls `sinon.useFakeXMLHttpRequest()`.

`createFakeServer` accepts optional properties to configure the fake server. See [options](#fake-server-options) below for configuration parameters.
`create()` accepts an optional properties object to configure the fake server. See [Configuration Properties](#configuration-properties) below for available options.

#### `var server = sinon.createFakeServerWithClock();`
#### `var server = sinon.fakeServerWithClock.create();`

Creates a server that also manages fake timers.

This is useful when testing `XHR` objects created with e.g. jQuery 1.3.x, which uses a timer to poll the object for completion, rather than the usual `onreadystatechange`.

Just as a `create()` above, an optional properties object can be provided to set configuration parameters during instantiation.

#### `server.configure(config);`

Configures the fake server.
Changes the configuration the fake server after it has been created.

See [options](#fake-server-options) below for configuration parameters.
This can be useful for changing the delay of an automatic response for a specific test requirement. For more options, see [Configuration Properties](#configuration-properties) below.

#### `server.respondWith(response);`

Expand Down Expand Up @@ -275,42 +282,11 @@ Responds to all `method` requests to URLs matching the regular expression.

Causes all queued asynchronous requests to receive a response.

If none of the responses added through `respondWith` match, the default response is `[404, {}, ""]`.

Synchronous requests are responded to immediately, so make sure to call `respondWith` upfront.

If called with arguments, `respondWith` will be called with those arguments before responding to requests.

#### `server.autoRespond = true;`

If set, will automatically respond to every request after a timeout.

The default timeout is 10ms but you can control it through the `autoRespondAfter` property.

Note that this feature is intended to help during mockup development, and is not suitable for use in tests. For synchronous immediate responses, use `respondImmediately` instead.

#### `server.autoRespondAfter = ms;`

Causes the server to automatically respond to incoming requests after a timeout.
If none of the responses added through `respondWith()` match, the default response is `[404, {}, ""]`.

#### `server.respondImmediately = true;`
Synchronous requests are responded to immediately so make sure to call `respondWith()` to configure the server response before calling `respond()`. If not, you will recieve the default `404 NOT FOUND` response.

If set, the server will respond to every request immediately and synchronously.

This is ideal for faking the server from within a test without having to call `server.respond()` after each request made in that test.

As this is synchronous and immediate, this is not suitable for simulating actual network latency in tests or mockups. To simulate network latency with automatic responses, see `server.autoRespond` and `server.autoRespondAfter`.

#### array `server.requests`

You can inspect the `server.requests` to verify request ordering, find unmatched requests or check that no requests has been done.
`server.requests` is an array of all the `FakeXMLHttpRequest` objects that have been created.

#### `Boolean server.fakeHTTPMethods`

If set to `true`, server will find `_method` parameter in POST body and recognize that as the actual method.

Supports a pattern common to Ruby on Rails applications. For custom HTTP method faking, override `server.getHTTPMethod(request)`.
If called with arguments, `respondWith()` will be called with those arguments before responding to requests.

#### `server.getHTTPMethod(request)`

Expand All @@ -324,42 +300,54 @@ This method can be overridden to provide custom behavior.

Restores the native XHR constructor.

### Fake server options
### Properties

#### Array[] `server.requests`

These options are properties on the server object and can be set directly
`server.requests` is an array of all the `FakeXMLHttpRequest` objects that have been created.

This property allows you to inspect the received requests to verify request ordering, find unmatched requests or check that no requests has been done.

### Configuration Properties

The Fake Server exposes configurable properties to modify the behavior of the server as desired. These properties can be set directly or with an object literal passed into `create(options)` and/or `server.configure(options)`.

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

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

You can also pass options with an object literal to `createFakeServer` and `.configure`.
// Change server now to respondImmediately
server.configure({ respondImmediately: true });
```

#### `Boolean autoRespond`
#### Boolean `autoRespond`

If set, will automatically respond to every request after a timeout.
If set, will automatically respond to every request after a timeout. **Default: false**.

The default timeout is 10ms but you can control it through the `autoRespondAfter` property.

Note that this feature is intended to help during mockup development, and is not suitable for use in tests.

For synchronous immediate responses, use `respondImmediately` instead.
Note that this feature is intended to help during mockup development, and is not suitable for use in tests. For synchronous immediate responses, use `respondImmediately` instead.

#### `Number autoRespondAfter (ms)`
#### Number `autoRespondAfter (ms)`

Causes the server to automatically respond to incoming requests after a timeout.
Causes the server to automatically respond to incoming requests after a timeout. Requires `server.autoRespond` to be set to `true` to have an effect. If `server.respondImmediately` is set to `true`, this setting is ignored.

#### `Boolean respondImmediately`
#### Boolean `respondImmediately`

If set, the server will respond to every request immediately and synchronously.
If set, the server will respond to every request immediately and synchronously. **Default: false**

This is ideal for faking the server from within a test without having to call `server.respond()` after each request made in that test.

As this is synchronous and immediate, this is not suitable for simulating actual network latency in tests or mockups. To simulate network latency with automatic responses, see `server.autoRespond` and `server.autoRespondAfter`.
As this is synchronous and immediate, this is not suitable for simulating actual network latency in tests or mockups. To simulate network latency with automatic responses, see `autoRespond` and `autoRespondAfter` properties. If `server.respondImmediately == true`, it will override all `autoRespond` behavior.

#### `boolean fakeHTTPMethods`
#### Boolean `fakeHTTPMethods`

If set to `true`, server will find `_method` parameter in `POST` body and recognize that as the actual method.

Supports a pattern common to Ruby on Rails applications.
If set to `true`, server will find `_method` parameter in POST body and recognize that as the actual method.

For custom HTTP method faking, override `server.getHTTPMethod(request)`
Supports a pattern common to Ruby on Rails applications. For custom HTTP method faking, override `server.getHTTPMethod(request)`.