From fb0199a133145b4f957693881491be747fa347c1 Mon Sep 17 00:00:00 2001 From: codejedi365 Date: Sun, 2 May 2021 16:41:14 -0500 Subject: [PATCH 1/2] [Docs] Update fake-server usage & descriptions With the update to support es6 modules, the organization of `nise` module inside of sinon namespace changed. `createFakeServer()` no longer exists but rather `fakeServer` is a property of an imported/required module `sinon` with a singular `create()` method. This is updated on the main page of https://sinonjs.org but not in the detailed API page here. Added additional clarity and important information for usage of parameters. Removed duplication of property descriptions to increase readability. --- .../release/fake-xhr-and-server.md | 128 ++++++++---------- 1 file changed, 58 insertions(+), 70 deletions(-) diff --git a/docs/release-source/release/fake-xhr-and-server.md b/docs/release-source/release/fake-xhr-and-server.md index f89b0bdc2..2d3661b26 100644 --- a/docs/release-source/release/fake-xhr-and-server.md +++ b/docs/release-source/release/fake-xhr-and-server.md @@ -177,19 +177,21 @@ 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 () { +suite("sinon.fakeServer", function () { + + setup(function () { + this.server = sinon.fakeServer.create(); + }); + + teardown(function () { this.server.restore(); - }, + }); - "test should fetch comments from server" : function () { + 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" }]']); @@ -200,30 +202,35 @@ For help with handling JSON-P please refer to our [notes below](#json-p) sinon.assert.calledWith(callback, [{ id: 12, comment: "Hey there" }]); - assert(server.requests.length > 0) - } -} + 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);` @@ -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)` @@ -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)`. From d648886432b2adbdfd8c668c441553d4f21fb1a5 Mon Sep 17 00:00:00 2001 From: codejedi365 Date: Sun, 2 May 2021 22:16:43 -0400 Subject: [PATCH 2/2] applied prettier to markdown --- .../release/fake-xhr-and-server.md | 44 +++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/release-source/release/fake-xhr-and-server.md b/docs/release-source/release/fake-xhr-and-server.md index 2d3661b26..29f098b9c 100644 --- a/docs/release-source/release/fake-xhr-and-server.md +++ b/docs/release-source/release/fake-xhr-and-server.md @@ -182,29 +182,29 @@ High-level API to manipulate `FakeXMLHttpRequest` instances. var sinon = require("sinon"); suite("sinon.fakeServer", function () { + setup(function () { + this.server = sinon.fakeServer.create(); + }); - setup(function () { - this.server = sinon.fakeServer.create(); - }); + teardown(function () { + this.server.restore(); + }); - 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" }]', + ]); - 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(); - 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); - }); + sinon.assert.calledWith(callback, [{ id: 12, comment: "Hey there" }]); + assert(server.requests.length > 0); + }); }); ``` @@ -230,7 +230,7 @@ Just as a `create()` above, an optional properties object can be provided to set Changes the configuration the fake server after it has been created. -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. +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);` @@ -310,7 +310,7 @@ This property allows you to inspect the received requests to verify request orde ### 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)`. +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 @@ -336,7 +336,7 @@ Note that this feature is intended to help during mockup development, and is not #### Number `autoRespondAfter (ms)` -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. +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` @@ -344,7 +344,7 @@ 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 `autoRespond` and `autoRespondAfter` properties. If `server.respondImmediately == true`, it will override all `autoRespond` behavior. +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`