diff --git a/docs/images/bg.png b/docs/images/bg.png new file mode 100644 index 000000000..ca3d2679c Binary files /dev/null and b/docs/images/bg.png differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..b148cee8e --- /dev/null +++ b/docs/index.md @@ -0,0 +1,881 @@ + +# SuperAgent + +SuperAgent is light-weight progressive ajax API crafted for flexibility, readability, and a low learning curve after being frustrated with many of the existing request APIs. It also works with Node.js! + +```javascript + request + .post('/api/pet') + .send({ name: 'Manny', species: 'cat' }) + .set('X-API-Key', 'foobar') + .set('Accept', 'application/json') + .then(res => { + alert('yay got ' + JSON.stringify(res.body)); + }); +``` + +## Test documentation + +[**中文文档**](docs/zh_CN/index.html) + +The following [test documentation](docs/test.html) was generated with [Mocha's](https://mochajs.org/) "doc" reporter, and directly reflects the test suite. This provides an additional source of documentation. + +## Request basics + +A request can be initiated by invoking the appropriate method on the `request` object, then calling `.then()` (or `.end()` [or `await`](#promise-and-generator-support)) to send the request. For example a simple __GET__ request: + +```javascript + request + .get('/search') + .then(res => { + // res.body, res.headers, res.status + }) + .catch(err => { + // err.message, err.response + }); +``` + +HTTP method may also be passed as a string: + +```javascript + request('GET', '/search').then(success, failure); +``` + +Old-style callbacks are also supported, but not recommended. *Instead of* `.then()` you can call `.end()`: + +```javascript + request('GET', '/search').end(function(err, res){ + if (res.ok) {} + }); +``` + +Absolute URLs can be used. In web browsers absolute URLs work only if the server implements [CORS](#cors). + +```javascript + request + .get('https://example.com/search') + .then(res => { + + }); +``` + +The __Node__ client supports making requests to [Unix Domain Sockets](https://en.wikipedia.org/wiki/Unix_domain_socket): + +```javascript + // pattern: https?+unix://SOCKET_PATH/REQUEST_PATH + // Use `%2F` as `/` in SOCKET_PATH + try { + const res = await request + .get('http+unix://%2Fabsolute%2Fpath%2Fto%2Funix.sock/search'); + // res.body, res.headers, res.status + } catch(err) { + // err.message, err.response + } +``` + +__DELETE__, __HEAD__, __PATCH__, __POST__, and __PUT__ requests can also be used, simply change the method name: + +```javascript + request + .head('/favicon.ico') + .then(res => { + + }); +``` + +__DELETE__ can be also called as `.del()` for compatibility with old IE where `delete` is a reserved word. + +The HTTP method defaults to __GET__, so if you wish, the following is valid: + +```javascript + request('/search', (err, res) => { + + }); +``` + +## Using HTTP/2 + +To make a request using HTTP/2 protocol only (with no HTTP/1.x fallback), use the `.http2()` method. + +```javascript + const request = require('superagent'); + const res = await request + .get('https://example.com/h2') + .http2(); +``` + +## Setting header fields + +Setting header fields is simple, invoke `.set()` with a field name and value: + +```javascript + request + .get('/search') + .set('API-Key', 'foobar') + .set('Accept', 'application/json') + .then(callback); +``` + +You may also pass an object to set several fields in a single call: + +```javascript + request + .get('/search') + .set({ 'API-Key': 'foobar', Accept: 'application/json' }) + .then(callback); +``` + +## `GET` requests + +The `.query()` method accepts objects, which when used with the __GET__ method will form a query-string. The following will produce the path `/search?query=Manny&range=1..5&order=desc`. + +```javascript + request + .get('/search') + .query({ query: 'Manny' }) + .query({ range: '1..5' }) + .query({ order: 'desc' }) + .then(res => { + + }); +``` + +Or as a single object: + +```javascript + request + .get('/search') + .query({ query: 'Manny', range: '1..5', order: 'desc' }) + .then(res => { + + }); +``` + +The `.query()` method accepts strings as well: + +```javascript + request + .get('/querystring') + .query('search=Manny&range=1..5') + .then(res => { + + }); +``` + +Or joined: + +```javascript + request + .get('/querystring') + .query('search=Manny') + .query('range=1..5') + .then(res => { + + }); +``` + +## `HEAD` requests + +You can also use the `.query()` method for HEAD requests. The following will produce the path `/users?email=joe@smith.com`. + +```javascript + request + .head('/users') + .query({ email: 'joe@smith.com' }) + .then(res => { + + }); +``` + +## `POST` / `PUT` requests + +A typical JSON __POST__ request might look a little like the following, where we set the Content-Type header field appropriately, and "write" some data, in this case just a JSON string. + +```javascript + request.post('/user') + .set('Content-Type', 'application/json') + .send('{"name":"tj","pet":"tobi"}') + .then(callback) + .catch(errorCallback) +``` + +Since JSON is undoubtedly the most common, it's the _default_! The following example is equivalent to the previous. + +```javascript + request.post('/user') + .send({ name: 'tj', pet: 'tobi' }) + .then(callback, errorCallback) +``` + +Or using multiple `.send()` calls: + +```javascript + request.post('/user') + .send({ name: 'tj' }) + .send({ pet: 'tobi' }) + .then(callback, errorCallback) +``` + +By default sending strings will set the `Content-Type` to `application/x-www-form-urlencoded`, + multiple calls will be concatenated with `&`, here resulting in `name=tj&pet=tobi`: + +```javascript + request.post('/user') + .send('name=tj') + .send('pet=tobi') + .then(callback, errorCallback); +``` + +SuperAgent formats are extensible, however by default "json" and "form" are supported. To send the data as `application/x-www-form-urlencoded` simply invoke `.type()` with "form", where the default is "json". This request will __POST__ the body "name=tj&pet=tobi". + +```javascript + request.post('/user') + .type('form') + .send({ name: 'tj' }) + .send({ pet: 'tobi' }) + .then(callback, errorCallback) +``` + +Sending a [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData) object is also supported. The following example will __POST__ the content of the HTML form identified by id="myForm": + +```javascript + request.post('/user') + .send(new FormData(document.getElementById('myForm'))) + .then(callback, errorCallback) +``` + +## Setting the `Content-Type` + +The obvious solution is to use the `.set()` method: + +```javascript + request.post('/user') + .set('Content-Type', 'application/json') +``` + +As a short-hand the `.type()` method is also available, accepting +the canonicalized MIME type name complete with type/subtype, or +simply the extension name such as "xml", "json", "png", etc: + +```javascript + request.post('/user') + .type('application/json') + + request.post('/user') + .type('json') + + request.post('/user') + .type('png') +``` + +## Serializing request body + +SuperAgent will automatically serialize JSON and forms. +You can setup automatic serialization for other types as well: + +```js +request.serialize['application/xml'] = function (obj) { + return 'string generated from obj'; +}; + +// going forward, all requests with a Content-type of +// 'application/xml' will be automatically serialized +``` +If you want to send the payload in a custom format, you can replace +the built-in serialization with the `.serialize()` method on a per-request basis: + +```js +request + .post('/user') + .send({foo: 'bar'}) + .serialize(obj => { + return 'string generated from obj'; + }); +``` +## Retrying requests + +When given the `.retry()` method, SuperAgent will automatically retry requests, if they fail in a way that is transient or could be due to a flaky Internet connection. + +This method has two optional arguments: number of retries (default 1) and a callback. It calls `callback(err, res)` before each retry. The callback may return `true`/`false` to control whether the request should be retried (but the maximum number of retries is always applied). + +```javascript + request + .get('https://example.com/search') + .retry(2) // or: + .retry(2, callback) + .then(finished); + .catch(failed); +``` + +Use `.retry()` only with requests that are *idempotent* (i.e. multiple requests reaching the server won't cause undesirable side effects like duplicate purchases). + +All request methods are tried by default (which means if you do not want POST requests to be retried, you will need to pass a custom retry callback). + +By default the following status codes are retried: + +* `408` +* `413` +* `429` +* `500` +* `502` +* `503` +* `504` +* `521` +* `522` +* `524` + +By default the following error codes are retried: + +* `'ETIMEDOUT'` +* `'ECONNRESET'` +* `'EADDRINUSE'` +* `'ECONNREFUSED'` +* `'EPIPE'` +* `'ENOTFOUND'` +* `'ENETUNREACH'` +* `'EAI_AGAIN'` + +## Setting Accept + +In a similar fashion to the `.type()` method it is also possible to set the `Accept` header via the short hand method `.accept()`. Which references `request.types` as well allowing you to specify either the full canonicalized MIME type name as `type/subtype`, or the extension suffix form as "xml", "json", "png", etc. for convenience: + +```javascript + request.get('/user') + .accept('application/json') + + request.get('/user') + .accept('json') + + request.post('/user') + .accept('png') +``` + +### Facebook and Accept JSON + +If you are calling Facebook's API, be sure to send an `Accept: application/json` header in your request. If you don't do this, Facebook will respond with `Content-Type: text/javascript; charset=UTF-8`, which SuperAgent will not parse and thus `res.body` will be undefined. You can do this with either `req.accept('json')` or `req.set('Accept', 'application/json')`. See [issue 1078](https://github.com/ladjs/superagent/issues/1078) for details. + +## Query strings + + `req.query(obj)` is a method which may be used to build up a query-string. For example populating `?format=json&dest=/login` on a __POST__: + +```javascript + request + .post('/') + .query({ format: 'json' }) + .query({ dest: '/login' }) + .send({ post: 'data', here: 'wahoo' }) + .then(callback); +``` + +By default the query string is not assembled in any particular order. An asciibetically-sorted query string can be enabled with `req.sortQuery()`. You may also provide a custom sorting comparison function with `req.sortQuery(myComparisonFn)`. The comparison function should take 2 arguments and return a negative/zero/positive integer. + +```js + // default order + request.get('/user') + .query('name=Nick') + .query('search=Manny') + .sortQuery() + .then(callback) + + // customized sort function + request.get('/user') + .query('name=Nick') + .query('search=Manny') + .sortQuery((a, b) => a.length - b.length) + .then(callback) +``` + +## TLS options + +In Node.js SuperAgent supports methods to configure HTTPS requests: + +- `.ca()`: Set the CA certificate(s) to trust +- `.cert()`: Set the client certificate chain(s) +- `.key()`: Set the client private key(s) +- `.pfx()`: Set the client PFX or PKCS12 encoded private key and certificate chain +- `.disableTLSCerts()`: Does not reject expired or invalid TLS certs. Sets internally `rejectUnauthorized=true`. *Be warned, this method allows MITM attacks.* + +For more information, see Node.js [https.request docs](https://nodejs.org/api/https.html#https_https_request_options_callback). + +```js +var key = fs.readFileSync('key.pem'), + cert = fs.readFileSync('cert.pem'); + +request + .post('/client-auth') + .key(key) + .cert(cert) + .then(callback); +``` + +```js +var ca = fs.readFileSync('ca.cert.pem'); + +request + .post('https://localhost/private-ca-server') + .ca(ca) + .then(res => {}); +``` + +## Parsing response bodies + +SuperAgent will parse known response-body data for you, +currently supporting `application/x-www-form-urlencoded`, +`application/json`, and `multipart/form-data`. You can setup +automatic parsing for other response-body data as well: + +```js +//browser +request.parse['application/xml'] = function (str) { + return {'object': 'parsed from str'}; +}; + +//node +request.parse['application/xml'] = function (res, cb) { + //parse response text and set res.body here + + cb(null, res); +}; + +//going forward, responses of type 'application/xml' +//will be parsed automatically +``` + +You can set a custom parser (that takes precedence over built-in parsers) with the `.buffer(true).parse(fn)` method. If response buffering is not enabled (`.buffer(false)`) then the `response` event will be emitted without waiting for the body parser to finish, so `response.body` won't be available. + +### JSON / Urlencoded + +The property `res.body` is the parsed object, for example if a request responded with the JSON string '{"user":{"name":"tobi"}}', `res.body.user.name` would be "tobi". Likewise the x-www-form-urlencoded value of "user[name]=tobi" would yield the same result. Only one level of nesting is supported. If you need more complex data, send JSON instead. + +Arrays are sent by repeating the key. `.send({color: ['red','blue']})` sends `color=red&color=blue`. If you want the array keys to contain `[]` in their name, you must add it yourself, as SuperAgent doesn't add it automatically. + +### Multipart + +The Node client supports _multipart/form-data_ via the [Formidable](https://github.com/felixge/node-formidable) module. When parsing multipart responses, the object `res.files` is also available to you. Suppose for example a request responds with the following multipart body: + + --whoop + Content-Disposition: attachment; name="image"; filename="tobi.png" + Content-Type: image/png + + ... data here ... + --whoop + Content-Disposition: form-data; name="name" + Content-Type: text/plain + + Tobi + --whoop-- + +You would have the values `res.body.name` provided as "Tobi", and `res.files.image` as a `File` object containing the path on disk, filename, and other properties. + +### Binary + +In browsers, you may use `.responseType('blob')` to request handling of binary response bodies. This API is unnecessary when running in node.js. The supported argument values for this method are + +- `'blob'` passed through to the XmlHTTPRequest `responseType` property +- `'arraybuffer'` passed through to the XmlHTTPRequest `responseType` property + +```js +req.get('/binary.data') + .responseType('blob') + .then(res => { + // res.body will be a browser native Blob type here + }); +``` + +For more information, see the Mozilla Developer Network [xhr.responseType docs](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/responseType). + +## Response properties + +Many helpful flags and properties are set on the `Response` object, ranging from the response text, parsed response body, header fields, status flags and more. + +### Response text + +The `res.text` property contains the unparsed response body string. This property is always present for the client API, and only when the mime type matches "text/*", "*/json", or "x-www-form-urlencoded" by default for node. The reasoning is to conserve memory, as buffering text of large bodies such as multipart files or images is extremely inefficient. To force buffering see the "Buffering responses" section. + +### Response body + +Much like SuperAgent can auto-serialize request data, it can also automatically parse it. When a parser is defined for the Content-Type, it is parsed, which by default includes "application/json" and "application/x-www-form-urlencoded". The parsed object is then available via `res.body`. + +### Response header fields + +The `res.header` contains an object of parsed header fields, lowercasing field names much like node does. For example `res.header['content-length']`. + +### Response Content-Type + +The Content-Type response header is special-cased, providing `res.type`, which is void of the charset (if any). For example the Content-Type of "text/html; charset=utf8" will provide "text/html" as `res.type`, and the `res.charset` property would then contain "utf8". + +### Response status + +The response status flags help determine if the request was a success, among other useful information, making SuperAgent ideal for interacting with RESTful web services. These flags are currently defined as: + +```javascript + var type = status / 100 | 0; + + // status / class + res.status = status; + res.statusType = type; + + // basics + res.info = 1 == type; + res.ok = 2 == type; + res.clientError = 4 == type; + res.serverError = 5 == type; + res.error = 4 == type || 5 == type; + + // sugar + res.accepted = 202 == status; + res.noContent = 204 == status || 1223 == status; + res.badRequest = 400 == status; + res.unauthorized = 401 == status; + res.notAcceptable = 406 == status; + res.notFound = 404 == status; + res.forbidden = 403 == status; +``` + +## Aborting requests + +To abort requests simply invoke the `req.abort()` method. + +## Timeouts + +Sometimes networks and servers get "stuck" and never respond after accepting a request. Set timeouts to avoid requests waiting forever. + + * `req.timeout({deadline:ms})` or `req.timeout(ms)` (where `ms` is a number of milliseconds > 0) sets a deadline for the entire request (including all uploads, redirects, server processing time) to complete. If the response isn't fully downloaded within that time, the request will be aborted. + + * `req.timeout({response:ms})` sets maximum time to wait for the first byte to arrive from the server, but it does not limit how long the entire download can take. Response timeout should be at least few seconds longer than just the time it takes the server to respond, because it also includes time to make DNS lookup, TCP/IP and TLS connections, and time to upload request data. + +You should use both `deadline` and `response` timeouts. This way you can use a short response timeout to detect unresponsive networks quickly, and a long deadline to give time for downloads on slow, but reliable, networks. Note that both of these timers limit how long *uploads* of attached files are allowed to take. Use long timeouts if you're uploading files. + +```javascript + request + .get('/big-file?network=slow') + .timeout({ + response: 5000, // Wait 5 seconds for the server to start sending, + deadline: 60000, // but allow 1 minute for the file to finish loading. + }) + .then(res => { + /* responded in time */ + }, err => { + if (err.timeout) { /* timed out! */ } else { /* other error */ } + }); +``` + +Timeout errors have a `.timeout` property. + +## Authentication + +In both Node and browsers auth available via the `.auth()` method: + +```javascript + request + .get('http://local') + .auth('tobi', 'learnboost') + .then(callback); +``` + +In the _Node_ client Basic auth can be in the URL as "user:pass": + +```javascript + request.get('http://tobi:learnboost@local').then(callback); +``` + +By default only `Basic` auth is used. In browser you can add `{type:'auto'}` to enable all methods built-in in the browser (Digest, NTLM, etc.): + +```javascript + request.auth('digest', 'secret', {type:'auto'}) +``` + +The `auth` method also supports a `type` of `bearer`, to specify token-based authentication: + +```javascript + request.auth('my_token', { type: 'bearer' }) +``` + +## Following redirects + +By default up to 5 redirects will be followed, however you may specify this with the `res.redirects(n)` method: + +```javascript + const response = await request.get('/some.png').redirects(2); +``` + +Redirects exceeding the limit are treated as errors. Use `.ok(res => res.status < 400)` to read them as successful responses. + +## Agents for global state + +### Saving cookies + +In Node SuperAgent does not save cookies by default, but you can use the `.agent()` method to create a copy of SuperAgent that saves cookies. Each copy has a separate cookie jar. + +```javascript + const agent = request.agent(); + agent + .post('/login') + .then(() => { + return agent.get('/cookied-page'); + }); +``` + +In browsers cookies are managed automatically by the browser, so the `.agent()` does not isolate cookies. + +### Default options for multiple requests + +Regular request methods called on the agent will be used as defaults for all requests made by that agent. + +```javascript + const agent = request.agent() + .use(plugin) + .auth(shared); + + await agent.get('/with-plugin-and-auth'); + await agent.get('/also-with-plugin-and-auth'); +``` + +The complete list of methods that the agent can use to set defaults is: `use`, `on`, `once`, `set`, `query`, `type`, `accept`, `auth`, `withCredentials`, `sortQuery`, `retry`, `ok`, `redirects`, `timeout`, `buffer`, `serialize`, `parse`, `ca`, `key`, `pfx`, `cert`. + +## Piping data + +The Node client allows you to pipe data to and from the request. Please note that `.pipe()` is used **instead of** `.end()`/`.then()` methods. + +For example piping a file's contents as the request: + +```javascript + const request = require('superagent'); + const fs = require('fs'); + + const stream = fs.createReadStream('path/to/my.json'); + const req = request.post('/somewhere'); + req.type('json'); + stream.pipe(req); +``` + +Note that when you pipe to a request, superagent sends the piped data with [chunked transfer encoding](https://en.wikipedia.org/wiki/Chunked_transfer_encoding), which isn't supported by all servers (for instance, Python WSGI servers). + +Or piping the response to a file: + +```javascript + const stream = fs.createWriteStream('path/to/my.json'); + const req = request.get('/some.json'); + req.pipe(stream); +``` + + It's not possible to mix pipes and callbacks or promises. Note that you should **NOT** attempt to pipe the result of `.end()` or the `Response` object: + +```javascript + // Don't do either of these: + const stream = getAWritableStream(); + const req = request + .get('/some.json') + // BAD: this pipes garbage to the stream and fails in unexpected ways + .end((err, this_does_not_work) => this_does_not_work.pipe(stream)) + const req = request + .get('/some.json') + .end() + // BAD: this is also unsupported, .pipe calls .end for you. + .pipe(nope_its_too_late); +``` + +In a [future version](https://github.com/ladjs/superagent/issues/1188) of superagent, improper calls to `pipe()` will fail. + +## Multipart requests + +SuperAgent is also great for _building_ multipart requests for which it provides methods `.attach()` and `.field()`. + +When you use `.field()` or `.attach()` you can't use `.send()` and you *must not* set `Content-Type` (the correct type will be set for you). + +### Attaching files + +To send a file use `.attach(name, [file], [options])`. You can attach multiple files by calling `.attach` multiple times. The arguments are: + + * `name` — field name in the form. + * `file` — either string with file path or `Blob`/`Buffer` object. + * `options` — (optional) either string with custom file name or `{filename: string}` object. In Node also `{contentType: 'mime/type'}` is supported. In browser create a `Blob` with an appropriate type instead. + +
+ +```javascript + request + .post('/upload') + .attach('image1', 'path/to/felix.jpeg') + .attach('image2', imageBuffer, 'luna.jpeg') + .field('caption', 'My cats') + .then(callback); +``` + +### Field values + +Much like form fields in HTML, you can set field values with `.field(name, value)` and `.field({name: value})`. Suppose you want to upload a few images with your name and email, your request might look something like this: + +```javascript + request + .post('/upload') + .field('user[name]', 'Tobi') + .field('user[email]', 'tobi@learnboost.com') + .field('friends[]', ['loki', 'jane']) + .attach('image', 'path/to/tobi.png') + .then(callback); +``` + +## Compression + +The node client supports compressed responses, best of all, you don't have to do anything! It just works. + +## Buffering responses + +To force buffering of response bodies as `res.text` you may invoke `req.buffer()`. To undo the default of buffering for text responses such as "text/plain", "text/html" etc you may invoke `req.buffer(false)`. + +When buffered the `res.buffered` flag is provided, you may use this to handle both buffered and unbuffered responses in the same callback. + +## CORS + +For security reasons, browsers will block cross-origin requests unless the server opts-in using CORS headers. Browsers will also make extra __OPTIONS__ requests to check what HTTP headers and methods are allowed by the server. [Read more about CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS). + +The `.withCredentials()` method enables the ability to send cookies from the origin, however only when `Access-Control-Allow-Origin` is _not_ a wildcard ("*"), and `Access-Control-Allow-Credentials` is "true". + +```javascript + request + .get('https://api.example.com:4001/') + .withCredentials() + .then(res => { + assert.equal(200, res.status); + assert.equal('tobi', res.text); + }) +``` + +## Error handling + +Your callback function will always be passed two arguments: error and response. If no error occurred, the first argument will be null: + +```javascript + request + .post('/upload') + .attach('image', 'path/to/tobi.png') + .then(res => { + + }); +``` + +An "error" event is also emitted, with you can listen for: + +```javascript + request + .post('/upload') + .attach('image', 'path/to/tobi.png') + .on('error', handle) + .then(res => { + + }); +``` + +Note that **superagent considers 4xx and 5xx responses (as well as unhandled 3xx responses) errors by default**. For example, if you get a `304 Not modified`, `403 Forbidden` or `500 Internal server error` response, this status information will be available via `err.status`. Errors from such responses also contain an `err.response` field with all of the properties mentioned in "[Response properties](#response-properties)". The library behaves in this way to handle the common case of wanting success responses and treating HTTP error status codes as errors while still allowing for custom logic around specific error conditions. + +Network failures, timeouts, and other errors that produce no response will contain no `err.status` or `err.response` fields. + +If you wish to handle 404 or other HTTP error responses, you can query the `err.status` property. When an HTTP error occurs (4xx or 5xx response) the `res.error` property is an `Error` object, this allows you to perform checks such as: + +```javascript + if (err && err.status === 404) { + alert('oh no ' + res.body.message); + } + else if (err) { + // all other error types we handle generically + } +``` + +Alternatively, you can use the `.ok(callback)` method to decide whether a response is an error or not. The callback to the `ok` function gets a response and returns `true` if the response should be interpreted as success. + +```javascript + request.get('/404') + .ok(res => res.status < 500) + .then(response => { + // reads 404 page as a successful response + }) +``` + +## Progress tracking + +SuperAgent fires `progress` events on upload and download of large files. + +```javascript + request.post(url) + .attach('field_name', file) + .on('progress', event => { + /* the event is: + { + direction: "upload" or "download" + percent: 0 to 100 // may be missing if file size is unknown + total: // total file size, may be missing + loaded: // bytes downloaded or uploaded so far + } */ + }) + .then() +``` + +## Testing on localhost + +### Forcing specific connection IP address + +In Node.js it's possible to ignore DNS resolution and direct all requests to a specific IP address using `.connect()` method. For example, this request will go to localhost instead of `example.com`: + +```javascript + const res = await request.get("http://example.com").connect("127.0.0.1"); +``` + +Because the request may be redirected, it's possible to specify multiple hostnames and multiple IPs, as well as a special `*` as the fallback (note: other wildcards are not supported). The requests will keep their `Host` header with the original value. `.connect(undefined)` turns off the feature. + +```javascript + const res = await request.get("http://redir.example.com:555") + .connect({ + "redir.example.com": "127.0.0.1", // redir.example.com:555 will use 127.0.0.1:555 + "www.example.com": false, // don't override this one; use DNS as normal + "mapped.example.com": { host: "127.0.0.1", port: 8080}, // mapped.example.com:* will use 127.0.0.1:8080 + "*": "proxy.example.com", // all other requests will go to this host + }); +``` + +### Ignoring broken/insecure HTTPS on localhost + +In Node.js, when HTTPS is misconfigured and insecure (e.g. using self-signed certificate *without* specifying own `.ca()`), it's still possible to permit requests to `localhost` by calling `.trustLocalhost()`: + +```javascript + const res = await request.get("https://localhost").trustLocalhost() +``` + +Together with `.connect("127.0.0.1")` this may be used to force HTTPS requests to any domain to be re-routed to `localhost` instead. + +It's generally safe to ignore broken HTTPS on `localhost`, because the loopback interface is not exposed to untrusted networks. Trusting `localhost` may become the default in the future. Use `.trustLocalhost(false)` to force check of `127.0.0.1`'s authenticity. + +We intentionally don't support disabling of HTTPS security when making requests to any other IP, because such options end up abused as a quick "fix" for HTTPS problems. You can get free HTTPS certificates from [Let's Encrypt](https://certbot.eff.org) or set your own CA (`.ca(ca_public_pem)`) to make your self-signed certificates trusted. + +## Promise and Generator support + +SuperAgent's request is a "thenable" object that's compatible with JavaScript promises and the `async`/`await` syntax. + +```javascript + const res = await request.get(url); +``` + +If you're using promises, **do not** call `.end()` or `.pipe()`. Any use of `.then()` or `await` disables all other ways of using the request. + +Libraries like [co](https://github.com/tj/co) or a web framework like [koa](https://github.com/koajs/koa) can `yield` on any SuperAgent method: + +```javascript + const req = request + .get('http://local') + .auth('tobi', 'learnboost'); + const res = yield req; +``` + +Note that SuperAgent expects the global `Promise` object to be present. You'll need to use v7 and a polyfill to use promises in Internet Explorer or Node.js 0.10. + +We have dropped support in v8 for IE. You must add a polyfill for WeakRef and BigInt if you wish to support Opera 85, iOS Safari 12.2-12.5, for example using : + +```html + +``` + +## Browser and node versions + +SuperAgent has two implementations: one for web browsers (using XHR) and one for Node.JS (using core http module). By default Browserify and WebPack will pick the browser version. + +If want to use WebPack to compile code for Node.JS, you *must* specify [node target](https://webpack.github.io/docs/configuration.html#target) in its configuration. diff --git a/docs/ko_KR/index.html b/docs/ko_KR/index.html new file mode 100644 index 000000000..13b9262c8 --- /dev/null +++ b/docs/ko_KR/index.html @@ -0,0 +1,1181 @@ + + + + + SuperAgent — elegant API for AJAX in Node and browsers + + + + + +

SuperAgent

+ SuperAgent는 기존의 복잡한 요청 API에 대한 불만에서 출발해 유연성, + 가독성, 그리고 낮은 학습 난이도를 목표로 설계된 경량 Ajax API입니다. + 또한 Node.js 환경에서도 동작합니다! +

     request
+       .post('/api/pet')
+       .send({ name: 'Manny', species: 'cat' })
+       .set('X-API-Key', 'foobar')
+       .set('Accept', 'application/json')
+       .then(res => {
+          alert('yay got ' + JSON.stringify(res.body));
+       });
+

테스트 문서

+ English +

+ 다음의 테스트 문서는 + Mocha's "doc" 리포터를 + 사용해 생성되었으며, 실제 테스트 스위트를 직접 반영합니다. 이 문서는 + 추가적인 참고 자료로 활용할 수 있습니다. +

기본 요청

+ 요청은 request 객체에서 적절한 메서드를 호출하여 시작되며, + 그 다음 .then() 또는 .end() 혹은 + await를 사용해 요청을 전송할 수 있습니다. 예를 들어, 간단한 + GET 요청은 다음과 같습니다. +

     request
+       .get('/search')
+       .then(res => {
+          // res.body, res.headers, res.status
+       })
+       .catch(err => {
+          // err.message, err.response
+       });
+

HTTP 메서드는 문자열로도 전달할 수 있습니다.

    request('GET', '/search').then(success, failure);
+

+ 예전 방식의 콜백도 지원되지만, 권장되지는 않습니다. + .then() 대신 .end()를 호출하여 요청을 전송할 + 수 있습니다. +

    request('GET', '/search').end(function(err, res){
+      if (res.ok) {}
+    });
+

+ 절대 URL을 사용할 수 있습니다. 단, 웹 브라우저에서는 서버가 + CORS를 구현한 경우에만 절대 URL이 정상적으로 + 작동합니다. +

     request
+       .get('https://example.com/search')
+       .then(res => {
+
+       });
+

+ Node 클라이언트는 + 유닉스 도메인 소켓을 통한 요청을 지원합니다. +

    // pattern: https?+unix://SOCKET_PATH/REQUEST_PATH
+    //          Use `%2F` as `/` in SOCKET_PATH
+    try {
+      const res = await request
+        .get('http+unix://%2Fabsolute%2Fpath%2Fto%2Funix.sock/search');
+      // res.body, res.headers, res.status
+    } catch(err) {
+      // err.message, err.response
+    }
+

+ DELETE, HEAD, PATCH, + POST, and PUT 요청도 사용할 수 있으며, + 다음 예시에서 메서드 이름만 변경하면 됩니다. +

    request
+      .head('/favicon.ico')
+      .then(res => {
+
+      });
+

+ DELETE는 delete가 예약어였던 구형 IE와의 + 호환성을 위해 .del() 메서드로도 호출할 수 있습니다. +

+ HTTP 메서드의 기본값은 GET이므로, 다음과 같이 작성해도 + 유효합니다. +

     request('/search', (err, res) => {
+
+     });
+

HTTP/2 사용하기

+ HTTP/1.x 폴백 없이 HTTP/2 프로토콜만 사용하려면 + .http2() 메서드를 호출하여 요청을 전송할 수 있습니다. +

    const request = require('superagent');
+    const res = await request
+      .get('https://example.com/h2')
+      .http2();
+

헤더 필드 설정하기

+ 헤더 필드 설정은 간단합니다. 필드 이름과 값을 + .set() 메서드에 전달하면 됩니다. +

     request
+       .get('/search')
+       .set('API-Key', 'foobar')
+       .set('Accept', 'application/json')
+       .then(callback);
+

여러 개의 헤더 필드를 한 번에 설정하려면 객체를 전달하면 됩니다.

     request
+       .get('/search')
+       .set({ 'API-Key': 'foobar', Accept: 'application/json' })
+       .then(callback);
+

`GET` 요청

+ .query() 메서드는 객체를 인자로 받아 + GET 요청 시 쿼리 문자열을 자동으로 생성합니다. 예를 + 들어 다음 코드는 + /search?query=Manny&range=1..5&order=desc 경로를 + 생성합니다. +

     request
+       .get('/search')
+       .query({ query: 'Manny' })
+       .query({ range: '1..5' })
+       .query({ order: 'desc' })
+       .then(res => {
+
+       });
+

또는 하나의 객체로 설정할 수 있습니다.

    request
+      .get('/search')
+      .query({ query: 'Manny', range: '1..5', order: 'desc' })
+      .then(res => {
+
+      });
+

.query() 메서드는 문자열도 받습니다.

      request
+        .get('/querystring')
+        .query('search=Manny&range=1..5')
+        .then(res => {
+
+        });
+

조인할 수도 있습니다.

      request
+        .get('/querystring')
+        .query('search=Manny')
+        .query('range=1..5')
+        .then(res => {
+
+        });
+

`HEAD` 요청하기

+ HEAD 요청에서도 .query() 메서드를 사용할 수 있습니다. 예를 + 들어 다음 코드는 /users?email=joe@smith.com 경로를 + 생성합니다. +

      request
+        .head('/users')
+        .query({ email: 'joe@smith.com' })
+        .then(res => {
+
+        });
+

`POST` / `PUT` 요청

+ 전형적인 JSON POST 요청은 Content-Type 헤더를 적절히 + 설정하고, 데이터를 JSON 형식으로 전송하는 방식입니다. 예를 들어 다음과 + 같은 코드가 이에 해당합니다. +

      request.post('/user')
+        .set('Content-Type', 'application/json')
+        .send('{"name":"tj","pet":"tobi"}')
+        .then(callback)
+        .catch(errorCallback)
+

+ JSON은 가장 일반적으로 사용되므로 기본값으로 설정되어 있습니다. 다음 + 예제는 앞선 예제와 동일한 동작을 수행합니다. +

      request.post('/user')
+        .send({ name: 'tj', pet: 'tobi' })
+        .then(callback, errorCallback)
+

또는 .send() 여러 번 호출할 수 있습니다.

      request.post('/user')
+        .send({ name: 'tj' })
+        .send({ pet: 'tobi' })
+        .then(callback, errorCallback)
+

+ 기본적으로 문자열을 전송하면 Content-Type이 + application/x-www-form-urlencoded로 자동 설정됩니다. 여러 + 번 .send()를 호출하면 각 문자열이 &로 + 연결되어 최종적으로 name=tj&pet=tobi와 같은 결과가 + 생성됩니다. +

      request.post('/user')
+        .send('name=tj')
+        .send('pet=tobi')
+        .then(callback, errorCallback);
+

+ SuperAgent는 다양한 형식으로 확장 가능하지만, 기본적으로 + "json"과 "form" 형식을 지원합니다. + application/x-www-form-urlencoded 형식으로 데이터를 + 전송하려면 .type('form')을 호출하면 됩니다. 기본 형식은 + "json"입니다. 다음 요청은 본문에 + "name=tj&pet=tobi"를 포함하여 POST됩니다. +

      request.post('/user')
+        .type('form')
+        .send({ name: 'tj' })
+        .send({ pet: 'tobi' })
+        .then(callback, errorCallback)
+

+ FormData + 객체를 사용하는 것도 지원됩니다. 다음 예제는 id="myForm"인 + HTML 폼의 내용을 POST 방식으로 전송합니다. +

      request.post('/user')
+        .send(new FormData(document.getElementById('myForm')))
+        .then(callback, errorCallback)
+

`Content-Type` 설정하기

+ 가장 명확한 해결책은 .set() 메서드를 사용하는 것입니다. +

     request.post('/user')
+       .set('Content-Type', 'application/json')
+

+ 간단하게 .type() 메서드를 사용할 수 있으며, 표준화된 MIME + 타입(type/subtype)을 직접 지정하거나 "xml", + "json", "png" 등과 같은 확장자 이름만으로도 설정할 + 수 있습니다. +

     request.post('/user')
+       .type('application/json')
+
+     request.post('/user')
+       .type('json')
+
+     request.post('/user')
+       .type('png')
+

요청 본문 직렬화하기

+ SuperAgent는 기본적으로 JSON과 폼 데이터를 자동으로 직렬화합니다. 또한 + 다른 콘텐츠 유형에 대해서도 자동 직렬화를 설정할 수 있습니다. +

request.serialize['application/xml'] = function (obj) {
+    return 'string generated from obj';
+};
+
+// 'application/xml' Content-type을 가진 모든 요청은
+// 자동으로 직렬화 됩니다.
+

+ 사용자 정의 형식으로 페이로드를 전송하려면, 요청 단위로 + .serialize() + 메서드를 사용해 SuperAgent의 기본 직렬화 방식을 교체할 수 있습니다. +

request
+    .post('/user')
+    .send({foo: 'bar'})
+    .serialize(obj => {
+        return 'string generated from obj';
+    });
+

요청 재시도하기

+ .retry() 메서드를 사용하면, 일시적인 오류나 불안정한 인터넷 + 연결로 인해 요청이 실패한 경우 SuperAgent가 자동으로 재시도합니다. +

+ 이 메서드는 두 개의 선택적 인자를 받습니다. 재시도 횟수(기본값은 1)와 + 콜백 함수입니다. 각 재시도 전에 callback(err, res)를 + 호출합니다. 콜백 함수는 요청을 재시도할지 여부를 결정하기 위해 + true 또는 false를 반환할 수 있습니다. 단, 최대 + 재시도 횟수는 항상 적용됩니다. +

     request
+       .get('https://example.com/search')
+       .retry(2) // 혹은
+       .retry(2, callback)
+       .then(finished);
+       .catch(failed);
+

+ 멱등한 요청인 경우에만 .retry() 메서드를 사용하세요. 예를 + 들어, 동일한 요청이 서버에 여러 번 도달하더라도 중복 구매와 같은 + 바람직하지 않은 부작용이 발생하지 않아야 합니다. +

+ 모든 요청 메서드는 기본적으로 재시도 대상에 포함됩니다. 따라서 POST + 요청을 재시도하지 않도록 하려면, 사용자 정의 재시도 콜백을 전달해야 + 합니다. +

기본적으로 다음과 같은 상태 코드는 자동으로 재시도됩니다.

408
413
429
500
502
503
504
521
522
524

기본적으로 다음과 같은 오류 코드가 자동으로 재시도됩니다.

'ETIMEDOUT'
'ECONNRESET'
'EADDRINUSE'
'ECONNREFUSED'
'EPIPE'
'ENOTFOUND'
'ENETUNREACH'
'EAI_AGAIN'

Accept 설정하기

+ .type() 메서드와 유사하게, .accept() 메서드를 + 사용하면 Accept 헤더를 간편하게 설정할 수 있습니다. 이 + 메서드는 request.types를 참조하며, + type/subtype 형식의 MIME 타입 전체 이름이나 + "xml", "json", "png" 등의 확장자 형태로도 + 지정할 수 있어 편리합니다. +

     request.get('/user')
+       .accept('application/json')
+
+     request.get('/user')
+       .accept('json')
+
+     request.post('/user')
+       .accept('png')
+

Facebook과 Accept JSON

+ Facebook API를 호출할 때는 반드시 요청 헤더에 + Accept: application/json을 포함해야 합니다. 그렇지 않으면 + Facebook은 Content-Type: text/javascript; charset=UTF-8으로 + 응답하게 되며, SuperAgent는 이 형식을 파싱하지 못해 + res.body가 undefined가 됩니다. + req.accept('json') 또는 + req.set('Accept', 'application/json')을 + 사용할 수 있습니다. 자세한 사항은 + issue 1078 + 에서 확인해보세요. +

쿼리 문자열

+ req.query(obj)는 쿼리 문자열을 구성하는 데 사용되는 + 메서드입니다. 예를 들어 POST 요청에서 + ?format=json&dest=/login과 같은 쿼리 문자열을 추가할 수 + 있습니다. +

    request
+      .post('/')
+      .query({ format: 'json' })
+      .query({ dest: '/login' })
+      .send({ post: 'data', here: 'wahoo' })
+      .then(callback);
+

+ 기본적으로 쿼리 문자열은 특정한 순서로 조립되지 않습니다. ASCII 순으로 + 정렬된 쿼리 문자열을 사용하려면 + req.sortQuery()를 호출하면 됩니다. 또한 + req.sortQuery(myComparisonFn)을 통해 사용자 정의 정렬 비교 + 함수를 전달할 수도 있습니다. 비교 함수는 두 개의 인자를 받아 음수, 0 + 또는 양수를 반환해야 합니다. +

 // 기본 정렬 방식
+ request.get('/user')
+   .query('name=Nick')
+   .query('search=Manny')
+   .sortQuery()
+   .then(callback)
+
+ // 사용자 정의 정렬 함수
+ request.get('/user')
+   .query('name=Nick')
+   .query('search=Manny')
+   .sortQuery((a, b) => a.length - b.length)
+   .then(callback)
+

TLS 옵션

+ Node.js에서 SuperAgent는 HTTPS 요청을 구성할 수 있는 다양한 메서드를 + 지원합니다. +

.ca(): 신뢰할 CA 인증서를 설정합니다.
.cert(): 클라이언트 인증서 체인을 설정합니다.
.key(): 클라이언트의 개인 키를 설정합니다.
+ .pfx(): PKCS12 형식의 PFX 파일을 사용하여 클라이언트의 + 개인 키와 인증서 체인을 설정합니다. +
+ .disableTLSCerts(): 만료되었거나 유효하지 않은 TLS + 인증서를 거부하지 않도록 설정합니다. 내부적으로 + rejectUnauthorized=true가 설정되며, 중간자 공격(MITM)에 + 노출될 수 있으므로 주의가 필요합니다. +

+ 더 자세한 내용은 Node.js + https.request 문서에서 확인할 수 있습니다. +

var key = fs.readFileSync('key.pem'),
+    cert = fs.readFileSync('cert.pem');
+
+request
+  .post('/client-auth')
+  .key(key)
+  .cert(cert)
+  .then(callback);
+

var ca = fs.readFileSync('ca.cert.pem');
+
+request
+  .post('https://localhost/private-ca-server')
+  .ca(ca)
+  .then(res => {});
+

응답 본문 파싱하기

+ SuperAgent는 응답 본문 데이터를 자동으로 파싱해줍니다. 현재 + application/x-www-form-urlencoded, + application/json, multipart/form-data을 + 지원합니다. 이외의 응답 본문 데이터에 대해서도 자동 파싱을 설정할 수 + 있습니다. +

// 브라우저
+request.parse['application/xml'] = function (str) {
+    return {'object': 'parsed from str'};
+};
+
+// node
+request.parse['application/xml'] = function (res, cb) {
+    //parse response text and set res.body here
+
+    cb(null, res);
+};
+
+// 앞으로 'application/xml' 유형의 반응은
+// 자동으로 파싱됩니다
+

+ .buffer(true).parse(fn) 메서드를 사용하면 내장된 파서보다 + 우선적으로 적용되는 사용자 정의 파서를 설정할 수 있습니다. + .buffer(false)로 응답 버퍼링이 비활성화되어 있다면, + response 이벤트는 본문 파싱이 완료되기 전에 발생하므로 + response.body를 사용할 수 없습니다. +

JSON / Urlencoded

+ res.body 속성은 파싱된 객체를 나타냅니다. 예를 들어, 응답이 + JSON 문자열 + '{"user":{"name":"tobi"}}'를 + 반환했다면, res.body.user.name은 "tobi" 값을 갖게 + 됩니다. 마찬가지로 x-www-form-urlencoded 형식의 + "user[name]=tobi"도 동일한 결과를 제공합니다. 단, 중첩은 한 + 단계까지만 지원되므로 더 복잡한 구조의 데이터를 다루려면 JSON 형식을 + 사용하는 것이 좋습니다. +

+ 배열은 key를 반복해서 전달하는 방식으로 전송됩니다. + .send({color: ['red','blue']})는 + color=red&color=blue로 변환되어 전송됩니다. 배열의 + key에 []를 포함시키고 싶다면 SuperAgent는 이를 자동으로 + 처리하지 않으므로, 직접 color[]와 같이 key 이름에 대괄호를 + 추가해야 합니다. +

다중 파트

+ Node 클라이언트는 + Formidable + 모듈을 통해 multipart/form-data를 지원합니다. 다중 파트 응답을 + 파싱할 때 res.files 객체를 사용할 수 있으며, 이 객체에는 + 업로드된 파일에 대한 정보가 포함됩니다. 예를 들어, 다음과 같은 multipart + 본문을 포함한 응답을 가정해볼 수 있습니다. +

--whoop
+Content-Disposition: attachment; name="image"; filename="tobi.png"
+Content-Type: image/png
+
+... data here ...
+--whoop
+Content-Disposition: form-data; name="name"
+Content-Type: text/plain
+
+Tobi
+--whoop--
+

+ res.body.name은 "Tobi" 값을 가지고 있으며, + res.files.image는 디스크 경로, 파일 이름 및 기타 속성을 + 포함한 File 객체입니다. +

바이너리

+ 브라우저에서는 바이너리 응답 본문을 처리하기 위해 + .responseType('blob')을 사용할 수 있습니다. 이 + API는 Node.js 환경에서는 필요하지 않습니다. 이 메서드에서 지원되는 인자 + 값은 다음과 같습니다. +

+ 'blob'는 XMLHttpRequest의 + responseType 속성에 그대로 전달됩니다. +
+ 'arraybuffer'도 마찬가지로 + responseType 속성에 전달됩니다. +

req.get('/binary.data')
+  .responseType('blob')
+  .then(res => {
+    // 여기서 res.body는 브라우저 기본 Blob 타입입니다.
+  });
+

+ 더 자세한 내용은 Mozilla Developer Network의 + XMLHttpRequest.responseType 문서에서 확인할 수 있습니다. +

응답 속성

+ Response 객체에는 응답 텍스트, 파싱된 응답 본문, 헤더 필드, + 상태 플래그 등 다양한 유용한 플래그와 속성이 설정되어 있습니다. +

응답 문자

+ res.text 속성에는 파싱되지 않은 응답 본문 문자열이 + 포함됩니다. 이 속성은 클라이언트 API에서는 항상 존재하며, Node + 환경에서는 MIME 타입이 "text/", "/json", + 또는 "x-www-form-urlencoded"와 일치할 경우에만 기본적으로 + 제공됩니다. 이러한 제한은 대용량 multipart 파일이나 이미지 등의 본문을 + 텍스트로 버퍼링하는 것이 매우 비효율적이기 때문에 메모리를 절약하기 위한 + 목적입니다. 응답을 강제로 버퍼링하려면 "응답 버퍼링" 섹션을 + 참조하세요. +

응답 본문

+ SuperAgent는 요청 데이터를 자동으로 직렬화할 뿐만 아니라, 자동으로 + 파싱할 수도 있습니다. Content-Type에 대해 파서가 정의되어 있는 경우, + 해당 타입에 맞게 응답이 파싱되며 기본적으로 + "application/json"과 + "application/x-www-form-urlencoded" 형식이 포함됩니다. 파싱된 + 객체는 res.body를 통해 접근할 수 있습니다. +

응답 헤더 필드

+ res.header는 파싱된 응답 헤더 필드를 담은 객체로, Node.js와 + 마찬가지로 필드 이름을 소문자로 변환하여 저장합니다. 예를 들어, + res.header['content-length']와 같이 접근할 수 + 있습니다. +

응답 콘텐츠 타입

+ Content-Type 응답 헤더는 특별하게 처리되어 res.type 속성은 + charset 정보를 제외한 콘텐츠 타입만을 제공합니다. 예를 들어 + Content-Type이 "text/html; charset=utf8"인 경우, + res.type은 "text/html"을 반환하고, + res.charset 속성에는 "utf8"이 포함됩니다. +

응답 상태

+ 응답 상태 플래그는 요청이 성공했는지 여부를 비롯한 다양한 유용한 정보를 + 판단하는 데 도움을 줍니다. 이를 통해 SuperAgent는 RESTful 웹 서비스와 + 효과적으로 상호작용할 수 있습니다. 현재 정의된 주요 플래그는 다음과 + 같습니다. +

     var type = status / 100 | 0;
+
+     // 상태 / 클래스
+     res.status = status;
+     res.statusType = type;
+
+     // 기본
+     res.info = 1 == type;
+     res.ok = 2 == type;
+     res.clientError = 4 == type;
+     res.serverError = 5 == type;
+     res.error = 4 == type || 5 == type;
+
+     // 편의 기능
+     res.accepted = 202 == status;
+     res.noContent = 204 == status || 1223 == status;
+     res.badRequest = 400 == status;
+     res.unauthorized = 401 == status;
+     res.notAcceptable = 406 == status;
+     res.notFound = 404 == status;
+     res.forbidden = 403 == status;
+

요청 중단하기

+ 요청을 중단하려면 req.abort() 메서드를 호출하기만 하면 + 됩니다. +

타임아웃

+ 때때로 네트워크나 서버가 요청을 수신한 후 응답 없이 멈춰버리는 경우가 + 있습니다. 이러한 무한 대기를 방지하려면 타임아웃을 설정해야 합니다. +

+
+ req.timeout({deadline:ms}) 또는 + req.timeout(ms)는 업로드, 리다이렉트, 서버 처리 시간을 + 포함한 전체 요청이 완료되어야 하는 최종 시간 제한을 설정합니다. + ms는 0보다 큰 밀리초 단위의 숫자이며, 제한 시간 내에 + 응답이 완료되지 않으면 요청은 중단됩니다. +
+
+
+ req.timeout({response:ms})는 서버로부터 첫 번째 + 바이트가 도착할 때까지의 최대 대기 시간을 설정합니다. 전체 다운로드 + 소요 시간은 제한하지 않습니다. 응답 타임아웃은 DNS 조회, TCP/IP 및 + TLS 연결, 요청 데이터 업로드 시간을 포함하므로, 서버의 실제 응답 + 시간보다 몇 초 더 길게 설정하는 것이 좋습니다. +
+

+ deadline과 response 타임아웃은 함께 사용하는 + 것이 좋습니다. 짧은 응답 타임아웃은 응답하지 않는 네트워크를 빠르게 + 감지하는 데 유용하고, 긴 데드라인은 느리지만 안정적인 네트워크 환경에서 + 다운로드를 완료할 수 있도록 여유 시간을 제공합니다. 두 타이머 모두 + 첨부된 파일 업로드에 허용되는 시간을 제한합니다. 파일을 업로드하는 + 경우에는 충분히 긴 타임아웃을 설정하는 것이 좋습니다. +

    request
+      .get('/big-file?network=slow')
+      .timeout({
+        response: 5000,  // 서버가 데이터를 보내기 시작할 때까지 최대 5초간 기다립니다.
+        deadline: 60000, // 파일 전체를 로드하는 데 최대 1분까지 허용합니다.
+      })
+      .then(res => {
+          /* 제시간 응답 수신 */
+        }, err => {
+          if (err.timeout) { /* 시간 초과! */ } else { /* 그 외 오류 */ }
+      });
+

타임아웃 오류에는 .timeout 속성이 포함되어 있습니다.

인증

+ Node와 브라우저 환경에서 .auth() 메서드를 사용하여 인증을 + 수행할 수 있습니다. +

    request
+      .get('http://local')
+      .auth('tobi', 'learnboost')
+      .then(callback);
+

+ Node 클라이언트에서는 기본 인증을 URL 내에 + "user:pass" 형식으로 포함시킬 수 있습니다. +

    request.get('http://tobi:learnboost@local').then(callback);
+

+ 기본적으로 Basic 인증만 사용됩니다. 브라우저에서는 + {type:'auto'}를 추가하면 Digest, NTLM 등 브라우저에 + 내장된 모든 인증 방식을 사용할 수 있습니다. +

    request.auth('digest', 'secret', {type:'auto'})
+

+ auth 메서드는 토큰 기반 인증을 위한 type의 + bearer 옵션도 지원합니다. +

    request.auth('my_token', { type: 'bearer' })
+

다음 리다이렉션 따라가기

+ 기본적으로 최대 5번까지 리다이렉션이 자동으로 따라가며, 필요에 따라 + res.redirects(n) 메서드를 사용하여 이 횟수를 지정할 수 + 있습니다. +

    const response = await request.get('/some.png').redirects(2);
+

+ 리다이렉션 횟수가 제한을 초과하면 오류로 간주됩니다. 이를 성공적인 + 응답으로 처리하려면 + .ok(res => res.status < 400) 메서드를 사용하세요. +

전역 상태를 위한 에이전트

쿠키 저장하기

+ Node에서 SuperAgent는 기본적으로 쿠키를 저장하지 않습니다. 하지만 + .agent() 메서드를 사용하면 쿠키를 저장하는 SuperAgent + 인스턴스를 생성할 수 있습니다. 각 인스턴스는 독립적인 쿠키 저장소를 + 가지고 있습니다. +

    const agent = request.agent();
+    agent
+      .post('/login')
+      .then(() => {
+        return agent.get('/cookied-page');
+      });
+

+ 브라우저에서는 쿠키가 자동으로 관리되므로 + .agent()를 사용해도 쿠키가 분리되지는 않습니다. +

+ 다중 요청을 위한 기본 옵션 +

+ 에이전트에서 호출된 일반 요청 메서드는 해당 에이전트가 처리하는 모든 + 요청에 대해 기본값으로 적용됩니다. +

    const agent = request.agent()
+      .use(plugin)
+      .auth(shared);
+
+    await agent.get('/with-plugin-and-auth');
+    await agent.get('/also-with-plugin-and-auth');
+

+ 에이전트가 기본 옵션을 설정할 수 있도록 지원하는 메서드 목록입니다. + use, on, once, set, + query, type, accept, + auth, withCredentials, sortQuery, + retry, ok, redirects, + timeout, buffer, serialize, + parse, ca, key, pfx, + cert. +

데이터 전달 방식

+ .pipe()는 .end() 또는 + .then() 메서드 대신 사용되며, Node + 클라이언트는 요청과 응답 간에 데이터를 주고받도록 파이프 처리할 수 + 있습니다. +

+ 예를 들어, 파일의 콘텐츠를 요청 본문으로 전달하는 경우는 다음과 + 같습니다. +

    const request = require('superagent');
+    const fs = require('fs');
+
+    const stream = fs.createReadStream('path/to/my.json');
+    const req = request.post('/somewhere');
+    req.type('json');
+    stream.pipe(req);
+

+ 요청에 데이터를 파이프할 경우, SuperAgent는 해당 데이터를 + 청크 전송 인코딩 + 방식으로 전송합니다. 이 방식은 Python WSGI 서버 등 모든 서버에서 + 지원되지는 않습니다. +

응답을 파일로 저장하려면 다음과 같이 파이프 처리할 수 있습니다.

    const stream = fs.createWriteStream('path/to/my.json');
+    const req = request.get('/some.json');
+    req.pipe(stream);
+

+ 파이프와 콜백 또는 프로미스는 함께 사용할 수 없으며, + .end()나 Response 객체의 결과를 파이프 + 처리해서는 안 됩니다. +

    // 이러한 방식으로 하지 마세요.
+    const stream = getAWritableStream();
+    const req = request
+      .get('/some.json')
+      // 나쁨: 이 방식은 스트림에 올바르지 않은 데이터를 전달하며 예기치 못한 방식으로 실패할 수 있습니다.
+      .end((err, this_does_not_work) => this_does_not_work.pipe(stream))
+    const req = request
+      .get('/some.json')
+      .end()
+      // 나쁨: 이 방식도 지원되지 않으며, .pipe는 자동으로 .end를 호출합니다.
+      .pipe(nope_its_too_late);
+

+ SuperAgent의 + 향후 버전에서는 pipe()를 부적절하게 호출하면 실패하게 됩니다. +

다중 부분 요청

+ .attach()와 .field() 메서드를 제공하는 + SuperAgent는 다중 부분 요청을 구성하는 데에도 매우 유용합니다. +

+ .field() 또는 .attach()를 사용할 경우 + .send()는 사용할 수 없으며, + Content-Type 헤더를 직접 설정해서는 안 됩니다. 올바른 + 타입은 자동으로 지정됩니다. +

파일 첨부하기

+ .attach(name, [file], [options])를 사용하여 파일을 전송할 + 수 있습니다. 여러 파일을 첨부하려면 .attach를 반복 호출하면 + 됩니다. 인자는 다음과 같습니다. +

name — 폼 이름 필드.
+ file — 파일 경로의 문자열 또는 Blob/Buffer + 객체. +
+ options — (선택) 사용자 정의 파일 이름의 문자열 또는 + {filename: string} 형식의 객체. In Node also + {contentType: 'mime/type'} is supported. In + browser create a Blob with an appropriate type instead. +

+
+ +

    request
+      .post('/upload')
+      .attach('image1', 'path/to/felix.jpeg')
+      .attach('image2', imageBuffer, 'luna.jpeg')
+      .field('caption', 'My cats')
+      .then(callback);
+

필드 값

+ .field(name, value) 및 .field({name: value})를 + 사용해 HTML 폼 필드처럼 값을 설정할 수 있습니다. 예를 들어 이름과 이메일 + 정보를 함께 여러 이미지를 업로드하려면, 요청은 다음과 같이 구성될 수 + 있습니다. +

     request
+       .post('/upload')
+       .field('user[name]', 'Tobi')
+       .field('user[email]', 'tobi@learnboost.com')
+       .field('friends[]', ['loki', 'jane'])
+       .attach('image', 'path/to/tobi.png')
+       .then(callback);
+

압축

+ node 클라이언트는 압축된 응답을 지원하며, 아무 것도 하지 않아도 됩니다! + 그냥 작동합니다. +

응답 버퍼링

+ .req.buffer()를 호출하면 응답 본문을 + res.text로 강제 버퍼링할 수 있습니다. + "text/plain", "text/html" 등 텍스트 응답의 기본 + 버퍼링을 취소하려면 req.buffer(false)를 호출하세요. +

+ res.buffered 플래그가 제공되면, 이를 활용하여 동일한 콜백 + 함수에서 버퍼링된 응답과 버퍼링되지 않은 응답을 모두 처리할 수 있습니다. +

CORS

+ 보안상의 이유로 브라우저는 서버가 CORS 헤더를 통해 명시적으로 허용하지 + 않으면 교차 출처 요청(cross-origin requests)을 차단합니다. 브라우저는 + 또한 서버가 어떤 HTTP 헤더와 메서드를 허용하는지 확인하기 위해 추가적인 + OPTIONS 요청을 전송합니다. + CORS에 대해 더 알아보기. +

+ .withCredentials() 메서드는 origin(출처)에서 쿠키를 전송할 + 수 있도록 활성화합니다. 단, 이 기능은 + Access-Control-Allow-Origin 값이 + 와일드카드("*")가 아니어야 하며, + Access-Control-Allow-Credentials 값이 "true"일 + 경우에만 작동합니다. +

    request
+      .get('https://api.example.com:4001/')
+      .withCredentials()
+      .then(res => {
+        assert.equal(200, res.status);
+        assert.equal('tobi', res.text);
+      })
+

오류 처리하기

+ 콜백 함수는 항상 두 개의 인자를 전달합니다. 오류와 응답입니다. 오류가 + 발생하지 않으면, 첫 번째 인자는 null 입니다. +

    request
+     .post('/upload')
+     .attach('image', 'path/to/tobi.png')
+     .then(res => {
+
+     });
+

+ "error" 이벤트도 발생하며, 이를 통해 오류를 감지하고 처리할 수 있습니다. +

    request
+      .post('/upload')
+      .attach('image', 'path/to/tobi.png')
+      .on('error', handle)
+      .then(res => {
+
+      });
+

+ SuperAgent는 기본적으로 4xx 및 5xx 응답(그리고 처리되지 않은 3xx + 응답도 포함)을 오류로 간주합니다. 예를 들어 304 Not Modified, + 403 Forbidden 또는 + 500 Internal Server Error 같은 응답을 받으면 해당 상태 + 정보는 err.status를 통해 확인할 수 있습니다. 이러한 + 응답으로부터 발생한 오류에는 "응답 요소"에서 언급한 모든 속성을 포함한 err.response 필드도 + 포함됩니다. 이 라이브러리는 일반적으로 성공 응답만을 원하고, HTTP 오류 + 상태 코드를 오류로 처리하는 경우를 대비하여 이러한 방식으로 동작합니다. + 하지만 특정 오류 조건에 대해서는 사용자 정의 로직을 허용하도록 설계되어 + 있습니다. +

+ 네트워크 실패, 시간초과, 응답 없는 오류는 err.status 또는 + err.response 필드를 포함하지 않습니다. +

+ 404 또는 HTTP 오류 응답을 처리하고 싶다면, + error.status 요소를 사용할 수 있습니다. HTTP 오류(4xx 또는 + 5xx 응답)가 발생했을 때 res.error 요소는 + Error 객체이고 이는 다음과 같이 에러 확인을 수행할 수 + 있습니다. +

    if (err && err.status === 404) {
+      alert('oh no ' + res.body.message);
+    }
+    else if (err) {
+      // 그 외 다른 모든 오류 유형은 일반적으로 처리합니다
+    }
+

+ 대안으로, .ok(callback) 메서드를 사용하여 응답이 오류인지 + 아닌지 결정할 수 있습니다. ok 콜백은 응답을 받고 응답이 + 성공으로 해석되면 true를 반환합니다. +

    request.get('/404')
+      .ok(res => res.status < 500)
+      .then(response => {
+        // 404 페이지를 성공적인 응답으로 처리합니다
+      })
+

진행과정 추적하기

+ SuperAgent는 업로드와 큰 파일 다운로드에서 + progress 이벤트를 동작시킵니다. +

    request.post(url)
+      .attach('field_name', file)
+      .on('progress', event => {
+        /* the event is:
+        {
+          direction: "upload" or "download"
+          percent: 0 to 100 // 0에서 100까지 (파일 크기를 알 수 없는 경우 생략될 수 있습니다)
+          total: // 전체 파일 크기 (생략될 수 있습니다)
+          loaded: // 현재까지 다운로드되거나 업로드된 바이트 수
+        } */
+      })
+      .then()
+

로컬 호스트에서 테스트하기

+ 특정 IP 주소 연결 설정하기 +

+ Node.js에서는 DNS를 무시하고 .connect() 메서드를 사용하여 + 모든 요청을 특정 IP 주소로 직접 연결할 수 있습니다. 예를 들어, 이 요청은 + example.com 대신 로컬호스트로 전달됩니다. +

    const res = await request.get("http://example.com").connect("127.0.0.1");
+

+ 요청은 리다이렉트 되어, 여러 호스트명과 IP를 특정지을 수 있으며 특별한 + *를 대체로 설정할 수 있습니다. (다른 와일드 카드는 지원되지 + 않습니다). 요청은 원본 값을 가지며 본인의 Host 헤더를 + 유지합니다. .connect(undefined)는 이러한 기능을 끕니다. +

    const res = await request.get("http://redir.example.com:555")
+      .connect({
+        "redir.example.com": "127.0.0.1", // redir.example.com:555는 127.0.0.1:555를 사용합니다.
+        "www.example.com": false, // 이 항목은 재정의하지 마세요. 일반적인 DNS 설정을 사용합니다.
+        "mapped.example.com": { host: "127.0.0.1", port: 8080}, // mapped.example.com의 모든 포트는 127.0.0.1:8080으로 매핑됩니다.
+        "*": "proxy.example.com", // 나머지 모든 요청은 이 호스트로 전달됩니다
+      });
+

+ 로컬 호스트에서 깨지거나 보안되지 않은 HTTPS 무시하기 +

+ Node.js에서 HTTPS 설정이 잘못되었거나 보안성이 떨어지는 경우(예: 자체 + 서명된 인증서를 사용하면서 + .ca()를 지정하지 않은 경우), + .trustLocalhost()를 호출하면 localhost로의 + 요청을 허용할 수 있습니다. +

    const res = await request.get("https://localhost").trustLocalhost()
+

+ .connect("127.0.0.1")와 함께 사용하면 HTTPS + 요청을 어떤 도메인에서든 localhost로 강제로 리다이렉트할 수 + 있습니다. +

+ localhost는 신뢰되지 않은 네트워크에 노출되지 않는 루프백 + 인터페이스이기 때문에, 깨진 HTTPS를 무시하는 것이 일반적으로 안전합니다. + localhost를 신뢰하도록 설정하는 것이 향후 기본값이 될 수 + 있습니다. 127.0.0.1'의 진위 여부를 강제로 검사하려면 + .trustLocalhost(false)를 사용하세요. +

+ 다른 IP 주소로 요청을 보낼 때 HTTPS 보안을 비활성화하는 기능은 + 의도적으로 지원하지 않습니다. 이러한 옵션은 HTTPS 문제를 빠르게 + "해결"하려는 방식으로 오용되는 경우가 많기 때문입니다. + Let's Encrypt를 통해 무료 + HTTPS 인증서를 발급하거나, .ca(ca_public_pem)을 사용해 자체 + 서명된 인증서를 신뢰할 수 있도록 직접 CA를 설정할 수 있습니다. +

Promise 및 Generator 지원

+ SuperAgent의 요청은 "thenable" 객체이며, JavaScript의 Promise + 및 async/await + 문법과 호환됩니다. +

    const res = await request.get(url);
+

+ Promise를 사용할 경우, + .end() 또는 .pipe()를 호출하지 + 마세요. .then() 또는 await를 사용하면 요청을 처리할 + 수 있는 다른 방식들이 모두 비활성화됩니다. +

+ co와 같은 라이브러리나 + koa와 같은 웹 + 프레임워크에서는 SuperAgent의 모든 메서드에서 yield를 + 사용할 수 있습니다. +

    const req = request
+      .get('http://local')
+      .auth('tobi', 'learnboost');
+    const res = yield req;
+

+ SuperAgent는 전역 Promise 객체가 존재하는 환경에서 + 동작하도록 설계되어 있습니다. Internet Explorer나 Node.js 0.10에서 + promise를 사용하려면 v7 버전과 폴리필이 필요합니다. +

+ v8 버전부터는 IE에 대한 지원이 중단되었습니다. Opera 85나 iOS Safari + 12.2–12.5 등을 지원하려면 WeakRef와 BigInt에 대한 폴리필을 추가해야 + 합니다. 예를 들어 + https://cdnjs.cloudflare.com/polyfill/을 사용할 수 있습니다. +

<script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=WeakRef,BigInt"></script>
+

브라우저와 node 버전

+ SuperAgent에는 두 가지 구현 방식이 있습니다. 하나는 웹 브라우저용(XHR + 사용)이고, 다른 하나는 Node.JS용(core http 모듈 사용)입니다. 기본적으로 + Browserify와 WebPack은 브라우저 버전을 선택합니다. +

+ Node.JS용 코드를 컴파일하려면 WebPack 설정에서 반드시 + node target + 을 지정해야 합니다. +

+ + + + + + diff --git a/docs/ko_KR/index.md b/docs/ko_KR/index.md new file mode 100644 index 000000000..8ecb8befc --- /dev/null +++ b/docs/ko_KR/index.md @@ -0,0 +1,877 @@ +# SuperAgent + +SuperAgent는 기존의 복잡한 요청 API에 대한 불만에서 출발해 유연성, 가독성, 그리고 낮은 학습 난이도를 목표로 설계된 경량 Ajax API입니다. 또한 Node.js 환경에서도 동작합니다! + +```javascript +request + .post('/api/pet') + .send({ name: 'Manny', species: 'cat' }) + .set('X-API-Key', 'foobar') + .set('Accept', 'application/json') + .then((res) => { + alert('yay got ' + JSON.stringify(res.body)); + }); +``` + +## 테스트 문서 + +[**English**](/superagent/) + +다음의 [테스트 문서](../test.html)는 [Mocha](https://mochajs.org/)의 "doc" 리포터를 사용해 생성되었으며, 실제 테스트 스위트를 직접 반영합니다. +이 문서는 추가적인 참고 자료로 활용할 수 있습니다. + +## 기본 요청 + +요청은 `request` 객체에서 적절한 메서드를 호출하여 시작되며, 그 다음 `.then()` 또는 `.end()` 혹은 [`await`](#promise-and-generator-support)를 사용해 요청을 전송할 수 있습니다. 예를 들어, 간단한 **GET** 요청은 다음과 같습니다. + +```javascript +request + .get('/search') + .then((res) => { + // res.body, res.headers, res.status + }) + .catch((err) => { + // err.message, err.response + }); +``` + +HTTP 메서드는 문자열로도 전달할 수 있습니다. + +```javascript +request('GET', '/search').then(success, failure); +``` + +예전 방식의 콜백도 지원되지만, 권장되지는 않습니다. `.then()` 대신 `.end()`를 호출하여 요청을 전송할 수 있습니다. + +```javascript +request('GET', '/search').end(function (err, res) { + if (res.ok) { + } +}); +``` + +절대 URL을 사용할 수 있습니다. 단, 웹 브라우저에서는 서버가 [CORS](#cors)를 구현한 경우에만 절대 URL이 정상적으로 작동합니다. + +```javascript +request.get('https://example.com/search').then((res) => {}); +``` + +**Node** 클라이언트는 [유닉스 도메인 소켓](https://ko.wikipedia.org/wiki/%EC%9C%A0%EB%8B%89%EC%8A%A4_%EB%8F%84%EB%A9%94%EC%9D%B8_%EC%86%8C%EC%BC%93)을 통한 요청을 지원합니다. + +```javascript +// pattern: https?+unix://SOCKET_PATH/REQUEST_PATH +// Use `%2F` as `/` in SOCKET_PATH +try { + const res = await request.get( + 'http+unix://%2Fabsolute%2Fpath%2Fto%2Funix.sock/search' + ); + // res.body, res.headers, res.status +} catch (err) { + // err.message, err.response +} +``` + +**DELETE**, **HEAD**, **PATCH**, **POST**, **PUT** 요청도 사용할 수 있으며, 다음 예시에서 메서드 이름만 변경하면 됩니다. + +```javascript +request.head('/favicon.ico').then((res) => {}); +``` + +**DELETE**는 `delete`가 예약어였던 구형 IE와의 호환성을 위해 `.del()` 메서드로도 호출할 수 있습니다. + +HTTP 메서드의 기본값은 **GET**이므로, 다음과 같이 작성해도 유효합니다. + +```javascript +request('/search', (err, res) => {}); +``` + +## HTTP/2 사용하기 + +HTTP/1.x 폴백 없이 HTTP/2 프로토콜만 사용하려면 `.http2()` 메서드를 호출하여 요청을 전송할 수 있습니다. + +```javascript +const request = require('superagent'); +const res = await request.get('https://example.com/h2').http2(); +``` + +## 헤더 필드 설정하기 + +헤더 필드 설정은 간단합니다. 필드 이름과 값을 `.set()` 메서드에 전달하면 됩니다. + +```javascript +request + .get('/search') + .set('API-Key', 'foobar') + .set('Accept', 'application/json') + .then(callback); +``` + +You may also pass an object to set several fields in a single call: + +여러 개의 헤더 필드를 한 번에 설정하려면 객체를 전달하면 됩니다. + +```javascript +request + .get('/search') + .set({ 'API-Key': 'foobar', Accept: 'application/json' }) + .then(callback); +``` + +## `GET` 요청 + +`.query()` 메서드는 객체를 인자로 받아 **GET** 요청 시 쿼리 문자열을 자동으로 생성합니다. 예를 들어 다음 코드는 `/search?query=Manny&range=1..5&order=desc` 경로를 생성합니다. + +````js +request + .get('/search') + .query({ query: 'Manny', range: '1..5', order: 'desc' }); + + +```javascript +request + .get('/search') + .query({ query: 'Manny' }) + .query({ range: '1..5' }) + .query({ order: 'desc' }) + .then((res) => {}); +```` + +또는 하나의 객체로 설정할 수 있습니다. + +```javascript +request + .get('/search') + .query({ query: 'Manny', range: '1..5', order: 'desc' }) + .then((res) => {}); +``` + +`.query()` 메서드는 문자열도 받습니다. + +```javascript +request + .get('/querystring') + .query('search=Manny&range=1..5') + .then((res) => {}); +``` + +조인할 수도 있습니다. + +```javascript +request + .get('/querystring') + .query('search=Manny') + .query('range=1..5') + .then((res) => {}); +``` + +## `HEAD` 요청하기 + +HEAD 요청에서도 `.query()` 메서드를 사용할 수 있습니다. 예를 들어 다음 코드는 `/users?email=joe@smith.com` 경로를 생성합니다. + +```javascript +request + .head('/users') + .query({ email: 'joe@smith.com' }) + .then((res) => {}); +``` + +## `POST` / `PUT` 요청 + +전형적인 JSON **POST** 요청은 Content-Type 헤더를 적절히 설정하고, +데이터를 JSON 형식으로 전송하는 방식입니다. 예를 들어 다음과 같은 코드가 이에 해당합니다. + +```javascript +request + .post('/user') + .set('Content-Type', 'application/json') + .send('{"name":"tj","pet":"tobi"}') + .then(callback) + .catch(errorCallback); +``` + +JSON은 가장 일반적으로 사용되므로 기본값으로 설정되어 있습니다. 다음 예제는 앞선 예제와 동일한 동작을 수행합니다. + +```javascript +request + .post('/user') + .send({ name: 'tj', pet: 'tobi' }) + .then(callback, errorCallback); +``` + +또는 `.send()` 여러 번 호출할 수 있습니다. + +```javascript +request + .post('/user') + .send({ name: 'tj' }) + .send({ pet: 'tobi' }) + .then(callback, errorCallback); +``` + +기본적으로 문자열을 전송하면 `Content-Type`이 `application/x-www-form-urlencoded`로 자동 설정됩니다. +여러 번 `.send()`를 호출하면 각 문자열이 `&`로 연결되어 최종적으로 `name=tj&pet=tobi`와 같은 결과가 생성됩니다. + +```javascript +request + .post('/user') + .send('name=tj') + .send('pet=tobi') + .then(callback, errorCallback); +``` + +SuperAgent는 다양한 형식으로 확장 가능하지만, 기본적으로 "json"과 "form" 형식을 지원합니다. `application/x-www-form-urlencoded` 형식으로 데이터를 전송하려면 `.type('form')`을 호출하면 됩니다. 기본 형식은 `"json"`입니다. 다음 요청은 본문에 `"name=tj&pet=tobi"`를 포함하여 **POST**됩니다. + +```javascript +request + .post('/user') + .type('form') + .send({ name: 'tj' }) + .send({ pet: 'tobi' }) + .then(callback, errorCallback); +``` + +[`FormData`](https://developer.mozilla.org/ko/docs/Web/API/FormData/FormData) 객체를 사용하는 것도 지원됩니다. 다음 예제는 `id="myForm"`인 HTML 폼의 내용을 **POST** 방식으로 전송합니다. + +```javascript +request + .post('/user') + .send(new FormData(document.getElementById('myForm'))) + .then(callback, errorCallback); +``` + +## `Content-Type` 설정하기 + +가장 명확한 해결책은 `.set()` 메서드를 사용하는 것입니다. + +```javascript +request.post('/user').set('Content-Type', 'application/json'); +``` + +간단하게 `.type()` 메서드를 사용할 수 있으며, +표준화된 MIME 타입(`type/subtype`)을 직접 지정하거나 +"xml", "json", "png" 등과 같은 확장자 이름만으로도 설정할 수 있습니다. + +```javascript +request.post('/user').type('application/json'); + +request.post('/user').type('json'); + +request.post('/user').type('png'); +``` + +## 요청 본문 직렬화하기 + +SuperAgent는 기본적으로 JSON과 폼 데이터를 자동으로 직렬화합니다. +또한 다른 콘텐츠 유형에 대해서도 자동 직렬화를 설정할 수 있습니다. + +```js +request.serialize['application/xml'] = function (obj) { + return 'string generated from obj'; +}; + +// 'application/xml' Content-type을 가진 모든 요청은 +// 자동으로 직렬화 됩니다. +``` + +사용자 정의 형식으로 페이로드를 전송하려면, +요청 단위로 `.serialize()` 메서드를 사용해 SuperAgent의 기본 직렬화 방식을 교체할 수 있습니다. + +```js +request + .post('/user') + .send({ foo: 'bar' }) + .serialize((obj) => { + return 'string generated from obj'; + }); +``` + +## 요청 재시도하기 + +`.retry()` 메서드를 사용하면, 일시적인 오류나 불안정한 인터넷 연결로 인해 요청이 실패한 경우 SuperAgent가 자동으로 재시도합니다. + +이 메서드는 두 개의 선택적 인자를 받습니다. 재시도 횟수(기본값은 1)와 콜백 함수입니다. 각 재시도 전에 `callback(err, res)`를 호출합니다. 콜백 함수는 요청을 재시도할지 여부를 결정하기 위해 `true` 또는 `false`를 반환할 수 있습니다. 단, 최대 재시도 횟수는 항상 적용됩니다. + +```javascript + request + .get('https://example.com/search') + .retry(2) // 혹은 + .retry(2, callback) + .then(finished); + .catch(failed); +``` + +멱등한 요청인 경우에만 `.retry()` 메서드를 사용하세요. 예를 들어, 동일한 요청이 서버에 여러 번 도달하더라도 중복 구매와 같은 바람직하지 않은 부작용이 발생하지 않아야 합니다. + +모든 요청 메서드는 기본적으로 재시도 대상에 포함됩니다. 따라서 POST 요청을 재시도하지 않도록 하려면, 사용자 정의 재시도 콜백을 전달해야 합니다. + +기본적으로 다음과 같은 상태 코드는 자동으로 재시도됩니다. + +- `408` +- `413` +- `429` +- `500` +- `502` +- `503` +- `504` +- `521` +- `522` +- `524` + +기본적으로 다음과 같은 오류 코드가 자동으로 재시도됩니다. + +- `'ETIMEDOUT'` +- `'ECONNRESET'` +- `'EADDRINUSE'` +- `'ECONNREFUSED'` +- `'EPIPE'` +- `'ENOTFOUND'` +- `'ENETUNREACH'` +- `'EAI_AGAIN'` + +## Accept 설정하기 + +`.type()` 메서드와 유사하게, `.accept()` 메서드를 사용하면 `Accept` 헤더를 간편하게 설정할 수 있습니다. 이 메서드는 `request.types`를 참조하며, `type/subtype` 형식의 MIME 타입 전체 이름이나 "xml", "json", "png" 등의 확장자 형태로도 지정할 수 있어 편리합니다. + +```javascript +request.get('/user').accept('application/json'); + +request.get('/user').accept('json'); + +request.post('/user').accept('png'); +``` + +### Facebook과 Accept JSON + +Facebook API를 호출할 때는 반드시 요청 헤더에 `Accept: application/json`을 포함해야 합니다. 그렇지 않으면 Facebook은 `Content-Type: text/javascript; charset=UTF-8`으로 응답하게 되며, SuperAgent는 이 형식을 파싱하지 못해 `res.body`가 `undefined`가 됩니다. `req.accept('json')` 또는 `req.set('Accept', 'application/json')`을 사용할 수 있습니다. 자세한 사항은 [issue 1078](https://github.com/ladjs/superagent/issues/1078)에서 확인해보세요. + +## 쿼리 문자열 + +`req.query(obj)`는 쿼리 문자열을 구성하는 데 사용되는 메서드입니다. 예를 들어 **POST** 요청에서 `?format=json&dest=/login`과 같은 쿼리 문자열을 추가할 수 있습니다. + +```javascript +request + .post('/') + .query({ format: 'json' }) + .query({ dest: '/login' }) + .send({ post: 'data', here: 'wahoo' }) + .then(callback); +``` + +기본적으로 쿼리 문자열은 특정한 순서로 조립되지 않습니다. ASCII 순으로 정렬된 쿼리 문자열을 사용하려면 `req.sortQuery()`를 호출하면 됩니다. 또한 `req.sortQuery(myComparisonFn)`을 통해 사용자 정의 정렬 비교 함수를 전달할 수도 있습니다. 비교 함수는 두 개의 인자를 받아 음수, 0 또는 양수를 반환해야 합니다. + +```js +// 기본 정렬 방식 +request + .get('/user') + .query('name=Nick') + .query('search=Manny') + .sortQuery() + .then(callback); + +// 사용자 정의 정렬 함수 +request + .get('/user') + .query('name=Nick') + .query('search=Manny') + .sortQuery((a, b) => a.length - b.length) + .then(callback); +``` + +## TLS 옵션 + +Node.js에서 SuperAgent는 HTTPS 요청을 구성할 수 있는 다양한 메서드를 지원합니다. + +- `.ca()`: 신뢰할 CA 인증서를 설정합니다. +- `.cert()`: 클라이언트 인증서 체인을 설정합니다. +- `.key()`: 클라이언트의 개인 키를 설정합니다. +- `.pfx()`: PKCS12 형식의 PFX 파일을 사용하여 클라이언트의 개인 키와 인증서 체인을 설정합니다. +- `.disableTLSCerts()`: 만료되었거나 유효하지 않은 TLS 인증서를 거부하지 않도록 설정합니다. 내부적으로 `rejectUnauthorized=true`가 설정되며, 중간자 공격(MITM)에 노출될 수 있으므로 주의가 필요합니다. + +더 자세한 내용은 Node.js [https.request 문서](https://nodejs.org/api/https.html#https_https_request_options_callback)에서 확인할 수 있습니다. + +```js +var key = fs.readFileSync('key.pem'), + cert = fs.readFileSync('cert.pem'); + +request.post('/client-auth').key(key).cert(cert).then(callback); +``` + +```js +var ca = fs.readFileSync('ca.cert.pem'); + +request + .post('https://localhost/private-ca-server') + .ca(ca) + .then((res) => {}); +``` + +## Parsing response bodies + +## 응답 본문 파싱하기 + +SuperAgent will parse known response-body data for you, +currently supporting `application/x-www-form-urlencoded`, +`application/json`, and `multipart/form-data`. You can setup +automatic parsing for other response-body data as well: + +SuperAgent는 응답 본문 데이터를 자동으로 파싱해줍니다. +현재 `application/x-www-form-urlencoded`, `application/json`, `multipart/form-data`을 지원합니다. 이외의 응답 본문 데이터에 대해서도 자동 파싱을 설정할 수 있습니다. + +```js +// 브라우저 +request.parse['application/xml'] = function (str) { + return { object: 'parsed from str' }; +}; + +// node +request.parse['application/xml'] = function (res, cb) { + // 응답 문자를 파싱하고 res.body를 여기서 설정하세요 + + cb(null, res); +}; + +// 앞으로 'application/xml' 유형의 반응은 +// 자동으로 파싱됩니다 +``` + +`.buffer(true).parse(fn)` 메서드를 사용하면 내장된 파서보다 우선적으로 적용되는 사용자 정의 파서를 설정할 수 있습니다. `.buffer(false)`로 응답 버퍼링이 비활성화되어 있다면, `response` 이벤트는 본문 파싱이 완료되기 전에 발생하므로 `response.body`를 사용할 수 없습니다. + +### JSON / Urlencoded + +`res.body` 속성은 파싱된 객체를 나타냅니다. 예를 들어, 응답이 JSON 문자열 `{"user":{"name":"tobi"}}`를 반환했다면, `res.body.user.name`은 "tobi" 값을 갖게 됩니다. 마찬가지로 x-www-form-urlencoded 형식의 "user[name]=tobi"도 동일한 결과를 제공합니다. 단, 중첩은 한 단계까지만 지원되므로 더 복잡한 구조의 데이터를 다루려면 JSON 형식을 사용하는 것이 좋습니다. + +배열은 key를 반복해서 전달하는 방식으로 전송됩니다. 예를 들어, `.send({ color: ['red', 'blue'] })`는 `color=red&color=blue`로 변환되어 전송됩니다. 배열의 key에 `[]`를 포함시키고 싶다면 SuperAgent는 이를 자동으로 처리하지 않으므로, 직접 `color[]`와 같이 key 이름에 대괄호를 추가해야 합니다. + +### 다중 파트 + +Node 클라이언트는 [Formidable](https://github.com/felixge/node-formidable) 모듈을 통해 *multipart/form-data*를 지원합니다. +다중 파트 응답을 파싱할 때 `res.files` 객체를 사용할 수 있으며, 이 객체에는 업로드된 파일에 대한 정보가 포함됩니다. 예를 들어, 다음과 같은 multipart 본문을 포함한 응답을 가정해볼 수 있습니다. + + --whoop + Content-Disposition: attachment; name="image"; filename="tobi.png" + Content-Type: image/png + + ... data here ... + --whoop + Content-Disposition: form-data; name="name" + Content-Type: text/plain + + Tobi + --whoop-- + +`res.body.name`은 "Tobi" 값을 가지고 있으며, `res.files.image`는 디스크 경로, 파일 이름 및 기타 속성을 포함한 `File` 객체입니다. + +### 바이너리 + +브라우저에서는 바이너리 응답 본문을 처리하기 위해 `.responseType('blob')`을 사용할 수 있습니다. 이 API는 Node.js 환경에서는 필요하지 않습니다. 이 메서드에서 지원되는 인자 값은 다음과 같습니다. + +- `'blob'`는 XMLHttpRequest의 `responseType` 속성에 그대로 전달됩니다. +- `'arraybuffer'`도 마찬가지로 `responseType` 속성에 전달됩니다. + +```js +req + .get('/binary.data') + .responseType('blob') + .then((res) => { + // 여기서 res.body는 브라우저 기본 Blob 타입입니다. + }); +``` + +더 자세한 내용은 Mozilla Developer Network의 [XMLHttpRequest.responseType 문서](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/responseType)에서 확인할 수 있습니다. + +## 응답 속성 + +`Response` 객체에는 응답 텍스트, 파싱된 응답 본문, 헤더 필드, 상태 플래그 등 다양한 유용한 플래그와 속성이 설정되어 있습니다. + +### 응답 문자 + +`res.text` 속성에는 파싱되지 않은 응답 본문 문자열이 포함됩니다. 이 속성은 클라이언트 API에서는 항상 존재하며, Node 환경에서는 MIME 타입이 "text/_", "_/json", "x-www-form-urlencoded"와 일치할 경우에만 기본적으로 제공됩니다. 이러한 제한은 대용량 multipart 파일이나 이미지 등의 본문을 텍스트로 버퍼링하는 것이 매우 비효율적이기 때문에 메모리를 절약하기 위한 목적입니다. 응답을 강제로 버퍼링하려면 "응답 버퍼링" 섹션을 참조하세요. + +### 응답 본문 + +SuperAgent는 요청 데이터를 자동으로 직렬화할 뿐만 아니라, 자동으로 파싱할 수도 있습니다. Content-Type에 대해 파서가 정의되어 있는 경우, 해당 타입에 맞게 응답이 파싱되며 기본적으로 "application/json"과 "application/x-www-form-urlencoded" 형식이 포함됩니다. 파싱된 객체는 `res.body`를 통해 접근할 수 있습니다. + +### 응답 헤더 필드 + +`res.header`는 파싱된 응답 헤더 필드를 담은 객체로, Node.js와 마찬가지로 필드 이름을 소문자로 변환하여 저장합니다. +예를 들어, `res.header['content-length']`와 같이 접근할 수 있습니다. + +### 응답 콘텐츠 타입 + +Content-Type 응답 헤더는 특별하게 처리되어 `res.type` 속성은 charset 정보를 제외한 콘텐츠 타입만을 제공합니다. 예를 들어 Content-Type이 "text/html; charset=utf8"인 경우, `res.type`은 "text/html"을 반환하고, `res.charset` 속성에는 "utf8"이 포함됩니다. + +### 응답 상태 + +응답 상태 플래그는 요청이 성공했는지 여부를 비롯한 다양한 유용한 정보를 판단하는 데 도움을 줍니다. 이를 통해 SuperAgent는 RESTful 웹 서비스와 효과적으로 상호작용할 수 있습니다. 현재 정의된 주요 플래그는 다음과 같습니다. + +```javascript +var type = (status / 100) | 0; + +// 상태 / 클래스 +res.status = status; +res.statusType = type; + +// 기본 +res.info = 1 == type; +res.ok = 2 == type; +res.clientError = 4 == type; +res.serverError = 5 == type; +res.error = 4 == type || 5 == type; + +// 편의 기능 +res.accepted = 202 == status; +res.noContent = 204 == status || 1223 == status; +res.badRequest = 400 == status; +res.unauthorized = 401 == status; +res.notAcceptable = 406 == status; +res.notFound = 404 == status; +res.forbidden = 403 == status; +``` + +## 요청 중단하기 + +요청을 중단하려면 `req.abort()` 메서드를 호출하기만 하면 됩니다. + +## 타임아웃 + +때때로 네트워크나 서버가 요청을 수신한 후 응답 없이 멈춰버리는 경우가 있습니다. 이러한 무한 대기를 방지하려면 타임아웃을 설정해야 합니다. + +- `req.timeout({deadline: ms})` 또는 `req.timeout(ms)`는 업로드, 리다이렉트, 서버 처리 시간을 포함한 전체 요청이 완료되어야 하는 최종 시간 제한을 설정합니다. `ms`는 0보다 큰 밀리초 단위의 숫자이며, 제한 시간 내에 응답이 완료되지 않으면 요청은 중단됩니다. + +- `req.timeout({response: ms})`는 서버로부터 첫 번째 바이트가 도착할 때까지의 최대 대기 시간을 설정합니다. 전체 다운로드 소요 시간은 제한하지 않습니다. 응답 타임아웃은 DNS 조회, TCP/IP 및 TLS 연결, 요청 데이터 업로드 시간을 포함하므로, 서버의 실제 응답 시간보다 몇 초 더 길게 설정하는 것이 좋습니다. + +`deadline`과 `response` 타임아웃은 함께 사용하는 것이 좋습니다. 짧은 응답 타임아웃은 응답하지 않는 네트워크를 빠르게 감지하는 데 유용하고, 긴 데드라인은 느리지만 안정적인 네트워크 환경에서 다운로드를 완료할 수 있도록 여유 시간을 제공합니다. 두 타이머 모두 첨부된 파일 업로드에 허용되는 시간을 제한합니다. 파일을 업로드하는 경우에는 충분히 긴 타임아웃을 설정하는 것이 좋습니다. + +```javascript +request + .get('/big-file?network=slow') + .timeout({ + response: 5000, // 서버가 데이터를 보내기 시작할 때까지 최대 5초간 기다립니다. + deadline: 60000 // 파일 전체를 로드하는 데 최대 1분까지 허용합니다. + }) + .then( + (res) => { + /* 제시간 응답 수신 */ + }, + (err) => { + if (err.timeout) { + /* 시간 초과! */ + } else { + /* 그 외 오류 */ + } + } + ); +``` + +타임아웃 오류에는 `.timeout` 속성이 포함되어 있습니다. + +## 인증 + +Node와 브라우저 환경에서 `.auth()` 메서드를 사용하여 인증을 수행할 수 있습니다. + +```javascript +request.get('http://local').auth('tobi', 'learnboost').then(callback); +``` + +_Node_ 클라이언트에서는 기본 인증을 URL 내에 "user:pass" 형식으로 포함시킬 수 있습니다. + +```javascript +request.get('http://tobi:learnboost@local').then(callback); +``` + +기본적으로 `Basic` 인증만 사용됩니다. 브라우저에서는 `{type: 'auto'}`를 추가하면 Digest, NTLM 등 브라우저에 내장된 모든 인증 방식을 사용할 수 있습니다. + +```javascript +request.auth('digest', 'secret', { type: 'auto' }); +``` + +`auth` 메서드는 토큰 기반 인증을 위한 `type: 'bearer'` 옵션도 지원합니다. + +```javascript +request.auth('my_token', { type: 'bearer' }); +``` + +## 다음 리다이렉션 따라가기 + +기본적으로 최대 5번까지 리다이렉션이 자동으로 따라가며, 필요에 따라 `res.redirects(n)` 메서드를 사용하여 이 횟수를 지정할 수 있습니다. + +```javascript +const response = await request.get('/some.png').redirects(2); +``` + +리다이렉션 횟수가 제한을 초과하면 오류로 간주됩니다. 이를 성공적인 응답으로 처리하려면 `.ok(res => res.status < 400)` 메서드를 사용하세요. + +## 전역 상태를 위한 에이전트 + +### 쿠키 저장하기 + +Node에서 SuperAgent는 기본적으로 쿠키를 저장하지 않습니다. 하지만 `.agent()` 메서드를 사용하면 쿠키를 저장하는 SuperAgent 인스턴스를 생성할 수 있습니다. 각 인스턴스는 독립적인 쿠키 저장소를 가지고 있습니다. + +```javascript +const agent = request.agent(); +agent.post('/login').then(() => { + return agent.get('/cookied-page'); +}); +``` + +브라우저에서는 쿠키가 자동으로 관리되므로 `.agent()`를 사용해도 쿠키가 분리되지는 않습니다. + +### 다중 요청을 위한 기본 옵션 + +에이전트에서 호출된 일반 요청 메서드는 해당 에이전트가 처리하는 모든 요청에 대해 기본값으로 적용됩니다. + +```javascript +const agent = request.agent().use(plugin).auth(shared); + +await agent.get('/with-plugin-and-auth'); +await agent.get('/also-with-plugin-and-auth'); +``` + +에이전트가 기본 옵션을 설정할 수 있도록 지원하는 메서드 목록입니다. `use`, `on`, `once`, `set`, `query`, `type`, `accept`, `auth`, `withCredentials`, `sortQuery`, `retry`, `ok`, `redirects`, `timeout`, `buffer`, `serialize`, `parse`, `ca`, `key`, `pfx`, `cert`. + +## 데이터 전달 방식 + +`.pipe()`는 `.end()` 또는 `.then()` 메서드 **대신** 사용되며, Node 클라이언트는 요청과 응답 간에 데이터를 주고받도록 파이프 처리할 수 있습니다. + +예를 들어, 파일의 콘텐츠를 요청 본문으로 전달하는 경우는 다음과 같습니다. + +```javascript +const request = require('superagent'); +const fs = require('fs'); + +const stream = fs.createReadStream('path/to/my.json'); +const req = request.post('/somewhere'); +req.type('json'); +stream.pipe(req); +``` + +요청에 데이터를 파이프할 경우, SuperAgent는 해당 데이터를 [청크 전송 인코딩](https://en.wikipedia.org/wiki/Chunked_transfer_encoding) 방식으로 전송합니다. 이 방식은 Python WSGI 서버 등 모든 서버에서 지원되지는 않습니다. + +응답을 파일로 저장하려면 다음과 같이 파이프 처리할 수 있습니다. + +```javascript +const stream = fs.createWriteStream('path/to/my.json'); +const req = request.get('/some.json'); +req.pipe(stream); +``` + +파이프와 콜백 또는 프로미스는 **함께 사용할 수 없으며**, `.end()`나 `Response` 객체의 결과를 파이프 처리해서는 안 됩니다. + +```javascript +// 이러한 방식으로 하지 마세요. +const stream = getAWritableStream(); +const req = request + .get('/some.json') + // 나쁨: 이 방식은 스트림에 올바르지 않은 데이터를 전달하며 예기치 못한 방식으로 실패할 수 있습니다. + .end((err, this_does_not_work) => this_does_not_work.pipe(stream)); +const req = request + .get('/some.json') + .end() + // 나쁨: 이 방식도 지원되지 않으며, .pipe는 자동으로 .end를 호출합니다. + .pipe(nope_its_too_late); +``` + +SuperAgent의 [향후 버전](https://github.com/ladjs/superagent/issues/1188)에서는 `pipe()`를 부적절하게 호출하면 실패하게 됩니다. + +## 다중 부분 요청 + +`.attach()`와 `.field()` 메서드를 제공하는 SuperAgent는 다중 부분 요청을 구성하는 데에도 매우 유용합니다. + +`.field()` 또는 `.attach()`를 사용할 경우 `.send()`는 사용할 수 없으며, `Content-Type` 헤더를 직접 설정해서는 안 됩니다. 올바른 타입은 자동으로 지정됩니다. + +### 파일 첨부하기 + +`.attach(name, [file], [options])`를 사용하여 파일을 전송할 수 있습니다. 여러 파일을 첨부하려면 `.attach`를 반복 호출하면 됩니다. 인자는 다음과 같습니다. + +- `name` — 폼 이름 필드 +- `file` — 파일 경로의 문자열 또는 `Blob`/`Buffer` 객체. +- `options` — (선택) 사용자 정의 파일 이름의 문자열 또는 `{filename: string}` 형식의 객체. Node 환경에서는 `{contentType: 'mime/type'}`도 지원하며 브라우저에서는 적절한 타입의 `Blob` 객체를 생성해야 합니다. + +
+ +```javascript +request + .post('/upload') + .attach('image1', 'path/to/felix.jpeg') + .attach('image2', imageBuffer, 'luna.jpeg') + .field('caption', 'My cats') + .then(callback); +``` + +### 필드 값 + +`.field(name, value)` 및 `.field({name: value})`를 사용해 HTML 폼 필드처럼 값을 설정할 수 있습니다. 예를 들어 이름과 이메일 정보를 함께 여러 이미지를 업로드하려면, 요청은 다음과 같이 구성될 수 있습니다. + +```javascript +request + .post('/upload') + .field('user[name]', 'Tobi') + .field('user[email]', 'tobi@learnboost.com') + .field('friends[]', ['loki', 'jane']) + .attach('image', 'path/to/tobi.png') + .then(callback); +``` + +## 압축 + +node 클라이언트는 압축된 응답을 지원하며, 아무 것도 하지 않아도 됩니다! 그냥 작동합니다. + +## 응답 버퍼링 + +To force buffering of response bodies as `res.text` you may invoke `req.buffer()`. To undo the default of buffering for text responses such as "text/plain", "text/html" etc you may invoke `req.buffer(false)`. + +`.req.buffer()`를 호출하면 응답 본문을 `res.text`로 강제 버퍼링할 수 있습니다. "text/plain", "text/html" 등 텍스트 응답의 기본 버퍼링을 취소하려면 `.req.buffer(false)`를 호출하세요. + +`res.buffered` 플래그가 제공되면, 이를 활용하여 동일한 콜백 함수에서 버퍼링된 응답과 버퍼링되지 않은 응답을 모두 처리할 수 있습니다. + +## CORS + +보안상의 이유로 브라우저는 서버가 CORS 헤더를 통해 명시적으로 허용하지 않으면 교차 출처 요청(cross-origin requests)을 차단합니다. 브라우저는 또한 서버가 어떤 HTTP 헤더와 메서드를 허용하는지 확인하기 위해 추가적인 **OPTIONS** 요청을 전송합니다. [CORS에 대해 더 알아보기](https://developer.mozilla.org/ko/docs/Web/HTTP/Guides/CORS). + +`.withCredentials()` 메서드는 origin(출처)에서 쿠키를 전송할 수 있도록 활성화합니다. 단, 이 기능은 `Access-Control-Allow-Origin` 값이 와일드카드("\*")가 _아니어야_ 하며, `Access-Control-Allow-Credentials` 값이 `"true"`일 경우에만 작동합니다. + +```javascript +request + .get('https://api.example.com:4001/') + .withCredentials() + .then((res) => { + assert.equal(200, res.status); + assert.equal('tobi', res.text); + }); +``` + +## 오류 처리하기 + +콜백 함수는 항상 두 개의 인자를 전달합니다. 오류와 응답입니다. 오류가 발생하지 않으면, 첫 번째 인자는 null 입니다. + +```javascript +request + .post('/upload') + .attach('image', 'path/to/tobi.png') + .then((res) => {}); +``` + +"error" 이벤트도 발생하며, 이를 통해 오류를 감지하고 처리할 수 있습니다. + +```javascript +request + .post('/upload') + .attach('image', 'path/to/tobi.png') + .on('error', handle) + .then((res) => {}); +``` + +**SuperAgent는 기본적으로 4xx 및 5xx 응답(그리고 처리되지 않은 3xx 응답도 포함)을 오류**로 간주합니다. 예를 들어 `304 Not Modified`, `403 Forbidden`, `500 Internal Server Error` 같은 응답을 받으면 해당 상태 정보는 `err.status`를 통해 확인할 수 있습니다. 이러한 응답으로부터 발생한 오류에는 "[응답 요소](#response-properties)"에서 언급한 모든 속성을 포함한 `err.response` 필드도 포함됩니다. 이 라이브러리는 일반적으로 성공 응답만을 원하고, HTTP 오류 상태 코드를 오류로 처리하는 경우를 대비하여 이러한 방식으로 동작합니다. 하지만 특정 오류 조건에 대해서는 사용자 정의 로직을 허용하도록 설계되어 있습니다. + +네트워크 실패, 시간초과, 응답 없는 오류는 `err.status` 또는 `err.response` 필드를 포함하지 않습니다. + +404 또는 HTTP 오류 응답을 처리하고 싶다면, `error.status` 요소를 사용할 수 있습니다. HTTP 오류(4xx 또는 5xx 응답)가 발생했을 때 `res.error` 요소는 `Error` 객체이고 이는 다음과 같이 에러 확인을 수행할 수 있습니다. + +```javascript +if (err && err.status === 404) { + alert('oh no ' + res.body.message); +} else if (err) { + // 그 외 다른 모든 오류 유형은 일반적으로 처리합니다 +} +``` + +대안으로, `.ok(callback)` 메서드를 사용하여 응답이 오류인지 아닌지 결정할 수 있습니다. `ok` 콜백은 응답을 받고 응답이 성공으로 해석되면 `true`를 반환합니다. + +```javascript +request + .get('/404') + .ok((res) => res.status < 500) + .then((response) => { + // 404 페이지를 성공적인 응답으로 처리합니다 + }); +``` + +## 진행과정 추적하기 + +SuperAgent는 업로드와 큰 파일 다운로드에서 `progress` 이벤트를 동작시킵니다. + +```javascript +request + .post(url) + .attach('field_name', file) + .on('progress', (event) => { + /* 이벤트 객체는 다음과 같습니다. + { + direction: "upload" or "download" + percent: 0 to 100 // 0에서 100까지 (파일 크기를 알 수 없는 경우 생략될 수 있습니다) + total: // 전체 파일 크기 (생략될 수 있습니다) + loaded: // 현재까지 다운로드되거나 업로드된 바이트 수 + } */ + }) + .then(); +``` + +## 로컬 호스트에서 테스트하기 + +### 특정 IP 주소 연결 설정하기 + +In Node.js it's possible to ignore DNS resolution and direct all requests to a specific IP address using `.connect()` method. For example, this request will go to localhost instead of `example.com`: + +Node.js에서는 DNS를 무시하고 `.connect()` 메서드를 사용하여 모든 요청을 특정 IP 주소로 직접 연결할 수 있습니다. 예를 들어, 이 요청은 `example.com` 대신 로컬호스트로 전달됩니다. + +```javascript +const res = await request.get('http://example.com').connect('127.0.0.1'); +``` + +요청은 리다이렉트 되어, 여러 호스트명과 IP를 특정지을 수 있으며 특별한 `*`를 대체로 설정할 수 있습니다. (다른 와일드 카드는 지원되지 않습니다). 요청은 원본 값을 가지며 본인의 `Host` 헤더를 유지합니다. `.connect(undefined)`는 이러한 기능을 끕니다. + +```javascript +const res = await request.get('http://redir.example.com:555').connect({ + 'redir.example.com': '127.0.0.1', // redir.example.com:555는 127.0.0.1:555를 사용합니다. + 'www.example.com': false, // 이 항목은 재정의하지 마세요. 일반적인 DNS 설정을 사용합니다. + 'mapped.example.com': { host: '127.0.0.1', port: 8080 }, // mapped.example.com의 모든 포트는 127.0.0.1:8080으로 매핑됩니다. + '*': 'proxy.example.com' // 나머지 모든 요청은 이 호스트로 전달됩니다 +}); +``` + +### 로컬 호스트에서 깨지거나 보안되지 않은 HTTPS 무시하기 + +Node.js에서 HTTPS 설정이 잘못되었거나 보안성이 떨어지는 경우(예: 자체 서명된 인증서를 사용하면서 `.ca()`를 지정하지 않은 경우), `.trustLocalhost()`를 호출하면 `localhost`로의 요청을 허용할 수 있습니다. + +```javascript +const res = await request.get('https://localhost').trustLocalhost(); +``` + +`.connect("127.0.0.1")`와 함께 사용하면 HTTPS 요청을 어떤 도메인에서든 `localhost`로 강제로 리다이렉트할 수 있습니다. + +`localhost`는 신뢰되지 않은 네트워크에 노출되지 않는 루프백 인터페이스이기 때문에, 깨진 HTTPS를 무시하는 것이 일반적으로 안전합니다. `localhost`를 신뢰하도록 설정하는 것이 향후 기본값이 될 수 있습니다. `127.0.0.1`의 진위 여부를 강제로 검사하려면 `.trustLocalhost(false)`를 사용하세요. + +다른 IP 주소로 요청을 보낼 때 HTTPS 보안을 비활성화하는 기능은 의도적으로 지원하지 않습니다. 이러한 옵션은 HTTPS 문제를 빠르게 "해결"하려는 방식으로 오용되는 경우가 많기 때문입니다. [Let's Encrypt](https://certbot.eff.org)를 통해 무료 HTTPS 인증서를 발급받거나, `.ca(ca_public_pem)`을 사용해 자체 서명된 인증서를 신뢰할 수 있도록 직접 CA를 설정할 수 있습니다. + +## Promise 및 Generator 지원 + +SuperAgent의 요청은 "thenable" 객체이며, JavaScript의 Promise 및 `async`/`await` 문법과 호환됩니다. + +```javascript +const res = await request.get(url); +``` + +Promise를 사용할 경우, **`.end()` 또는 `.pipe()`를 호출하지 마세요**. `.then()` 또는 `await`를 사용하면 요청을 처리할 수 있는 다른 방식들이 모두 비활성화됩니다. + +[co](https://github.com/tj/co)와 같은 라이브러리나 [koa](https://github.com/koajs/koa)와 같은 웹 프레임워크에서는 SuperAgent의 모든 메서드에서 `yield`를 사용할 수 있습니다. + +```javascript + const req = request + .get('http://local') + .auth('tobi', 'learnboost'); + const res = yield req; +``` + +SuperAgent는 전역 `Promise` 객체가 존재하는 환경에서 동작하도록 설계되어 있습니다. Internet Explorer나 Node.js 0.10에서 promise를 사용하려면 v7 버전과 폴리필이 필요합니다. + +v8 버전부터는 IE에 대한 지원이 중단되었습니다. Opera 85나 iOS Safari 12.2–12.5 등을 지원하려면 WeakRef와 BigInt에 대한 폴리필을 추가해야 합니다. 예를 들어 을 사용할 수 있습니다. + +```html + +``` + +## 브라우저와 node 버전 + +SuperAgent에는 두 가지 구현 방식이 있습니다. 하나는 웹 브라우저용(XHR 사용)이고, 다른 하나는 Node.JS용(core http 모듈 사용)입니다. 기본적으로 Browserify와 WebPack은 브라우저 버전을 선택합니다. + +Node.JS용 코드를 컴파일하려면 WebPack 설정에서 반드시 [node target](https://webpack.github.io/docs/configuration.html#target)을 지정해야 합니다. diff --git a/docs/style.css b/docs/style.css new file mode 100644 index 000000000..958428013 --- /dev/null +++ b/docs/style.css @@ -0,0 +1,88 @@ +body { + padding: 40px 80px; + font: 14px/1.5 "Helvetica Neue", Helvetica, sans-serif; + background: #181818 url(images/bg.png); + text-align: center; +} + +#content { + margin: 0 auto; + padding: 10px 40px; + text-align: left; + background: white; + width: 50%; + -webkit-border-radius: 2px; + -moz-border-radius: 2px; + border-radius: 2px; + -webkit-box-shadow: 0 2px 5px 0 black; +} + +#menu { + font-size: 13px; + margin: 0; + padding: 0; + text-align: left; + position: fixed; + top: 15px; + left: 15px; +} + +#menu ul { + margin: 0; + padding: 0; +} + +#menu li { + list-style: none; +} + +#menu a { + color: rgba(255,255,255,.5); + text-decoration: none; +} + +#menu a:hover { + color: white; +} + +#menu .active a { + color: white; +} + +pre { + padding: 10px; +} + +code { + font-family: monaco, monospace, sans-serif; + font-size: 0.85em; +} + +p code { + border: 1px solid #ECEA75; + padding: 1px 3px; + -webkit-border-radius: 2px; + -moz-border-radius: 2px; + border-radius: 2px; + background: #FDFCD1; +} + +pre { + padding: 20px 25px; + border: 1px solid #ddd; + -webkit-box-shadow: inset 0 0 5px #eee; + -moz-box-shadow: inset 0 0 5px #eee; + box-shadow: inset 0 0 5px #eee; + overflow: scroll; +} + +code .comment { color: #ddd } +code .init { color: #2F6FAD } +code .string { color: #5890AD } +code .keyword { color: #8A6343 } +code .number { color: #2F6FAD } + +/* override tocbot style to avoid vertical white line in table of content */ +.toc-link::before { + content: initial; +} diff --git a/docs/tail.html b/docs/tail.html new file mode 100644 index 000000000..e88720bbe --- /dev/null +++ b/docs/tail.html @@ -0,0 +1,36 @@ +

+test on node with http1 +test on plain node +

Agent

should remember defaults

if (typeof Promise === 'undefined') {
+  return;
+}
+let called = 0;
+let event_called = 0;
+const agent = request
+  .agent()
+  .accept('json')
+  .use(() => {
+    called++;
+  })
+  .once('request', () => {
+    event_called++;
+  })
+  .query({ hello: 'world' })
+  .set('X-test', 'testing');
+assert.equal(0, called);
+assert.equal(0, event_called);
+return agent
+  .get(`${base}/echo`)
+  .then((res) => {
+    assert.equal(1, called);
+    assert.equal(1, event_called);
+    assert.equal('application/json', res.headers.accept);
+    assert.equal('testing', res.headers['x-test']);
+    return agent.get(`${base}/querystring`);
+  })
+  .then((res) => {
+    assert.equal(2, called);
+    assert.equal(2, event_called);
+    assert.deepEqual({ hello: 'world' }, res.body);
+  });

request

res.statusCode

should set statusCode

request.get(`${uri}/login`, (error, res) => {
+  try {
+    assert.strictEqual(res.statusCode, 200);
+    done();
+  } catch (err) {
+    done(err);
+  }
+});

should allow the send shorthand

with callback in the method call

request.get(`${uri}/login`, (error, res) => {
+  assert.equal(res.status, 200);
+  done();
+});

with data in the method call

request.post(`${uri}/echo`, { foo: 'bar' }).end((error, res) => {
+  assert.equal('{"foo":"bar"}', res.text);
+  done();
+});

with callback and data in the method call

request.post(`${uri}/echo`, { foo: 'bar' }, (error, res) => {
+  assert.equal('{"foo":"bar"}', res.text);
+  done();
+});

with a callback

should invoke .end()

request.get(`${uri}/login`, (error, res) => {
+  try {
+    assert.equal(res.status, 200);
+    done();
+  } catch (err) {
+    done(err);
+  }
+});

.end()

should issue a request

request.get(`${uri}/login`).end((error, res) => {
+  try {
+    assert.equal(res.status, 200);
+    done();
+  } catch (err) {
+    done(err);
+  }
+});

is optional with a promise

if (typeof Promise === 'undefined') {
+  return;
+}
+return request
+  .get(`${uri}/login`)
+  .then((res) => res.status)
+  .then()
+  .then((status) => {
+    assert.equal(200, status, 'Real promises pass results through');
+  });

called only once with a promise

if (typeof Promise === 'undefined') {
+  return;
+}
+const request_ = request.get(`${uri}/unique`);
+return Promise.all([request_, request_, request_]).then((results) => {
+  for (const item of results) {
+    assert.deepEqual(
+      item.body,
+      results[0].body,
+      'It should keep returning the same result after being called once'
+    );
+  }
+});

res.error

ok

let calledErrorEvent = false;
+let calledOKHandler = false;
+request
+  .get(`${uri}/error`)
+  .ok((res) => {
+    assert.strictEqual(500, res.status);
+    calledOKHandler = true;
+    return true;
+  })
+  .on('error', (error) => {
+    calledErrorEvent = true;
+  })
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      assert.strictEqual(res.status, 500);
+      assert(!calledErrorEvent);
+      assert(calledOKHandler);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should be an Error object

let calledErrorEvent = false;
+request
+  .get(`${uri}/error`)
+  .on('error', (error) => {
+    assert.strictEqual(error.status, 500);
+    calledErrorEvent = true;
+  })
+  .end((error, res) => {
+    try {
+      if (NODE) {
+        res.error.message.should.equal('cannot GET /error (500)');
+      } else {
+        res.error.message.should.equal(`cannot GET ${uri}/error (500)`);
+      }
+      assert.strictEqual(res.error.status, 500);
+      assert(error, 'should have an error for 500');
+      assert.equal(error.message, 'Internal Server Error');
+      assert(calledErrorEvent);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

with .then() promise

if (typeof Promise === 'undefined') {
+  return;
+}
+return request.get(`${uri}/error`).then(
+  () => {
+    assert.fail();
+  },
+  (err) => {
+    assert.equal(err.message, 'Internal Server Error');
+  }
+);

with .ok() returning false

if (typeof Promise === 'undefined') {
+  return;
+}
+return request
+  .get(`${uri}/echo`)
+  .ok(() => false)
+  .then(
+    () => {
+      assert.fail();
+    },
+    (err) => {
+      assert.equal(200, err.response.status);
+      assert.equal(err.message, 'OK');
+    }
+  );

with .ok() throwing an Error

if (typeof Promise === 'undefined') {
+  return;
+}
+return request
+  .get(`${uri}/echo`)
+  .ok(() => {
+    throw new Error('boom');
+  })
+  .then(
+    () => {
+      assert.fail();
+    },
+    (err) => {
+      assert.equal(200, err.status);
+      assert.equal(200, err.response.status);
+      assert.equal(err.message, 'boom');
+    }
+  );

with .ok() throwing an Error with status

if (typeof Promise === 'undefined') {
+  return;
+}
+return request
+  .get(`${uri}/echo`)
+  .ok(() => {
+    const err = new Error('boom');
+    err.status = 404;
+    throw err;
+  })
+  .then(
+    () => {
+      assert.fail();
+    },
+    (err) => {
+      assert.equal(404, err.status);
+      assert.equal(200, err.response.status);
+      assert.equal(err.message, 'boom');
+    }
+  );

res.header

should be an object

request.get(`${uri}/login`).end((error, res) => {
+  try {
+    assert.equal('Express', res.header['x-powered-by']);
+    done();
+  } catch (err) {
+    done(err);
+  }
+});

set headers

should only set headers for ownProperties of header

try {
+  request
+    .get(`${uri}/echo-headers`)
+    .set('valid', 'ok')
+    .end((error, res) => {
+      if (
+        !error &&
+        res.body &&
+        res.body.valid &&
+        !res.body.hasOwnProperty('invalid')
+      ) {
+        return done();
+      }
+      done(error || new Error('fail'));
+    });
+} catch (err) {
+  done(err);
+}

res.charset

should be set when present

request.get(`${uri}/login`).end((error, res) => {
+  try {
+    res.charset.should.equal('utf-8');
+    done();
+  } catch (err) {
+    done(err);
+  }
+});

res.statusType

should provide the first digit

request.get(`${uri}/login`).end((error, res) => {
+  try {
+    assert(!error, 'should not have an error for success responses');
+    assert.equal(200, res.status);
+    assert.equal(2, res.statusType);
+    done();
+  } catch (err) {
+    done(err);
+  }
+});

res.type

should provide the mime-type void of params

request.get(`${uri}/login`).end((error, res) => {
+  try {
+    res.type.should.equal('text/html');
+    res.charset.should.equal('utf-8');
+    done();
+  } catch (err) {
+    done(err);
+  }
+});

req.set(field, val)

should set the header field

request
+  .post(`${uri}/echo`)
+  .set('X-Foo', 'bar')
+  .set('X-Bar', 'baz')
+  .end((error, res) => {
+    try {
+      assert.equal('bar', res.header['x-foo']);
+      assert.equal('baz', res.header['x-bar']);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

req.set(obj)

should set the header fields

request
+  .post(`${uri}/echo`)
+  .set({ 'X-Foo': 'bar', 'X-Bar': 'baz' })
+  .end((error, res) => {
+    try {
+      assert.equal('bar', res.header['x-foo']);
+      assert.equal('baz', res.header['x-bar']);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

req.type(str)

should set the Content-Type

request
+  .post(`${uri}/echo`)
+  .type('text/x-foo')
+  .end((error, res) => {
+    try {
+      res.header['content-type'].should.equal('text/x-foo');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should map "json"

request
+  .post(`${uri}/echo`)
+  .type('json')
+  .send('{"a": 1}')
+  .end((error, res) => {
+    try {
+      res.should.be.json();
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should map "html"

request
+  .post(`${uri}/echo`)
+  .type('html')
+  .end((error, res) => {
+    try {
+      res.header['content-type'].should.equal('text/html');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

req.accept(str)

should set Accept

request
+  .get(`${uri}/echo`)
+  .accept('text/x-foo')
+  .end((error, res) => {
+    try {
+      res.header.accept.should.equal('text/x-foo');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should map "json"

request
+  .get(`${uri}/echo`)
+  .accept('json')
+  .end((error, res) => {
+    try {
+      res.header.accept.should.equal('application/json');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should map "xml"

request
+  .get(`${uri}/echo`)
+  .accept('xml')
+  .end((error, res) => {
+    try {
+      // Mime module keeps changing this :(
+      assert(
+        res.header.accept == 'application/xml' ||
+          res.header.accept == 'text/xml'
+      );
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should map "html"

request
+  .get(`${uri}/echo`)
+  .accept('html')
+  .end((error, res) => {
+    try {
+      res.header.accept.should.equal('text/html');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

req.send(str)

should write the string

request
+  .post(`${uri}/echo`)
+  .type('json')
+  .send('{"name":"tobi"}')
+  .end((error, res) => {
+    try {
+      res.text.should.equal('{"name":"tobi"}');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

req.send(Object)

should default to json

request
+  .post(`${uri}/echo`)
+  .send({ name: 'tobi' })
+  .end((error, res) => {
+    try {
+      res.should.be.json();
+      res.text.should.equal('{"name":"tobi"}');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

when called several times

should merge the objects

request
+  .post(`${uri}/echo`)
+  .send({ name: 'tobi' })
+  .send({ age: 1 })
+  .end((error, res) => {
+    try {
+      res.should.be.json();
+      if (NODE) {
+        res.buffered.should.be.true();
+      }
+      res.text.should.equal('{"name":"tobi","age":1}');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

.end(fn)

should check arity

request
+  .post(`${uri}/echo`)
+  .send({ name: 'tobi' })
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      res.text.should.equal('{"name":"tobi"}');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should emit request

const request_ = request.post(`${uri}/echo`);
+request_.on('request', (request) => {
+  assert.equal(request_, request);
+  done();
+});
+request_.end();

should emit response

request
+  .post(`${uri}/echo`)
+  .send({ name: 'tobi' })
+  .on('response', (res) => {
+    res.text.should.equal('{"name":"tobi"}');
+    done();
+  })
+  .end();

.then(fulfill, reject)

should support successful fulfills with .then(fulfill)

if (typeof Promise === 'undefined') {
+  return done();
+}
+request
+  .post(`${uri}/echo`)
+  .send({ name: 'tobi' })
+  .then((res) => {
+    res.type.should.equal('application/json');
+    res.text.should.equal('{"name":"tobi"}');
+    done();
+  });

should reject an error with .then(null, reject)

if (typeof Promise === 'undefined') {
+  return done();
+}
+request.get(`${uri}/error`).then(null, (err) => {
+  assert.equal(err.status, 500);
+  assert.equal(err.response.text, 'boom');
+  done();
+});

.catch(reject)

should reject an error with .catch(reject)

if (typeof Promise === 'undefined') {
+  return done();
+}
+request.get(`${uri}/error`).catch((err) => {
+  assert.equal(err.status, 500);
+  assert.equal(err.response.text, 'boom');
+  done();
+});

.abort()

should abort the request

const request_ = request.get(`${uri}/delay/3000`);
+request_.end((error, res) => {
+  try {
+    assert(false, 'should not complete the request');
+  } catch (err) {
+    done(err);
+  }
+});
+request_.on('error', (error) => {
+  done(error);
+});
+request_.on('abort', done);
+setTimeout(() => {
+  request_.abort();
+}, 500);

should abort the promise

const request_ = request.get(`${uri}/delay/3000`);
+setTimeout(() => {
+  request_.abort();
+}, 10);
+return request_.then(
+  () => {
+    assert.fail('should not complete the request');
+  },
+  (err) => {
+    assert.equal('ABORTED', err.code);
+  }
+);

should allow chaining .abort() several times

const request_ = request.get(`${uri}/delay/3000`);
+request_.end((error, res) => {
+  try {
+    assert(false, 'should not complete the request');
+  } catch (err) {
+    done(err);
+  }
+});
+// This also verifies only a single 'done' event is emitted
+request_.on('abort', done);
+setTimeout(() => {
+  request_.abort().abort().abort();
+}, 1000);

should not allow abort then end

request
+  .get(`${uri}/delay/3000`)
+  .abort()
+  .end((error, res) => {
+    done(error ? undefined : new Error('Expected abort error'));
+  });

req.toJSON()

should describe the request

const request_ = request.post(`${uri}/echo`).send({ foo: 'baz' });
+request_.end((error, res) => {
+  try {
+    const json = request_.toJSON();
+    assert.equal('POST', json.method);
+    assert(/\/echo$/.test(json.url));
+    assert.equal('baz', json.data.foo);
+    done();
+  } catch (err) {
+    done(err);
+  }
+});

req.options()

should allow request body

request
+  .options(`${uri}/options/echo/body`)
+  .send({ foo: 'baz' })
+  .end((error, res) => {
+    try {
+      assert.equal(error, null);
+      assert.strictEqual(res.body.foo, 'baz');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

req.sortQuery()

nop with no querystring

request
+  .get(`${uri}/url`)
+  .sortQuery()
+  .end((error, res) => {
+    try {
+      assert.equal(res.text, '/url');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should sort the request querystring

request
+  .get(`${uri}/url`)
+  .query('search=Manny')
+  .query('order=desc')
+  .sortQuery()
+  .end((error, res) => {
+    try {
+      assert.equal(res.text, '/url?order=desc&search=Manny');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should allow disabling sorting

request
+  .get(`${uri}/url`)
+  .query('search=Manny')
+  .query('order=desc')
+  .sortQuery() // take default of true
+  .sortQuery(false) // override it in later call
+  .end((error, res) => {
+    try {
+      assert.equal(res.text, '/url?search=Manny&order=desc');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should sort the request querystring using customized function

request
+  .get(`${uri}/url`)
+  .query('name=Nick')
+  .query('search=Manny')
+  .query('order=desc')
+  .sortQuery((a, b) => a.length - b.length)
+  .end((error, res) => {
+    try {
+      assert.equal(res.text, '/url?name=Nick&order=desc&search=Manny');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

+ +

req.set("Content-Type", contentType)

should work with just the contentType component

request
+  .post(`${uri}/echo`)
+  .set('Content-Type', 'application/json')
+  .send({ name: 'tobi' })
+  .end((error) => {
+    assert(!error);
+    done();
+  });

should work with the charset component

request
+  .post(`${uri}/echo`)
+  .set('Content-Type', 'application/json; charset=utf-8')
+  .send({ name: 'tobi' })
+  .end((error) => {
+    assert(!error);
+    done();
+  });

req.send(Object) as "form"

with req.type() set to form

should send x-www-form-urlencoded data

request
+  .post(`${base}/echo`)
+  .type('form')
+  .send({ name: 'tobi' })
+  .end((error, res) => {
+    res.header['content-type'].should.equal(
+      'application/x-www-form-urlencoded'
+    );
+    res.text.should.equal('name=tobi');
+    done();
+  });

when called several times

should merge the objects

request
+  .post(`${base}/echo`)
+  .type('form')
+  .send({ name: { first: 'tobi', last: 'holowaychuk' } })
+  .send({ age: '1' })
+  .end((error, res) => {
+    res.header['content-type'].should.equal(
+      'application/x-www-form-urlencoded'
+    );
+    res.text.should.equal(
+      'name%5Bfirst%5D=tobi&name%5Blast%5D=holowaychuk&age=1'
+    );
+    done();
+  });

+ +

req.attach

ignores null file

request
+  .post('/echo')
+  .attach('image', null)
+  .end((error, res) => {
+    done();
+  });

req.field

allow bools

if (!formDataSupported) {
+  return done();
+}
+request
+  .post(`${base}/formecho`)
+  .field('bools', true)
+  .field('strings', 'true')
+  .end((error, res) => {
+    assert.ifError(error);
+    assert.deepStrictEqual(res.body, { bools: 'true', strings: 'true' });
+    done();
+  });

allow objects

if (!formDataSupported) {
+  return done();
+}
+request
+  .post(`${base}/formecho`)
+  .field({ bools: true, strings: 'true' })
+  .end((error, res) => {
+    assert.ifError(error);
+    assert.deepStrictEqual(res.body, { bools: 'true', strings: 'true' });
+    done();
+  });

works with arrays in objects

if (!formDataSupported) {
+  return done();
+}
+request
+  .post(`${base}/formecho`)
+  .field({ numbers: [1, 2, 3] })
+  .end((error, res) => {
+    assert.ifError(error);
+    assert.deepStrictEqual(res.body, { numbers: ['1', '2', '3'] });
+    done();
+  });

works with arrays

if (!formDataSupported) {
+  return done();
+}
+request
+  .post(`${base}/formecho`)
+  .field('letters', ['a', 'b', 'c'])
+  .end((error, res) => {
+    assert.ifError(error);
+    assert.deepStrictEqual(res.body, { letters: ['a', 'b', 'c'] });
+    done();
+  });

throw when empty

should.throws(() => {
+  request.post(`${base}/echo`).field();
+}, /name/);
+should.throws(() => {
+  request.post(`${base}/echo`).field('name');
+}, /val/);

cannot be mixed with send()

assert.throws(() => {
+  request.post('/echo').field('form', 'data').send('hi');
+});
+assert.throws(() => {
+  request.post('/echo').send('hi').field('form', 'data');
+});

req.send(Object) as "json"

should default to json

request
+  .post(`${uri}/echo`)
+  .send({ name: 'tobi' })
+  .end((error, res) => {
+    res.should.be.json();
+    res.text.should.equal('{"name":"tobi"}');
+    done();
+  });

should work with arrays

request
+  .post(`${uri}/echo`)
+  .send([1, 2, 3])
+  .end((error, res) => {
+    res.should.be.json();
+    res.text.should.equal('[1,2,3]');
+    done();
+  });

should work with value null

request
+  .post(`${uri}/echo`)
+  .type('json')
+  .send('null')
+  .end((error, res) => {
+    res.should.be.json();
+    assert.strictEqual(res.body, null);
+    done();
+  });

should work with value false

request
+  .post(`${uri}/echo`)
+  .type('json')
+  .send('false')
+  .end((error, res) => {
+    res.should.be.json();
+    res.body.should.equal(false);
+    done();
+  });

should work with empty string value

request
+  .post(`${uri}/echo`)
+  .type('json')
+  .send('""')
+  .end((error, res) => {
+    res.should.be.json();
+    res.body.should.equal('');
+    done();
+  });

should work with vendor MIME type

request
+  .post(`${uri}/echo`)
+  .set('Content-Type', 'application/vnd.example+json')
+  .send({ name: 'vendor' })
+  .end((error, res) => {
+    res.text.should.equal('{"name":"vendor"}');
+    ({ name: 'vendor' }.should.eql(res.body));
+    done();
+  });

when called several times

should merge the objects

request
+  .post(`${uri}/echo`)
+  .send({ name: 'tobi' })
+  .send({ age: 1 })
+  .end((error, res) => {
+    res.should.be.json();
+    res.text.should.equal('{"name":"tobi","age":1}');
+    ({ name: 'tobi', age: 1 }.should.eql(res.body));
+    done();
+  });

res.body

application/json

should parse the body

request.get(`${uri}/json`).end((error, res) => {
+  res.text.should.equal('{"name":"manny"}');
+  res.body.should.eql({ name: 'manny' });
+  done();
+});

Invalid JSON response

should return the raw response

request.get(`${uri}/invalid-json`).end((error, res) => {
+  assert.deepEqual(
+    error.rawResponse,
+    ")]}', {'header':{'code':200,'text':'OK','version':'1.0'},'data':'some data'}"
+  );
+  done();
+});

should return the http status code

request.get(`${uri}/invalid-json-forbidden`).end((error, res) => {
+  assert.equal(error.statusCode, 403);
+  done();
+});

+ +

request

on redirect

should retain header fields

request
+  .get(`${base}/header`)
+  .set('X-Foo', 'bar')
+  .end((error, res) => {
+    try {
+      assert(res.body);
+      res.body.should.have.property('x-foo', 'bar');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should preserve timeout across redirects

request
+  .get(`${base}/movies/random`)
+  .timeout(250)
+  .end((error, res) => {
+    try {
+      assert(error instanceof Error, 'expected an error');
+      error.should.have.property('timeout', 250);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should successfully redirect after retry on error

const id = Math.random() * 1_000_000 * Date.now();
+request
+  .get(`${base}/error/redirect/${id}`)
+  .retry(2)
+  .end((error, res) => {
+    assert(res.ok, 'response should be ok');
+    assert(res.text, 'first movie page');
+    done();
+  });

should preserve retries across redirects

const id = Math.random() * 1_000_000 * Date.now();
+request
+  .get(`${base}/error/redirect-error${id}`)
+  .retry(2)
+  .end((error, res) => {
+    assert(error, 'expected an error');
+    assert.equal(2, error.retries, 'expected an error with .retries');
+    assert.equal(500, error.status, 'expected an error status of 500');
+    done();
+  });

on 303

should redirect with same method

request
+  .put(`${base}/redirect-303`)
+  .send({ msg: 'hello' })
+  .redirects(1)
+  .on('redirect', (res) => {
+    res.headers.location.should.equal('/reply-method');
+  })
+  .end((error, res) => {
+    if (error) {
+      done(error);
+      return;
+    }
+    res.text.should.equal('method=get');
+    done();
+  });

on 307

should redirect with same method

if (isMSIE) return done(); // IE9 broken
+request
+  .put(`${base}/redirect-307`)
+  .send({ msg: 'hello' })
+  .redirects(1)
+  .on('redirect', (res) => {
+    res.headers.location.should.equal('/reply-method');
+  })
+  .end((error, res) => {
+    if (error) {
+      done(error);
+      return;
+    }
+    res.text.should.equal('method=put');
+    done();
+  });

on 308

should redirect with same method

if (isMSIE) return done(); // IE9 broken
+request
+  .put(`${base}/redirect-308`)
+  .send({ msg: 'hello' })
+  .redirects(1)
+  .on('redirect', (res) => {
+    res.headers.location.should.equal('/reply-method');
+  })
+  .end((error, res) => {
+    if (error) {
+      done(error);
+      return;
+    }
+    res.text.should.equal('method=put');
+    done();
+  });

+ +

request

Request inheritance

assert(request.get(`${uri}/`) instanceof request.Request);

request() simple GET without callback

request('GET', 'test/test.request.js').end();
+next();

request() simple GET

request('GET', `${uri}/ok`).end((error, res) => {
+  try {
+    assert(res instanceof request.Response, 'respond with Response');
+    assert(res.ok, 'response should be ok');
+    assert(res.text, 'res.text');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() simple HEAD

request.head(`${uri}/ok`).end((error, res) => {
+  try {
+    assert(res instanceof request.Response, 'respond with Response');
+    assert(res.ok, 'response should be ok');
+    assert(!res.text, 'res.text');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() GET 5xx

request('GET', `${uri}/error`).end((error, res) => {
+  try {
+    assert(error);
+    assert.equal(error.message, 'Internal Server Error');
+    assert(!res.ok, 'response should not be ok');
+    assert(res.error, 'response should be an error');
+    assert(!res.clientError, 'response should not be a client error');
+    assert(res.serverError, 'response should be a server error');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() GET 4xx

request('GET', `${uri}/notfound`).end((error, res) => {
+  try {
+    assert(error);
+    assert.equal(error.message, 'Not Found');
+    assert(!res.ok, 'response should not be ok');
+    assert(res.error, 'response should be an error');
+    assert(res.clientError, 'response should be a client error');
+    assert(!res.serverError, 'response should not be a server error');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() GET 404 Not Found

request('GET', `${uri}/notfound`).end((error, res) => {
+  try {
+    assert(error);
+    assert(res.notFound, 'response should be .notFound');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() GET 400 Bad Request

request('GET', `${uri}/bad-request`).end((error, res) => {
+  try {
+    assert(error);
+    assert(res.badRequest, 'response should be .badRequest');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() GET 401 Bad Request

request('GET', `${uri}/unauthorized`).end((error, res) => {
+  try {
+    assert(error);
+    assert(res.unauthorized, 'response should be .unauthorized');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() GET 406 Not Acceptable

request('GET', `${uri}/not-acceptable`).end((error, res) => {
+  try {
+    assert(error);
+    assert(res.notAcceptable, 'response should be .notAcceptable');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() GET 204 No Content

request('GET', `${uri}/no-content`).end((error, res) => {
+  try {
+    assert.ifError(error);
+    assert(res.noContent, 'response should be .noContent');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() DELETE 204 No Content

request('DELETE', `${uri}/no-content`).end((error, res) => {
+  try {
+    assert.ifError(error);
+    assert(res.noContent, 'response should be .noContent');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() header parsing

request('GET', `${uri}/notfound`).end((error, res) => {
+  try {
+    assert(error);
+    assert.equal('text/html; charset=utf-8', res.header['content-type']);
+    assert.equal('Express', res.header['x-powered-by']);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() .status

request('GET', `${uri}/notfound`).end((error, res) => {
+  try {
+    assert(error);
+    assert.equal(404, res.status, 'response .status');
+    assert.equal(4, res.statusType, 'response .statusType');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

get()

request.get(`${uri}/notfound`).end((error, res) => {
+  try {
+    assert(error);
+    assert.equal(404, res.status, 'response .status');
+    assert.equal(4, res.statusType, 'response .statusType');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

put()

request.put(`${uri}/user/12`).end((error, res) => {
+  try {
+    assert.equal('updated', res.text, 'response text');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

put().send()

request
+  .put(`${uri}/user/13/body`)
+  .send({ user: 'new' })
+  .end((error, res) => {
+    try {
+      assert.equal('received new', res.text, 'response text');
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

post()

request.post(`${uri}/user`).end((error, res) => {
+  try {
+    assert.equal('created', res.text, 'response text');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

del()

request.del(`${uri}/user/12`).end((error, res) => {
+  try {
+    assert.equal('deleted', res.text, 'response text');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

delete()

request.delete(`${uri}/user/12`).end((error, res) => {
+  try {
+    assert.equal('deleted', res.text, 'response text');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

post() data

request
+  .post(`${uri}/todo/item`)
+  .type('application/octet-stream')
+  .send('tobi')
+  .end((error, res) => {
+    try {
+      assert.equal('added "tobi"', res.text, 'response text');
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .type()

request
+  .post(`${uri}/user/12/pet`)
+  .type('urlencoded')
+  .send('pet=tobi')
+  .end((error, res) => {
+    try {
+      assert.equal('added pet "tobi"', res.text, 'response text');
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .type() with alias

request
+  .post(`${uri}/user/12/pet`)
+  .type('application/x-www-form-urlencoded')
+  .send('pet=tobi')
+  .end((error, res) => {
+    try {
+      assert.equal('added pet "tobi"', res.text, 'response text');
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .get() with no data or callback

request.get(`${uri}/echo-header/content-type`);
+next();

request .send() with no data only

request.post(`${uri}/user/5/pet`).type('urlencoded').send('pet=tobi');
+next();

request .send() with callback only

request
+  .get(`${uri}/echo-header/accept`)
+  .set('Accept', 'foo/bar')
+  .end((error, res) => {
+    try {
+      assert.equal('foo/bar', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .accept() with json

request
+  .get(`${uri}/echo-header/accept`)
+  .accept('json')
+  .end((error, res) => {
+    try {
+      assert.equal('application/json', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .accept() with application/json

request
+  .get(`${uri}/echo-header/accept`)
+  .accept('application/json')
+  .end((error, res) => {
+    try {
+      assert.equal('application/json', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .accept() with xml

request
+  .get(`${uri}/echo-header/accept`)
+  .accept('xml')
+  .end((error, res) => {
+    try {
+      // We can't depend on mime module to be consistent with this
+      assert(res.text == 'application/xml' || res.text == 'text/xml');
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .accept() with application/xml

request
+  .get(`${uri}/echo-header/accept`)
+  .accept('application/xml')
+  .end((error, res) => {
+    try {
+      assert.equal('application/xml', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .end()

request
+  .put(`${uri}/echo-header/content-type`)
+  .set('Content-Type', 'text/plain')
+  .send('wahoo')
+  .end((error, res) => {
+    try {
+      assert.equal('text/plain', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .send()

request
+  .put(`${uri}/echo-header/content-type`)
+  .set('Content-Type', 'text/plain')
+  .send('wahoo')
+  .end((error, res) => {
+    try {
+      assert.equal('text/plain', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .set()

request
+  .put(`${uri}/echo-header/content-type`)
+  .set('Content-Type', 'text/plain')
+  .send('wahoo')
+  .end((error, res) => {
+    try {
+      assert.equal('text/plain', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .set(object)

request
+  .put(`${uri}/echo-header/content-type`)
+  .set({ 'Content-Type': 'text/plain' })
+  .send('wahoo')
+  .end((error, res) => {
+    try {
+      assert.equal('text/plain', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

POST urlencoded

request
+  .post(`${uri}/pet`)
+  .type('urlencoded')
+  .send({ name: 'Manny', species: 'cat' })
+  .end((error, res) => {
+    try {
+      assert.equal('added Manny the cat', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

POST json

request
+  .post(`${uri}/pet`)
+  .type('json')
+  .send({ name: 'Manny', species: 'cat' })
+  .end((error, res) => {
+    try {
+      assert.equal('added Manny the cat', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

POST json array

request
+  .post(`${uri}/echo`)
+  .send([1, 2, 3])
+  .end((error, res) => {
+    try {
+      assert.equal(
+        'application/json',
+        res.header['content-type'].split(';')[0]
+      );
+      assert.equal('[1,2,3]', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

POST json default

request
+  .post(`${uri}/pet`)
+  .send({ name: 'Manny', species: 'cat' })
+  .end((error, res) => {
+    try {
+      assert.equal('added Manny the cat', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

POST json contentType charset

request
+  .post(`${uri}/echo`)
+  .set('Content-Type', 'application/json; charset=UTF-8')
+  .send({ data: ['data1', 'data2'] })
+  .end((error, res) => {
+    try {
+      assert.equal('{"data":["data1","data2"]}', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

POST json contentType vendor

request
+  .post(`${uri}/echo`)
+  .set('Content-Type', 'application/vnd.example+json')
+  .send({ data: ['data1', 'data2'] })
+  .end((error, res) => {
+    try {
+      assert.equal('{"data":["data1","data2"]}', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

POST multiple .send() calls

request
+  .post(`${uri}/pet`)
+  .send({ name: 'Manny' })
+  .send({ species: 'cat' })
+  .end((error, res) => {
+    try {
+      assert.equal('added Manny the cat', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

POST multiple .send() strings

request
+  .post(`${uri}/echo`)
+  .send('user[name]=tj')
+  .send('user[email]=tj@vision-media.ca')
+  .end((error, res) => {
+    try {
+      assert.equal(
+        'application/x-www-form-urlencoded',
+        res.header['content-type'].split(';')[0]
+      );
+      assert.equal(
+        res.text,
+        'user[name]=tj&user[email]=tj@vision-media.ca'
+      );
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

POST with no data

request
+  .post(`${uri}/empty-body`)
+  .send()
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      assert(res.noContent, 'response should be .noContent');
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET .type

request.get(`${uri}/pets`).end((error, res) => {
+  try {
+    assert.equal('application/json', res.type);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

GET Content-Type params

request.get(`${uri}/text`).end((error, res) => {
+  try {
+    assert.equal('utf-8', res.charset);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

GET json

request.get(`${uri}/pets`).end((error, res) => {
+  try {
+    assert.deepEqual(res.body, ['tobi', 'loki', 'jane']);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

GET json-seq

request
+  .get(`${uri}/json-seq`)
+  .buffer()
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      assert.deepEqual(res.text, '\u001E{"id":1}\n\u001E{"id":2}\n');
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET binary data

request
+  .get(`${uri}/binary-data`)
+  .buffer()
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      assert.deepEqual(res.body, binData);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET x-www-form-urlencoded

request.get(`${uri}/foo`).end((error, res) => {
+  try {
+    assert.deepEqual(res.body, { foo: 'bar' });
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

GET shorthand

request.get(`${uri}/foo`, (error, res) => {
+  try {
+    assert.equal('foo=bar', res.text);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

POST shorthand

request.post(`${uri}/user/0/pet`, { pet: 'tobi' }, (error, res) => {
+  try {
+    assert.equal('added pet "tobi"', res.text);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

POST shorthand without callback

request.post(`${uri}/user/0/pet`, { pet: 'tobi' }).end((error, res) => {
+  try {
+    assert.equal('added pet "tobi"', res.text);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

GET querystring object with array

request
+  .get(`${uri}/querystring`)
+  .query({ val: ['a', 'b', 'c'] })
+  .end((error, res) => {
+    try {
+      assert.deepEqual(res.body, { val: ['a', 'b', 'c'] });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET querystring object with array and primitives

request
+  .get(`${uri}/querystring`)
+  .query({ array: ['a', 'b', 'c'], string: 'foo', number: 10 })
+  .end((error, res) => {
+    try {
+      assert.deepEqual(res.body, {
+        array: ['a', 'b', 'c'],
+        string: 'foo',
+        number: 10
+      });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET querystring object with two arrays

request
+  .get(`${uri}/querystring`)
+  .query({ array1: ['a', 'b', 'c'], array2: [1, 2, 3] })
+  .end((error, res) => {
+    try {
+      assert.deepEqual(res.body, {
+        array1: ['a', 'b', 'c'],
+        array2: [1, 2, 3]
+      });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET querystring object

request
+  .get(`${uri}/querystring`)
+  .query({ search: 'Manny' })
+  .end((error, res) => {
+    try {
+      assert.deepEqual(res.body, { search: 'Manny' });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET querystring append original

request
+  .get(`${uri}/querystring?search=Manny`)
+  .query({ range: '1..5' })
+  .end((error, res) => {
+    try {
+      assert.deepEqual(res.body, { search: 'Manny', range: '1..5' });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET querystring multiple objects

request
+  .get(`${uri}/querystring`)
+  .query({ search: 'Manny' })
+  .query({ range: '1..5' })
+  .query({ order: 'desc' })
+  .end((error, res) => {
+    try {
+      assert.deepEqual(res.body, {
+        search: 'Manny',
+        range: '1..5',
+        order: 'desc'
+      });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET querystring with strings

request
+  .get(`${uri}/querystring`)
+  .query('search=Manny')
+  .query('range=1..5')
+  .query('order=desc')
+  .end((error, res) => {
+    try {
+      assert.deepEqual(res.body, {
+        search: 'Manny',
+        range: '1..5',
+        order: 'desc'
+      });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET querystring with strings and objects

request
+  .get(`${uri}/querystring`)
+  .query('search=Manny')
+  .query({ order: 'desc', range: '1..5' })
+  .end((error, res) => {
+    try {
+      assert.deepEqual(res.body, {
+        search: 'Manny',
+        range: '1..5',
+        order: 'desc'
+      });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET shorthand payload goes to querystring

request.get(
+  `${uri}/querystring`,
+  { foo: 'FOO', bar: 'BAR' },
+  (error, res) => {
+    try {
+      assert.deepEqual(res.body, { foo: 'FOO', bar: 'BAR' });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  }
+);

HEAD shorthand payload goes to querystring

request.head(
+  `${uri}/querystring-in-header`,
+  { foo: 'FOO', bar: 'BAR' },
+  (error, res) => {
+    try {
+      assert.deepEqual(JSON.parse(res.headers.query), {
+        foo: 'FOO',
+        bar: 'BAR'
+      });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  }
+);

request(method, url)

request('GET', `${uri}/foo`).end((error, res) => {
+  try {
+    assert.equal('bar', res.body.foo);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request(url)

request(`${uri}/foo`).end((error, res) => {
+  try {
+    assert.equal('bar', res.body.foo);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request(url, fn)

request(`${uri}/foo`, (error, res) => {
+  try {
+    assert.equal('bar', res.body.foo);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

req.timeout(ms)

const request_ = request.get(`${uri}/delay/3000`).timeout(1000);
+request_.end((error, res) => {
+  try {
+    assert(error, 'error missing');
+    assert.equal(1000, error.timeout, 'err.timeout missing');
+    assert.equal(
+      'Timeout of 1000ms exceeded',
+      error.message,
+      'err.message incorrect'
+    );
+    assert.equal(null, res);
+    assert(request_.timedout, true);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

req.timeout(ms) with redirect

const request_ = request.get(`${uri}/delay/const`).timeout(1000);
+request_.end((error, res) => {
+  try {
+    assert(error, 'error missing');
+    assert.equal(1000, error.timeout, 'err.timeout missing');
+    assert.equal(
+      'Timeout of 1000ms exceeded',
+      error.message,
+      'err.message incorrect'
+    );
+    assert.equal(null, res);
+    assert(request_.timedout, true);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request event

request
+  .get(`${uri}/foo`)
+  .on('request', (request_) => {
+    try {
+      assert.equal(`${uri}/foo`, request_.url);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  })
+  .end();

response event

request
+  .get(`${uri}/foo`)
+  .on('response', (res) => {
+    try {
+      assert.equal('bar', res.body.foo);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  })
+  .end();

response should set statusCode

request.get(`${uri}/ok`, (error, res) => {
+  try {
+    assert.strictEqual(res.statusCode, 200);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

req.toJSON()

request.get(`${uri}/ok`).end((error, res) => {
+  try {
+    const index = (res.request || res.req).toJSON();
+    for (const property of ['url', 'method', 'data', 'headers']) {
+      assert(index.hasOwnProperty(property));
+    }
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

.retry(count)

should not retry if passed "0"

request
+  .get(`${base}/error`)
+  .retry(0)
+  .end((error, res) => {
+    try {
+      assert(error, 'expected an error');
+      assert.equal(
+        undefined,
+        error.retries,
+        'expected an error without .retries'
+      );
+      assert.equal(500, error.status, 'expected an error status of 500');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should not retry if passed an invalid number

request
+  .get(`${base}/error`)
+  .retry(-2)
+  .end((error, res) => {
+    try {
+      assert(error, 'expected an error');
+      assert.equal(
+        undefined,
+        error.retries,
+        'expected an error without .retries'
+      );
+      assert.equal(500, error.status, 'expected an error status of 500');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should not retry if passed undefined

request
+  .get(`${base}/error`)
+  .retry(undefined)
+  .end((error, res) => {
+    try {
+      assert(error, 'expected an error');
+      assert.equal(
+        undefined,
+        error.retries,
+        'expected an error without .retries'
+      );
+      assert.equal(500, error.status, 'expected an error status of 500');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should handle server error after repeat attempt

request
+  .get(`${base}/error`)
+  .retry(2)
+  .end((error, res) => {
+    try {
+      assert(error, 'expected an error');
+      assert.equal(2, error.retries, 'expected an error with .retries');
+      assert.equal(500, error.status, 'expected an error status of 500');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should retry if passed nothing

request
+  .get(`${base}/error`)
+  .retry()
+  .end((error, res) => {
+    try {
+      assert(error, 'expected an error');
+      assert.equal(1, error.retries, 'expected an error with .retries');
+      assert.equal(500, error.status, 'expected an error status of 500');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should retry if passed "true"

request
+  .get(`${base}/error`)
+  .retry(true)
+  .end((error, res) => {
+    try {
+      assert(error, 'expected an error');
+      assert.equal(1, error.retries, 'expected an error with .retries');
+      assert.equal(500, error.status, 'expected an error status of 500');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should handle successful request after repeat attempt from server error

request
+  .get(`${base}/error/ok/${uniqid()}`)
+  .query({ qs: 'present' })
+  .retry(2)
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      assert(res.ok, 'response should be ok');
+      assert(res.text, 'res.text');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should handle server timeout error after repeat attempt

request
+  .get(`${base}/delay/400`)
+  .timeout(200)
+  .retry(2)
+  .end((error, res) => {
+    try {
+      assert(error, 'expected an error');
+      assert.equal(2, error.retries, 'expected an error with .retries');
+      assert.equal(
+        'number',
+        typeof error.timeout,
+        'expected an error with .timeout'
+      );
+      assert.equal('ECONNABORTED', error.code, 'expected abort error code');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should handle successful request after repeat attempt from server timeout

const url = `/delay/1200/ok/${uniqid()}?built=in`;
+request
+  .get(base + url)
+  .query('string=ified')
+  .query({ json: 'ed' })
+  .timeout(600)
+  .retry(2)
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      assert(res.ok, 'response should be ok');
+      assert.equal(res.text, `ok = ${url}&string=ified&json=ed`);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should handle successful request after repeat attempt from server timeout when using .then(fulfill, reject)

const url = `/delay/1200/ok/${uniqid()}?built=in`;
+request
+  .get(base + url)
+  .query('string=ified')
+  .query({ json: 'ed' })
+  .timeout(600)
+  .retry(1)
+  .then((res, error) => {
+    try {
+      assert.ifError(error);
+      assert(res.ok, 'response should be ok');
+      assert.equal(res.text, `ok = ${url}&string=ified&json=ed`);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should correctly abort a retry attempt

let aborted = false;
+const request_ = request.get(`${base}/delay/400`).timeout(200).retry(2);
+request_.end((error, res) => {
+  try {
+    assert(false, 'should not complete the request');
+  } catch (err) {
+    done(err);
+  }
+});
+request_.on('abort', () => {
+  aborted = true;
+});
+setTimeout(() => {
+  request_.abort();
+  setTimeout(() => {
+    try {
+      assert(aborted, 'should be aborted');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  }, 150);
+}, 150);

should correctly retain header fields

request
+  .get(`${base}/error/ok/${uniqid()}`)
+  .query({ qs: 'present' })
+  .retry(2)
+  .set('X-Foo', 'bar')
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      assert(res.body);
+      res.body.should.have.property('x-foo', 'bar');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should not retry on 4xx responses

request
+  .get(`${base}/bad-request`)
+  .retry(2)
+  .end((error, res) => {
+    try {
+      assert(error, 'expected an error');
+      assert.equal(0, error.retries, 'expected an error with 0 .retries');
+      assert.equal(400, error.status, 'expected an error status of 400');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should execute callback on retry if passed

let callbackCallCount = 0;
+function retryCallback(request) {
+  callbackCallCount++;
+}
+request
+  .get(`${base}/error`)
+  .retry(2, retryCallback)
+  .end((error, res) => {
+    try {
+      assert(error, 'expected an error');
+      assert.equal(2, error.retries, 'expected an error with .retries');
+      assert.equal(500, error.status, 'expected an error status of 500');
+      assert.equal(
+        2,
+        callbackCallCount,
+        'expected the callback to be called on each retry'
+      );
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

.timeout(ms)

when timeout is exceeded

should error

request
+  .get(`${base}/delay/500`)
+  .timeout(150)
+  .end((error, res) => {
+    assert(error, 'expected an error');
+    assert.equal(
+      'number',
+      typeof error.timeout,
+      'expected an error with .timeout'
+    );
+    assert.equal('ECONNABORTED', error.code, 'expected abort error code');
+    done();
+  });

should error in promise interface

request
+  .get(`${base}/delay/500`)
+  .timeout(150)
+  .catch((err) => {
+    assert(err, 'expected an error');
+    assert.equal(
+      'number',
+      typeof err.timeout,
+      'expected an error with .timeout'
+    );
+    assert.equal('ECONNABORTED', err.code, 'expected abort error code');
+    done();
+  });

should handle gzip timeout

request
+  .get(`${base}/delay/zip`)
+  .timeout(150)
+  .end((error, res) => {
+    assert(error, 'expected an error');
+    assert.equal(
+      'number',
+      typeof error.timeout,
+      'expected an error with .timeout'
+    );
+    assert.equal('ECONNABORTED', error.code, 'expected abort error code');
+    done();
+  });

should handle buffer timeout

request
+  .get(`${base}/delay/json`)
+  .buffer(true)
+  .timeout(150)
+  .end((error, res) => {
+    assert(error, 'expected an error');
+    assert.equal(
+      'number',
+      typeof error.timeout,
+      'expected an error with .timeout'
+    );
+    assert.equal('ECONNABORTED', error.code, 'expected abort error code');
+    done();
+  });

should error on deadline

request
+  .get(`${base}/delay/500`)
+  .timeout({ deadline: 150 })
+  .end((error, res) => {
+    assert(error, 'expected an error');
+    assert.equal(
+      'number',
+      typeof error.timeout,
+      'expected an error with .timeout'
+    );
+    assert.equal('ECONNABORTED', error.code, 'expected abort error code');
+    done();
+  });

should support setting individual options

request
+  .get(`${base}/delay/500`)
+  .timeout({ deadline: 10 })
+  .timeout({ response: 99_999 })
+  .end((error, res) => {
+    assert(error, 'expected an error');
+    assert.equal('ECONNABORTED', error.code, 'expected abort error code');
+    assert.equal('ETIME', error.errno);
+    done();
+  });

should error on response

request
+  .get(`${base}/delay/500`)
+  .timeout({ response: 150 })
+  .end((error, res) => {
+    assert(error, 'expected an error');
+    assert.equal(
+      'number',
+      typeof error.timeout,
+      'expected an error with .timeout'
+    );
+    assert.equal('ECONNABORTED', error.code, 'expected abort error code');
+    assert.equal('ETIMEDOUT', error.errno);
+    done();
+  });

should accept slow body with fast response

request
+  .get(`${base}/delay/slowbody`)
+  .timeout({ response: 1000 })
+  .on('progress', () => {
+    // This only makes the test faster without relying on arbitrary timeouts
+    request.get(`${base}/delay/slowbody/finish`).end();
+  })
+  .end(done);

+ +

request

use

should use plugin success

const now = `${Date.now()}`;
+function uuid(request_) {
+  request_.set('X-UUID', now);
+  return request_;
+}
+function prefix(request_) {
+  request_.url = uri + request_.url;
+  return request_;
+}
+request
+  .get('/echo')
+  .use(uuid)
+  .use(prefix)
+  .end((error, res) => {
+    assert.strictEqual(res.statusCode, 200);
+    assert.equal(res.get('X-UUID'), now);
+    done();
+  });

+ +

subclass

should be an instance of Request

const request_ = request.get('/');
+assert(request_ instanceof request.Request);

should use patched subclass

assert(OriginalRequest);
+let constructorCalled;
+let sendCalled;
+function NewRequest(...args) {
+  constructorCalled = true;
+  OriginalRequest.apply(this, args);
+}
+NewRequest.prototype = Object.create(OriginalRequest.prototype);
+NewRequest.prototype.send = function () {
+  sendCalled = true;
+  return this;
+};
+request.Request = NewRequest;
+const request_ = request.get('/').send();
+assert(constructorCalled);
+assert(sendCalled);
+assert(request_ instanceof NewRequest);
+assert(request_ instanceof OriginalRequest);

should use patched subclass in agent too

if (!request.agent) return; // Node-only
+function NewRequest(...args) {
+  OriginalRequest.apply(this, args);
+}
+NewRequest.prototype = Object.create(OriginalRequest.prototype);
+request.Request = NewRequest;
+const request_ = request.agent().del('/');
+assert(request_ instanceof NewRequest);
+assert(request_ instanceof OriginalRequest);

request

persistent agent

should gain a session on POST

agent3.post(`${base}/signin`).then((res) => {
+        res.should.have.status(200);
+        should.not.exist(res.headers['set-cookie']);
+        res.text.should.containEql('dashboard');
+      })

should start with empty session (set cookies)

agent1.get(`${base}/dashboard`).end((error, res) => {
+  should.exist(error);
+  res.should.have.status(401);
+  should.exist(res.headers['set-cookie']);
+  done();
+});

should gain a session (cookies already set)

agent1.post(`${base}/signin`).then((res) => {
+        res.should.have.status(200);
+        should.not.exist(res.headers['set-cookie']);
+        res.text.should.containEql('dashboard');
+      })

should persist cookies across requests

agent1.get(`${base}/dashboard`).then((res) => {
+        res.should.have.status(200);
+      })

should have the cookie set in the end callback

agent4
+        .post(`${base}/setcookie`)
+        .then(() => agent4.get(`${base}/getcookie`))
+        .then((res) => {
+          res.should.have.status(200);
+          assert.strictEqual(res.text, 'jar');
+        })

should not share cookies

agent2.get(`${base}/dashboard`).end((error, res) => {
+  should.exist(error);
+  res.should.have.status(401);
+  done();
+});

should not lose cookies between agents

agent1.get(`${base}/dashboard`).then((res) => {
+        res.should.have.status(200);
+      })

should be able to follow redirects

agent1.get(base).then((res) => {
+        res.should.have.status(200);
+        res.text.should.containEql('dashboard');
+      })

should be able to post redirects

agent1
+        .post(`${base}/redirect`)
+        .send({ foo: 'bar', baz: 'blaaah' })
+        .then((res) => {
+          res.should.have.status(200);
+          res.text.should.containEql('simple');
+          res.redirects.should.eql([`${base}/simple`]);
+        })

should be able to limit redirects

agent1
+  .get(base)
+  .redirects(0)
+  .end((error, res) => {
+    should.exist(error);
+    res.should.have.status(302);
+    res.redirects.should.eql([]);
+    res.header.location.should.equal('/dashboard');
+    done();
+  });

should be able to create a new session (clear cookie)

agent1.post(`${base}/signout`).then((res) => {
+        res.should.have.status(200);
+        should.exist(res.headers['set-cookie']);
+      })

should regenerate with an empty session

agent1.get(`${base}/dashboard`).end((error, res) => {
+  should.exist(error);
+  res.should.have.status(401);
+  should.not.exist(res.headers['set-cookie']);
+  done();
+});

+ +

Basic auth

when credentials are present in url

should set Authorization

const new_url = URL.parse(base);
+new_url.auth = 'tobi:learnboost';
+new_url.pathname = '/basic-auth';
+request.get(URL.format(new_url)).end((error, res) => {
+  res.status.should.equal(200);
+  done();
+});

req.auth(user, pass)

should set Authorization

request
+  .get(`${base}/basic-auth`)
+  .auth('tobi', 'learnboost')
+  .end((error, res) => {
+    res.status.should.equal(200);
+    done();
+  });

req.auth(user + ":" + pass)

should set authorization

request
+  .get(`${base}/basic-auth/again`)
+  .auth('tobi')
+  .end((error, res) => {
+    res.status.should.eql(200);
+    done();
+  });

+ +

[node] request

should send body with .get().send()

request
+  .get(`${base}/echo`)
+  .set('Content-Type', 'text/plain')
+  .send('wahoo')
+  .end((error, res) => {
+    try {
+      assert.equal('wahoo', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

with an url

should preserve the encoding of the url

request.get(`${base}/url?a=(b%29`).end((error, res) => {
+  assert.equal('/url?a=(b%29', res.text);
+  done();
+});

with an object

should format the url

request.get(url.parse(`${base}/login`)).then((res) => {
+        assert(res.ok);
+      })

without a schema

should default to http

request.get(`${base}/login`).then((res) => {
+        assert.equal(res.status, 200);
+      })

res.toJSON()

should describe the response

request
+        .post(`${base}/echo`)
+        .send({ foo: 'baz' })
+        .then((res) => {
+          const object = res.toJSON();
+          assert.equal('object', typeof object.header);
+          assert.equal('object', typeof object.req);
+          assert.equal(200, object.status);
+          assert.equal('{"foo":"baz"}', object.text);
+        })

res.links

should default to an empty object

request.get(`${base}/login`).then((res) => {
+        res.links.should.eql({});
+      })

should parse the Link header field

request.get(`${base}/links`).end((error, res) => {
+  res.links.next.should.equal(
+    'https://api.github.com/repos/visionmedia/mocha/issues?page=2'
+  );
+  done();
+});

req.unset(field)

should remove the header field

request
+  .post(`${base}/echo`)
+  .unset('User-Agent')
+  .end((error, res) => {
+    assert.equal(void 0, res.header['user-agent']);
+    done();
+  });

case-insensitive

should set/get header fields case-insensitively

const r = request.post(`${base}/echo`);
+r.set('MiXeD', 'helloes');
+assert.strictEqual(r.get('mixed'), 'helloes');

should unset header fields case-insensitively

const r = request.post(`${base}/echo`);
+r.set('MiXeD', 'helloes');
+r.unset('MIXED');
+assert.strictEqual(r.get('mixed'), undefined);

req.write(str)

should write the given data

const request_ = request.post(`${base}/echo`);
+request_.set('Content-Type', 'application/json');
+assert.equal('boolean', typeof request_.write('{"name"'));
+assert.equal('boolean', typeof request_.write(':"tobi"}'));
+request_.end((error, res) => {
+  res.text.should.equal('{"name":"tobi"}');
+  done();
+});

req.pipe(stream)

should pipe the response to the given stream

const stream = new EventEmitter();
+stream.buf = '';
+stream.writable = true;
+stream.write = function (chunk) {
+  this.buf += chunk;
+};
+stream.end = function () {
+  this.buf.should.equal('{"name":"tobi"}');
+  done();
+};
+request.post(`${base}/echo`).send('{"name":"tobi"}').pipe(stream);

.buffer()

should enable buffering

request
+  .get(`${base}/custom`)
+  .buffer()
+  .end((error, res) => {
+    assert.ifError(error);
+    assert.equal('custom stuff', res.text);
+    assert(res.buffered);
+    done();
+  });

should take precedence over request.buffer['someMimeType'] = false

const type = 'application/barbaz';
+const send = 'some text';
+request.buffer[type] = false;
+request
+  .post(`${base}/echo`)
+  .type(type)
+  .send(send)
+  .buffer()
+  .end((error, res) => {
+    delete request.buffer[type];
+    assert.ifError(error);
+    assert.equal(res.type, type);
+    assert.equal(send, res.text);
+    assert(res.buffered);
+    done();
+  });

.buffer(false)

should disable buffering

request
+  .post(`${base}/echo`)
+  .type('application/x-dog')
+  .send('hello this is dog')
+  .buffer(false)
+  .end((error, res) => {
+    assert.ifError(error);
+    assert.equal(null, res.text);
+    res.body.should.eql({});
+    let buf = '';
+    res.setEncoding('utf8');
+    res.on('data', (chunk) => {
+      buf += chunk;
+    });
+    res.on('end', () => {
+      buf.should.equal('hello this is dog');
+      done();
+    });
+  });

should take precedence over request.buffer['someMimeType'] = true

const type = 'application/foobar';
+const send = 'hello this is a dog';
+request.buffer[type] = true;
+request
+  .post(`${base}/echo`)
+  .type(type)
+  .send(send)
+  .buffer(false)
+  .end((error, res) => {
+    delete request.buffer[type];
+    assert.ifError(error);
+    assert.equal(null, res.text);
+    assert.equal(res.type, type);
+    assert(!res.buffered);
+    res.body.should.eql({});
+    let buf = '';
+    res.setEncoding('utf8');
+    res.on('data', (chunk) => {
+      buf += chunk;
+    });
+    res.on('end', () => {
+      buf.should.equal(send);
+      done();
+    });
+  });

.withCredentials()

should not throw an error when using the client-side "withCredentials" method

request
+  .get(`${base}/custom`)
+  .withCredentials()
+  .end((error, res) => {
+    assert.ifError(error);
+    done();
+  });

.agent()

should return the defaut agent

const request_ = request.post(`${base}/echo`);
+request_.agent().should.equal(false);
+done();

.agent(undefined)

should set an agent to undefined and ensure it is chainable

const request_ = request.get(`${base}/echo`);
+const returnValue = request_.agent(undefined);
+returnValue.should.equal(request_);
+assert.strictEqual(request_.agent(), undefined);
+done();

.agent(new http.Agent())

should set passed agent

const http = require('http');
+const request_ = request.get(`${base}/echo`);
+const agent = new http.Agent();
+const returnValue = request_.agent(agent);
+returnValue.should.equal(request_);
+request_.agent().should.equal(agent);
+done();

with a content type other than application/json or text/*

should still use buffering

return request
+  .post(`${base}/echo`)
+  .type('application/x-dog')
+  .send('hello this is dog')
+  .then((res) => {
+    assert.equal(null, res.text);
+    assert.equal(res.body.toString(), 'hello this is dog');
+    res.buffered.should.be.true;
+  });

content-length

should be set to the byte length of a non-buffer object

const decoder = new StringDecoder('utf8');
+let img = fs.readFileSync(`${__dirname}/fixtures/test.png`);
+img = decoder.write(img);
+request
+  .post(`${base}/echo`)
+  .type('application/x-image')
+  .send(img)
+  .buffer(false)
+  .end((error, res) => {
+    assert.ifError(error);
+    assert(!res.buffered);
+    assert.equal(res.header['content-length'], Buffer.byteLength(img));
+    done();
+  });

should be set to the length of a buffer object

const img = fs.readFileSync(`${__dirname}/fixtures/test.png`);
+request
+  .post(`${base}/echo`)
+  .type('application/x-image')
+  .send(img)
+  .buffer(true)
+  .end((error, res) => {
+    assert.ifError(error);
+    assert(res.buffered);
+    assert.equal(res.header['content-length'], img.length);
+    done();
+  });

req.buffer['someMimeType']

should respect that agent.buffer(true) takes precedent

const agent = request.agent();
+agent.buffer(true);
+const type = 'application/somerandomtype';
+const send = 'somerandomtext';
+request.buffer[type] = false;
+agent
+  .post(`${base}/echo`)
+  .type(type)
+  .send(send)
+  .end((error, res) => {
+    delete request.buffer[type];
+    assert.ifError(error);
+    assert.equal(res.type, type);
+    assert.equal(send, res.text);
+    assert(res.buffered);
+    done();
+  });

should respect that agent.buffer(false) takes precedent

const agent = request.agent();
+agent.buffer(false);
+const type = 'application/barrr';
+const send = 'some random text2';
+request.buffer[type] = true;
+agent
+  .post(`${base}/echo`)
+  .type(type)
+  .send(send)
+  .end((error, res) => {
+    delete request.buffer[type];
+    assert.ifError(error);
+    assert.equal(null, res.text);
+    assert.equal(res.type, type);
+    assert(!res.buffered);
+    res.body.should.eql({});
+    let buf = '';
+    res.setEncoding('utf8');
+    res.on('data', (chunk) => {
+      buf += chunk;
+    });
+    res.on('end', () => {
+      buf.should.equal(send);
+      done();
+    });
+  });

should disable buffering for that mimetype when false

const type = 'application/bar';
+const send = 'some random text';
+request.buffer[type] = false;
+request
+  .post(`${base}/echo`)
+  .type(type)
+  .send(send)
+  .end((error, res) => {
+    delete request.buffer[type];
+    assert.ifError(error);
+    assert.equal(null, res.text);
+    assert.equal(res.type, type);
+    assert(!res.buffered);
+    res.body.should.eql({});
+    let buf = '';
+    res.setEncoding('utf8');
+    res.on('data', (chunk) => {
+      buf += chunk;
+    });
+    res.on('end', () => {
+      buf.should.equal(send);
+      done();
+    });
+  });

should enable buffering for that mimetype when true

const type = 'application/baz';
+const send = 'woooo';
+request.buffer[type] = true;
+request
+  .post(`${base}/echo`)
+  .type(type)
+  .send(send)
+  .end((error, res) => {
+    delete request.buffer[type];
+    assert.ifError(error);
+    assert.equal(res.type, type);
+    assert.equal(send, res.text);
+    assert(res.buffered);
+    done();
+  });

should fallback to default handling for that mimetype when undefined

const type = 'application/bazzz';
+const send = 'woooooo';
+return request
+  .post(`${base}/echo`)
+  .type(type)
+  .send(send)
+  .then((res) => {
+    assert.equal(res.type, type);
+    assert.equal(send, res.body.toString());
+    assert(res.buffered);
+  });

exports

should expose .protocols

Object.keys(request.protocols).should.eql(['http:', 'https:', 'http2:']);

should expose .serialize

Object.keys(request.serialize).should.eql([
+  'application/x-www-form-urlencoded',
+  'application/json'
+]);

should expose .parse

Object.keys(request.parse).should.eql([
+  'application/x-www-form-urlencoded',
+  'application/json',
+  'text',
+  'application/json-seq',
+  'application/octet-stream',
+  'application/pdf',
+  'image'
+]);

should export .buffer

Object.keys(request.buffer).should.eql([]);

flags

with 4xx response

should set res.error and res.clientError

request.get(`${base}/notfound`).end((error, res) => {
+  assert(error);
+  assert(!res.ok, 'response should not be ok');
+  assert(res.error, 'response should be an error');
+  assert(res.clientError, 'response should be a client error');
+  assert(!res.serverError, 'response should not be a server error');
+  done();
+});

with 5xx response

should set res.error and res.serverError

request.get(`${base}/error`).end((error, res) => {
+  assert(error);
+  assert(!res.ok, 'response should not be ok');
+  assert(!res.notFound, 'response should not be notFound');
+  assert(res.error, 'response should be an error');
+  assert(!res.clientError, 'response should not be a client error');
+  assert(res.serverError, 'response should be a server error');
+  done();
+});

with 404 Not Found

should res.notFound

request.get(`${base}/notfound`).end((error, res) => {
+  assert(error);
+  assert(res.notFound, 'response should be .notFound');
+  done();
+});

with 400 Bad Request

should set req.badRequest

request.get(`${base}/bad-request`).end((error, res) => {
+  assert(error);
+  assert(res.badRequest, 'response should be .badRequest');
+  done();
+});

with 401 Bad Request

should set res.unauthorized

request.get(`${base}/unauthorized`).end((error, res) => {
+  assert(error);
+  assert(res.unauthorized, 'response should be .unauthorized');
+  done();
+});

with 406 Not Acceptable

should set res.notAcceptable

request.get(`${base}/not-acceptable`).end((error, res) => {
+  assert(error);
+  assert(res.notAcceptable, 'response should be .notAcceptable');
+  done();
+});

with 204 No Content

should set res.noContent

request.get(`${base}/no-content`).end((error, res) => {
+  assert(!error);
+  assert(res.noContent, 'response should be .noContent');
+  done();
+});

with 201 Created

should set res.created

request.post(`${base}/created`).end((error, res) => {
+  assert(!error);
+  assert(res.created, 'response should be .created');
+  done();
+});

with 422 Unprocessable Entity

should set res.unprocessableEntity

request.post(`${base}/unprocessable-entity`).end((error, res) => {
+  assert(error);
+  assert(
+    res.unprocessableEntity,
+    'response should be .unprocessableEntity'
+  );
+  done();
+});

+ +

Merging objects

Don't mix Buffer and JSON

assert.throws(() => {
+  request
+    .post('/echo')
+    .send(Buffer.from('some buffer'))
+    .send({ allowed: false });
+});

req.send(String)

should default to "form"

request
+  .post(`${base}/echo`)
+  .send('user[name]=tj')
+  .send('user[email]=tj@vision-media.ca')
+  .end((error, res) => {
+    res.header['content-type'].should.equal(
+      'application/x-www-form-urlencoded'
+    );
+    res.body.should.eql({
+      user: { name: 'tj', email: 'tj@vision-media.ca' }
+    });
+    done();
+  });

res.body

application/x-www-form-urlencoded

should parse the body

request.get(`${base}/form-data`).end((error, res) => {
+  res.text.should.equal('pet[name]=manny');
+  res.body.should.eql({ pet: { name: 'manny' } });
+  done();
+});

+ +

https

certificate authority

request

should give a good response

request
+  .get(testEndpoint)
+  .ca(ca)
+  .end((error, res) => {
+    assert.ifError(error);
+    assert(res.ok);
+    assert.strictEqual('Safe and secure!', res.text);
+    done();
+  });

should reject unauthorized response

return request
+  .get(testEndpoint)
+  .trustLocalhost(false)
+  .then(
+    () => {
+      throw new Error('Allows MITM');
+    },
+    () => {}
+  );

should not reject unauthorized response

return request
+  .get(testEndpoint)
+  .disableTLSCerts()
+  .then(({ status }) => {
+    assert.strictEqual(status, 200);
+  });

should trust localhost unauthorized response

return request.get(testEndpoint).trustLocalhost(true);

should trust overriden localhost unauthorized response

return request
+  .get(`https://example.com:${server.address().port}`)
+  .connect('127.0.0.1')
+  .trustLocalhost();

.agent

should be able to make multiple requests without redefining the certificate

const agent = request.agent({ ca });
+agent.get(testEndpoint).end((error, res) => {
+  assert.ifError(error);
+  assert(res.ok);
+  assert.strictEqual('Safe and secure!', res.text);
+  agent.get(url.parse(testEndpoint)).end((error, res) => {
+    assert.ifError(error);
+    assert(res.ok);
+    assert.strictEqual('Safe and secure!', res.text);
+    done();
+  });
+});

+ +

client certificates

request

+ +

.agent

+ +

res.body

image/png

should parse the body

request.get(`${base}/image`).end((error, res) => {
+  res.type.should.equal('image/png');
+  Buffer.isBuffer(res.body).should.be.true();
+  (res.body.length - img.length).should.equal(0);
+  done();
+});

application/octet-stream

should parse the body

request
+  .get(`${base}/image-as-octets`)
+  .buffer(true) // that's tech debt :(
+  .end((error, res) => {
+    res.type.should.equal('application/octet-stream');
+    Buffer.isBuffer(res.body).should.be.true();
+    (res.body.length - img.length).should.equal(0);
+    done();
+  });

application/octet-stream

should parse the body (using responseType)

request
+  .get(`${base}/image-as-octets`)
+  .responseType('blob')
+  .end((error, res) => {
+    res.type.should.equal('application/octet-stream');
+    Buffer.isBuffer(res.body).should.be.true();
+    (res.body.length - img.length).should.equal(0);
+    done();
+  });

+ +

zlib

should deflate the content

request.get(base).end((error, res) => {
+  res.should.have.status(200);
+  res.text.should.equal(subject);
+  res.headers['content-length'].should.be.below(subject.length);
+  done();
+});

should protect from zip bombs

request
+  .get(base)
+  .buffer(true)
+  .maxResponseSize(1)
+  .end((error, res) => {
+    try {
+      assert.equal('Maximum response size reached', error && error.message);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should ignore trailing junk

request.get(`${base}/junk`).end((error, res) => {
+  res.should.have.status(200);
+  res.text.should.equal(subject);
+  done();
+});

should ignore missing data

request.get(`${base}/chopped`).end((error, res) => {
+  assert.equal(undefined, error);
+  res.should.have.status(200);
+  res.text.should.startWith(subject);
+  done();
+});

should handle corrupted responses

request.get(`${base}/corrupt`).end((error, res) => {
+  assert(error, 'missing error');
+  assert(!res, 'response should not be defined');
+  done();
+});

should handle no content with gzip header

request.get(`${base}/nocontent`).end((error, res) => {
+  assert.ifError(error);
+  assert(res);
+  res.should.have.status(204);
+  res.text.should.equal('');
+  res.headers.should.not.have.property('content-length');
+  done();
+});

without encoding set

should buffer if asked

return request
+  .get(`${base}/binary`)
+  .buffer(true)
+  .then((res) => {
+    res.should.have.status(200);
+    assert(res.headers['content-length']);
+    assert(res.body.byteLength);
+    assert.equal(subject, res.body.toString());
+  });

should emit buffers

request.get(`${base}/binary`).end((error, res) => {
+  res.should.have.status(200);
+  res.headers['content-length'].should.be.below(subject.length);
+  res.on('data', (chunk) => {
+    chunk.should.have.length(subject.length);
+  });
+  res.on('end', done);
+});

req.lookup()

should set a custom lookup

const r = request.get(`${base}/ok`).lookup(myLookup);
+assert(r.lookup() === myLookup);
+r.then((res) => {
+  res.text.should.equal('ok');
+  done();
+});

Multipart

#field(name, value)

should set a multipart field value

const request_ = request.post(`${base}/echo`);
+request_.field('user[name]', 'tobi');
+request_.field('user[age]', '2');
+request_.field('user[species]', 'ferret');
+return request_.then((res) => {
+  res.body['user[name]'].should.equal('tobi');
+  res.body['user[age]'].should.equal('2');
+  res.body['user[species]'].should.equal('ferret');
+});

should work with file attachments

const request_ = request.post(`${base}/echo`);
+request_.field('name', 'Tobi');
+request_.attach('document', 'test/node/fixtures/user.html');
+request_.field('species', 'ferret');
+return request_.then((res) => {
+  res.body.name.should.equal('Tobi');
+  res.body.species.should.equal('ferret');
+  const html = res.files.document;
+  html.originalFilename.should.equal('user.html');
+  html.mimetype.should.equal('text/html');
+  read(html.filepath).should.equal('<h1>name</h1>');
+});

#attach(name, path)

should attach a file

const request_ = request.post(`${base}/echo`);
+request_.attach('one', 'test/node/fixtures/user.html');
+request_.attach('two', 'test/node/fixtures/user.json');
+request_.attach('three', 'test/node/fixtures/user.txt');
+return request_.then((res) => {
+  const html = res.files.one;
+  const json = res.files.two;
+  const text = res.files.three;
+  html.originalFilename.should.equal('user.html');
+  html.mimetype.should.equal('text/html');
+  read(html.filepath).should.equal('<h1>name</h1>');
+  json.originalFilename.should.equal('user.json');
+  json.mimetype.should.equal('application/json');
+  read(json.filepath).should.equal('{"name":"tobi"}');
+  text.originalFilename.should.equal('user.txt');
+  text.mimetype.should.equal('text/plain');
+  read(text.filepath).should.equal('Tobi');
+});

when a file does not exist

should fail the request with an error

const request_ = request.post(`${base}/echo`);
+request_.attach('name', 'foo');
+// request_.attach('name2', 'bar');
+// request_.attach('name3', 'baz');
+request_.end((error, res) => {
+  assert.ok(Boolean(error), 'Request should have failed.');
+  error.code.should.equal('ENOENT');
+  error.message.should.containEql('ENOENT');
+  if (IS_WINDOWS) {
+    error.path.toLowerCase().should.equal(
+      getFullPath('foo').toLowerCase()
+    );
+  } else {
+    error.path.should.equal(getFullPath('foo'));
+  }
+  done();
+});

promise should fail

return request
+  .post(`${base}/echo`)
+  .field({ a: 1, b: 2 })
+  .attach('c', 'does-not-exist.txt')
+  .then(
+    (res) => assert.fail('It should not allow this'),
+    (err) => {
+      err.code.should.equal('ENOENT');
+      if (IS_WINDOWS) {
+        err.path.toLowerCase().should.equal(
+          getFullPath('does-not-exist.txt').toLowerCase()
+        );
+      } else {
+        err.path.should.equal(getFullPath('does-not-exist.txt'));
+      }
+    }
+  );

should report ENOENT via the callback

request
+  .post(`${base}/echo`)
+  .attach('name', 'file-does-not-exist')
+  .end((error, res) => {
+    assert.ok(Boolean(error), 'Request should have failed');
+    error.code.should.equal('ENOENT');
+    done();
+  });

should report ENOENT via Promise

return request
+  .post(`${base}/echo`)
+  .attach('name', 'file-does-not-exist')
+  .then(
+    (res) => assert.fail('Request should have failed'),
+    (err) => err.code.should.equal('ENOENT')
+  );

#attach(name, path, filename)

should use the custom filename

request
+        .post(`${base}/echo`)
+        .attach('document', 'test/node/fixtures/user.html', 'doc.html')
+        .then((res) => {
+          const html = res.files.document;
+          html.originalFilename.should.equal('doc.html');
+          html.mimetype.should.equal('text/html');
+          read(html.filepath).should.equal('<h1>name</h1>');
+        })

should fire progress event

let loaded = 0;
+let total = 0;
+let uploadEventWasFired = false;
+request
+  .post(`${base}/echo`)
+  .attach('document', 'test/node/fixtures/user.html')
+  .on('progress', (event) => {
+    total = event.total;
+    loaded = event.loaded;
+    if (event.direction === 'upload') {
+      uploadEventWasFired = true;
+    }
+  })
+  .end((error, res) => {
+    if (error) return done(error);
+    const html = res.files.document;
+    html.originalFilename.should.equal('user.html');
+    html.mimetype.should.equal('text/html');
+    read(html.filepath).should.equal('<h1>name</h1>');
+    total.should.equal(223);
+    loaded.should.equal(223);
+    uploadEventWasFired.should.equal(true);
+    done();
+  });

filesystem errors should be caught

request
+  .post(`${base}/echo`)
+  .attach('filedata', 'test/node/fixtures/non-existent-file.ext')
+  .end((error, res) => {
+    assert.ok(Boolean(error), 'Request should have failed.');
+    error.code.should.equal('ENOENT');
+    if (IS_WINDOWS) {
+      error.path.toLowerCase().should.equal(
+        getFullPath('test/node/fixtures/non-existent-file.ext').toLowerCase()
+      );
+    } else {
+      error.path.should.equal(
+        getFullPath('test/node/fixtures/non-existent-file.ext')
+      );
+    }
+    done();
+  });

#field(name, val)

should set a multipart field value

request
+  .post(`${base}/echo`)
+  .field('first-name', 'foo')
+  .field('last-name', 'bar')
+  .end((error, res) => {
+    if (error) done(error);
+    res.should.be.ok();
+    res.body['first-name'].should.equal('foo');
+    res.body['last-name'].should.equal('bar');
+    done();
+  });

#field(object)

should set multiple multipart fields

request
+  .post(`${base}/echo`)
+  .field({ 'first-name': 'foo', 'last-name': 'bar' })
+  .end((error, res) => {
+    if (error) done(error);
+    res.should.be.ok();
+    res.body['first-name'].should.equal('foo');
+    res.body['last-name'].should.equal('bar');
+    done();
+  });

+ +

with network error

should error

request.get(`http://localhost:${this.port}/`).end((error, res) => {
+  assert(error, 'expected an error');
+  done();
+});

request

not modified

should start with 200

request.get(`${base}/if-mod`).end((error, res) => {
+  res.should.have.status(200);
+  res.text.should.match(/^\d+$/);
+  ts = Number(res.text);
+  done();
+});

should then be 304

request
+  .get(`${base}/if-mod`)
+  .set('If-Modified-Since', new Date(ts).toUTCString())
+  .end((error, res) => {
+    res.should.have.status(304);
+    // res.text.should.be.empty
+    done();
+  });

+ +

req.parse(fn)

should take precedence over default parsers

request
+  .get(`${base}/manny`)
+  .parse(request.parse['application/json'])
+  .end((error, res) => {
+    assert(res.ok);
+    assert.equal('{"name":"manny"}', res.text);
+    assert.equal('manny', res.body.name);
+    done();
+  });

should be the only parser

request
+      .get(`${base}/image`)
+      .buffer(false)
+      .parse((res, fn) => {
+        res.on('data', () => {});
+      })
+      .then((res) => {
+        assert(res.ok);
+        assert.strictEqual(res.text, undefined);
+        res.body.should.eql({});
+      })

should emit error if parser throws

request
+  .get(`${base}/manny`)
+  .parse(() => {
+    throw new Error('I am broken');
+  })
+  .on('error', (error) => {
+    error.message.should.equal('I am broken');
+    done();
+  })
+  .end();

should emit error if parser returns an error

request
+  .get(`${base}/manny`)
+  .parse((res, fn) => {
+    fn(new Error('I am broken'));
+  })
+  .on('error', (error) => {
+    error.message.should.equal('I am broken');
+    done();
+  })
+  .end();

should not emit error on chunked json

request.get(`${base}/chunked-json`).end((error) => {
+  assert.ifError(error);
+  done();
+});

should not emit error on aborted chunked json

const request_ = request.get(`${base}/chunked-json`);
+request_.end((error) => {
+  assert.ifError(error);
+  done();
+});
+setTimeout(() => {
+  request_.abort();
+}, 50);

pipe on redirect

should follow Location

const stream = fs.createWriteStream(destinationPath);
+const redirects = [];
+const request_ = request
+  .get(base)
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .connect({
+    inapplicable: 'should be ignored'
+  });
+stream.on('finish', () => {
+  redirects.should.eql(['/movies', '/movies/all', '/movies/all/0']);
+  fs.readFileSync(destinationPath, 'utf8').should.eql('first movie page');
+  done();
+});
+request_.pipe(stream);

request pipe

should act as a writable stream

const request_ = request.post(base);
+const stream = fs.createReadStream('test/node/fixtures/user.json');
+request_.type('json');
+request_.on('response', (res) => {
+  res.body.should.eql({ name: 'tobi' });
+  done();
+});
+stream.pipe(request_);

end() stops piping

const stream = fs.createWriteStream(destinationPath);
+request.get(base).end((error, res) => {
+  try {
+    res.pipe(stream);
+    return done(new Error('Did not prevent nonsense pipe'));
+  } catch {
+    /* expected error */
+  }
+  done();
+});

should act as a readable stream

const stream = fs.createWriteStream(destinationPath);
+let responseCalled = false;
+const request_ = request.get(base);
+request_.type('json');
+request_.on('response', (res) => {
+  res.status.should.eql(200);
+  responseCalled = true;
+});
+stream.on('finish', () => {
+  JSON.parse(fs.readFileSync(destinationPath)).should.eql({
+    name: 'tobi'
+  });
+  responseCalled.should.be.true();
+  done();
+});
+request_.pipe(stream);

should follow redirects

const stream = fs.createWriteStream(destinationPath);
+let responseCalled = false;
+const request_ = request.get(base + '/redirect');
+request_.type('json');
+request_.on('response', (res) => {
+  res.status.should.eql(200);
+  responseCalled = true;
+});
+stream.on('finish', () => {
+  JSON.parse(fs.readFileSync(destinationPath)).should.eql({
+    name: 'tobi'
+  });
+  responseCalled.should.be.true();
+  done();
+});
+request_.pipe(stream);

should not throw on bad redirects

const stream = fs.createWriteStream(destinationPath);
+let responseCalled = false;
+let errorCalled = false;
+const request_ = request.get(base + '/badRedirectNoLocation');
+request_.type('json');
+request_.on('response', (res) => {
+  responseCalled = true;
+});
+request_.on('error', (error) => {
+  error.message.should.eql('No location header for redirect');
+  errorCalled = true;
+  stream.end();
+});
+stream.on('finish', () => {
+  responseCalled.should.be.false();
+  errorCalled.should.be.true();
+  done();
+});
+request_.pipe(stream);

req.query(String)

should support passing in a string

request
+  .del(base)
+  .query('name=t%F6bi')
+  .end((error, res) => {
+    res.body.should.eql({ name: 't%F6bi' });
+    done();
+  });

should work with url query-string and string for query

request
+  .del(`${base}/?name=tobi`)
+  .query('age=2%20')
+  .end((error, res) => {
+    res.body.should.eql({ name: 'tobi', age: '2 ' });
+    done();
+  });

should support compound elements in a string

request
+  .del(base)
+  .query('name=t%F6bi&age=2')
+  .end((error, res) => {
+    res.body.should.eql({ name: 't%F6bi', age: '2' });
+    done();
+  });

should work when called multiple times with a string

request
+  .del(base)
+  .query('name=t%F6bi')
+  .query('age=2%F6')
+  .end((error, res) => {
+    res.body.should.eql({ name: 't%F6bi', age: '2%F6' });
+    done();
+  });

should work with normal `query` object and query string

request
+  .del(base)
+  .query('name=t%F6bi')
+  .query({ age: '2' })
+  .end((error, res) => {
+    res.body.should.eql({ name: 't%F6bi', age: '2' });
+    done();
+  });

should not encode raw backticks, but leave encoded ones as is

return Promise.all([
+  request
+    .get(`${base}/raw-query`)
+    .query('name=`t%60bi`&age`=2')
+    .then((res) => {
+      res.text.should.eql('name=`t%60bi`&age`=2');
+    }),
+  request.get(base + '/raw-query?`age%60`=2%60`').then((res) => {
+    res.text.should.eql('`age%60`=2%60`');
+  }),
+  request
+    .get(`${base}/raw-query`)
+    .query('name=`t%60bi`')
+    .query('age`=2')
+    .then((res) => {
+      res.text.should.eql('name=`t%60bi`&age`=2');
+    })
+]);

req.query(Object)

should construct the query-string

request
+  .del(base)
+  .query({ name: 'tobi' })
+  .query({ order: 'asc' })
+  .query({ limit: ['1', '2'] })
+  .end((error, res) => {
+    res.body.should.eql({ name: 'tobi', order: 'asc', limit: ['1', '2'] });
+    done();
+  });

should encode raw backticks

request
+  .get(`${base}/raw-query`)
+  .query({ name: '`tobi`' })
+  .query({ 'orde%60r': null })
+  .query({ '`limit`': ['%602`'] })
+  .end((error, res) => {
+    res.text.should.eql('name=%60tobi%60&orde%2560r&%60limit%60=%25602%60');
+    done();
+  });

should not error on dates

const date = new Date(0);
+request
+  .del(base)
+  .query({ at: date })
+  .end((error, res) => {
+    assert.equal(date.toISOString(), res.body.at);
+    done();
+  });

should work after setting header fields

request
+  .del(base)
+  .set('Foo', 'bar')
+  .set('Bar', 'baz')
+  .query({ name: 'tobi' })
+  .query({ order: 'asc' })
+  .query({ limit: ['1', '2'] })
+  .end((error, res) => {
+    res.body.should.eql({ name: 'tobi', order: 'asc', limit: ['1', '2'] });
+    done();
+  });

should append to the original query-string

request
+  .del(`${base}/?name=tobi`)
+  .query({ order: 'asc' })
+  .end((error, res) => {
+    res.body.should.eql({ name: 'tobi', order: 'asc' });
+    done();
+  });

should retain the original query-string

request.del(`${base}/?name=tobi`).end((error, res) => {
+  res.body.should.eql({ name: 'tobi' });
+  done();
+});

should keep only keys with null querystring values

request
+  .del(`${base}/url`)
+  .query({ nil: null })
+  .end((error, res) => {
+    res.text.should.equal('/url?nil');
+    done();
+  });

query-string should be sent on pipe

this.timeout(15_000);
+const request_ = request.put(`${base}/?name=tobi`);
+const stream = fs.createReadStream('test/node/fixtures/user.json');
+request_.on('response', (res) => {
+  res.body.should.eql({ name: 'tobi' });
+  done();
+});
+request_.on('error', (err) => {
+  done(err);
+});
+stream.on('error', function (err) {
+  done(err);
+});
+stream.pipe(request_);

request.get

on 301 redirect

should follow Location with a GET request

const request_ = request.get(`${base}/test-301`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  headers.host.should.eql(`localhost:${server2.address().port}`);
+  res.status.should.eql(200);
+  res.text.should.eql('GET');
+  done();
+});

on 302 redirect

should follow Location with a GET request

const request_ = request.get(`${base}/test-302`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  res.status.should.eql(200);
+  res.text.should.eql('GET');
+  done();
+});

on 303 redirect

should follow Location with a GET request

const request_ = request.get(`${base}/test-303`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  headers.host.should.eql(`localhost:${server2.address().port}`);
+  res.status.should.eql(200);
+  res.text.should.eql('GET');
+  done();
+});

on 307 redirect

should follow Location with a GET request

const request_ = request.get(`${base}/test-307`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  headers.host.should.eql(`localhost:${server2.address().port}`);
+  res.status.should.eql(200);
+  res.text.should.eql('GET');
+  done();
+});

on 308 redirect

should follow Location with a GET request

const request_ = request.get(`${base}/test-308`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  headers.host.should.eql(`localhost:${server2.address().port}`);
+  res.status.should.eql(200);
+  res.text.should.eql('GET');
+  done();
+});

+ +

request.post

on 301 redirect

should follow Location with a GET request

const request_ = request.post(`${base}/test-301`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  headers.host.should.eql(`localhost:${server2.address().port}`);
+  res.status.should.eql(200);
+  res.text.should.eql('GET');
+  done();
+});

on 302 redirect

should follow Location with a GET request

const request_ = request.post(`${base}/test-302`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  headers.host.should.eql(`localhost:${server2.address().port}`);
+  res.status.should.eql(200);
+  res.text.should.eql('GET');
+  done();
+});

on 303 redirect

should follow Location with a GET request

const request_ = request.post(`${base}/test-303`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  headers.host.should.eql(`localhost:${server2.address().port}`);
+  res.status.should.eql(200);
+  res.text.should.eql('GET');
+  done();
+});

on 307 redirect

should follow Location with a POST request

const request_ = request.post(`${base}/test-307`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  headers.host.should.eql(`localhost:${server2.address().port}`);
+  res.status.should.eql(200);
+  res.text.should.eql('POST');
+  done();
+});

on 308 redirect

should follow Location with a POST request

const request_ = request.post(`${base}/test-308`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  headers.host.should.eql(`localhost:${server2.address().port}`);
+  res.status.should.eql(200);
+  res.text.should.eql('POST');
+  done();
+});

+ +

request

on redirect

should merge cookies if agent is used

request
+  .agent()
+  .get(`${base}/cookie-redirect`)
+  .set('Cookie', 'orig=1; replaced=not')
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      assert(/orig=1/.test(res.text), 'orig=1/.test');
+      assert(/replaced=yes/.test(res.text), 'replaced=yes/.test');
+      assert(/from-redir=1/.test(res.text), 'from-redir=1');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should not merge cookies if agent is not used

request
+  .get(`${base}/cookie-redirect`)
+  .set('Cookie', 'orig=1; replaced=not')
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      assert(/orig=1/.test(res.text), '/orig=1');
+      assert(/replaced=not/.test(res.text), '/replaced=not');
+      assert(!/replaced=yes/.test(res.text), '!/replaced=yes');
+      assert(!/from-redir/.test(res.text), '!/from-redir');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should have previously set cookie for subsquent requests when agent is used

const agent = request.agent();
+agent.get(`${base}/set-cookie`).end((error) => {
+  assert.ifError(error);
+  agent
+    .get(`${base}/show-cookies`)
+    .set({ Cookie: 'orig=1' })
+    .end((error, res) => {
+      try {
+        assert.ifError(error);
+        assert(/orig=1/.test(res.text), 'orig=1/.test');
+        assert(/persist=123/.test(res.text), 'persist=123');
+        done();
+      } catch (err) {
+        done(err);
+      }
+    });
+});

should follow Location

const redirects = [];
+request
+  .get(base)
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .end((error, res) => {
+    try {
+      const array = ['/movies', '/movies/all', '/movies/all/0'];
+      redirects.should.eql(array);
+      res.text.should.equal('first movie page');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should follow Location with IP override

const redirects = [];
+const url = URL.parse(base);
+return request
+  .get(`http://redir.example.com:${url.port || '80'}${url.pathname}`)
+  .connect({
+    '*': url.hostname
+  })
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .then((res) => {
+    const array = ['/movies', '/movies/all', '/movies/all/0'];
+    redirects.should.eql(array);
+    res.text.should.equal('first movie page');
+  });

should follow Location with IP:port override

const redirects = [];
+const url = URL.parse(base);
+return request
+  .get(`http://redir.example.com:9999${url.pathname}`)
+  .connect({
+    '*': { host: url.hostname, port: url.port || 80 }
+  })
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .then((res) => {
+    const array = ['/movies', '/movies/all', '/movies/all/0'];
+    redirects.should.eql(array);
+    res.text.should.equal('first movie page');
+  });

should not follow on HEAD by default

const redirects = [];
+return request
+  .head(base)
+  .ok(() => true)
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .then((res) => {
+    redirects.should.eql([]);
+    res.status.should.equal(302);
+  });

should follow on HEAD when redirects are set

const redirects = [];
+request
+  .head(base)
+  .redirects(10)
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .end((error, res) => {
+    try {
+      const array = [];
+      array.push('/movies', '/movies/all', '/movies/all/0');
+      redirects.should.eql(array);
+      assert(!res.text);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should remove Content-* fields

request
+  .post(`${base}/header`)
+  .type('txt')
+  .set('X-Foo', 'bar')
+  .set('X-Bar', 'baz')
+  .send('hey')
+  .end((error, res) => {
+    try {
+      assert(res.body);
+      res.body.should.have.property('x-foo', 'bar');
+      res.body.should.have.property('x-bar', 'baz');
+      res.body.should.not.have.property('content-type');
+      res.body.should.not.have.property('content-length');
+      res.body.should.not.have.property('transfer-encoding');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should retain cookies

request
+  .get(`${base}/header`)
+  .set('Cookie', 'foo=bar;')
+  .end((error, res) => {
+    try {
+      assert(res.body);
+      res.body.should.have.property('cookie', 'foo=bar;');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should not resend query parameters

const redirects = [];
+const query = [];
+request
+  .get(`${base}/?foo=bar`)
+  .on('redirect', (res) => {
+    query.push(res.headers.query);
+    redirects.push(res.headers.location);
+  })
+  .end((error, res) => {
+    try {
+      const array = [];
+      array.push('/movies', '/movies/all', '/movies/all/0');
+      redirects.should.eql(array);
+      res.text.should.equal('first movie page');
+      query.should.eql(['{"foo":"bar"}', '{}', '{}']);
+      res.headers.query.should.eql('{}');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should handle no location header

request.get(`${base}/bad-redirect`).end((error, res) => {
+  try {
+    error.message.should.equal('No location header for redirect');
+    done();
+  } catch (err) {
+    done(err);
+  }
+});

when relative

should redirect to a sibling path

const redirects = [];
+request
+  .get(`${base}/relative`)
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .end((error, res) => {
+    try {
+      redirects.should.eql(['tobi']);
+      res.text.should.equal('tobi');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should redirect to a parent path

const redirects = [];
+request
+  .get(`${base}/relative/sub`)
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .end((error, res) => {
+    try {
+      redirects.should.eql(['../tobi']);
+      res.text.should.equal('tobi');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

req.redirects(n)

should alter the default number of redirects to follow

const redirects = [];
+request
+  .get(base)
+  .redirects(2)
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .end((error, res) => {
+    try {
+      const array = [];
+      assert(res.redirect, 'res.redirect');
+      array.push('/movies', '/movies/all');
+      redirects.should.eql(array);
+      res.text.should.match(/Moved Temporarily|Found/);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

on POST

should redirect as GET

const redirects = [];
+return request
+  .post(`${base}/movie`)
+  .send({ name: 'Tobi' })
+  .redirects(2)
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .then((res) => {
+    redirects.should.eql(['/movies/all/0']);
+    res.text.should.equal('first movie page');
+  });

using multipart/form-data should redirect as GET

const redirects = [];
+request
+  .post(`${base}/movie`)
+  .type('form')
+  .field('name', 'Tobi')
+  .redirects(2)
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .then((res) => {
+    redirects.should.eql(['/movies/all/0']);
+    res.text.should.equal('first movie page');
+  });

+ +

response

should act as a readable stream

const request_ = request.get(base).buffer(false);
+request_.end((error, res) => {
+  if (error) return done(error);
+  let trackEndEvent = 0;
+  let trackCloseEvent = 0;
+  res.on('end', () => {
+    trackEndEvent++;
+    trackEndEvent.should.equal(1);
+    if (!process.env.HTTP2_TEST) {
+      trackCloseEvent.should.equal(0); // close should not have been called
+    }
+    done();
+  });
+  res.on('close', () => {
+    trackCloseEvent++;
+  });
+  setTimeout(() => {
+    (() => {
+      res.pause();
+    }).should.not.throw();
+    (() => {
+      res.resume();
+    }).should.not.throw();
+    (() => {
+      res.destroy();
+    }).should.not.throw();
+  }, 50);
+});

req.serialize(fn)

should take precedence over default parsers

request
+  .post(`${base}/echo`)
+  .send({ foo: 123 })
+  .serialize(() => '{"bar":456}')
+  .end((error, res) => {
+    assert.ifError(error);
+    assert.equal('{"bar":456}', res.text);
+    assert.equal(456, res.body.bar);
+    done();
+  });

request.get().set()

should set host header after get()

app.get('/', (request_, res) => {
+  assert.equal(request_.hostname, 'example.com');
+  res.end();
+});
+server = http.createServer(app);
+server.listen(0, function listening() {
+  request
+    .get(`http://localhost:${server.address().port}`)
+    .set('host', 'example.com')
+    .then(() => {
+      return request
+        .get(`http://example.com:${server.address().port}`)
+        .connect({
+          'example.com': 'localhost',
+          '*': 'fail'
+        });
+    })
+    .then(() => done(), done);
+});

res.toError()

should return an Error

request.get(base).end((err, res) => {
+  const error = res.toError();
+  assert.equal(error.status, 400);
+  assert.equal(error.method, 'GET');
+  assert.equal(error.path, '/');
+  assert.equal(error.message, 'cannot GET / (400)');
+  assert.equal(error.text, 'invalid json');
+  done();
+});

[unix-sockets] http

request

path: / (root)

request.get(`${base}/`).end((error, res) => {
+  assert(res.ok);
+  assert.strictEqual('root ok!', res.text);
+  done();
+});

path: /request/path

request.get(`${base}/request/path`).end((error, res) => {
+  assert(res.ok);
+  assert.strictEqual('request path ok!', res.text);
+  done();
+});

+ +

[unix-sockets] https

request

path: / (root)

request
+  .get(`${base}/`)
+  .ca(cacert)
+  .end((error, res) => {
+    assert.ifError(error);
+    assert(res.ok);
+    assert.strictEqual('root ok!', res.text);
+    done();
+  });

path: /request/path

request
+  .get(`${base}/request/path`)
+  .ca(cacert)
+  .end((error, res) => {
+    assert.ifError(error);
+    assert(res.ok);
+    assert.strictEqual('request path ok!', res.text);
+    done();
+  });

+ +

req.get()

should not set a default user-agent

request.get(`${base}/ua`).then((res) => {
+      assert(res.headers);
+      assert(!res.headers['user-agent']);
+    })

utils.type(str)

should return the mime type

utils
+  .type('application/json; charset=utf-8')
+  .should.equal('application/json');
+utils.type('application/json').should.equal('application/json');

utils.params(str)

should return the field parameters

const object = utils.params('application/json; charset=utf-8; foo  = bar');
+object.charset.should.equal('utf-8');
+object.foo.should.equal('bar');
+utils.params('application/json').should.eql({});

utils.parseLinks(str)

should parse links

const string_ =
+  '<https://api.github.com/repos/visionmedia/mocha/issues?page=2>; rel="next", <https://api.github.com/repos/visionmedia/mocha/issues?page=5>; rel="last"';
+const returnValue = utils.parseLinks(string_);
+returnValue.next.should.equal(
+  'https://api.github.com/repos/visionmedia/mocha/issues?page=2'
+);
+returnValue.last.should.equal(
+  'https://api.github.com/repos/visionmedia/mocha/issues?page=5'
+);

+-------------------|---------|----------|---------|---------|--------------------------------------- +File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s +-------------------|---------|----------|---------|---------|--------------------------------------- +All files | 85.79 | 79.93 | 78.06 | 86.6 | + src | 92.5 | 83.83 | 91.83 | 93.84 | + agent-base.js | 100 | 100 | 100 | 100 | + request-base.js | 91.01 | 83.9 | 94.28 | 93.06 | ...21,262,316,501,525-533,579,757,768 + response-base.js | 100 | 100 | 75 | 100 | + utils.js | 92.85 | 71.42 | 85.71 | 91.66 | 94-98 + src/node | 82.28 | 78 | 68.42 | 82.94 | + agent.js | 89.79 | 66.66 | 100 | 88.63 | 39,43,47,51,101 + http2wrapper.js | 24.8 | 4.34 | 0 | 21.49 | ...76,180-181,185-186,190-191,196-198 + index.js | 92.49 | 83.03 | 87.71 | 93.1 | ...,977,1142,1182-1186,1220-1221,1301 + response.js | 90 | 83.33 | 55.55 | 89.79 | 78,86,94,120-121 + unzip.js | 100 | 92.85 | 100 | 100 | 47 + src/node/parsers | 97.61 | 75 | 100 | 97.61 | + image.js | 100 | 100 | 100 | 100 | + index.js | 100 | 100 | 100 | 100 | + json.js | 100 | 75 | 100 | 100 | 15 + text.js | 100 | 100 | 100 | 100 | + urlencoded.js | 90 | 100 | 100 | 90 | 17 +-------------------|---------|----------|---------|---------|--------------------------------------- +test on node with http2 +test on plain node +

Agent

should remember defaults

if (typeof Promise === 'undefined') {
+  return;
+}
+let called = 0;
+let event_called = 0;
+const agent = request
+  .agent()
+  .accept('json')
+  .use(() => {
+    called++;
+  })
+  .once('request', () => {
+    event_called++;
+  })
+  .query({ hello: 'world' })
+  .set('X-test', 'testing');
+assert.equal(0, called);
+assert.equal(0, event_called);
+return agent
+  .get(`${base}/echo`)
+  .then((res) => {
+    assert.equal(1, called);
+    assert.equal(1, event_called);
+    assert.equal('application/json', res.headers.accept);
+    assert.equal('testing', res.headers['x-test']);
+    return agent.get(`${base}/querystring`);
+  })
+  .then((res) => {
+    assert.equal(2, called);
+    assert.equal(2, event_called);
+    assert.deepEqual({ hello: 'world' }, res.body);
+  });

request

res.statusCode

should set statusCode

request.get(`${uri}/login`, (error, res) => {
+  try {
+    assert.strictEqual(res.statusCode, 200);
+    done();
+  } catch (err) {
+    done(err);
+  }
+});

should allow the send shorthand

with callback in the method call

request.get(`${uri}/login`, (error, res) => {
+  assert.equal(res.status, 200);
+  done();
+});

with data in the method call

request.post(`${uri}/echo`, { foo: 'bar' }).end((error, res) => {
+  assert.equal('{"foo":"bar"}', res.text);
+  done();
+});

with callback and data in the method call

request.post(`${uri}/echo`, { foo: 'bar' }, (error, res) => {
+  assert.equal('{"foo":"bar"}', res.text);
+  done();
+});

with a callback

should invoke .end()

request.get(`${uri}/login`, (error, res) => {
+  try {
+    assert.equal(res.status, 200);
+    done();
+  } catch (err) {
+    done(err);
+  }
+});

.end()

should issue a request

request.get(`${uri}/login`).end((error, res) => {
+  try {
+    assert.equal(res.status, 200);
+    done();
+  } catch (err) {
+    done(err);
+  }
+});

is optional with a promise

if (typeof Promise === 'undefined') {
+  return;
+}
+return request
+  .get(`${uri}/login`)
+  .then((res) => res.status)
+  .then()
+  .then((status) => {
+    assert.equal(200, status, 'Real promises pass results through');
+  });

called only once with a promise

if (typeof Promise === 'undefined') {
+  return;
+}
+const request_ = request.get(`${uri}/unique`);
+return Promise.all([request_, request_, request_]).then((results) => {
+  for (const item of results) {
+    assert.deepEqual(
+      item.body,
+      results[0].body,
+      'It should keep returning the same result after being called once'
+    );
+  }
+});

res.error

ok

let calledErrorEvent = false;
+let calledOKHandler = false;
+request
+  .get(`${uri}/error`)
+  .ok((res) => {
+    assert.strictEqual(500, res.status);
+    calledOKHandler = true;
+    return true;
+  })
+  .on('error', (error) => {
+    calledErrorEvent = true;
+  })
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      assert.strictEqual(res.status, 500);
+      assert(!calledErrorEvent);
+      assert(calledOKHandler);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should be an Error object

let calledErrorEvent = false;
+request
+  .get(`${uri}/error`)
+  .on('error', (error) => {
+    assert.strictEqual(error.status, 500);
+    calledErrorEvent = true;
+  })
+  .end((error, res) => {
+    try {
+      if (NODE) {
+        res.error.message.should.equal('cannot GET /error (500)');
+      } else {
+        res.error.message.should.equal(`cannot GET ${uri}/error (500)`);
+      }
+      assert.strictEqual(res.error.status, 500);
+      assert(error, 'should have an error for 500');
+      assert.equal(error.message, 'Internal Server Error');
+      assert(calledErrorEvent);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

with .then() promise

if (typeof Promise === 'undefined') {
+  return;
+}
+return request.get(`${uri}/error`).then(
+  () => {
+    assert.fail();
+  },
+  (err) => {
+    assert.equal(err.message, 'Internal Server Error');
+  }
+);

with .ok() returning false

if (typeof Promise === 'undefined') {
+  return;
+}
+return request
+  .get(`${uri}/echo`)
+  .ok(() => false)
+  .then(
+    () => {
+      assert.fail();
+    },
+    (err) => {
+      assert.equal(200, err.response.status);
+      assert.equal(err.message, 'OK');
+    }
+  );

with .ok() throwing an Error

if (typeof Promise === 'undefined') {
+  return;
+}
+return request
+  .get(`${uri}/echo`)
+  .ok(() => {
+    throw new Error('boom');
+  })
+  .then(
+    () => {
+      assert.fail();
+    },
+    (err) => {
+      assert.equal(200, err.status);
+      assert.equal(200, err.response.status);
+      assert.equal(err.message, 'boom');
+    }
+  );

with .ok() throwing an Error with status

if (typeof Promise === 'undefined') {
+  return;
+}
+return request
+  .get(`${uri}/echo`)
+  .ok(() => {
+    const err = new Error('boom');
+    err.status = 404;
+    throw err;
+  })
+  .then(
+    () => {
+      assert.fail();
+    },
+    (err) => {
+      assert.equal(404, err.status);
+      assert.equal(200, err.response.status);
+      assert.equal(err.message, 'boom');
+    }
+  );

res.header

should be an object

request.get(`${uri}/login`).end((error, res) => {
+  try {
+    assert.equal('Express', res.header['x-powered-by']);
+    done();
+  } catch (err) {
+    done(err);
+  }
+});

set headers

should only set headers for ownProperties of header

try {
+  request
+    .get(`${uri}/echo-headers`)
+    .set('valid', 'ok')
+    .end((error, res) => {
+      if (
+        !error &&
+        res.body &&
+        res.body.valid &&
+        !res.body.hasOwnProperty('invalid')
+      ) {
+        return done();
+      }
+      done(error || new Error('fail'));
+    });
+} catch (err) {
+  done(err);
+}

res.charset

should be set when present

request.get(`${uri}/login`).end((error, res) => {
+  try {
+    res.charset.should.equal('utf-8');
+    done();
+  } catch (err) {
+    done(err);
+  }
+});

res.statusType

should provide the first digit

request.get(`${uri}/login`).end((error, res) => {
+  try {
+    assert(!error, 'should not have an error for success responses');
+    assert.equal(200, res.status);
+    assert.equal(2, res.statusType);
+    done();
+  } catch (err) {
+    done(err);
+  }
+});

res.type

should provide the mime-type void of params

request.get(`${uri}/login`).end((error, res) => {
+  try {
+    res.type.should.equal('text/html');
+    res.charset.should.equal('utf-8');
+    done();
+  } catch (err) {
+    done(err);
+  }
+});

req.set(field, val)

should set the header field

request
+  .post(`${uri}/echo`)
+  .set('X-Foo', 'bar')
+  .set('X-Bar', 'baz')
+  .end((error, res) => {
+    try {
+      assert.equal('bar', res.header['x-foo']);
+      assert.equal('baz', res.header['x-bar']);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

req.set(obj)

should set the header fields

request
+  .post(`${uri}/echo`)
+  .set({ 'X-Foo': 'bar', 'X-Bar': 'baz' })
+  .end((error, res) => {
+    try {
+      assert.equal('bar', res.header['x-foo']);
+      assert.equal('baz', res.header['x-bar']);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

req.type(str)

should set the Content-Type

request
+  .post(`${uri}/echo`)
+  .type('text/x-foo')
+  .end((error, res) => {
+    try {
+      res.header['content-type'].should.equal('text/x-foo');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should map "json"

request
+  .post(`${uri}/echo`)
+  .type('json')
+  .send('{"a": 1}')
+  .end((error, res) => {
+    try {
+      res.should.be.json();
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should map "html"

request
+  .post(`${uri}/echo`)
+  .type('html')
+  .end((error, res) => {
+    try {
+      res.header['content-type'].should.equal('text/html');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

req.accept(str)

should set Accept

request
+  .get(`${uri}/echo`)
+  .accept('text/x-foo')
+  .end((error, res) => {
+    try {
+      res.header.accept.should.equal('text/x-foo');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should map "json"

request
+  .get(`${uri}/echo`)
+  .accept('json')
+  .end((error, res) => {
+    try {
+      res.header.accept.should.equal('application/json');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should map "xml"

request
+  .get(`${uri}/echo`)
+  .accept('xml')
+  .end((error, res) => {
+    try {
+      // Mime module keeps changing this :(
+      assert(
+        res.header.accept == 'application/xml' ||
+          res.header.accept == 'text/xml'
+      );
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should map "html"

request
+  .get(`${uri}/echo`)
+  .accept('html')
+  .end((error, res) => {
+    try {
+      res.header.accept.should.equal('text/html');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

req.send(str)

should write the string

request
+  .post(`${uri}/echo`)
+  .type('json')
+  .send('{"name":"tobi"}')
+  .end((error, res) => {
+    try {
+      res.text.should.equal('{"name":"tobi"}');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

req.send(Object)

should default to json

request
+  .post(`${uri}/echo`)
+  .send({ name: 'tobi' })
+  .end((error, res) => {
+    try {
+      res.should.be.json();
+      res.text.should.equal('{"name":"tobi"}');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

when called several times

should merge the objects

request
+  .post(`${uri}/echo`)
+  .send({ name: 'tobi' })
+  .send({ age: 1 })
+  .end((error, res) => {
+    try {
+      res.should.be.json();
+      if (NODE) {
+        res.buffered.should.be.true();
+      }
+      res.text.should.equal('{"name":"tobi","age":1}');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

.end(fn)

should check arity

request
+  .post(`${uri}/echo`)
+  .send({ name: 'tobi' })
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      res.text.should.equal('{"name":"tobi"}');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should emit request

const request_ = request.post(`${uri}/echo`);
+request_.on('request', (request) => {
+  assert.equal(request_, request);
+  done();
+});
+request_.end();

should emit response

request
+  .post(`${uri}/echo`)
+  .send({ name: 'tobi' })
+  .on('response', (res) => {
+    res.text.should.equal('{"name":"tobi"}');
+    done();
+  })
+  .end();

.then(fulfill, reject)

should support successful fulfills with .then(fulfill)

if (typeof Promise === 'undefined') {
+  return done();
+}
+request
+  .post(`${uri}/echo`)
+  .send({ name: 'tobi' })
+  .then((res) => {
+    res.type.should.equal('application/json');
+    res.text.should.equal('{"name":"tobi"}');
+    done();
+  });

should reject an error with .then(null, reject)

if (typeof Promise === 'undefined') {
+  return done();
+}
+request.get(`${uri}/error`).then(null, (err) => {
+  assert.equal(err.status, 500);
+  assert.equal(err.response.text, 'boom');
+  done();
+});

.catch(reject)

should reject an error with .catch(reject)

if (typeof Promise === 'undefined') {
+  return done();
+}
+request.get(`${uri}/error`).catch((err) => {
+  assert.equal(err.status, 500);
+  assert.equal(err.response.text, 'boom');
+  done();
+});

.abort()

should abort the request

const request_ = request.get(`${uri}/delay/3000`);
+request_.end((error, res) => {
+  try {
+    assert(false, 'should not complete the request');
+  } catch (err) {
+    done(err);
+  }
+});
+request_.on('error', (error) => {
+  done(error);
+});
+request_.on('abort', done);
+setTimeout(() => {
+  request_.abort();
+}, 500);

should abort the promise

const request_ = request.get(`${uri}/delay/3000`);
+setTimeout(() => {
+  request_.abort();
+}, 10);
+return request_.then(
+  () => {
+    assert.fail('should not complete the request');
+  },
+  (err) => {
+    assert.equal('ABORTED', err.code);
+  }
+);

should allow chaining .abort() several times

const request_ = request.get(`${uri}/delay/3000`);
+request_.end((error, res) => {
+  try {
+    assert(false, 'should not complete the request');
+  } catch (err) {
+    done(err);
+  }
+});
+// This also verifies only a single 'done' event is emitted
+request_.on('abort', done);
+setTimeout(() => {
+  request_.abort().abort().abort();
+}, 1000);

should not allow abort then end

request
+  .get(`${uri}/delay/3000`)
+  .abort()
+  .end((error, res) => {
+    done(error ? undefined : new Error('Expected abort error'));
+  });

req.toJSON()

should describe the request

const request_ = request.post(`${uri}/echo`).send({ foo: 'baz' });
+request_.end((error, res) => {
+  try {
+    const json = request_.toJSON();
+    assert.equal('POST', json.method);
+    assert(/\/echo$/.test(json.url));
+    assert.equal('baz', json.data.foo);
+    done();
+  } catch (err) {
+    done(err);
+  }
+});

req.options()

should allow request body

request
+  .options(`${uri}/options/echo/body`)
+  .send({ foo: 'baz' })
+  .end((error, res) => {
+    try {
+      assert.equal(error, null);
+      assert.strictEqual(res.body.foo, 'baz');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

req.sortQuery()

nop with no querystring

request
+  .get(`${uri}/url`)
+  .sortQuery()
+  .end((error, res) => {
+    try {
+      assert.equal(res.text, '/url');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should sort the request querystring

request
+  .get(`${uri}/url`)
+  .query('search=Manny')
+  .query('order=desc')
+  .sortQuery()
+  .end((error, res) => {
+    try {
+      assert.equal(res.text, '/url?order=desc&search=Manny');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should allow disabling sorting

request
+  .get(`${uri}/url`)
+  .query('search=Manny')
+  .query('order=desc')
+  .sortQuery() // take default of true
+  .sortQuery(false) // override it in later call
+  .end((error, res) => {
+    try {
+      assert.equal(res.text, '/url?search=Manny&order=desc');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should sort the request querystring using customized function

request
+  .get(`${uri}/url`)
+  .query('name=Nick')
+  .query('search=Manny')
+  .query('order=desc')
+  .sortQuery((a, b) => a.length - b.length)
+  .end((error, res) => {
+    try {
+      assert.equal(res.text, '/url?name=Nick&order=desc&search=Manny');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

+ +

req.set("Content-Type", contentType)

should work with just the contentType component

request
+  .post(`${uri}/echo`)
+  .set('Content-Type', 'application/json')
+  .send({ name: 'tobi' })
+  .end((error) => {
+    assert(!error);
+    done();
+  });

should work with the charset component

request
+  .post(`${uri}/echo`)
+  .set('Content-Type', 'application/json; charset=utf-8')
+  .send({ name: 'tobi' })
+  .end((error) => {
+    assert(!error);
+    done();
+  });

req.send(Object) as "form"

with req.type() set to form

should send x-www-form-urlencoded data

request
+  .post(`${base}/echo`)
+  .type('form')
+  .send({ name: 'tobi' })
+  .end((error, res) => {
+    res.header['content-type'].should.equal(
+      'application/x-www-form-urlencoded'
+    );
+    res.text.should.equal('name=tobi');
+    done();
+  });

when called several times

should merge the objects

request
+  .post(`${base}/echo`)
+  .type('form')
+  .send({ name: { first: 'tobi', last: 'holowaychuk' } })
+  .send({ age: '1' })
+  .end((error, res) => {
+    res.header['content-type'].should.equal(
+      'application/x-www-form-urlencoded'
+    );
+    res.text.should.equal(
+      'name%5Bfirst%5D=tobi&name%5Blast%5D=holowaychuk&age=1'
+    );
+    done();
+  });

+ +

req.attach

ignores null file

request
+  .post('/echo')
+  .attach('image', null)
+  .end((error, res) => {
+    done();
+  });

req.field

allow bools

if (!formDataSupported) {
+  return done();
+}
+request
+  .post(`${base}/formecho`)
+  .field('bools', true)
+  .field('strings', 'true')
+  .end((error, res) => {
+    assert.ifError(error);
+    assert.deepStrictEqual(res.body, { bools: 'true', strings: 'true' });
+    done();
+  });

allow objects

if (!formDataSupported) {
+  return done();
+}
+request
+  .post(`${base}/formecho`)
+  .field({ bools: true, strings: 'true' })
+  .end((error, res) => {
+    assert.ifError(error);
+    assert.deepStrictEqual(res.body, { bools: 'true', strings: 'true' });
+    done();
+  });

works with arrays in objects

if (!formDataSupported) {
+  return done();
+}
+request
+  .post(`${base}/formecho`)
+  .field({ numbers: [1, 2, 3] })
+  .end((error, res) => {
+    assert.ifError(error);
+    assert.deepStrictEqual(res.body, { numbers: ['1', '2', '3'] });
+    done();
+  });

works with arrays

if (!formDataSupported) {
+  return done();
+}
+request
+  .post(`${base}/formecho`)
+  .field('letters', ['a', 'b', 'c'])
+  .end((error, res) => {
+    assert.ifError(error);
+    assert.deepStrictEqual(res.body, { letters: ['a', 'b', 'c'] });
+    done();
+  });

throw when empty

should.throws(() => {
+  request.post(`${base}/echo`).field();
+}, /name/);
+should.throws(() => {
+  request.post(`${base}/echo`).field('name');
+}, /val/);

cannot be mixed with send()

assert.throws(() => {
+  request.post('/echo').field('form', 'data').send('hi');
+});
+assert.throws(() => {
+  request.post('/echo').send('hi').field('form', 'data');
+});

req.send(Object) as "json"

should default to json

request
+  .post(`${uri}/echo`)
+  .send({ name: 'tobi' })
+  .end((error, res) => {
+    res.should.be.json();
+    res.text.should.equal('{"name":"tobi"}');
+    done();
+  });

should work with arrays

request
+  .post(`${uri}/echo`)
+  .send([1, 2, 3])
+  .end((error, res) => {
+    res.should.be.json();
+    res.text.should.equal('[1,2,3]');
+    done();
+  });

should work with value null

request
+  .post(`${uri}/echo`)
+  .type('json')
+  .send('null')
+  .end((error, res) => {
+    res.should.be.json();
+    assert.strictEqual(res.body, null);
+    done();
+  });

should work with value false

request
+  .post(`${uri}/echo`)
+  .type('json')
+  .send('false')
+  .end((error, res) => {
+    res.should.be.json();
+    res.body.should.equal(false);
+    done();
+  });

should work with empty string value

request
+  .post(`${uri}/echo`)
+  .type('json')
+  .send('""')
+  .end((error, res) => {
+    res.should.be.json();
+    res.body.should.equal('');
+    done();
+  });

should work with vendor MIME type

request
+  .post(`${uri}/echo`)
+  .set('Content-Type', 'application/vnd.example+json')
+  .send({ name: 'vendor' })
+  .end((error, res) => {
+    res.text.should.equal('{"name":"vendor"}');
+    ({ name: 'vendor' }.should.eql(res.body));
+    done();
+  });

when called several times

should merge the objects

request
+  .post(`${uri}/echo`)
+  .send({ name: 'tobi' })
+  .send({ age: 1 })
+  .end((error, res) => {
+    res.should.be.json();
+    res.text.should.equal('{"name":"tobi","age":1}');
+    ({ name: 'tobi', age: 1 }.should.eql(res.body));
+    done();
+  });

res.body

application/json

should parse the body

request.get(`${uri}/json`).end((error, res) => {
+  res.text.should.equal('{"name":"manny"}');
+  res.body.should.eql({ name: 'manny' });
+  done();
+});

Invalid JSON response

should return the raw response

request.get(`${uri}/invalid-json`).end((error, res) => {
+  assert.deepEqual(
+    error.rawResponse,
+    ")]}', {'header':{'code':200,'text':'OK','version':'1.0'},'data':'some data'}"
+  );
+  done();
+});

should return the http status code

request.get(`${uri}/invalid-json-forbidden`).end((error, res) => {
+  assert.equal(error.statusCode, 403);
+  done();
+});

+ +

request

on redirect

should retain header fields

request
+  .get(`${base}/header`)
+  .set('X-Foo', 'bar')
+  .end((error, res) => {
+    try {
+      assert(res.body);
+      res.body.should.have.property('x-foo', 'bar');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should preserve timeout across redirects

request
+  .get(`${base}/movies/random`)
+  .timeout(250)
+  .end((error, res) => {
+    try {
+      assert(error instanceof Error, 'expected an error');
+      error.should.have.property('timeout', 250);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should successfully redirect after retry on error

const id = Math.random() * 1_000_000 * Date.now();
+request
+  .get(`${base}/error/redirect/${id}`)
+  .retry(2)
+  .end((error, res) => {
+    assert(res.ok, 'response should be ok');
+    assert(res.text, 'first movie page');
+    done();
+  });

should preserve retries across redirects

const id = Math.random() * 1_000_000 * Date.now();
+request
+  .get(`${base}/error/redirect-error${id}`)
+  .retry(2)
+  .end((error, res) => {
+    assert(error, 'expected an error');
+    assert.equal(2, error.retries, 'expected an error with .retries');
+    assert.equal(500, error.status, 'expected an error status of 500');
+    done();
+  });

on 303

should redirect with same method

request
+  .put(`${base}/redirect-303`)
+  .send({ msg: 'hello' })
+  .redirects(1)
+  .on('redirect', (res) => {
+    res.headers.location.should.equal('/reply-method');
+  })
+  .end((error, res) => {
+    if (error) {
+      done(error);
+      return;
+    }
+    res.text.should.equal('method=get');
+    done();
+  });

on 307

should redirect with same method

if (isMSIE) return done(); // IE9 broken
+request
+  .put(`${base}/redirect-307`)
+  .send({ msg: 'hello' })
+  .redirects(1)
+  .on('redirect', (res) => {
+    res.headers.location.should.equal('/reply-method');
+  })
+  .end((error, res) => {
+    if (error) {
+      done(error);
+      return;
+    }
+    res.text.should.equal('method=put');
+    done();
+  });

on 308

should redirect with same method

if (isMSIE) return done(); // IE9 broken
+request
+  .put(`${base}/redirect-308`)
+  .send({ msg: 'hello' })
+  .redirects(1)
+  .on('redirect', (res) => {
+    res.headers.location.should.equal('/reply-method');
+  })
+  .end((error, res) => {
+    if (error) {
+      done(error);
+      return;
+    }
+    res.text.should.equal('method=put');
+    done();
+  });

+ +

request

Request inheritance

assert(request.get(`${uri}/`) instanceof request.Request);

request() simple GET without callback

request('GET', 'test/test.request.js').end();
+next();

request() simple GET

request('GET', `${uri}/ok`).end((error, res) => {
+  try {
+    assert(res instanceof request.Response, 'respond with Response');
+    assert(res.ok, 'response should be ok');
+    assert(res.text, 'res.text');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() simple HEAD

request.head(`${uri}/ok`).end((error, res) => {
+  try {
+    assert(res instanceof request.Response, 'respond with Response');
+    assert(res.ok, 'response should be ok');
+    assert(!res.text, 'res.text');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() GET 5xx

request('GET', `${uri}/error`).end((error, res) => {
+  try {
+    assert(error);
+    assert.equal(error.message, 'Internal Server Error');
+    assert(!res.ok, 'response should not be ok');
+    assert(res.error, 'response should be an error');
+    assert(!res.clientError, 'response should not be a client error');
+    assert(res.serverError, 'response should be a server error');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() GET 4xx

request('GET', `${uri}/notfound`).end((error, res) => {
+  try {
+    assert(error);
+    assert.equal(error.message, 'Not Found');
+    assert(!res.ok, 'response should not be ok');
+    assert(res.error, 'response should be an error');
+    assert(res.clientError, 'response should be a client error');
+    assert(!res.serverError, 'response should not be a server error');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() GET 404 Not Found

request('GET', `${uri}/notfound`).end((error, res) => {
+  try {
+    assert(error);
+    assert(res.notFound, 'response should be .notFound');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() GET 400 Bad Request

request('GET', `${uri}/bad-request`).end((error, res) => {
+  try {
+    assert(error);
+    assert(res.badRequest, 'response should be .badRequest');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() GET 401 Bad Request

request('GET', `${uri}/unauthorized`).end((error, res) => {
+  try {
+    assert(error);
+    assert(res.unauthorized, 'response should be .unauthorized');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() GET 406 Not Acceptable

request('GET', `${uri}/not-acceptable`).end((error, res) => {
+  try {
+    assert(error);
+    assert(res.notAcceptable, 'response should be .notAcceptable');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() GET 204 No Content

request('GET', `${uri}/no-content`).end((error, res) => {
+  try {
+    assert.ifError(error);
+    assert(res.noContent, 'response should be .noContent');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() DELETE 204 No Content

request('DELETE', `${uri}/no-content`).end((error, res) => {
+  try {
+    assert.ifError(error);
+    assert(res.noContent, 'response should be .noContent');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() header parsing

request('GET', `${uri}/notfound`).end((error, res) => {
+  try {
+    assert(error);
+    assert.equal('text/html; charset=utf-8', res.header['content-type']);
+    assert.equal('Express', res.header['x-powered-by']);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request() .status

request('GET', `${uri}/notfound`).end((error, res) => {
+  try {
+    assert(error);
+    assert.equal(404, res.status, 'response .status');
+    assert.equal(4, res.statusType, 'response .statusType');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

get()

request.get(`${uri}/notfound`).end((error, res) => {
+  try {
+    assert(error);
+    assert.equal(404, res.status, 'response .status');
+    assert.equal(4, res.statusType, 'response .statusType');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

put()

request.put(`${uri}/user/12`).end((error, res) => {
+  try {
+    assert.equal('updated', res.text, 'response text');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

put().send()

request
+  .put(`${uri}/user/13/body`)
+  .send({ user: 'new' })
+  .end((error, res) => {
+    try {
+      assert.equal('received new', res.text, 'response text');
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

post()

request.post(`${uri}/user`).end((error, res) => {
+  try {
+    assert.equal('created', res.text, 'response text');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

del()

request.del(`${uri}/user/12`).end((error, res) => {
+  try {
+    assert.equal('deleted', res.text, 'response text');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

delete()

request.delete(`${uri}/user/12`).end((error, res) => {
+  try {
+    assert.equal('deleted', res.text, 'response text');
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

post() data

request
+  .post(`${uri}/todo/item`)
+  .type('application/octet-stream')
+  .send('tobi')
+  .end((error, res) => {
+    try {
+      assert.equal('added "tobi"', res.text, 'response text');
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .type()

request
+  .post(`${uri}/user/12/pet`)
+  .type('urlencoded')
+  .send('pet=tobi')
+  .end((error, res) => {
+    try {
+      assert.equal('added pet "tobi"', res.text, 'response text');
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .type() with alias

request
+  .post(`${uri}/user/12/pet`)
+  .type('application/x-www-form-urlencoded')
+  .send('pet=tobi')
+  .end((error, res) => {
+    try {
+      assert.equal('added pet "tobi"', res.text, 'response text');
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .get() with no data or callback

request.get(`${uri}/echo-header/content-type`);
+next();

request .send() with no data only

request.post(`${uri}/user/5/pet`).type('urlencoded').send('pet=tobi');
+next();

request .send() with callback only

request
+  .get(`${uri}/echo-header/accept`)
+  .set('Accept', 'foo/bar')
+  .end((error, res) => {
+    try {
+      assert.equal('foo/bar', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .accept() with json

request
+  .get(`${uri}/echo-header/accept`)
+  .accept('json')
+  .end((error, res) => {
+    try {
+      assert.equal('application/json', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .accept() with application/json

request
+  .get(`${uri}/echo-header/accept`)
+  .accept('application/json')
+  .end((error, res) => {
+    try {
+      assert.equal('application/json', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .accept() with xml

request
+  .get(`${uri}/echo-header/accept`)
+  .accept('xml')
+  .end((error, res) => {
+    try {
+      // We can't depend on mime module to be consistent with this
+      assert(res.text == 'application/xml' || res.text == 'text/xml');
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .accept() with application/xml

request
+  .get(`${uri}/echo-header/accept`)
+  .accept('application/xml')
+  .end((error, res) => {
+    try {
+      assert.equal('application/xml', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .end()

request
+  .put(`${uri}/echo-header/content-type`)
+  .set('Content-Type', 'text/plain')
+  .send('wahoo')
+  .end((error, res) => {
+    try {
+      assert.equal('text/plain', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .send()

request
+  .put(`${uri}/echo-header/content-type`)
+  .set('Content-Type', 'text/plain')
+  .send('wahoo')
+  .end((error, res) => {
+    try {
+      assert.equal('text/plain', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .set()

request
+  .put(`${uri}/echo-header/content-type`)
+  .set('Content-Type', 'text/plain')
+  .send('wahoo')
+  .end((error, res) => {
+    try {
+      assert.equal('text/plain', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

request .set(object)

request
+  .put(`${uri}/echo-header/content-type`)
+  .set({ 'Content-Type': 'text/plain' })
+  .send('wahoo')
+  .end((error, res) => {
+    try {
+      assert.equal('text/plain', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

POST urlencoded

request
+  .post(`${uri}/pet`)
+  .type('urlencoded')
+  .send({ name: 'Manny', species: 'cat' })
+  .end((error, res) => {
+    try {
+      assert.equal('added Manny the cat', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

POST json

request
+  .post(`${uri}/pet`)
+  .type('json')
+  .send({ name: 'Manny', species: 'cat' })
+  .end((error, res) => {
+    try {
+      assert.equal('added Manny the cat', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

POST json array

request
+  .post(`${uri}/echo`)
+  .send([1, 2, 3])
+  .end((error, res) => {
+    try {
+      assert.equal(
+        'application/json',
+        res.header['content-type'].split(';')[0]
+      );
+      assert.equal('[1,2,3]', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

POST json default

request
+  .post(`${uri}/pet`)
+  .send({ name: 'Manny', species: 'cat' })
+  .end((error, res) => {
+    try {
+      assert.equal('added Manny the cat', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

POST json contentType charset

request
+  .post(`${uri}/echo`)
+  .set('Content-Type', 'application/json; charset=UTF-8')
+  .send({ data: ['data1', 'data2'] })
+  .end((error, res) => {
+    try {
+      assert.equal('{"data":["data1","data2"]}', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

POST json contentType vendor

request
+  .post(`${uri}/echo`)
+  .set('Content-Type', 'application/vnd.example+json')
+  .send({ data: ['data1', 'data2'] })
+  .end((error, res) => {
+    try {
+      assert.equal('{"data":["data1","data2"]}', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

POST multiple .send() calls

request
+  .post(`${uri}/pet`)
+  .send({ name: 'Manny' })
+  .send({ species: 'cat' })
+  .end((error, res) => {
+    try {
+      assert.equal('added Manny the cat', res.text);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

POST multiple .send() strings

request
+  .post(`${uri}/echo`)
+  .send('user[name]=tj')
+  .send('user[email]=tj@vision-media.ca')
+  .end((error, res) => {
+    try {
+      assert.equal(
+        'application/x-www-form-urlencoded',
+        res.header['content-type'].split(';')[0]
+      );
+      assert.equal(
+        res.text,
+        'user[name]=tj&user[email]=tj@vision-media.ca'
+      );
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

POST with no data

request
+  .post(`${uri}/empty-body`)
+  .send()
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      assert(res.noContent, 'response should be .noContent');
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET .type

request.get(`${uri}/pets`).end((error, res) => {
+  try {
+    assert.equal('application/json', res.type);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

GET Content-Type params

request.get(`${uri}/text`).end((error, res) => {
+  try {
+    assert.equal('utf-8', res.charset);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

GET json

request.get(`${uri}/pets`).end((error, res) => {
+  try {
+    assert.deepEqual(res.body, ['tobi', 'loki', 'jane']);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

GET json-seq

request
+  .get(`${uri}/json-seq`)
+  .buffer()
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      assert.deepEqual(res.text, '\u001E{"id":1}\n\u001E{"id":2}\n');
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET binary data

request
+  .get(`${uri}/binary-data`)
+  .buffer()
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      assert.deepEqual(res.body, binData);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET x-www-form-urlencoded

request.get(`${uri}/foo`).end((error, res) => {
+  try {
+    assert.deepEqual(res.body, { foo: 'bar' });
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

GET shorthand

request.get(`${uri}/foo`, (error, res) => {
+  try {
+    assert.equal('foo=bar', res.text);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

POST shorthand

request.post(`${uri}/user/0/pet`, { pet: 'tobi' }, (error, res) => {
+  try {
+    assert.equal('added pet "tobi"', res.text);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

POST shorthand without callback

request.post(`${uri}/user/0/pet`, { pet: 'tobi' }).end((error, res) => {
+  try {
+    assert.equal('added pet "tobi"', res.text);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

GET querystring object with array

request
+  .get(`${uri}/querystring`)
+  .query({ val: ['a', 'b', 'c'] })
+  .end((error, res) => {
+    try {
+      assert.deepEqual(res.body, { val: ['a', 'b', 'c'] });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET querystring object with array and primitives

request
+  .get(`${uri}/querystring`)
+  .query({ array: ['a', 'b', 'c'], string: 'foo', number: 10 })
+  .end((error, res) => {
+    try {
+      assert.deepEqual(res.body, {
+        array: ['a', 'b', 'c'],
+        string: 'foo',
+        number: 10
+      });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET querystring object with two arrays

request
+  .get(`${uri}/querystring`)
+  .query({ array1: ['a', 'b', 'c'], array2: [1, 2, 3] })
+  .end((error, res) => {
+    try {
+      assert.deepEqual(res.body, {
+        array1: ['a', 'b', 'c'],
+        array2: [1, 2, 3]
+      });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET querystring object

request
+  .get(`${uri}/querystring`)
+  .query({ search: 'Manny' })
+  .end((error, res) => {
+    try {
+      assert.deepEqual(res.body, { search: 'Manny' });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET querystring append original

request
+  .get(`${uri}/querystring?search=Manny`)
+  .query({ range: '1..5' })
+  .end((error, res) => {
+    try {
+      assert.deepEqual(res.body, { search: 'Manny', range: '1..5' });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET querystring multiple objects

request
+  .get(`${uri}/querystring`)
+  .query({ search: 'Manny' })
+  .query({ range: '1..5' })
+  .query({ order: 'desc' })
+  .end((error, res) => {
+    try {
+      assert.deepEqual(res.body, {
+        search: 'Manny',
+        range: '1..5',
+        order: 'desc'
+      });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET querystring with strings

request
+  .get(`${uri}/querystring`)
+  .query('search=Manny')
+  .query('range=1..5')
+  .query('order=desc')
+  .end((error, res) => {
+    try {
+      assert.deepEqual(res.body, {
+        search: 'Manny',
+        range: '1..5',
+        order: 'desc'
+      });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET querystring with strings and objects

request
+  .get(`${uri}/querystring`)
+  .query('search=Manny')
+  .query({ order: 'desc', range: '1..5' })
+  .end((error, res) => {
+    try {
+      assert.deepEqual(res.body, {
+        search: 'Manny',
+        range: '1..5',
+        order: 'desc'
+      });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });

GET shorthand payload goes to querystring

request.get(
+  `${uri}/querystring`,
+  { foo: 'FOO', bar: 'BAR' },
+  (error, res) => {
+    try {
+      assert.deepEqual(res.body, { foo: 'FOO', bar: 'BAR' });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  }
+);

HEAD shorthand payload goes to querystring

request.head(
+  `${uri}/querystring-in-header`,
+  { foo: 'FOO', bar: 'BAR' },
+  (error, res) => {
+    try {
+      assert.deepEqual(JSON.parse(res.headers.query), {
+        foo: 'FOO',
+        bar: 'BAR'
+      });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  }
+);

request(method, url)

request('GET', `${uri}/foo`).end((error, res) => {
+  try {
+    assert.equal('bar', res.body.foo);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request(url)

request(`${uri}/foo`).end((error, res) => {
+  try {
+    assert.equal('bar', res.body.foo);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request(url, fn)

request(`${uri}/foo`, (error, res) => {
+  try {
+    assert.equal('bar', res.body.foo);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

req.timeout(ms)

const request_ = request.get(`${uri}/delay/3000`).timeout(1000);
+request_.end((error, res) => {
+  try {
+    assert(error, 'error missing');
+    assert.equal(1000, error.timeout, 'err.timeout missing');
+    assert.equal(
+      'Timeout of 1000ms exceeded',
+      error.message,
+      'err.message incorrect'
+    );
+    assert.equal(null, res);
+    assert(request_.timedout, true);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

req.timeout(ms) with redirect

const request_ = request.get(`${uri}/delay/const`).timeout(1000);
+request_.end((error, res) => {
+  try {
+    assert(error, 'error missing');
+    assert.equal(1000, error.timeout, 'err.timeout missing');
+    assert.equal(
+      'Timeout of 1000ms exceeded',
+      error.message,
+      'err.message incorrect'
+    );
+    assert.equal(null, res);
+    assert(request_.timedout, true);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

request event

request
+  .get(`${uri}/foo`)
+  .on('request', (request_) => {
+    try {
+      assert.equal(`${uri}/foo`, request_.url);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  })
+  .end();

response event

request
+  .get(`${uri}/foo`)
+  .on('response', (res) => {
+    try {
+      assert.equal('bar', res.body.foo);
+      next();
+    } catch (err) {
+      next(err);
+    }
+  })
+  .end();

response should set statusCode

request.get(`${uri}/ok`, (error, res) => {
+  try {
+    assert.strictEqual(res.statusCode, 200);
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

req.toJSON()

request.get(`${uri}/ok`).end((error, res) => {
+  try {
+    const index = (res.request || res.req).toJSON();
+    for (const property of ['url', 'method', 'data', 'headers']) {
+      assert(index.hasOwnProperty(property));
+    }
+    next();
+  } catch (err) {
+    next(err);
+  }
+});

.retry(count)

should not retry if passed "0"

request
+  .get(`${base}/error`)
+  .retry(0)
+  .end((error, res) => {
+    try {
+      assert(error, 'expected an error');
+      assert.equal(
+        undefined,
+        error.retries,
+        'expected an error without .retries'
+      );
+      assert.equal(500, error.status, 'expected an error status of 500');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should not retry if passed an invalid number

request
+  .get(`${base}/error`)
+  .retry(-2)
+  .end((error, res) => {
+    try {
+      assert(error, 'expected an error');
+      assert.equal(
+        undefined,
+        error.retries,
+        'expected an error without .retries'
+      );
+      assert.equal(500, error.status, 'expected an error status of 500');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should not retry if passed undefined

request
+  .get(`${base}/error`)
+  .retry(undefined)
+  .end((error, res) => {
+    try {
+      assert(error, 'expected an error');
+      assert.equal(
+        undefined,
+        error.retries,
+        'expected an error without .retries'
+      );
+      assert.equal(500, error.status, 'expected an error status of 500');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should handle server error after repeat attempt

request
+  .get(`${base}/error`)
+  .retry(2)
+  .end((error, res) => {
+    try {
+      assert(error, 'expected an error');
+      assert.equal(2, error.retries, 'expected an error with .retries');
+      assert.equal(500, error.status, 'expected an error status of 500');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should retry if passed nothing

request
+  .get(`${base}/error`)
+  .retry()
+  .end((error, res) => {
+    try {
+      assert(error, 'expected an error');
+      assert.equal(1, error.retries, 'expected an error with .retries');
+      assert.equal(500, error.status, 'expected an error status of 500');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should retry if passed "true"

request
+  .get(`${base}/error`)
+  .retry(true)
+  .end((error, res) => {
+    try {
+      assert(error, 'expected an error');
+      assert.equal(1, error.retries, 'expected an error with .retries');
+      assert.equal(500, error.status, 'expected an error status of 500');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should handle successful request after repeat attempt from server error

request
+  .get(`${base}/error/ok/${uniqid()}`)
+  .query({ qs: 'present' })
+  .retry(2)
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      assert(res.ok, 'response should be ok');
+      assert(res.text, 'res.text');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should handle server timeout error after repeat attempt

request
+  .get(`${base}/delay/400`)
+  .timeout(200)
+  .retry(2)
+  .end((error, res) => {
+    try {
+      assert(error, 'expected an error');
+      assert.equal(2, error.retries, 'expected an error with .retries');
+      assert.equal(
+        'number',
+        typeof error.timeout,
+        'expected an error with .timeout'
+      );
+      assert.equal('ECONNABORTED', error.code, 'expected abort error code');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should handle successful request after repeat attempt from server timeout

const url = `/delay/1200/ok/${uniqid()}?built=in`;
+request
+  .get(base + url)
+  .query('string=ified')
+  .query({ json: 'ed' })
+  .timeout(600)
+  .retry(2)
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      assert(res.ok, 'response should be ok');
+      assert.equal(res.text, `ok = ${url}&string=ified&json=ed`);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should handle successful request after repeat attempt from server timeout when using .then(fulfill, reject)

const url = `/delay/1200/ok/${uniqid()}?built=in`;
+request
+  .get(base + url)
+  .query('string=ified')
+  .query({ json: 'ed' })
+  .timeout(600)
+  .retry(1)
+  .then((res, error) => {
+    try {
+      assert.ifError(error);
+      assert(res.ok, 'response should be ok');
+      assert.equal(res.text, `ok = ${url}&string=ified&json=ed`);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should correctly abort a retry attempt

let aborted = false;
+const request_ = request.get(`${base}/delay/400`).timeout(200).retry(2);
+request_.end((error, res) => {
+  try {
+    assert(false, 'should not complete the request');
+  } catch (err) {
+    done(err);
+  }
+});
+request_.on('abort', () => {
+  aborted = true;
+});
+setTimeout(() => {
+  request_.abort();
+  setTimeout(() => {
+    try {
+      assert(aborted, 'should be aborted');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  }, 150);
+}, 150);

should correctly retain header fields

request
+  .get(`${base}/error/ok/${uniqid()}`)
+  .query({ qs: 'present' })
+  .retry(2)
+  .set('X-Foo', 'bar')
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      assert(res.body);
+      res.body.should.have.property('x-foo', 'bar');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should not retry on 4xx responses

request
+  .get(`${base}/bad-request`)
+  .retry(2)
+  .end((error, res) => {
+    try {
+      assert(error, 'expected an error');
+      assert.equal(0, error.retries, 'expected an error with 0 .retries');
+      assert.equal(400, error.status, 'expected an error status of 400');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should execute callback on retry if passed

let callbackCallCount = 0;
+function retryCallback(request) {
+  callbackCallCount++;
+}
+request
+  .get(`${base}/error`)
+  .retry(2, retryCallback)
+  .end((error, res) => {
+    try {
+      assert(error, 'expected an error');
+      assert.equal(2, error.retries, 'expected an error with .retries');
+      assert.equal(500, error.status, 'expected an error status of 500');
+      assert.equal(
+        2,
+        callbackCallCount,
+        'expected the callback to be called on each retry'
+      );
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

.timeout(ms)

when timeout is exceeded

should error

request
+  .get(`${base}/delay/500`)
+  .timeout(150)
+  .end((error, res) => {
+    assert(error, 'expected an error');
+    assert.equal(
+      'number',
+      typeof error.timeout,
+      'expected an error with .timeout'
+    );
+    assert.equal('ECONNABORTED', error.code, 'expected abort error code');
+    done();
+  });

should error in promise interface

request
+  .get(`${base}/delay/500`)
+  .timeout(150)
+  .catch((err) => {
+    assert(err, 'expected an error');
+    assert.equal(
+      'number',
+      typeof err.timeout,
+      'expected an error with .timeout'
+    );
+    assert.equal('ECONNABORTED', err.code, 'expected abort error code');
+    done();
+  });

should handle gzip timeout

request
+  .get(`${base}/delay/zip`)
+  .timeout(150)
+  .end((error, res) => {
+    assert(error, 'expected an error');
+    assert.equal(
+      'number',
+      typeof error.timeout,
+      'expected an error with .timeout'
+    );
+    assert.equal('ECONNABORTED', error.code, 'expected abort error code');
+    done();
+  });

should handle buffer timeout

request
+  .get(`${base}/delay/json`)
+  .buffer(true)
+  .timeout(150)
+  .end((error, res) => {
+    assert(error, 'expected an error');
+    assert.equal(
+      'number',
+      typeof error.timeout,
+      'expected an error with .timeout'
+    );
+    assert.equal('ECONNABORTED', error.code, 'expected abort error code');
+    done();
+  });

should error on deadline

request
+  .get(`${base}/delay/500`)
+  .timeout({ deadline: 150 })
+  .end((error, res) => {
+    assert(error, 'expected an error');
+    assert.equal(
+      'number',
+      typeof error.timeout,
+      'expected an error with .timeout'
+    );
+    assert.equal('ECONNABORTED', error.code, 'expected abort error code');
+    done();
+  });

should support setting individual options

request
+  .get(`${base}/delay/500`)
+  .timeout({ deadline: 10 })
+  .timeout({ response: 99_999 })
+  .end((error, res) => {
+    assert(error, 'expected an error');
+    assert.equal('ECONNABORTED', error.code, 'expected abort error code');
+    assert.equal('ETIME', error.errno);
+    done();
+  });

should error on response

request
+  .get(`${base}/delay/500`)
+  .timeout({ response: 150 })
+  .end((error, res) => {
+    assert(error, 'expected an error');
+    assert.equal(
+      'number',
+      typeof error.timeout,
+      'expected an error with .timeout'
+    );
+    assert.equal('ECONNABORTED', error.code, 'expected abort error code');
+    assert.equal('ETIMEDOUT', error.errno);
+    done();
+  });

should accept slow body with fast response

request
+  .get(`${base}/delay/slowbody`)
+  .timeout({ response: 1000 })
+  .on('progress', () => {
+    // This only makes the test faster without relying on arbitrary timeouts
+    request.get(`${base}/delay/slowbody/finish`).end();
+  })
+  .end(done);

+ +

request

use

should use plugin success

const now = `${Date.now()}`;
+function uuid(request_) {
+  request_.set('X-UUID', now);
+  return request_;
+}
+function prefix(request_) {
+  request_.url = uri + request_.url;
+  return request_;
+}
+request
+  .get('/echo')
+  .use(uuid)
+  .use(prefix)
+  .end((error, res) => {
+    assert.strictEqual(res.statusCode, 200);
+    assert.equal(res.get('X-UUID'), now);
+    done();
+  });

+ +

subclass

should be an instance of Request

const request_ = request.get('/');
+assert(request_ instanceof request.Request);

should use patched subclass

assert(OriginalRequest);
+let constructorCalled;
+let sendCalled;
+function NewRequest(...args) {
+  constructorCalled = true;
+  OriginalRequest.apply(this, args);
+}
+NewRequest.prototype = Object.create(OriginalRequest.prototype);
+NewRequest.prototype.send = function () {
+  sendCalled = true;
+  return this;
+};
+request.Request = NewRequest;
+const request_ = request.get('/').send();
+assert(constructorCalled);
+assert(sendCalled);
+assert(request_ instanceof NewRequest);
+assert(request_ instanceof OriginalRequest);

should use patched subclass in agent too

if (!request.agent) return; // Node-only
+function NewRequest(...args) {
+  OriginalRequest.apply(this, args);
+}
+NewRequest.prototype = Object.create(OriginalRequest.prototype);
+request.Request = NewRequest;
+const request_ = request.agent().del('/');
+assert(request_ instanceof NewRequest);
+assert(request_ instanceof OriginalRequest);

request

persistent agent

should gain a session on POST

agent3.post(`${base}/signin`).then((res) => {
+        res.should.have.status(200);
+        should.not.exist(res.headers['set-cookie']);
+        res.text.should.containEql('dashboard');
+      })

should start with empty session (set cookies)

agent1.get(`${base}/dashboard`).end((error, res) => {
+  should.exist(error);
+  res.should.have.status(401);
+  should.exist(res.headers['set-cookie']);
+  done();
+});

should gain a session (cookies already set)

agent1.post(`${base}/signin`).then((res) => {
+        res.should.have.status(200);
+        should.not.exist(res.headers['set-cookie']);
+        res.text.should.containEql('dashboard');
+      })

should persist cookies across requests

agent1.get(`${base}/dashboard`).then((res) => {
+        res.should.have.status(200);
+      })

should have the cookie set in the end callback

agent4
+        .post(`${base}/setcookie`)
+        .then(() => agent4.get(`${base}/getcookie`))
+        .then((res) => {
+          res.should.have.status(200);
+          assert.strictEqual(res.text, 'jar');
+        })

should not share cookies

agent2.get(`${base}/dashboard`).end((error, res) => {
+  should.exist(error);
+  res.should.have.status(401);
+  done();
+});

should not lose cookies between agents

agent1.get(`${base}/dashboard`).then((res) => {
+        res.should.have.status(200);
+      })

should be able to follow redirects

agent1.get(base).then((res) => {
+        res.should.have.status(200);
+        res.text.should.containEql('dashboard');
+      })

should be able to post redirects

agent1
+        .post(`${base}/redirect`)
+        .send({ foo: 'bar', baz: 'blaaah' })
+        .then((res) => {
+          res.should.have.status(200);
+          res.text.should.containEql('simple');
+          res.redirects.should.eql([`${base}/simple`]);
+        })

should be able to limit redirects

agent1
+  .get(base)
+  .redirects(0)
+  .end((error, res) => {
+    should.exist(error);
+    res.should.have.status(302);
+    res.redirects.should.eql([]);
+    res.header.location.should.equal('/dashboard');
+    done();
+  });

should be able to create a new session (clear cookie)

agent1.post(`${base}/signout`).then((res) => {
+        res.should.have.status(200);
+        should.exist(res.headers['set-cookie']);
+      })

should regenerate with an empty session

agent1.get(`${base}/dashboard`).end((error, res) => {
+  should.exist(error);
+  res.should.have.status(401);
+  should.not.exist(res.headers['set-cookie']);
+  done();
+});

+ +

Basic auth

when credentials are present in url

should set Authorization

const new_url = URL.parse(base);
+new_url.auth = 'tobi:learnboost';
+new_url.pathname = '/basic-auth';
+request.get(URL.format(new_url)).end((error, res) => {
+  res.status.should.equal(200);
+  done();
+});

req.auth(user, pass)

should set Authorization

request
+  .get(`${base}/basic-auth`)
+  .auth('tobi', 'learnboost')
+  .end((error, res) => {
+    res.status.should.equal(200);
+    done();
+  });

req.auth(user + ":" + pass)

should set authorization

request
+  .get(`${base}/basic-auth/again`)
+  .auth('tobi')
+  .end((error, res) => {
+    res.status.should.eql(200);
+    done();
+  });

+ +

[node] request

with an url

should preserve the encoding of the url

request.get(`${base}/url?a=(b%29`).end((error, res) => {
+  assert.equal('/url?a=(b%29', res.text);
+  done();
+});

with an object

should format the url

request.get(url.parse(`${base}/login`)).then((res) => {
+        assert(res.ok);
+      })

without a schema

should default to http

request.get(`${base}/login`).then((res) => {
+        assert.equal(res.status, 200);
+      })

res.toJSON()

should describe the response

request
+        .post(`${base}/echo`)
+        .send({ foo: 'baz' })
+        .then((res) => {
+          const object = res.toJSON();
+          assert.equal('object', typeof object.header);
+          assert.equal('object', typeof object.req);
+          assert.equal(200, object.status);
+          assert.equal('{"foo":"baz"}', object.text);
+        })

res.links

should default to an empty object

request.get(`${base}/login`).then((res) => {
+        res.links.should.eql({});
+      })

should parse the Link header field

request.get(`${base}/links`).end((error, res) => {
+  res.links.next.should.equal(
+    'https://api.github.com/repos/visionmedia/mocha/issues?page=2'
+  );
+  done();
+});

req.unset(field)

should remove the header field

request
+  .post(`${base}/echo`)
+  .unset('User-Agent')
+  .end((error, res) => {
+    assert.equal(void 0, res.header['user-agent']);
+    done();
+  });

case-insensitive

should set/get header fields case-insensitively

const r = request.post(`${base}/echo`);
+r.set('MiXeD', 'helloes');
+assert.strictEqual(r.get('mixed'), 'helloes');

should unset header fields case-insensitively

const r = request.post(`${base}/echo`);
+r.set('MiXeD', 'helloes');
+r.unset('MIXED');
+assert.strictEqual(r.get('mixed'), undefined);

req.write(str)

should write the given data

const request_ = request.post(`${base}/echo`);
+request_.set('Content-Type', 'application/json');
+assert.equal('boolean', typeof request_.write('{"name"'));
+assert.equal('boolean', typeof request_.write(':"tobi"}'));
+request_.end((error, res) => {
+  res.text.should.equal('{"name":"tobi"}');
+  done();
+});

req.pipe(stream)

should pipe the response to the given stream

const stream = new EventEmitter();
+stream.buf = '';
+stream.writable = true;
+stream.write = function (chunk) {
+  this.buf += chunk;
+};
+stream.end = function () {
+  this.buf.should.equal('{"name":"tobi"}');
+  done();
+};
+request.post(`${base}/echo`).send('{"name":"tobi"}').pipe(stream);

.buffer()

should enable buffering

request
+  .get(`${base}/custom`)
+  .buffer()
+  .end((error, res) => {
+    assert.ifError(error);
+    assert.equal('custom stuff', res.text);
+    assert(res.buffered);
+    done();
+  });

should take precedence over request.buffer['someMimeType'] = false

const type = 'application/barbaz';
+const send = 'some text';
+request.buffer[type] = false;
+request
+  .post(`${base}/echo`)
+  .type(type)
+  .send(send)
+  .buffer()
+  .end((error, res) => {
+    delete request.buffer[type];
+    assert.ifError(error);
+    assert.equal(res.type, type);
+    assert.equal(send, res.text);
+    assert(res.buffered);
+    done();
+  });

.buffer(false)

should disable buffering

request
+  .post(`${base}/echo`)
+  .type('application/x-dog')
+  .send('hello this is dog')
+  .buffer(false)
+  .end((error, res) => {
+    assert.ifError(error);
+    assert.equal(null, res.text);
+    res.body.should.eql({});
+    let buf = '';
+    res.setEncoding('utf8');
+    res.on('data', (chunk) => {
+      buf += chunk;
+    });
+    res.on('end', () => {
+      buf.should.equal('hello this is dog');
+      done();
+    });
+  });

should take precedence over request.buffer['someMimeType'] = true

const type = 'application/foobar';
+const send = 'hello this is a dog';
+request.buffer[type] = true;
+request
+  .post(`${base}/echo`)
+  .type(type)
+  .send(send)
+  .buffer(false)
+  .end((error, res) => {
+    delete request.buffer[type];
+    assert.ifError(error);
+    assert.equal(null, res.text);
+    assert.equal(res.type, type);
+    assert(!res.buffered);
+    res.body.should.eql({});
+    let buf = '';
+    res.setEncoding('utf8');
+    res.on('data', (chunk) => {
+      buf += chunk;
+    });
+    res.on('end', () => {
+      buf.should.equal(send);
+      done();
+    });
+  });

.withCredentials()

should not throw an error when using the client-side "withCredentials" method

request
+  .get(`${base}/custom`)
+  .withCredentials()
+  .end((error, res) => {
+    assert.ifError(error);
+    done();
+  });

.agent()

should return the defaut agent

const request_ = request.post(`${base}/echo`);
+request_.agent().should.equal(false);
+done();

.agent(undefined)

should set an agent to undefined and ensure it is chainable

const request_ = request.get(`${base}/echo`);
+const returnValue = request_.agent(undefined);
+returnValue.should.equal(request_);
+assert.strictEqual(request_.agent(), undefined);
+done();

.agent(new http.Agent())

should set passed agent

const http = require('http');
+const request_ = request.get(`${base}/echo`);
+const agent = new http.Agent();
+const returnValue = request_.agent(agent);
+returnValue.should.equal(request_);
+request_.agent().should.equal(agent);
+done();

with a content type other than application/json or text/*

should still use buffering

return request
+  .post(`${base}/echo`)
+  .type('application/x-dog')
+  .send('hello this is dog')
+  .then((res) => {
+    assert.equal(null, res.text);
+    assert.equal(res.body.toString(), 'hello this is dog');
+    res.buffered.should.be.true;
+  });

content-length

should be set to the byte length of a non-buffer object

const decoder = new StringDecoder('utf8');
+let img = fs.readFileSync(`${__dirname}/fixtures/test.png`);
+img = decoder.write(img);
+request
+  .post(`${base}/echo`)
+  .type('application/x-image')
+  .send(img)
+  .buffer(false)
+  .end((error, res) => {
+    assert.ifError(error);
+    assert(!res.buffered);
+    assert.equal(res.header['content-length'], Buffer.byteLength(img));
+    done();
+  });

should be set to the length of a buffer object

const img = fs.readFileSync(`${__dirname}/fixtures/test.png`);
+request
+  .post(`${base}/echo`)
+  .type('application/x-image')
+  .send(img)
+  .buffer(true)
+  .end((error, res) => {
+    assert.ifError(error);
+    assert(res.buffered);
+    assert.equal(res.header['content-length'], img.length);
+    done();
+  });

+ +

req.buffer['someMimeType']

should respect that agent.buffer(true) takes precedent

const agent = request.agent();
+agent.buffer(true);
+const type = 'application/somerandomtype';
+const send = 'somerandomtext';
+request.buffer[type] = false;
+agent
+  .post(`${base}/echo`)
+  .type(type)
+  .send(send)
+  .end((error, res) => {
+    delete request.buffer[type];
+    assert.ifError(error);
+    assert.equal(res.type, type);
+    assert.equal(send, res.text);
+    assert(res.buffered);
+    done();
+  });

should respect that agent.buffer(false) takes precedent

const agent = request.agent();
+agent.buffer(false);
+const type = 'application/barrr';
+const send = 'some random text2';
+request.buffer[type] = true;
+agent
+  .post(`${base}/echo`)
+  .type(type)
+  .send(send)
+  .end((error, res) => {
+    delete request.buffer[type];
+    assert.ifError(error);
+    assert.equal(null, res.text);
+    assert.equal(res.type, type);
+    assert(!res.buffered);
+    res.body.should.eql({});
+    let buf = '';
+    res.setEncoding('utf8');
+    res.on('data', (chunk) => {
+      buf += chunk;
+    });
+    res.on('end', () => {
+      buf.should.equal(send);
+      done();
+    });
+  });

should disable buffering for that mimetype when false

const type = 'application/bar';
+const send = 'some random text';
+request.buffer[type] = false;
+request
+  .post(`${base}/echo`)
+  .type(type)
+  .send(send)
+  .end((error, res) => {
+    delete request.buffer[type];
+    assert.ifError(error);
+    assert.equal(null, res.text);
+    assert.equal(res.type, type);
+    assert(!res.buffered);
+    res.body.should.eql({});
+    let buf = '';
+    res.setEncoding('utf8');
+    res.on('data', (chunk) => {
+      buf += chunk;
+    });
+    res.on('end', () => {
+      buf.should.equal(send);
+      done();
+    });
+  });

should enable buffering for that mimetype when true

const type = 'application/baz';
+const send = 'woooo';
+request.buffer[type] = true;
+request
+  .post(`${base}/echo`)
+  .type(type)
+  .send(send)
+  .end((error, res) => {
+    delete request.buffer[type];
+    assert.ifError(error);
+    assert.equal(res.type, type);
+    assert.equal(send, res.text);
+    assert(res.buffered);
+    done();
+  });

should fallback to default handling for that mimetype when undefined

const type = 'application/bazzz';
+const send = 'woooooo';
+return request
+  .post(`${base}/echo`)
+  .type(type)
+  .send(send)
+  .then((res) => {
+    assert.equal(res.type, type);
+    assert.equal(send, res.body.toString());
+    assert(res.buffered);
+  });

exports

should expose .protocols

Object.keys(request.protocols).should.eql(['http:', 'https:', 'http2:']);

should expose .serialize

Object.keys(request.serialize).should.eql([
+  'application/x-www-form-urlencoded',
+  'application/json'
+]);

should expose .parse

Object.keys(request.parse).should.eql([
+  'application/x-www-form-urlencoded',
+  'application/json',
+  'text',
+  'application/json-seq',
+  'application/octet-stream',
+  'application/pdf',
+  'image'
+]);

should export .buffer

Object.keys(request.buffer).should.eql([]);

flags

with 4xx response

should set res.error and res.clientError

request.get(`${base}/notfound`).end((error, res) => {
+  assert(error);
+  assert(!res.ok, 'response should not be ok');
+  assert(res.error, 'response should be an error');
+  assert(res.clientError, 'response should be a client error');
+  assert(!res.serverError, 'response should not be a server error');
+  done();
+});

with 5xx response

should set res.error and res.serverError

request.get(`${base}/error`).end((error, res) => {
+  assert(error);
+  assert(!res.ok, 'response should not be ok');
+  assert(!res.notFound, 'response should not be notFound');
+  assert(res.error, 'response should be an error');
+  assert(!res.clientError, 'response should not be a client error');
+  assert(res.serverError, 'response should be a server error');
+  done();
+});

with 404 Not Found

should res.notFound

request.get(`${base}/notfound`).end((error, res) => {
+  assert(error);
+  assert(res.notFound, 'response should be .notFound');
+  done();
+});

with 400 Bad Request

should set req.badRequest

request.get(`${base}/bad-request`).end((error, res) => {
+  assert(error);
+  assert(res.badRequest, 'response should be .badRequest');
+  done();
+});

with 401 Bad Request

should set res.unauthorized

request.get(`${base}/unauthorized`).end((error, res) => {
+  assert(error);
+  assert(res.unauthorized, 'response should be .unauthorized');
+  done();
+});

with 406 Not Acceptable

should set res.notAcceptable

request.get(`${base}/not-acceptable`).end((error, res) => {
+  assert(error);
+  assert(res.notAcceptable, 'response should be .notAcceptable');
+  done();
+});

with 204 No Content

should set res.noContent

request.get(`${base}/no-content`).end((error, res) => {
+  assert(!error);
+  assert(res.noContent, 'response should be .noContent');
+  done();
+});

with 201 Created

should set res.created

request.post(`${base}/created`).end((error, res) => {
+  assert(!error);
+  assert(res.created, 'response should be .created');
+  done();
+});

with 422 Unprocessable Entity

should set res.unprocessableEntity

request.post(`${base}/unprocessable-entity`).end((error, res) => {
+  assert(error);
+  assert(
+    res.unprocessableEntity,
+    'response should be .unprocessableEntity'
+  );
+  done();
+});

+ +

Merging objects

Don't mix Buffer and JSON

assert.throws(() => {
+  request
+    .post('/echo')
+    .send(Buffer.from('some buffer'))
+    .send({ allowed: false });
+});

req.send(String)

should default to "form"

request
+  .post(`${base}/echo`)
+  .send('user[name]=tj')
+  .send('user[email]=tj@vision-media.ca')
+  .end((error, res) => {
+    res.header['content-type'].should.equal(
+      'application/x-www-form-urlencoded'
+    );
+    res.body.should.eql({
+      user: { name: 'tj', email: 'tj@vision-media.ca' }
+    });
+    done();
+  });

res.body

application/x-www-form-urlencoded

should parse the body

request.get(`${base}/form-data`).end((error, res) => {
+  res.text.should.equal('pet[name]=manny');
+  res.body.should.eql({ pet: { name: 'manny' } });
+  done();
+});

+ +

request.get().http2()

should preserve the encoding of the url

request
+  .get(`${base}/url?a=(b%29`)
+  .http2()
+  .end((error, res) => {
+    assert.equal('/url?a=(b%29', res.text);
+    done();
+  });

should format the url

request
+      .get(url.parse(`${base}/login`))
+      .http2()
+      .then((res) => {
+        assert(res.ok);
+      })

https

certificate authority

request

should give a good response

request
+  .get(testEndpoint)
+  .ca(ca)
+  .end((error, res) => {
+    assert.ifError(error);
+    assert(res.ok);
+    assert.strictEqual('Safe and secure!', res.text);
+    done();
+  });

should reject unauthorized response

return request
+  .get(testEndpoint)
+  .trustLocalhost(false)
+  .then(
+    () => {
+      throw new Error('Allows MITM');
+    },
+    () => {}
+  );

should not reject unauthorized response

return request
+  .get(testEndpoint)
+  .disableTLSCerts()
+  .then(({ status }) => {
+    assert.strictEqual(status, 200);
+  });

should trust localhost unauthorized response

return request.get(testEndpoint).trustLocalhost(true);

should trust overriden localhost unauthorized response

return request
+  .get(`https://example.com:${server.address().port}`)
+  .connect('127.0.0.1')
+  .trustLocalhost();

.agent

should be able to make multiple requests without redefining the certificate

const agent = request.agent({ ca });
+agent.get(testEndpoint).end((error, res) => {
+  assert.ifError(error);
+  assert(res.ok);
+  assert.strictEqual('Safe and secure!', res.text);
+  agent.get(url.parse(testEndpoint)).end((error, res) => {
+    assert.ifError(error);
+    assert(res.ok);
+    assert.strictEqual('Safe and secure!', res.text);
+    done();
+  });
+});

+ +

client certificates

request

+ +

.agent

+ +

res.body

image/png

should parse the body

request.get(`${base}/image`).end((error, res) => {
+  res.type.should.equal('image/png');
+  Buffer.isBuffer(res.body).should.be.true();
+  (res.body.length - img.length).should.equal(0);
+  done();
+});

application/octet-stream

should parse the body

request
+  .get(`${base}/image-as-octets`)
+  .buffer(true) // that's tech debt :(
+  .end((error, res) => {
+    res.type.should.equal('application/octet-stream');
+    Buffer.isBuffer(res.body).should.be.true();
+    (res.body.length - img.length).should.equal(0);
+    done();
+  });

application/octet-stream

should parse the body (using responseType)

request
+  .get(`${base}/image-as-octets`)
+  .responseType('blob')
+  .end((error, res) => {
+    res.type.should.equal('application/octet-stream');
+    Buffer.isBuffer(res.body).should.be.true();
+    (res.body.length - img.length).should.equal(0);
+    done();
+  });

+ +

zlib

should deflate the content

request.get(base).end((error, res) => {
+  res.should.have.status(200);
+  res.text.should.equal(subject);
+  res.headers['content-length'].should.be.below(subject.length);
+  done();
+});

should protect from zip bombs

request
+  .get(base)
+  .buffer(true)
+  .maxResponseSize(1)
+  .end((error, res) => {
+    try {
+      assert.equal('Maximum response size reached', error && error.message);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should ignore trailing junk

request.get(`${base}/junk`).end((error, res) => {
+  res.should.have.status(200);
+  res.text.should.equal(subject);
+  done();
+});

should ignore missing data

request.get(`${base}/chopped`).end((error, res) => {
+  assert.equal(undefined, error);
+  res.should.have.status(200);
+  res.text.should.startWith(subject);
+  done();
+});

should handle corrupted responses

request.get(`${base}/corrupt`).end((error, res) => {
+  assert(error, 'missing error');
+  assert(!res, 'response should not be defined');
+  done();
+});

should handle no content with gzip header

request.get(`${base}/nocontent`).end((error, res) => {
+  assert.ifError(error);
+  assert(res);
+  res.should.have.status(204);
+  res.text.should.equal('');
+  res.headers.should.not.have.property('content-length');
+  done();
+});

without encoding set

should buffer if asked

return request
+  .get(`${base}/binary`)
+  .buffer(true)
+  .then((res) => {
+    res.should.have.status(200);
+    assert(res.headers['content-length']);
+    assert(res.body.byteLength);
+    assert.equal(subject, res.body.toString());
+  });

should emit buffers

request.get(`${base}/binary`).end((error, res) => {
+  res.should.have.status(200);
+  res.headers['content-length'].should.be.below(subject.length);
+  res.on('data', (chunk) => {
+    chunk.should.have.length(subject.length);
+  });
+  res.on('end', done);
+});

req.lookup()

should set a custom lookup

const r = request.get(`${base}/ok`).lookup(myLookup);
+assert(r.lookup() === myLookup);
+r.then((res) => {
+  res.text.should.equal('ok');
+  done();
+});

Multipart

#field(name, value)

should set a multipart field value

const request_ = request.post(`${base}/echo`);
+request_.field('user[name]', 'tobi');
+request_.field('user[age]', '2');
+request_.field('user[species]', 'ferret');
+return request_.then((res) => {
+  res.body['user[name]'].should.equal('tobi');
+  res.body['user[age]'].should.equal('2');
+  res.body['user[species]'].should.equal('ferret');
+});

should work with file attachments

const request_ = request.post(`${base}/echo`);
+request_.field('name', 'Tobi');
+request_.attach('document', 'test/node/fixtures/user.html');
+request_.field('species', 'ferret');
+return request_.then((res) => {
+  res.body.name.should.equal('Tobi');
+  res.body.species.should.equal('ferret');
+  const html = res.files.document;
+  html.originalFilename.should.equal('user.html');
+  html.mimetype.should.equal('text/html');
+  read(html.filepath).should.equal('<h1>name</h1>');
+});

#attach(name, path)

should attach a file

const request_ = request.post(`${base}/echo`);
+request_.attach('one', 'test/node/fixtures/user.html');
+request_.attach('two', 'test/node/fixtures/user.json');
+request_.attach('three', 'test/node/fixtures/user.txt');
+return request_.then((res) => {
+  const html = res.files.one;
+  const json = res.files.two;
+  const text = res.files.three;
+  html.originalFilename.should.equal('user.html');
+  html.mimetype.should.equal('text/html');
+  read(html.filepath).should.equal('<h1>name</h1>');
+  json.originalFilename.should.equal('user.json');
+  json.mimetype.should.equal('application/json');
+  read(json.filepath).should.equal('{"name":"tobi"}');
+  text.originalFilename.should.equal('user.txt');
+  text.mimetype.should.equal('text/plain');
+  read(text.filepath).should.equal('Tobi');
+});

when a file does not exist

should fail the request with an error

const request_ = request.post(`${base}/echo`);
+request_.attach('name', 'foo');
+// request_.attach('name2', 'bar');
+// request_.attach('name3', 'baz');
+request_.end((error, res) => {
+  assert.ok(Boolean(error), 'Request should have failed.');
+  error.code.should.equal('ENOENT');
+  error.message.should.containEql('ENOENT');
+  if (IS_WINDOWS) {
+    error.path.toLowerCase().should.equal(
+      getFullPath('foo').toLowerCase()
+    );
+  } else {
+    error.path.should.equal(getFullPath('foo'));
+  }
+  done();
+});

promise should fail

return request
+  .post(`${base}/echo`)
+  .field({ a: 1, b: 2 })
+  .attach('c', 'does-not-exist.txt')
+  .then(
+    (res) => assert.fail('It should not allow this'),
+    (err) => {
+      err.code.should.equal('ENOENT');
+      if (IS_WINDOWS) {
+        err.path.toLowerCase().should.equal(
+          getFullPath('does-not-exist.txt').toLowerCase()
+        );
+      } else {
+        err.path.should.equal(getFullPath('does-not-exist.txt'));
+      }
+    }
+  );

should report ENOENT via the callback

request
+  .post(`${base}/echo`)
+  .attach('name', 'file-does-not-exist')
+  .end((error, res) => {
+    assert.ok(Boolean(error), 'Request should have failed');
+    error.code.should.equal('ENOENT');
+    done();
+  });

should report ENOENT via Promise

return request
+  .post(`${base}/echo`)
+  .attach('name', 'file-does-not-exist')
+  .then(
+    (res) => assert.fail('Request should have failed'),
+    (err) => err.code.should.equal('ENOENT')
+  );

#attach(name, path, filename)

should use the custom filename

request
+        .post(`${base}/echo`)
+        .attach('document', 'test/node/fixtures/user.html', 'doc.html')
+        .then((res) => {
+          const html = res.files.document;
+          html.originalFilename.should.equal('doc.html');
+          html.mimetype.should.equal('text/html');
+          read(html.filepath).should.equal('<h1>name</h1>');
+        })

should fire progress event

let loaded = 0;
+let total = 0;
+let uploadEventWasFired = false;
+request
+  .post(`${base}/echo`)
+  .attach('document', 'test/node/fixtures/user.html')
+  .on('progress', (event) => {
+    total = event.total;
+    loaded = event.loaded;
+    if (event.direction === 'upload') {
+      uploadEventWasFired = true;
+    }
+  })
+  .end((error, res) => {
+    if (error) return done(error);
+    const html = res.files.document;
+    html.originalFilename.should.equal('user.html');
+    html.mimetype.should.equal('text/html');
+    read(html.filepath).should.equal('<h1>name</h1>');
+    total.should.equal(223);
+    loaded.should.equal(223);
+    uploadEventWasFired.should.equal(true);
+    done();
+  });

filesystem errors should be caught

request
+  .post(`${base}/echo`)
+  .attach('filedata', 'test/node/fixtures/non-existent-file.ext')
+  .end((error, res) => {
+    assert.ok(Boolean(error), 'Request should have failed.');
+    error.code.should.equal('ENOENT');
+    if (IS_WINDOWS) {
+      error.path.toLowerCase().should.equal(
+        getFullPath('test/node/fixtures/non-existent-file.ext').toLowerCase()
+      );
+    } else {
+      error.path.should.equal(
+        getFullPath('test/node/fixtures/non-existent-file.ext')
+      );
+    }
+    done();
+  });

#field(name, val)

should set a multipart field value

request
+  .post(`${base}/echo`)
+  .field('first-name', 'foo')
+  .field('last-name', 'bar')
+  .end((error, res) => {
+    if (error) done(error);
+    res.should.be.ok();
+    res.body['first-name'].should.equal('foo');
+    res.body['last-name'].should.equal('bar');
+    done();
+  });

#field(object)

should set multiple multipart fields

request
+  .post(`${base}/echo`)
+  .field({ 'first-name': 'foo', 'last-name': 'bar' })
+  .end((error, res) => {
+    if (error) done(error);
+    res.should.be.ok();
+    res.body['first-name'].should.equal('foo');
+    res.body['last-name'].should.equal('bar');
+    done();
+  });

+ +

with network error

should error

request.get(`http://localhost:${this.port}/`).end((error, res) => {
+  assert(error, 'expected an error');
+  done();
+});

request

not modified

should start with 200

request.get(`${base}/if-mod`).end((error, res) => {
+  res.should.have.status(200);
+  res.text.should.match(/^\d+$/);
+  ts = Number(res.text);
+  done();
+});

should then be 304

request
+  .get(`${base}/if-mod`)
+  .set('If-Modified-Since', new Date(ts).toUTCString())
+  .end((error, res) => {
+    res.should.have.status(304);
+    // res.text.should.be.empty
+    done();
+  });

+ +

req.parse(fn)

should take precedence over default parsers

request
+  .get(`${base}/manny`)
+  .parse(request.parse['application/json'])
+  .end((error, res) => {
+    assert(res.ok);
+    assert.equal('{"name":"manny"}', res.text);
+    assert.equal('manny', res.body.name);
+    done();
+  });

should be the only parser

request
+      .get(`${base}/image`)
+      .buffer(false)
+      .parse((res, fn) => {
+        res.on('data', () => {});
+      })
+      .then((res) => {
+        assert(res.ok);
+        assert.strictEqual(res.text, undefined);
+        res.body.should.eql({});
+      })

should emit error if parser throws

request
+  .get(`${base}/manny`)
+  .parse(() => {
+    throw new Error('I am broken');
+  })
+  .on('error', (error) => {
+    error.message.should.equal('I am broken');
+    done();
+  })
+  .end();

should emit error if parser returns an error

request
+  .get(`${base}/manny`)
+  .parse((res, fn) => {
+    fn(new Error('I am broken'));
+  })
+  .on('error', (error) => {
+    error.message.should.equal('I am broken');
+    done();
+  })
+  .end();

pipe on redirect

should follow Location

const stream = fs.createWriteStream(destinationPath);
+const redirects = [];
+const request_ = request
+  .get(base)
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .connect({
+    inapplicable: 'should be ignored'
+  });
+stream.on('finish', () => {
+  redirects.should.eql(['/movies', '/movies/all', '/movies/all/0']);
+  fs.readFileSync(destinationPath, 'utf8').should.eql('first movie page');
+  done();
+});
+request_.pipe(stream);

request pipe

should act as a writable stream

const request_ = request.post(base);
+const stream = fs.createReadStream('test/node/fixtures/user.json');
+request_.type('json');
+request_.on('response', (res) => {
+  res.body.should.eql({ name: 'tobi' });
+  done();
+});
+stream.pipe(request_);

end() stops piping

const stream = fs.createWriteStream(destinationPath);
+request.get(base).end((error, res) => {
+  try {
+    res.pipe(stream);
+    return done(new Error('Did not prevent nonsense pipe'));
+  } catch {
+    /* expected error */
+  }
+  done();
+});

should act as a readable stream

const stream = fs.createWriteStream(destinationPath);
+let responseCalled = false;
+const request_ = request.get(base);
+request_.type('json');
+request_.on('response', (res) => {
+  res.status.should.eql(200);
+  responseCalled = true;
+});
+stream.on('finish', () => {
+  JSON.parse(fs.readFileSync(destinationPath)).should.eql({
+    name: 'tobi'
+  });
+  responseCalled.should.be.true();
+  done();
+});
+request_.pipe(stream);

should follow redirects

const stream = fs.createWriteStream(destinationPath);
+let responseCalled = false;
+const request_ = request.get(base + '/redirect');
+request_.type('json');
+request_.on('response', (res) => {
+  res.status.should.eql(200);
+  responseCalled = true;
+});
+stream.on('finish', () => {
+  JSON.parse(fs.readFileSync(destinationPath)).should.eql({
+    name: 'tobi'
+  });
+  responseCalled.should.be.true();
+  done();
+});
+request_.pipe(stream);

should not throw on bad redirects

const stream = fs.createWriteStream(destinationPath);
+let responseCalled = false;
+let errorCalled = false;
+const request_ = request.get(base + '/badRedirectNoLocation');
+request_.type('json');
+request_.on('response', (res) => {
+  responseCalled = true;
+});
+request_.on('error', (error) => {
+  error.message.should.eql('No location header for redirect');
+  errorCalled = true;
+  stream.end();
+});
+stream.on('finish', () => {
+  responseCalled.should.be.false();
+  errorCalled.should.be.true();
+  done();
+});
+request_.pipe(stream);

req.query(String)

should support passing in a string

request
+  .del(base)
+  .query('name=t%F6bi')
+  .end((error, res) => {
+    res.body.should.eql({ name: 't%F6bi' });
+    done();
+  });

should work with url query-string and string for query

request
+  .del(`${base}/?name=tobi`)
+  .query('age=2%20')
+  .end((error, res) => {
+    res.body.should.eql({ name: 'tobi', age: '2 ' });
+    done();
+  });

should support compound elements in a string

request
+  .del(base)
+  .query('name=t%F6bi&age=2')
+  .end((error, res) => {
+    res.body.should.eql({ name: 't%F6bi', age: '2' });
+    done();
+  });

should work when called multiple times with a string

request
+  .del(base)
+  .query('name=t%F6bi')
+  .query('age=2%F6')
+  .end((error, res) => {
+    res.body.should.eql({ name: 't%F6bi', age: '2%F6' });
+    done();
+  });

should work with normal `query` object and query string

request
+  .del(base)
+  .query('name=t%F6bi')
+  .query({ age: '2' })
+  .end((error, res) => {
+    res.body.should.eql({ name: 't%F6bi', age: '2' });
+    done();
+  });

should not encode raw backticks, but leave encoded ones as is

return Promise.all([
+  request
+    .get(`${base}/raw-query`)
+    .query('name=`t%60bi`&age`=2')
+    .then((res) => {
+      res.text.should.eql('name=`t%60bi`&age`=2');
+    }),
+  request.get(base + '/raw-query?`age%60`=2%60`').then((res) => {
+    res.text.should.eql('`age%60`=2%60`');
+  }),
+  request
+    .get(`${base}/raw-query`)
+    .query('name=`t%60bi`')
+    .query('age`=2')
+    .then((res) => {
+      res.text.should.eql('name=`t%60bi`&age`=2');
+    })
+]);

req.query(Object)

should construct the query-string

request
+  .del(base)
+  .query({ name: 'tobi' })
+  .query({ order: 'asc' })
+  .query({ limit: ['1', '2'] })
+  .end((error, res) => {
+    res.body.should.eql({ name: 'tobi', order: 'asc', limit: ['1', '2'] });
+    done();
+  });

should encode raw backticks

request
+  .get(`${base}/raw-query`)
+  .query({ name: '`tobi`' })
+  .query({ 'orde%60r': null })
+  .query({ '`limit`': ['%602`'] })
+  .end((error, res) => {
+    res.text.should.eql('name=%60tobi%60&orde%2560r&%60limit%60=%25602%60');
+    done();
+  });

should not error on dates

const date = new Date(0);
+request
+  .del(base)
+  .query({ at: date })
+  .end((error, res) => {
+    assert.equal(date.toISOString(), res.body.at);
+    done();
+  });

should work after setting header fields

request
+  .del(base)
+  .set('Foo', 'bar')
+  .set('Bar', 'baz')
+  .query({ name: 'tobi' })
+  .query({ order: 'asc' })
+  .query({ limit: ['1', '2'] })
+  .end((error, res) => {
+    res.body.should.eql({ name: 'tobi', order: 'asc', limit: ['1', '2'] });
+    done();
+  });

should append to the original query-string

request
+  .del(`${base}/?name=tobi`)
+  .query({ order: 'asc' })
+  .end((error, res) => {
+    res.body.should.eql({ name: 'tobi', order: 'asc' });
+    done();
+  });

should retain the original query-string

request.del(`${base}/?name=tobi`).end((error, res) => {
+  res.body.should.eql({ name: 'tobi' });
+  done();
+});

should keep only keys with null querystring values

request
+  .del(`${base}/url`)
+  .query({ nil: null })
+  .end((error, res) => {
+    res.text.should.equal('/url?nil');
+    done();
+  });

query-string should be sent on pipe

this.timeout(15_000);
+const request_ = request.put(`${base}/?name=tobi`);
+const stream = fs.createReadStream('test/node/fixtures/user.json');
+request_.on('response', (res) => {
+  res.body.should.eql({ name: 'tobi' });
+  done();
+});
+request_.on('error', (err) => {
+  done(err);
+});
+stream.on('error', function (err) {
+  done(err);
+});
+stream.pipe(request_);

request.get

on 301 redirect

should follow Location with a GET request

const request_ = request.get(`${base}/test-301`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  headers.host.should.eql(`localhost:${server2.address().port}`);
+  res.status.should.eql(200);
+  res.text.should.eql('GET');
+  done();
+});

on 302 redirect

should follow Location with a GET request

const request_ = request.get(`${base}/test-302`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  res.status.should.eql(200);
+  res.text.should.eql('GET');
+  done();
+});

on 303 redirect

should follow Location with a GET request

const request_ = request.get(`${base}/test-303`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  headers.host.should.eql(`localhost:${server2.address().port}`);
+  res.status.should.eql(200);
+  res.text.should.eql('GET');
+  done();
+});

on 307 redirect

should follow Location with a GET request

const request_ = request.get(`${base}/test-307`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  headers.host.should.eql(`localhost:${server2.address().port}`);
+  res.status.should.eql(200);
+  res.text.should.eql('GET');
+  done();
+});

on 308 redirect

should follow Location with a GET request

const request_ = request.get(`${base}/test-308`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  headers.host.should.eql(`localhost:${server2.address().port}`);
+  res.status.should.eql(200);
+  res.text.should.eql('GET');
+  done();
+});

+ +

request.post

on 301 redirect

should follow Location with a GET request

const request_ = request.post(`${base}/test-301`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  headers.host.should.eql(`localhost:${server2.address().port}`);
+  res.status.should.eql(200);
+  res.text.should.eql('GET');
+  done();
+});

on 302 redirect

should follow Location with a GET request

const request_ = request.post(`${base}/test-302`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  headers.host.should.eql(`localhost:${server2.address().port}`);
+  res.status.should.eql(200);
+  res.text.should.eql('GET');
+  done();
+});

on 303 redirect

should follow Location with a GET request

const request_ = request.post(`${base}/test-303`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  headers.host.should.eql(`localhost:${server2.address().port}`);
+  res.status.should.eql(200);
+  res.text.should.eql('GET');
+  done();
+});

on 307 redirect

should follow Location with a POST request

const request_ = request.post(`${base}/test-307`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  headers.host.should.eql(`localhost:${server2.address().port}`);
+  res.status.should.eql(200);
+  res.text.should.eql('POST');
+  done();
+});

on 308 redirect

should follow Location with a POST request

const request_ = request.post(`${base}/test-308`).redirects(1);
+request_.end((error, res) => {
+  const headers = request_.req.getHeaders
+    ? request_.req.getHeaders()
+    : request_.req._headers;
+  headers.host.should.eql(`localhost:${server2.address().port}`);
+  res.status.should.eql(200);
+  res.text.should.eql('POST');
+  done();
+});

+ +

request

on redirect

should merge cookies if agent is used

request
+  .agent()
+  .get(`${base}/cookie-redirect`)
+  .set('Cookie', 'orig=1; replaced=not')
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      assert(/orig=1/.test(res.text), 'orig=1/.test');
+      assert(/replaced=yes/.test(res.text), 'replaced=yes/.test');
+      assert(/from-redir=1/.test(res.text), 'from-redir=1');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should not merge cookies if agent is not used

request
+  .get(`${base}/cookie-redirect`)
+  .set('Cookie', 'orig=1; replaced=not')
+  .end((error, res) => {
+    try {
+      assert.ifError(error);
+      assert(/orig=1/.test(res.text), '/orig=1');
+      assert(/replaced=not/.test(res.text), '/replaced=not');
+      assert(!/replaced=yes/.test(res.text), '!/replaced=yes');
+      assert(!/from-redir/.test(res.text), '!/from-redir');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should have previously set cookie for subsquent requests when agent is used

const agent = request.agent();
+agent.get(`${base}/set-cookie`).end((error) => {
+  assert.ifError(error);
+  agent
+    .get(`${base}/show-cookies`)
+    .set({ Cookie: 'orig=1' })
+    .end((error, res) => {
+      try {
+        assert.ifError(error);
+        assert(/orig=1/.test(res.text), 'orig=1/.test');
+        assert(/persist=123/.test(res.text), 'persist=123');
+        done();
+      } catch (err) {
+        done(err);
+      }
+    });
+});

should follow Location

const redirects = [];
+request
+  .get(base)
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .end((error, res) => {
+    try {
+      const array = ['/movies', '/movies/all', '/movies/all/0'];
+      redirects.should.eql(array);
+      res.text.should.equal('first movie page');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should follow Location with IP override

const redirects = [];
+const url = URL.parse(base);
+return request
+  .get(`http://redir.example.com:${url.port || '80'}${url.pathname}`)
+  .connect({
+    '*': url.hostname
+  })
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .then((res) => {
+    const array = ['/movies', '/movies/all', '/movies/all/0'];
+    redirects.should.eql(array);
+    res.text.should.equal('first movie page');
+  });

should follow Location with IP:port override

const redirects = [];
+const url = URL.parse(base);
+return request
+  .get(`http://redir.example.com:9999${url.pathname}`)
+  .connect({
+    '*': { host: url.hostname, port: url.port || 80 }
+  })
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .then((res) => {
+    const array = ['/movies', '/movies/all', '/movies/all/0'];
+    redirects.should.eql(array);
+    res.text.should.equal('first movie page');
+  });

should not follow on HEAD by default

const redirects = [];
+return request
+  .head(base)
+  .ok(() => true)
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .then((res) => {
+    redirects.should.eql([]);
+    res.status.should.equal(302);
+  });

should follow on HEAD when redirects are set

const redirects = [];
+request
+  .head(base)
+  .redirects(10)
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .end((error, res) => {
+    try {
+      const array = [];
+      array.push('/movies', '/movies/all', '/movies/all/0');
+      redirects.should.eql(array);
+      assert(!res.text);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should remove Content-* fields

request
+  .post(`${base}/header`)
+  .type('txt')
+  .set('X-Foo', 'bar')
+  .set('X-Bar', 'baz')
+  .send('hey')
+  .end((error, res) => {
+    try {
+      assert(res.body);
+      res.body.should.have.property('x-foo', 'bar');
+      res.body.should.have.property('x-bar', 'baz');
+      res.body.should.not.have.property('content-type');
+      res.body.should.not.have.property('content-length');
+      res.body.should.not.have.property('transfer-encoding');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should retain cookies

request
+  .get(`${base}/header`)
+  .set('Cookie', 'foo=bar;')
+  .end((error, res) => {
+    try {
+      assert(res.body);
+      res.body.should.have.property('cookie', 'foo=bar;');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should not resend query parameters

const redirects = [];
+const query = [];
+request
+  .get(`${base}/?foo=bar`)
+  .on('redirect', (res) => {
+    query.push(res.headers.query);
+    redirects.push(res.headers.location);
+  })
+  .end((error, res) => {
+    try {
+      const array = [];
+      array.push('/movies', '/movies/all', '/movies/all/0');
+      redirects.should.eql(array);
+      res.text.should.equal('first movie page');
+      query.should.eql(['{"foo":"bar"}', '{}', '{}']);
+      res.headers.query.should.eql('{}');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should handle no location header

request.get(`${base}/bad-redirect`).end((error, res) => {
+  try {
+    error.message.should.equal('No location header for redirect');
+    done();
+  } catch (err) {
+    done(err);
+  }
+});

when relative

should redirect to a sibling path

const redirects = [];
+request
+  .get(`${base}/relative`)
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .end((error, res) => {
+    try {
+      redirects.should.eql(['tobi']);
+      res.text.should.equal('tobi');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

should redirect to a parent path

const redirects = [];
+request
+  .get(`${base}/relative/sub`)
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .end((error, res) => {
+    try {
+      redirects.should.eql(['../tobi']);
+      res.text.should.equal('tobi');
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

req.redirects(n)

should alter the default number of redirects to follow

const redirects = [];
+request
+  .get(base)
+  .redirects(2)
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .end((error, res) => {
+    try {
+      const array = [];
+      assert(res.redirect, 'res.redirect');
+      array.push('/movies', '/movies/all');
+      redirects.should.eql(array);
+      res.text.should.match(/Moved Temporarily|Found/);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  });

on POST

should redirect as GET

const redirects = [];
+return request
+  .post(`${base}/movie`)
+  .send({ name: 'Tobi' })
+  .redirects(2)
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .then((res) => {
+    redirects.should.eql(['/movies/all/0']);
+    res.text.should.equal('first movie page');
+  });

using multipart/form-data should redirect as GET

const redirects = [];
+request
+  .post(`${base}/movie`)
+  .type('form')
+  .field('name', 'Tobi')
+  .redirects(2)
+  .on('redirect', (res) => {
+    redirects.push(res.headers.location);
+  })
+  .then((res) => {
+    redirects.should.eql(['/movies/all/0']);
+    res.text.should.equal('first movie page');
+  });

+ +

response

should act as a readable stream

const request_ = request.get(base).buffer(false);
+request_.end((error, res) => {
+  if (error) return done(error);
+  let trackEndEvent = 0;
+  let trackCloseEvent = 0;
+  res.on('end', () => {
+    trackEndEvent++;
+    trackEndEvent.should.equal(1);
+    if (!process.env.HTTP2_TEST) {
+      trackCloseEvent.should.equal(0); // close should not have been called
+    }
+    done();
+  });
+  res.on('close', () => {
+    trackCloseEvent++;
+  });
+  setTimeout(() => {
+    (() => {
+      res.pause();
+    }).should.not.throw();
+    (() => {
+      res.resume();
+    }).should.not.throw();
+    (() => {
+      res.destroy();
+    }).should.not.throw();
+  }, 50);
+});

req.serialize(fn)

should take precedence over default parsers

request
+  .post(`${base}/echo`)
+  .send({ foo: 123 })
+  .serialize(() => '{"bar":456}')
+  .end((error, res) => {
+    assert.ifError(error);
+    assert.equal('{"bar":456}', res.text);
+    assert.equal(456, res.body.bar);
+    done();
+  });

res.toError()

should return an Error

request.get(base).end((err, res) => {
+  const error = res.toError();
+  assert.equal(error.status, 400);
+  assert.equal(error.method, 'GET');
+  assert.equal(error.path, '/');
+  assert.equal(error.message, 'cannot GET / (400)');
+  assert.equal(error.text, 'invalid json');
+  done();
+});

[unix-sockets] http

request

path: / (root)

request.get(`${base}/`).end((error, res) => {
+  assert(res.ok);
+  assert.strictEqual('root ok!', res.text);
+  done();
+});

path: /request/path

request.get(`${base}/request/path`).end((error, res) => {
+  assert(res.ok);
+  assert.strictEqual('request path ok!', res.text);
+  done();
+});

+ +

[unix-sockets] https

request

path: / (root)

request
+  .get(`${base}/`)
+  .ca(cacert)
+  .end((error, res) => {
+    assert.ifError(error);
+    assert(res.ok);
+    assert.strictEqual('root ok!', res.text);
+    done();
+  });

path: /request/path

request
+  .get(`${base}/request/path`)
+  .ca(cacert)
+  .end((error, res) => {
+    assert.ifError(error);
+    assert(res.ok);
+    assert.strictEqual('request path ok!', res.text);
+    done();
+  });

+ +

req.get()

should not set a default user-agent

request.get(`${base}/ua`).then((res) => {
+      assert(res.headers);
+      assert(!res.headers['user-agent']);
+    })

utils.type(str)

should return the mime type

utils
+  .type('application/json; charset=utf-8')
+  .should.equal('application/json');
+utils.type('application/json').should.equal('application/json');

utils.params(str)

should return the field parameters

const object = utils.params('application/json; charset=utf-8; foo  = bar');
+object.charset.should.equal('utf-8');
+object.foo.should.equal('bar');
+utils.params('application/json').should.eql({});

utils.parseLinks(str)

should parse links

const string_ =
+  '<https://api.github.com/repos/visionmedia/mocha/issues?page=2>; rel="next", <https://api.github.com/repos/visionmedia/mocha/issues?page=5>; rel="last"';
+const returnValue = utils.parseLinks(string_);
+returnValue.next.should.equal(
+  'https://api.github.com/repos/visionmedia/mocha/issues?page=2'
+);
+returnValue.last.should.equal(
+  'https://api.github.com/repos/visionmedia/mocha/issues?page=5'
+);

+-------------------|---------|----------|---------|---------|--------------------------------------- +File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s +-------------------|---------|----------|---------|---------|--------------------------------------- +All files | 93.42 | 83.3 | 89.67 | 93.92 | + src | 92.5 | 83.83 | 91.83 | 93.84 | + agent-base.js | 100 | 100 | 100 | 100 | + request-base.js | 91.01 | 83.9 | 94.28 | 93.06 | ...21,262,316,501,525-533,579,757,768 + response-base.js | 100 | 100 | 75 | 100 | + utils.js | 92.85 | 71.42 | 85.71 | 91.66 | 94-98 + src/node | 93.61 | 83.12 | 87.36 | 93.75 | + agent.js | 89.79 | 66.66 | 100 | 88.63 | 39,43,47,51,101 + http2wrapper.js | 96 | 82.6 | 89.47 | 96.26 | 14,83,185-186 + index.js | 93.36 | 83.63 | 89.47 | 93.66 | ...,977,1182-1186,1220-1221,1275,1301 + response.js | 90 | 83.33 | 55.55 | 89.79 | 78,86,94,120-121 + unzip.js | 100 | 92.85 | 100 | 100 | 47 + src/node/parsers | 97.61 | 75 | 100 | 97.61 | + image.js | 100 | 100 | 100 | 100 | + index.js | 100 | 100 | 100 | 100 | + json.js | 100 | 75 | 100 | 100 | 15 + text.js | 100 | 100 | 100 | 100 | + urlencoded.js | 90 | 100 | 100 | 90 | 17 +-------------------|---------|----------|---------|---------|--------------------------------------- +

SuperAgent

SuperAgent是轻量级的渐进式ajax API，具有灵活性、可读性和较低的学习曲线。它也适用于Node.js!

 request
+   .post('/api/pet')
+   .send({ name: 'Manny', species: 'cat' })
+   .set('X-API-Key', 'foobar')
+   .set('Accept', 'application/json')
+   .then(res => {
+      alert('yay got ' + JSON.stringify(res.body));
+   });
+

测试文档

English

下面的测试文档是用Mocha的"文档"报告器生成的，并直接反映了测试套件。这提供了额外的文档来源。

基本请求

可以通过调用 request 对象上的适当方法来发起请求，然后调用 .then() ( 或 .end() 或 await )发送请求。例如一个简单的 GET 请求：

 request
+   .get('/search')
+   .then(res => {
+      // res.body, res.headers, res.status
+   })
+   .catch(err => {
+      // err.message, err.response
+   });
+

HTTP 方法也可以作为字符串传递：
译者注：大小写皆可。

request('GET', '/search').then(success, failure);
+

旧式回调也受支持，但不推荐使用。您可以调用 .end() 代替 .then()：

request('GET', '/search').end(function(err, res){
+  if (res.ok) {}
+});
+

可以使用绝对 URL。在 Web 浏览器中，绝对 URL 仅在服务器实现 CORS 时才有效。

 request
+   .get('https://example.com/search')
+   .then(res => {
+
+   });
+

Node 客户端支持向 Unix 域套接字发出请求：

// pattern: https?+unix://SOCKET_PATH/REQUEST_PATH
+//在套接字路径中将 `%2F` 用作 `/`
+try {
+  const res = await request
+    .get('http+unix://%2Fabsolute%2Fpath%2Fto%2Funix.sock/search');
+  // res.body, res.headers, res.status
+} catch(err) {
+  // err.message, err.response
+}
+

DELETE__、__HEAD__、__PATCH__、__POST 和 PUT 请求也可以使用，只需更改方法名称：

request
+  .head('/favicon.ico')
+  .then(res => {
+
+  });
+

DELETE 也可以用 .del() 调用以与旧版 IE 兼容，其中 delete 是保留字。

HTTP 方法默认为 __GET__，因此如果您愿意，以下代码是有效的：

 request('/search', (err, res) => {
+
+ });
+

使用 HTTP/2

要使用 HTTP/2 协议（没有 HTTP/1.x 后备），请使用 .http2() 方法。

    const request = require('superagent');
+    const res = await request
+      .get('https://example.com/h2')
+      .http2();
+

设置请求头字段

设置请求头字段很简单，调用 .set() 时传入字段名称和值：

 request
+   .get('/search')
+   .set('API-Key', 'foobar')
+   .set('Accept', 'application/json')
+   .then(callback);
+

您还可以在一次调用中传入一个对象来设置多个字段：

 request
+   .get('/search')
+   .set({ 'API-Key': 'foobar', Accept: 'application/json' })
+   .then(callback);
+

`GET` 请求

.query() 方法接受对象，当与 GET 方法一起使用时将形成一个查询字符串。以下将产生路径 /search?query=Manny&range=1..5&order=desc。 +译者注：.query() 方法的参数不需要提前进行url编码。

 request
+   .get('/search')
+   .query({ query: 'Manny' })
+   .query({ range: '1..5' })
+   .query({ order: 'desc' })
+   .then(res => {
+
+   });
+

或传入单个对象：

request
+  .get('/search')
+  .query({ query: 'Manny', range: '1..5', order: 'desc' })
+  .then(res => {
+
+  });
+

.query() 方法也可以接受字符串。

  request
+    .get('/querystring')
+    .query('search=Manny&range=1..5')
+    .then(res => {
+
+    });
+

或者一个个加入：

  request
+    .get('/querystring')
+    .query('search=Manny')
+    .query('range=1..5')
+    .then(res => {
+
+    });
+

`HEAD` 请求

您还可以对 HEAD 请求使用 .query() 方法。以下将生成路径 /users?email=joe@smith.com。

  request
+    .head('/users')
+    .query({ email: 'joe@smith.com' })
+    .then(res => {
+
+    });
+

`POST` / `PUT` 请求

一个典型的 JSON POST 请求可能如下所示，我们适当地设置 Content-Type 请求头字段，并"写入"一些数据，在本例中只是一个 JSON 字符串。

  request.post('/user')
+    .set('Content-Type', 'application/json')
+    .send('{"name":"tj","pet":"tobi"}')
+    .then(callback)
+    .catch(errorCallback)
+

由于 JSON 无疑是最常见的，所以它是默认的！下面的例子与前面的例子是等价的。

  request.post('/user')
+    .send({ name: 'tj', pet: 'tobi' })
+    .then(callback, errorCallback)
+

或者调用多个 .send()：

  request.post('/user')
+    .send({ name: 'tj' })
+    .send({ pet: 'tobi' })
+    .then(callback, errorCallback)
+

默认情况下，发送字符串会将 Content-Type 设置为 application/x-www-form-urlencoded，多个调用将用 & 连接，这里产生 name=tj&pet=tobi：

  request.post('/user')
+    .send('name=tj')
+    .send('pet=tobi')
+    .then(callback, errorCallback);
+

SuperAgent 格式是可扩展的，但默认情况下支持 "json" 和 "form"。要将数据作为 application/x-www-form-urlencoded 发送，只需在调用 .type() 时传入 "form"，默认为 "json"。此 POST 请求的请求体将是 "name=tj&pet=tobi"。

  request.post('/user')
+    .type('form')
+    .send({ name: 'tj' })
+    .send({ pet: 'tobi' })
+    .then(callback, errorCallback)
+

还支持发送 FormData 对象。以下示例将 POST 请求由 id="myForm" 标识的 HTML 表单的内容：

  request.post('/user')
+    .send(new FormData(document.getElementById('myForm')))
+    .then(callback, errorCallback)
+

设置 `Content-Type`

显而易见的解决方案是使用 .set() 方法：

 request.post('/user')
+   .set('Content-Type', 'application/json')
+

.type() 方法也可以作为简写，接受带有类型/子类型的规范化 MIME 类型名称，或者只是扩展名，例如"xml"、"json"、"png"等：

 request.post('/user')
+   .type('application/json')
+
+ request.post('/user')
+   .type('json')
+
+ request.post('/user')
+   .type('png')
+

序列化请求体

SuperAgent 将自动序列化 JSON 和表单。您也可以为其他类型设置自动序列化：

request.serialize['application/xml'] = function (obj) {
+    return '从obj生成的字符串';
+};
+
+// 接下来，内容类型为 "application/xml" 的所有请求都将自动序列化
+

如果您想以自定义格式发送数据体(payload)，您可以根据每个请求将内置序列化替换为 .serialize() 方法：

request
+    .post('/user')
+    .send({foo: 'bar'})
+    .serialize(obj => {
+        return '从obj生成的字符串';
+    });
+

重试请求

如果请求暂时失败或可能是网络连接不稳定造成的失败，且当给定 .retry() 方法时，SuperAgent 将自动重试请求。

此方法有两个可选参数：重试次数（默认为 1）和回调函数。它在每次重试之前调用 callback(err, res) 。回调可以返回 true/false 以控制是否应重试请求（但始终应该用最大重试次数）。 + request + .get('https://example.com/search') + .retry(2) // 或者： + .retry(2, callback) // 二选一 + .then(finished); + .catch(failed);

.retry() 仅用于幂等请求（即到达服务器的多个请求不会导致重复购买等不良副作用）。

默认情况下会尝试所有请求方法（这意味着如果您不希望重试 POST 请求，则需要传递自定义的重试回调函数）。

默认情况下会重试以下状态代码：

408
413
429
500
502
503
504
521
522
524

默认情况下会重试以下错误代码：

'ETIMEDOUT'
'ECONNRESET'
'EADDRINUSE'
'ECONNREFUSED'
'EPIPE'
'ENOTFOUND'
'ENETUNREACH'
'EAI_AGAIN'

设置 Accept

与 .type() 方法类似，也可以通过简写方法 .accept() 设置 Accept 请求头。方便起见，其中还引用了 request.types，允许您将完整的规范化 MIME 类型名称指定为类型/子类型，或将扩展后缀形式指定为"xml"、"json"、"png"等：

 request.get('/user')
+   .accept('application/json')
+
+ request.get('/user')
+   .accept('json')
+
+ request.post('/user')
+   .accept('png')
+

Facebook 和 Accept JSON

如果您正在调用 Facebook 的 API，请务必在您的请求中发送 Accept: application/json 请求头。如果你不这样做，Facebook 会回复 Content-Type: text/javascript; charset=UTF-8，SuperAgent 将不会解析，因此 res.body 将是未定义的。您可以使用 req.accept('json') 或 req.header('Accept', 'application/json') 来执行此操作。有关详细信息，请参阅 issue 1078。

查询字符串(Query strings)

req.query(obj) 是一种可用于构建查询字符串的方法。例如在 POST 上增加 ?format=json&dest=/login：

request
+  .post('/')
+  .query({ format: 'json' })
+  .query({ dest: '/login' })
+  .send({ post: 'data', here: 'wahoo' })
+  .then(callback);
+

默认情况下，查询字符串不按任何特定顺序组装。可以使用 req.sortQuery() 启用 ASCIIbetically 排序的查询字符串。您还可以使用 req.sortQuery(myComparisonFn) 提供自定义排序比较函数。比较函数应该接受 2 个参数并返回一个负/零/正整数。

 // 默认顺序
+ request.get('/user')
+   .query('name=Nick')
+   .query('search=Manny')
+   .sortQuery()
+   .then(callback)
+
+ // 自定义排序函数
+ request.get('/user')
+   .query('name=Nick')
+   .query('search=Manny')
+   .sortQuery((a, b) => a.length - b.length)
+   .then(callback)
+

TLS 选项

在 Node.js 中，SuperAgent 支持配置 HTTPS 请求的方法：

.ca(): 将 CA 证书设置为信任
.cert(): 设置客户端证书链
.key(): 设置客户端私钥
.pfx(): 设置客户端 PFX 或 PKCS12 编码的私钥和证书链
.disableTLSCerts(): 不拒绝过期或无效的 TLS 证书。在内部设置 rejectUnauthorized=true。请注意，此方法允许中间人攻击。

有关更多信息，请参阅 Node.js https.request 文档。

var key = fs.readFileSync('key.pem'),
+    cert = fs.readFileSync('cert.pem');
+
+request
+  .post('/client-auth')
+  .key(key)
+  .cert(cert)
+  .then(callback);
+

var ca = fs.readFileSync('ca.cert.pem');
+
+request
+  .post('https://localhost/private-ca-server')
+  .ca(ca)
+  .then(res => {});
+

解析响应体

SuperAgent将为您解析已知的响应主体数据，目前支持application/x-www-form-urlencoded，application/json，以及multipart/form data。您可以设置自动解析其他响应主体数据：

//浏览器
+request.parse['application/xml'] = function (str) {
+    return {'object': '从str解析的'};
+};
+
+//node
+request.parse['application/xml'] = function (res, cb) {
+    //解析响应文本并在此处设置res.body
+
+    cb(null, res);
+};
+
+//接下来，将自动解析 'application/xml' 类型的响应
+

您可以使用 .buffer(true).parse(fn) 方法设置自定义解析器（优先于内置解析器）。如果未启用响应缓冲 (.buffer(false))，则将触发响应(response)事件而无需等待正文解析器完成，因此 response.body 将不可用。

JSON / Urlencoded

属性 res.body 是解析后的对象，例如，如果请求以 JSON 字符串 '{"user":{"name":"tobi"}}' 响应，则 res.body.user.name 将为 "tobi" .同样，"user[name]=tobi" 的 x-www-form-urlencoded 值将产生相同的结果。仅支持一级嵌套。如果您需要更复杂的数据，请改为发送 JSON。

通过重复的键发送数组。 .send({color: ['red','blue']}) 会发送 color=red&color=blue。如果您希望数组键的名称中包含 []，您必须自己添加它，因为 SuperAgent 不会自动添加它。

Multipart

Node 客户端通过 Formidable 模块支持 _multipart/form-data_。解析 multipart 响应时，对象 res.files 也可供您使用。例如，假设一个请求使用以下 multipart 请求体进行响应：

--whoop
+Content-Disposition: attachment; name="image"; filename="tobi.png"
+Content-Type: image/png
+
+... data here ...
+--whoop
+Content-Disposition: form-data; name="name"
+Content-Type: text/plain
+
+Tobi
+--whoop--
+

res.body.name的值将为 "Tobi"，并且 res.files.image 将作为包含磁盘路径、文件名和其他属性的 File 对象。

二进制数据

在浏览器中，您可以使用 .responseType('blob') 来请求处理二进制响应体。在 node.js 中运行时不需要此 API。此方法支持的参数值为

'blob' 赋值给 XmlHTTPRequest 的 responseType 属性
'arraybuffer' 赋值给 XmlHTTPRequest 的 responseType 属性

req.get('/binary.data')
+  .responseType('blob')
+  .then(res => {
+    // res.body 将是浏览器原生 Blob 类型
+  });
+

有关更多信息，请参阅 Mozilla 开发人员网络 xhr.responseType 文档。

响应属性

在 Response 对象上设置了许多有用的标志和属性，包括响应文本、解析的响应正文、响应头字段、状态标志等等。

响应文本

res.text 属性包含未解析的响应正文字符串。此属性始终存在于客户端 API 中，并且仅当默认情况下节点的 mime 类型与 "text/"、"/json" 或 "x-www-form-urlencoded" 匹配时。原因是为了节省内存，因为缓冲大型正文（例如 multipart 文件或图像）的文本效率极低。要强制缓冲，请参阅"缓冲响应"部分。

响应体

就像 SuperAgent 可以自动序列化请求数据一样，它也可以自动解析响应体。为 Content-Type 定义解析器时，会对其进行解析，默认情况下包括 "application/json" 和 "application/x-www-form-urlencoded"。然后可以通过 res.body 获得解析的对象。

响应头字段

res.header 包含已解析的响应头字段的对象，字段名称小写，就像 node 做的一样。例如 res.header['content-length']。

响应内容类型(Content-Type)

Content-Type 响应头是特殊情况，提供 res.type，它没有字符集（也可以有）。例如，"text/html; charset=utf8" 的 Content-Type 将提供 "text/html" 作为 res.type，然后 res.charset 属性将包含 "utf8"。

响应状态

响应状态标志有助于确定请求是否成功，以及其他有用的信息，使 SuperAgent 成为与 RESTful Web 服务交互的理想选择。这些标志当前定义为：

 var type = status / 100 | 0;
+
+ // status / class
+ res.status = status;
+ res.statusType = type;
+
+ // basics
+ res.info = 1 == type;
+ res.ok = 2 == type;
+ res.clientError = 4 == type;
+ res.serverError = 5 == type;
+ res.error = 4 == type || 5 == type;
+
+ // 语法糖
+ res.accepted = 202 == status;
+ res.noContent = 204 == status || 1223 == status;
+ res.badRequest = 400 == status;
+ res.unauthorized = 401 == status;
+ res.notAcceptable = 406 == status;
+ res.notFound = 404 == status;
+ res.forbidden = 403 == status;
+

中止请求

要中止请求，只需调用 req.abort() 方法。

超时设定

有时网络和服务器会 "卡住" 并且在接受请求后从不响应。设置超时以避免请求永远等待。

req.timeout({deadline:ms}) 或 req.timeout(ms)（其中 ms 是毫秒数 > 0）设置完成整个请求（包括所有上传、重定向、服务器处理时间）的最后期限。如果在这段时间内没有完全下载响应，则请求将被中止。
+
req.timeout({response:ms}) 设置等待第一个字节从服务器到达的最长时间，但它不限制整个下载需要多长时间。响应超时应该至少比服务器响应的时间长几秒钟，因为它还包括进行 DNS 查找、TCP/IP 和 TLS 连接的时间，以及上传请求数据的时间。
+

您应该同时使用 deadline 和 response 超时。通过这种方式，您可以使用较短的响应超时来快速检测无响应的网络，并使用较长的截止时间来为缓慢但可靠的网络上的下载留出时间。请注意，这两个计时器都限制了允许上传附件的时间。如果您要上传文件，请使用长超时。

request
+  .get('/big-file?network=slow')
+  .timeout({
+    response: 5000,  // 等待 5 秒让服务器开始发送
+    deadline: 60000, // 但允许文件用 1 分钟完成加载。
+  })
+  .then(res => {
+      /* 及时响应 */
+    }, err => {
+      if (err.timeout) { /* 超时! */ } else { /* 其他错误 */ }
+  });
+

超时错误有个 .timeout 属性。

验证

在 Node 和浏览器中都可以通过 .auth() 方法进行身份验证：

request
+  .get('http://local')
+  .auth('tobi', 'learnboost')
+  .then(callback);
+

在 Node 客户端中，基本身份验证可以在 URL 中写成 "user:pass"：

request.get('http://tobi:learnboost@local').then(callback);
+

默认情况下，仅使用基本(Basic)身份验证。在浏览器中，您可以添加 {type:'auto'} 以启用浏览器中内置的所有方法（Digest、NTLM 等）：

request.auth('digest', 'secret', {type:'auto'})
+

auth 方法还支持一种承载类型，以指定基于令牌的身份验证：

request.auth('my_token', { type: 'bearer' })
+

跟随重定向

默认情况下将跟随最多 5 个重定向，但是您可以使用 res.redirects(n) 方法指定它：

const response = await request.get('/some.png').redirects(2);
+

超出限制的重定向被视为错误。使用 .ok(res => res.status < 400) 将它们读取为成功响应。

全局状态代理程序

+ +

在 Node 中 SuperAgent 默认不保存 cookie，但您可以使用 .agent() 方法创建保存 cookie 的 SuperAgent 副本。每个副本都有一个单独的 cookie 储存器。

const agent = request.agent();
+agent
+  .post('/login')
+  .then(() => {
+    return agent.get('/cookied-page');
+  });
+

在浏览器中，cookie 由浏览器自动管理，因此 .agent() 不会隔离 cookie。

多个请求的默认选项

代理程序上调用的常规请求方法将用作该代理发出的所有请求的默认值。

const agent = request.agent()
+  .use(plugin)
+  .auth(shared);
+
+await agent.get('/with-plugin-and-auth'); // 带有插件和身份验证
+await agent.get('/also-with-plugin-and-auth'); // 也带有插件和身份验证
+

代理可以用来设置默认值的完整方法列表是：use、 on、 once、 set、 query、 type、 accept、 auth、 withCredentials、 sortQuery、 retry、 ok、 redirects、 timeout、 buffer、 serialize、 parse、 ca、 key、 pfx、 cert.

管道数据

Node 客户端允许您通过管道将数据传入和传出请求。请注意，使用 .pipe() 代替 .end()/.then() 方法。

管道文件的内容作为请求的例子：

const request = require('superagent');
+const fs = require('fs');
+
+const stream = fs.createReadStream('path/to/my.json');
+const req = request.post('/somewhere');
+req.type('json');
+stream.pipe(req);
+

请注意，当您通过管道发送请求时，superagent 使用分块传输编码发送管道数据，并非所有服务器（例如 Python WSGI 服务器）都支持。

或将响应传送到文件：

const stream = fs.createWriteStream('path/to/my.json');
+const req = request.get('/some.json');
+req.pipe(stream);
+

不能混合使用管道和回调函数或 promises。请注意，您不应尝试通过管道传输 .end() 或 Response 对象的结果：

// 别特么这么写：
+const stream = getAWritableStream();
+const req = request
+  .get('/some.json')
+  // BAD: 这会将无用信息管道传输到流中并以意想不到的方式失败
+  .end((err, this_does_not_work) => this_does_not_work.pipe(stream))
+const req = request
+  .get('/some.json')
+  .end()
+  // BAD: 这也不支持，调用 .end 之后调用 .pipe。
+  .pipe(nope_its_too_late);
+

在 superagent 的未来版本中，对 pipe() 的不当调用将失败。

多部分请求

SuperAgent 也非常适合构建它提供方法 .attach() 和 .field() 的多部分请求。

当您使用 .field() 或 .attach() 时，您不能使用 .send() 并且您不能设置 Content-Type（将为您设置正确的类型）。

附加文件

要发送文件，请使用 .attach(name, [file], [options])。您可以通过多次调用 .attach 来附加多个文件。参数是：

name — form 表单中的字段名。
file — 带有文件路径的字符串或 Blob/Buffer 对象。
options — （可选）自定义文件名的字符串或 {filename: string} 对象。在 Node 中也支持 {contentType: 'mime/type'}。在浏览器中创建一个具有适当类型的 Blob。

+
+ +

request
+  .post('/upload')
+  .attach('image1', 'path/to/felix.jpeg')
+  .attach('image2', imageBuffer, 'luna.jpeg')
+  .field('caption', 'My cats')
+  .then(callback);
+

字段值

与 HTML 中的表单字段非常相似，您可以使用 .field(name, value) 和 .field({name: value}) 设置字段值。假设您想上传一些带有您的姓名和电子邮件的图片，您的请求可能如下所示：

 request
+   .post('/upload')
+   .field('user[name]', 'Tobi')
+   .field('user[email]', 'tobi@learnboost.com')
+   .field('friends[]', ['loki', 'jane'])
+   .attach('image', 'path/to/tobi.png')
+   .then(callback);
+

压缩

node 客户端支持压缩过的响应，最重要的是，您无需执行任何操作！它就能用。

缓冲响应

要强制将响应主体缓冲为 res.text，您可以调用 req.buffer()。要取消对文本响应（例如 "text/plain"、"text/html" 等）的默认缓冲，您可以调用 req.buffer(false)。

当缓冲提供 res.buffered 标志时，您可以使用它在同一个回调中处理缓冲和非缓冲响应。

CORS

出于安全原因，浏览器将阻止跨域请求，除非服务器选择使用 CORS 标头。浏览器还会发出额外的 OPTIONS 请求来检查服务器允许哪些 HTTP 标头和方法。阅读有关 CORS 的更多信息。

.withCredentials() 方法支持从源发送 cookie，但仅当 Access-Control-Allow-Origin 不是通配符 ("*") 且 Access-Control-Allow-Credentials 为 "true" 时。

request
+  .get('https://api.example.com:4001/')
+  .withCredentials()
+  .then(res => {
+    assert.equal(200, res.status);
+    assert.equal('tobi', res.text);
+  })
+

错误处理

您的回调函数将始终传递两个参数：错误和响应。如果没有发生错误，第一个参数将为null：

request
+ .post('/upload')
+ .attach('image', 'path/to/tobi.png')
+ .then(res => {
+
+ });
+

还会触发"错误"事件，您可以监听：

request
+  .post('/upload')
+  .attach('image', 'path/to/tobi.png')
+  .on('error', handle)
+  .then(res => {
+
+  });
+

请注意，默认情况下，superagent 会考虑 4xx 和 5xx 响应（以及未处理的 3xx 响应）视为错误。例如，如果您收到 304 Not modified、403 Forbidden 或 500 Internal server 错误响应，则此状态信息将通过 err.status 提供。来自此类响应的错误还包含一个 err.response 字段，其中包含"响应属性"中提到的所有属性。该库以这种方式运行以处理需要成功响应并将 HTTP 错误状态代码视为错误的常见情况，同时仍允许围绕特定错误条件进行自定义逻辑。

网络故障、超时和其他不产生响应的错误将不包含 err.status 或 err.response 字段。

如果您希望处理 404 或其他 HTTP 错误响应，您可以查询 err.status 属性。当发生 HTTP 错误（4xx 或 5xx 响应）时， res.error 属性是一个 Error 对象，这允许您执行以下检查：

if (err && err.status === 404) {
+  alert('oh no ' + res.body.message);
+}
+else if (err) {
+  // 所有其他需要处理的错误类型
+}
+

或者，您可以使用 .ok(callback) 方法来确定响应是否为错误。 ok 函数的回调函数获得响应，如果响应应该被解释为成功，则返回 true。

request.get('/404')
+  .ok(res => res.status < 500)
+  .then(response => {
+    // 将 404 页面作为成功响应
+  })
+

进度跟踪

SuperAgent 在上传和下载大文件时触发 progress 事件。

request.post(url)
+  .attach('field_name', file)
+  .on('progress', event => {
+    /* event的值：
+    {
+      direction: "upload" or "download"
+      percent: 0 to 100 // 如果文件大小未知，可能会没有
+      total: // 总文件大小，可能没有
+      loaded: // 到目前为止下载或上传的字节数
+    } */
+  })
+  .then()
+

在本地主机上测试

强制连接特定 IP 地址

在 Node.js 中，可以忽略 DNS 解析并使用 .connect() 方法将所有请求定向到特定 IP 地址。例如，此请求将转到 localhost 而不是 example.com：

const res = await request.get("http://example.com").connect("127.0.0.1");
+

因为请求可能被重定向，所以可以指定多个主机名和多个 IP，以及一个特殊的 * 作为后备（注意：不支持其他通配符）。请求将保留其 Host 请求头的原始值。

const res = await request.get("http://redir.example.com:555")
+  .connect({
+    "redir.example.com": "127.0.0.1", // redir.example.com:555 将使用 127.0.0.1:555
+    "www.example.com": false, // 不覆盖这个；正常使用 DNS
+    "mapped.example.com": { host: "127.0.0.1", port: 8080}, // mapped.example.com:* 将使用 127.0.0.1:8080
+    "*": "proxy.example.com", // 所有其他请求都将发送到该主机
+  });
+

忽略本地主机上损坏/不安全的 HTTPS

在 Node.js 中，当 HTTPS 配置错误且不安全（例如，使用自签名证书而不指定自己的 .ca()）时，仍然可以通过调用 .trustLocalhost() 来允许对 localhost 的请求：

const res = await request.get("https://localhost").trustLocalhost()
+

与 .connect("127.0.0.1") 一起，这可用于强制将对任何域的 HTTPS 请求重新路由到 localhost。

忽略本地主机上损坏的 HTTPS 通常是安全的，因为环回接口不会暴露给不受信任的网络。信任 localhost 可能会成为未来的默认设置。使用 .trustLocalhost(false) 强制检查 127.0.0.1 的可靠性。

当向任何其他 IP 发出请求时，我们故意不支持禁用 HTTPS 安全性，因为这些选项最终被滥用为 HTTPS 问题的快速"修复"。您可以从 Let's Encrypt 获得免费的 HTTPS 证书或设置您自己的 CA (.ca(ca_public_pem)) 以使您的自签名证书受信任。

Promise 和生成器函数支持

SuperAgent 的请求是一个 "thenable" 对象(带有then方法的对象)，它与 JavaScript Promise 和 async/await 语法兼容。

const res = await request.get(url);
+

如果你使用 Promise，不要调用 .end() 或 .pipe()。任何使用 .then() 或 await 都会禁用所有其他使用请求的方式。像 co 这样的库或像 koa 这样的 web 框架可以在任何 SuperAgent 方法上 yield：

const req = request
+  .get('http://local')
+  .auth('tobi', 'learnboost');
+const res = yield req;
+

请注意，SuperAgent 期望全局 Promise 对象存在。您需要一个 polyfill 才能在 Internet Explorer 或 Node.js 0.10 中使用 Promise。

浏览器和 node 版本

SuperAgent 有两种实现：一种用于 Web 浏览器（使用 XHR），另一种用于 Node.JS（使用核心 http 模块）。默认情况下，Browserify 和 WebPack 将选择浏览器版本。

如果要使用 WebPack 为 Node.JS 编译代码，您必须在其配置中指定node target。

在 electron 中使用浏览器版本

Electron 开发人员报告说，如果您希望使用浏览器版本的 SuperAgent 而不是 Node 版本，您可以 require('superagent/superagent')。这样您的请求将显示在 Chrome 开发者工具的"网络(Network)"选项卡中。请注意，自动化测试套件未涵盖此环境，也未得到官方支持。

使用代理发送请求

可以使用另一个作者的 superagent-proxy 模块

翻译说明

文档全部内容都是根据原英文文档翻译的，译者也没水平，所以如果有错误还请指出

SuperAgent

SuperAgent is light-weight progressive ajax API crafted for flexibility, readability, and a low learning curve after being frustrated with many of the existing request APIs. It also works with Node.js!

     request
+       .post('/api/pet')
+       .send({ name: 'Manny', species: 'cat' })
+       .set('X-API-Key', 'foobar')
+       .set('Accept', 'application/json')
+       .then(res => {
+          alert('yay got ' + JSON.stringify(res.body));
+       });
+

Test documentation

中文文档

The following test documentation was generated with Mocha's "doc" reporter, and directly reflects the test suite. This provides an additional source of documentation.

Request basics

A request can be initiated by invoking the appropriate method on the request object, then calling .then() (or .end() or await) to send the request. For example a simple GET request:

     request
+       .get('/search')
+       .then(res => {
+          // res.body, res.headers, res.status
+       })
+       .catch(err => {
+          // err.message, err.response
+       });
+

HTTP method may also be passed as a string:

    request('GET', '/search').then(success, failure);
+

Old-style callbacks are also supported, but not recommended. Instead of .then() you can call .end():

    request('GET', '/search').end(function(err, res){
+      if (res.ok) {}
+    });
+

Absolute URLs can be used. In web browsers absolute URLs work only if the server implements CORS.

     request
+       .get('https://example.com/search')
+       .then(res => {
+
+       });
+

The Node client supports making requests to Unix Domain Sockets:

    // pattern: https?+unix://SOCKET_PATH/REQUEST_PATH
+    //          Use `%2F` as `/` in SOCKET_PATH
+    try {
+      const res = await request
+        .get('http+unix://%2Fabsolute%2Fpath%2Fto%2Funix.sock/search');
+      // res.body, res.headers, res.status
+    } catch(err) {
+      // err.message, err.response
+    }
+

DELETE, HEAD, PATCH, POST, and PUT requests can also be used, simply change the method name:

    request
+      .head('/favicon.ico')
+      .then(res => {
+
+      });
+

DELETE can be also called as .del() for compatibility with old IE where delete is a reserved word.

The HTTP method defaults to GET, so if you wish, the following is valid:

     request('/search', (err, res) => {
+
+     });
+

Using HTTP/2

To make a request using HTTP/2 protocol only (with no HTTP/1.x fallback), use the .http2() method.

    const request = require('superagent');
+    const res = await request
+      .get('https://example.com/h2')
+      .http2();
+

Setting header fields

Setting header fields is simple, invoke .set() with a field name and value:

     request
+       .get('/search')
+       .set('API-Key', 'foobar')
+       .set('Accept', 'application/json')
+       .then(callback);
+

You may also pass an object to set several fields in a single call:

     request
+       .get('/search')
+       .set({ 'API-Key': 'foobar', Accept: 'application/json' })
+       .then(callback);
+

`GET` requests

The .query() method accepts objects, which when used with the GET method will form a query-string. The following will produce the path /search?query=Manny&range=1..5&order=desc.

     request
+       .get('/search')
+       .query({ query: 'Manny' })
+       .query({ range: '1..5' })
+       .query({ order: 'desc' })
+       .then(res => {
+
+       });
+

Or as a single object:

    request
+      .get('/search')
+      .query({ query: 'Manny', range: '1..5', order: 'desc' })
+      .then(res => {
+
+      });
+

The .query() method accepts strings as well:

      request
+        .get('/querystring')
+        .query('search=Manny&range=1..5')
+        .then(res => {
+
+        });
+

Or joined:

      request
+        .get('/querystring')
+        .query('search=Manny')
+        .query('range=1..5')
+        .then(res => {
+
+        });
+

`HEAD` requests

You can also use the .query() method for HEAD requests. The following will produce the path /users?email=joe@smith.com.

      request
+        .head('/users')
+        .query({ email: 'joe@smith.com' })
+        .then(res => {
+
+        });
+

`POST` / `PUT` requests

A typical JSON POST request might look a little like the following, where we set the Content-Type header field appropriately, and "write" some data, in this case just a JSON string.

      request.post('/user')
+        .set('Content-Type', 'application/json')
+        .send('{"name":"tj","pet":"tobi"}')
+        .then(callback)
+        .catch(errorCallback)
+

Since JSON is undoubtedly the most common, it's the default! The following example is equivalent to the previous.

      request.post('/user')
+        .send({ name: 'tj', pet: 'tobi' })
+        .then(callback, errorCallback)
+

Or using multiple .send() calls:

      request.post('/user')
+        .send({ name: 'tj' })
+        .send({ pet: 'tobi' })
+        .then(callback, errorCallback)
+

By default sending strings will set the Content-Type to application/x-www-form-urlencoded, + multiple calls will be concatenated with &, here resulting in name=tj&pet=tobi:

      request.post('/user')
+        .send('name=tj')
+        .send('pet=tobi')
+        .then(callback, errorCallback);
+

SuperAgent formats are extensible, however by default "json" and "form" are supported. To send the data as application/x-www-form-urlencoded simply invoke .type() with "form", where the default is "json". This request will POST the body "name=tj&pet=tobi".

      request.post('/user')
+        .type('form')
+        .send({ name: 'tj' })
+        .send({ pet: 'tobi' })
+        .then(callback, errorCallback)
+

Sending a FormData object is also supported. The following example will POST the content of the HTML form identified by id="myForm":

      request.post('/user')
+        .send(new FormData(document.getElementById('myForm')))
+        .then(callback, errorCallback)
+

Setting the `Content-Type`

The obvious solution is to use the .set() method:

     request.post('/user')
+       .set('Content-Type', 'application/json')
+

As a short-hand the .type() method is also available, accepting +the canonicalized MIME type name complete with type/subtype, or +simply the extension name such as "xml", "json", "png", etc:

     request.post('/user')
+       .type('application/json')
+
+     request.post('/user')
+       .type('json')
+
+     request.post('/user')
+       .type('png')
+

Serializing request body

SuperAgent will automatically serialize JSON and forms. +You can setup automatic serialization for other types as well:

request.serialize['application/xml'] = function (obj) {
+    return 'string generated from obj';
+};
+
+// going forward, all requests with a Content-type of
+// 'application/xml' will be automatically serialized
+

If you want to send the payload in a custom format, you can replace +the built-in serialization with the .serialize() method on a per-request basis:

request
+    .post('/user')
+    .send({foo: 'bar'})
+    .serialize(obj => {
+        return 'string generated from obj';
+    });
+

Retrying requests

When given the .retry() method, SuperAgent will automatically retry requests, if they fail in a way that is transient or could be due to a flaky Internet connection.

This method has two optional arguments: number of retries (default 1) and a callback. It calls callback(err, res) before each retry. The callback may return true/false to control whether the request should be retried (but the maximum number of retries is always applied).

     request
+       .get('https://example.com/search')
+       .retry(2) // or:
+       .retry(2, callback)
+       .then(finished);
+       .catch(failed);
+

Use .retry() only with requests that are idempotent (i.e. multiple requests reaching the server won't cause undesirable side effects like duplicate purchases).

All request methods are tried by default (which means if you do not want POST requests to be retried, you will need to pass a custom retry callback).

By default the following status codes are retried:

408
413
429
500
502
503
504
521
522
524

By default the following error codes are retried:

'ETIMEDOUT'
'ECONNRESET'
'EADDRINUSE'
'ECONNREFUSED'
'EPIPE'
'ENOTFOUND'
'ENETUNREACH'
'EAI_AGAIN'

Setting Accept

In a similar fashion to the .type() method it is also possible to set the Accept header via the short hand method .accept(). Which references request.types as well allowing you to specify either the full canonicalized MIME type name as type/subtype, or the extension suffix form as "xml", "json", "png", etc. for convenience:

     request.get('/user')
+       .accept('application/json')
+
+     request.get('/user')
+       .accept('json')
+
+     request.post('/user')
+       .accept('png')
+

Facebook and Accept JSON

If you are calling Facebook's API, be sure to send an Accept: application/json header in your request. If you don't do this, Facebook will respond with Content-Type: text/javascript; charset=UTF-8, which SuperAgent will not parse and thus res.body will be undefined. You can do this with either req.accept('json') or req.set('Accept', 'application/json'). See issue 1078 for details.

Query strings

req.query(obj) is a method which may be used to build up a query-string. For example populating ?format=json&dest=/login on a POST:

    request
+      .post('/')
+      .query({ format: 'json' })
+      .query({ dest: '/login' })
+      .send({ post: 'data', here: 'wahoo' })
+      .then(callback);
+

By default the query string is not assembled in any particular order. An asciibetically-sorted query string can be enabled with req.sortQuery(). You may also provide a custom sorting comparison function with req.sortQuery(myComparisonFn). The comparison function should take 2 arguments and return a negative/zero/positive integer.

 // default order
+ request.get('/user')
+   .query('name=Nick')
+   .query('search=Manny')
+   .sortQuery()
+   .then(callback)
+
+ // customized sort function
+ request.get('/user')
+   .query('name=Nick')
+   .query('search=Manny')
+   .sortQuery((a, b) => a.length - b.length)
+   .then(callback)
+

TLS options

In Node.js SuperAgent supports methods to configure HTTPS requests:

.ca(): Set the CA certificate(s) to trust
.cert(): Set the client certificate chain(s)
.key(): Set the client private key(s)
.pfx(): Set the client PFX or PKCS12 encoded private key and certificate chain
.disableTLSCerts(): Does not reject expired or invalid TLS certs. Sets internally rejectUnauthorized=true. Be warned, this method allows MITM attacks.

For more information, see Node.js https.request docs.

var key = fs.readFileSync('key.pem'),
+    cert = fs.readFileSync('cert.pem');
+
+request
+  .post('/client-auth')
+  .key(key)
+  .cert(cert)
+  .then(callback);
+

var ca = fs.readFileSync('ca.cert.pem');
+
+request
+  .post('https://localhost/private-ca-server')
+  .ca(ca)
+  .then(res => {});
+

Parsing response bodies

SuperAgent will parse known response-body data for you, +currently supporting application/x-www-form-urlencoded, +application/json, and multipart/form-data. You can setup +automatic parsing for other response-body data as well:

//browser
+request.parse['application/xml'] = function (str) {
+    return {'object': 'parsed from str'};
+};
+
+//node
+request.parse['application/xml'] = function (res, cb) {
+    //parse response text and set res.body here
+
+    cb(null, res);
+};
+
+//going forward, responses of type 'application/xml'
+//will be parsed automatically
+

You can set a custom parser (that takes precedence over built-in parsers) with the .buffer(true).parse(fn) method. If response buffering is not enabled (.buffer(false)) then the response event will be emitted without waiting for the body parser to finish, so response.body won't be available.

JSON / Urlencoded

The property res.body is the parsed object, for example if a request responded with the JSON string '{"user":{"name":"tobi"}}', res.body.user.name would be "tobi". Likewise the x-www-form-urlencoded value of "user[name]=tobi" would yield the same result. Only one level of nesting is supported. If you need more complex data, send JSON instead.

Arrays are sent by repeating the key. .send({color: ['red','blue']}) sends color=red&color=blue. If you want the array keys to contain [] in their name, you must add it yourself, as SuperAgent doesn't add it automatically.

Multipart

The Node client supports multipart/form-data via the Formidable module. When parsing multipart responses, the object res.files is also available to you. Suppose for example a request responds with the following multipart body:

--whoop
+Content-Disposition: attachment; name="image"; filename="tobi.png"
+Content-Type: image/png
+
+... data here ...
+--whoop
+Content-Disposition: form-data; name="name"
+Content-Type: text/plain
+
+Tobi
+--whoop--
+

You would have the values res.body.name provided as "Tobi", and res.files.image as a File object containing the path on disk, filename, and other properties.

Binary

In browsers, you may use .responseType('blob') to request handling of binary response bodies. This API is unnecessary when running in node.js. The supported argument values for this method are

'blob' passed through to the XmlHTTPRequest responseType property
'arraybuffer' passed through to the XmlHTTPRequest responseType property

req.get('/binary.data')
+  .responseType('blob')
+  .then(res => {
+    // res.body will be a browser native Blob type here
+  });
+

For more information, see the Mozilla Developer Network xhr.responseType docs.

Response properties

Many helpful flags and properties are set on the Response object, ranging from the response text, parsed response body, header fields, status flags and more.

Response text

The res.text property contains the unparsed response body string. This property is always present for the client API, and only when the mime type matches "text/", "/json", or "x-www-form-urlencoded" by default for node. The reasoning is to conserve memory, as buffering text of large bodies such as multipart files or images is extremely inefficient. To force buffering see the "Buffering responses" section.

Response body

Much like SuperAgent can auto-serialize request data, it can also automatically parse it. When a parser is defined for the Content-Type, it is parsed, which by default includes "application/json" and "application/x-www-form-urlencoded". The parsed object is then available via res.body.

Response header fields

The res.header contains an object of parsed header fields, lowercasing field names much like node does. For example res.header['content-length'].

Response Content-Type

The Content-Type response header is special-cased, providing res.type, which is void of the charset (if any). For example the Content-Type of "text/html; charset=utf8" will provide "text/html" as res.type, and the res.charset property would then contain "utf8".

Response status

The response status flags help determine if the request was a success, among other useful information, making SuperAgent ideal for interacting with RESTful web services. These flags are currently defined as:

     var type = status / 100 | 0;
+
+     // status / class
+     res.status = status;
+     res.statusType = type;
+
+     // basics
+     res.info = 1 == type;
+     res.ok = 2 == type;
+     res.clientError = 4 == type;
+     res.serverError = 5 == type;
+     res.error = 4 == type || 5 == type;
+
+     // sugar
+     res.accepted = 202 == status;
+     res.noContent = 204 == status || 1223 == status;
+     res.badRequest = 400 == status;
+     res.unauthorized = 401 == status;
+     res.notAcceptable = 406 == status;
+     res.notFound = 404 == status;
+     res.forbidden = 403 == status;
+

Aborting requests

To abort requests simply invoke the req.abort() method.

Timeouts

Sometimes networks and servers get "stuck" and never respond after accepting a request. Set timeouts to avoid requests waiting forever.

req.timeout({deadline:ms}) or req.timeout(ms) (where ms is a number of milliseconds > 0) sets a deadline for the entire request (including all uploads, redirects, server processing time) to complete. If the response isn't fully downloaded within that time, the request will be aborted.
+
req.timeout({response:ms}) sets maximum time to wait for the first byte to arrive from the server, but it does not limit how long the entire download can take. Response timeout should be at least few seconds longer than just the time it takes the server to respond, because it also includes time to make DNS lookup, TCP/IP and TLS connections, and time to upload request data.
+

You should use both deadline and response timeouts. This way you can use a short response timeout to detect unresponsive networks quickly, and a long deadline to give time for downloads on slow, but reliable, networks. Note that both of these timers limit how long uploads of attached files are allowed to take. Use long timeouts if you're uploading files.

    request
+      .get('/big-file?network=slow')
+      .timeout({
+        response: 5000,  // Wait 5 seconds for the server to start sending,
+        deadline: 60000, // but allow 1 minute for the file to finish loading.
+      })
+      .then(res => {
+          /* responded in time */
+        }, err => {
+          if (err.timeout) { /* timed out! */ } else { /* other error */ }
+      });
+

Timeout errors have a .timeout property.

Authentication

In both Node and browsers auth available via the .auth() method:

    request
+      .get('http://local')
+      .auth('tobi', 'learnboost')
+      .then(callback);
+

In the Node client Basic auth can be in the URL as "user:pass":

    request.get('http://tobi:learnboost@local').then(callback);
+

By default only Basic auth is used. In browser you can add {type:'auto'} to enable all methods built-in in the browser (Digest, NTLM, etc.):

    request.auth('digest', 'secret', {type:'auto'})
+

The auth method also supports a type of bearer, to specify token-based authentication:

    request.auth('my_token', { type: 'bearer' })
+

Following redirects

By default up to 5 redirects will be followed, however you may specify this with the res.redirects(n) method:

    const response = await request.get('/some.png').redirects(2);
+

Redirects exceeding the limit are treated as errors. Use .ok(res => res.status < 400) to read them as successful responses.

Agents for global state

Saving cookies

In Node SuperAgent does not save cookies by default, but you can use the .agent() method to create a copy of SuperAgent that saves cookies. Each copy has a separate cookie jar.

    const agent = request.agent();
+    agent
+      .post('/login')
+      .then(() => {
+        return agent.get('/cookied-page');
+      });
+

In browsers cookies are managed automatically by the browser, so the .agent() does not isolate cookies.

Default options for multiple requests

Regular request methods called on the agent will be used as defaults for all requests made by that agent.

    const agent = request.agent()
+      .use(plugin)
+      .auth(shared);
+
+    await agent.get('/with-plugin-and-auth');
+    await agent.get('/also-with-plugin-and-auth');
+

The complete list of methods that the agent can use to set defaults is: use, on, once, set, query, type, accept, auth, withCredentials, sortQuery, retry, ok, redirects, timeout, buffer, serialize, parse, ca, key, pfx, cert.

Piping data

The Node client allows you to pipe data to and from the request. Please note that .pipe() is used instead of .end()/.then() methods.

For example piping a file's contents as the request:

    const request = require('superagent');
+    const fs = require('fs');
+
+    const stream = fs.createReadStream('path/to/my.json');
+    const req = request.post('/somewhere');
+    req.type('json');
+    stream.pipe(req);
+

Note that when you pipe to a request, superagent sends the piped data with chunked transfer encoding, which isn't supported by all servers (for instance, Python WSGI servers).

Or piping the response to a file:

    const stream = fs.createWriteStream('path/to/my.json');
+    const req = request.get('/some.json');
+    req.pipe(stream);
+

It's not possible to mix pipes and callbacks or promises. Note that you should NOT attempt to pipe the result of .end() or the Response object:

    // Don't do either of these:
+    const stream = getAWritableStream();
+    const req = request
+      .get('/some.json')
+      // BAD: this pipes garbage to the stream and fails in unexpected ways
+      .end((err, this_does_not_work) => this_does_not_work.pipe(stream))
+    const req = request
+      .get('/some.json')
+      .end()
+      // BAD: this is also unsupported, .pipe calls .end for you.
+      .pipe(nope_its_too_late);
+

In a future version of superagent, improper calls to pipe() will fail.

Multipart requests

SuperAgent is also great for building multipart requests for which it provides methods .attach() and .field().

When you use .field() or .attach() you can't use .send() and you must not set Content-Type (the correct type will be set for you).

Attaching files

To send a file use .attach(name, [file], [options]). You can attach multiple files by calling .attach multiple times. The arguments are:

name — field name in the form.
file — either string with file path or Blob/Buffer object.
options — (optional) either string with custom file name or {filename: string} object. In Node also {contentType: 'mime/type'} is supported. In browser create a Blob with an appropriate type instead.

+
+ +

    request
+      .post('/upload')
+      .attach('image1', 'path/to/felix.jpeg')
+      .attach('image2', imageBuffer, 'luna.jpeg')
+      .field('caption', 'My cats')
+      .then(callback);
+

Field values

Much like form fields in HTML, you can set field values with .field(name, value) and .field({name: value}). Suppose you want to upload a few images with your name and email, your request might look something like this:

     request
+       .post('/upload')
+       .field('user[name]', 'Tobi')
+       .field('user[email]', 'tobi@learnboost.com')
+       .field('friends[]', ['loki', 'jane'])
+       .attach('image', 'path/to/tobi.png')
+       .then(callback);
+

Compression

The node client supports compressed responses, best of all, you don't have to do anything! It just works.

Buffering responses

To force buffering of response bodies as res.text you may invoke req.buffer(). To undo the default of buffering for text responses such as "text/plain", "text/html" etc you may invoke req.buffer(false).

When buffered the res.buffered flag is provided, you may use this to handle both buffered and unbuffered responses in the same callback.

CORS

For security reasons, browsers will block cross-origin requests unless the server opts-in using CORS headers. Browsers will also make extra OPTIONS requests to check what HTTP headers and methods are allowed by the server. Read more about CORS.

The .withCredentials() method enables the ability to send cookies from the origin, however only when Access-Control-Allow-Origin is not a wildcard ("*"), and Access-Control-Allow-Credentials is "true".

    request
+      .get('https://api.example.com:4001/')
+      .withCredentials()
+      .then(res => {
+        assert.equal(200, res.status);
+        assert.equal('tobi', res.text);
+      })
+

Error handling

Your callback function will always be passed two arguments: error and response. If no error occurred, the first argument will be null:

    request
+     .post('/upload')
+     .attach('image', 'path/to/tobi.png')
+     .then(res => {
+
+     });
+

An "error" event is also emitted, with you can listen for:

    request
+      .post('/upload')
+      .attach('image', 'path/to/tobi.png')
+      .on('error', handle)
+      .then(res => {
+
+      });
+

Note that superagent considers 4xx and 5xx responses (as well as unhandled 3xx responses) errors by default. For example, if you get a 304 Not modified, 403 Forbidden or 500 Internal server error response, this status information will be available via err.status. Errors from such responses also contain an err.response field with all of the properties mentioned in "Response properties". The library behaves in this way to handle the common case of wanting success responses and treating HTTP error status codes as errors while still allowing for custom logic around specific error conditions.

Network failures, timeouts, and other errors that produce no response will contain no err.status or err.response fields.

If you wish to handle 404 or other HTTP error responses, you can query the err.status property. When an HTTP error occurs (4xx or 5xx response) the res.error property is an Error object, this allows you to perform checks such as:

    if (err && err.status === 404) {
+      alert('oh no ' + res.body.message);
+    }
+    else if (err) {
+      // all other error types we handle generically
+    }
+

Alternatively, you can use the .ok(callback) method to decide whether a response is an error or not. The callback to the ok function gets a response and returns true if the response should be interpreted as success.

    request.get('/404')
+      .ok(res => res.status < 500)
+      .then(response => {
+        // reads 404 page as a successful response
+      })
+

Progress tracking

SuperAgent fires progress events on upload and download of large files.

    request.post(url)
+      .attach('field_name', file)
+      .on('progress', event => {
+        /* the event is:
+        {
+          direction: "upload" or "download"
+          percent: 0 to 100 // may be missing if file size is unknown
+          total: // total file size, may be missing
+          loaded: // bytes downloaded or uploaded so far
+        } */
+      })
+      .then()
+

Testing on localhost

Forcing specific connection IP address

In Node.js it's possible to ignore DNS resolution and direct all requests to a specific IP address using .connect() method. For example, this request will go to localhost instead of example.com:

    const res = await request.get("http://example.com").connect("127.0.0.1");
+

Because the request may be redirected, it's possible to specify multiple hostnames and multiple IPs, as well as a special * as the fallback (note: other wildcards are not supported). The requests will keep their Host header with the original value. .connect(undefined) turns off the feature.

    const res = await request.get("http://redir.example.com:555")
+      .connect({
+        "redir.example.com": "127.0.0.1", // redir.example.com:555 will use 127.0.0.1:555
+        "www.example.com": false, // don't override this one; use DNS as normal
+        "mapped.example.com": { host: "127.0.0.1", port: 8080}, // mapped.example.com:* will use 127.0.0.1:8080
+        "*": "proxy.example.com", // all other requests will go to this host
+      });
+

Ignoring broken/insecure HTTPS on localhost

In Node.js, when HTTPS is misconfigured and insecure (e.g. using self-signed certificate without specifying own .ca()), it's still possible to permit requests to localhost by calling .trustLocalhost():

    const res = await request.get("https://localhost").trustLocalhost()
+

Together with .connect("127.0.0.1") this may be used to force HTTPS requests to any domain to be re-routed to localhost instead.

It's generally safe to ignore broken HTTPS on localhost, because the loopback interface is not exposed to untrusted networks. Trusting localhost may become the default in the future. Use .trustLocalhost(false) to force check of 127.0.0.1's authenticity.

We intentionally don't support disabling of HTTPS security when making requests to any other IP, because such options end up abused as a quick "fix" for HTTPS problems. You can get free HTTPS certificates from Let's Encrypt or set your own CA (.ca(ca_public_pem)) to make your self-signed certificates trusted.

Promise and Generator support

SuperAgent's request is a "thenable" object that's compatible with JavaScript promises and the async/await syntax.

    const res = await request.get(url);
+

If you're using promises, do not call .end() or .pipe(). Any use of .then() or await disables all other ways of using the request.

Libraries like co or a web framework like koa can yield on any SuperAgent method:

    const req = request
+      .get('http://local')
+      .auth('tobi', 'learnboost');
+    const res = yield req;
+

Note that SuperAgent expects the global Promise object to be present. You'll need to use v7 and a polyfill to use promises in Internet Explorer or Node.js 0.10.

We have dropped support in v8 for IE. You must add a polyfill for WeakRef and BigInt if you wish to support Opera 85, iOS Safari 12.2-12.5, for example using https://cdnjs.cloudflare.com/polyfill/:

<script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=WeakRef,BigInt"></script>
+

Browser and node versions

SuperAgent has two implementations: one for web browsers (using XHR) and one for Node.JS (using core http module). By default Browserify and WebPack will pick the browser version.

If want to use WebPack to compile code for Node.JS, you must specify node target in its configuration.

+ +

name

; rel="next", ; rel="last"'; - var ret = utils.parseLinks(str); - ret.next.should.equal('https://api.github.com/repos/visionmedia/mocha/issues?page=2'); - ret.last.should.equal('https://api.github.com/repos/visionmedia/mocha/issues?page=5'); - }) -}) + utils.type('application/json').should.equal('application/json'); + }); +}); + +describe('utils.params(str)', () => { + it('should return the field parameters', () => { + const object = utils.params('application/json; charset=utf-8; foo = bar'); + object.charset.should.equal('utf-8'); + object.foo.should.equal('bar'); + + utils.params('application/json').should.eql({}); + }); +}); + +describe('utils.parseLinks(str)', () => { + it('should parse links', () => { + const string_ = + '; rel="next", ; rel="last"'; + const returnValue = utils.parseLinks(string_); + returnValue.next.should.equal( + 'https://api.github.com/repos/visionmedia/mocha/issues?page=2' + ); + returnValue.last.should.equal( + 'https://api.github.com/repos/visionmedia/mocha/issues?page=5' + ); + }); +}); + +describe('utils.isGzipOrDeflateEncoding(res)', () => { + it('should return true when content encoding is gzip', () => { + utils.isGzipOrDeflateEncoding({ + headers: { + 'content-encoding': 'gzip', + }, + }).should.equal(true); + }); + it('should return true when content encoding is deflate', () => { + utils.isGzipOrDeflateEncoding({ + headers: { + 'content-encoding': 'deflate', + }, + }).should.equal(true); + }); + it('should return false when content encoding is bla', () => { + utils.isGzipOrDeflateEncoding({ + headers: { + 'content-encoding': 'bla', + }, + }).should.equal(false); + }); + + it('should return true when content encoding has a lot of spaces followed with gzip', () => { + utils.isGzipOrDeflateEncoding({ + headers: { + 'content-encoding': " " * 10**6 + " gzip", + }, + }).should.equal(false); + }); + + it('should return true when content encoding repeates it self', () => { + utils.isGzipOrDeflateEncoding({ + headers: { + 'content-encoding': "gzip deflate gzip deflate gzip deflate gzip deflate gzip deflate gzip deflate gzip deflate gzip deflate", + }, + }).should.equal(false); + }); + + it('should return true when content encoding repeates it self wuth a lot of spaces', () => { + utils.isGzipOrDeflateEncoding({ + headers: { + 'content-encoding': " gzip deflate gzip deflate gzip deflate gzip deflate gzip deflate gzip deflate", + }, + }).should.equal(false); + }); + + it('should return true when content encoding - nested patterns', () => { + utils.isGzipOrDeflateEncoding({ + headers: { + 'content-encoding': " " * 10**5 + ("gzip deflate " * 1000) + }, + }).should.equal(false); + }); + + +}); + +describe('utils.isBrotliEncoding(res)', () => { + it('should return true when content encoding is br', () => { + utils.isBrotliEncoding({ + headers: { + 'content-encoding': 'br', + }, + }).should.equal(true); + }); + it('should return false when content encoding is bla', () => { + utils.isBrotliEncoding({ + headers: { + 'content-encoding': 'bla', + }, + }).should.equal(false); + }); + + it('should return true when content encoding has a lot of spaces followed with br', () => { + utils.isBrotliEncoding({ + headers: { + 'content-encoding': " " * 10**6 + " br", + }, + }).should.equal(false); + }); + + it('should return true when content encoding repeates it self', () => { + utils.isBrotliEncoding({ + headers: { + 'content-encoding': " br br br br br br br br br br br br br br br br br br br br br br br br br br br br br br", + }, + }).should.equal(false); + }); + + it('should return true when content encoding repeates it self wuth a lot of spaces', () => { + utils.isBrotliEncoding({ + headers: { + 'content-encoding': "br br br br br br br br br br br br br br", + }, + }).should.equal(false); + }); + + it('should return true when content encoding - nested patterns', () => { + utils.isBrotliEncoding({ + headers: { + 'content-encoding': " " * 10**5 + ("br " * 1000) + }, + }).should.equal(false); + }); + +}); diff --git a/test/redirects.js b/test/redirects.js new file mode 100644 index 000000000..7cba5f46a --- /dev/null +++ b/test/redirects.js @@ -0,0 +1,141 @@ +const assert = require('assert'); + +const getSetup = require('./support/setup'); +const request = require('./support/client'); + +describe('request', function () { + let setup; + let base; + let isMSIE; + + before(async () => { + setup = await getSetup(); + base = setup.uri; + isMSIE = !setup.NODE && /Trident\//.test(navigator.userAgent); + }); + + this.timeout(20_000); + describe('on redirect', () => { + it('should retain header fields', (done) => { + request + .get(`${base}/header`) + .set('X-Foo', 'bar') + .end((error, res) => { + try { + assert(res.body); + res.body.should.have.property('x-foo', 'bar'); + done(); + } catch (err) { + done(err); + } + }); + }); + + it('should preserve timeout across redirects', (done) => { + request + .get(`${base}/movies/random`) + .timeout(250) + .end((error, res) => { + try { + assert(error instanceof Error, 'expected an error'); + error.should.have.property('timeout', 250); + done(); + } catch (err) { + done(err); + } + }); + }); + + it('should successfully redirect after retry on error', (done) => { + const id = Math.random() * 1_000_000 * Date.now(); + request + .get(`${base}/error/redirect/${id}`) + .retry(2) + .end((error, res) => { + assert(res.ok, 'response should be ok'); + assert(res.text, 'first movie page'); + done(); + }); + }); + + it('should preserve retries across redirects', (done) => { + const id = Math.random() * 1_000_000 * Date.now(); + request + .get(`${base}/error/redirect-error${id}`) + .retry(2) + .end((error, res) => { + assert(error, 'expected an error'); + assert.equal(2, error.retries, 'expected an error with .retries'); + assert.equal(500, error.status, 'expected an error status of 500'); + done(); + }); + }); + }); + + describe('on 303', () => { + it('should redirect with same method', (done) => { + request + .put(`${base}/redirect-303`) + .send({ msg: 'hello' }) + .redirects(1) + .on('redirect', (res) => { + res.headers.location.should.equal('/reply-method'); + }) + .end((error, res) => { + if (error) { + done(error); + return; + } + + res.text.should.equal('method=get'); + done(); + }); + }); + }); + + describe('on 307', () => { + it('should redirect with same method', (done) => { + if (isMSIE) return done(); // IE9 broken + + request + .put(`${base}/redirect-307`) + .send({ msg: 'hello' }) + .redirects(1) + .on('redirect', (res) => { + res.headers.location.should.equal('/reply-method'); + }) + .end((error, res) => { + if (error) { + done(error); + return; + } + + res.text.should.equal('method=put'); + done(); + }); + }); + }); + + describe('on 308', () => { + it('should redirect with same method', (done) => { + if (isMSIE) return done(); // IE9 broken + + request + .put(`${base}/redirect-308`) + .send({ msg: 'hello' }) + .redirects(1) + .on('redirect', (res) => { + res.headers.location.should.equal('/reply-method'); + }) + .end((error, res) => { + if (error) { + done(error); + return; + } + + res.text.should.equal('method=put'); + done(); + }); + }); + }); +}); diff --git a/test/request.js b/test/request.js new file mode 100644 index 000000000..e4ec3b739 --- /dev/null +++ b/test/request.js @@ -0,0 +1,991 @@ +const fs = require('fs'); + +const assert = require('assert'); +const getSetup = require('./support/setup'); + +const request = require('./support/client'); + +const binData = fs.readFileSync(`${__dirname}/node/fixtures/test.aac`); + +describe('request', function () { + let setup; + let uri; + + before(async () => { + setup = await getSetup(); + uri = setup.uri; + }); + + this.timeout(20_000); + + it('Request inheritance', () => { + assert(request.get(`${uri}/`) instanceof request.Request); + }); + + it('request() simple GET without callback', (next) => { + request('GET', 'test/test.request.js').end(); + next(); + }); + + it('request() simple GET', (next) => { + request('GET', `${uri}/ok`).end((error, res) => { + try { + assert(res instanceof request.Response, 'respond with Response'); + assert(res.ok, 'response should be ok'); + assert(res.text, 'res.text'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request() simple HEAD', (next) => { + request.head(`${uri}/ok`).end((error, res) => { + try { + assert(res instanceof request.Response, 'respond with Response'); + assert(res.ok, 'response should be ok'); + assert(!res.text, 'res.text'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request() GET 5xx', (next) => { + request('GET', `${uri}/error`).end((error, res) => { + try { + assert(error); + assert.equal(error.message, 'Internal Server Error'); + assert(!res.ok, 'response should not be ok'); + assert(res.error, 'response should be an error'); + assert(!res.clientError, 'response should not be a client error'); + assert(res.serverError, 'response should be a server error'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request() GET 4xx', (next) => { + request('GET', `${uri}/notfound`).end((error, res) => { + try { + assert(error); + assert.equal(error.message, 'Not Found'); + assert(!res.ok, 'response should not be ok'); + assert(res.error, 'response should be an error'); + assert(res.clientError, 'response should be a client error'); + assert(!res.serverError, 'response should not be a server error'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request() GET 404 Not Found', (next) => { + request('GET', `${uri}/notfound`).end((error, res) => { + try { + assert(error); + assert(res.notFound, 'response should be .notFound'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request() GET 400 Bad Request', (next) => { + request('GET', `${uri}/bad-request`).end((error, res) => { + try { + assert(error); + assert(res.badRequest, 'response should be .badRequest'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request() GET 401 Bad Request', (next) => { + request('GET', `${uri}/unauthorized`).end((error, res) => { + try { + assert(error); + assert(res.unauthorized, 'response should be .unauthorized'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request() GET 406 Not Acceptable', (next) => { + request('GET', `${uri}/not-acceptable`).end((error, res) => { + try { + assert(error); + assert(res.notAcceptable, 'response should be .notAcceptable'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request() GET 204 No Content', (next) => { + request('GET', `${uri}/no-content`).end((error, res) => { + try { + assert.ifError(error); + assert(res.noContent, 'response should be .noContent'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request() DELETE 204 No Content', (next) => { + request('DELETE', `${uri}/no-content`).end((error, res) => { + try { + assert.ifError(error); + assert(res.noContent, 'response should be .noContent'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request() header parsing', (next) => { + request('GET', `${uri}/notfound`).end((error, res) => { + try { + assert(error); + assert.equal('text/html; charset=utf-8', res.header['content-type']); + assert.equal('Express', res.header['x-powered-by']); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request() .status', (next) => { + request('GET', `${uri}/notfound`).end((error, res) => { + try { + assert(error); + assert.equal(404, res.status, 'response .status'); + assert.equal(4, res.statusType, 'response .statusType'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('get()', (next) => { + request.get(`${uri}/notfound`).end((error, res) => { + try { + assert(error); + assert.equal(404, res.status, 'response .status'); + assert.equal(4, res.statusType, 'response .statusType'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('put()', (next) => { + request.put(`${uri}/user/12`).end((error, res) => { + try { + assert.equal('updated', res.text, 'response text'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('put().send()', (next) => { + request + .put(`${uri}/user/13/body`) + .send({ user: 'new' }) + .end((error, res) => { + try { + assert.equal('received new', res.text, 'response text'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('post()', (next) => { + request.post(`${uri}/user`).end((error, res) => { + try { + assert.equal('created', res.text, 'response text'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('del()', (next) => { + request.del(`${uri}/user/12`).end((error, res) => { + try { + assert.equal('deleted', res.text, 'response text'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('delete()', (next) => { + request.delete(`${uri}/user/12`).end((error, res) => { + try { + assert.equal('deleted', res.text, 'response text'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('post() data', (next) => { + request + .post(`${uri}/todo/item`) + .type('application/octet-stream') + .send('tobi') + .end((error, res) => { + try { + assert.equal('added "tobi"', res.text, 'response text'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request .type()', (next) => { + request + .post(`${uri}/user/12/pet`) + .type('urlencoded') + .send('pet=tobi') + .end((error, res) => { + try { + assert.equal('added pet "tobi"', res.text, 'response text'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request .type() with alias', (next) => { + request + .post(`${uri}/user/12/pet`) + .type('application/x-www-form-urlencoded') + .send('pet=tobi') + .end((error, res) => { + try { + assert.equal('added pet "tobi"', res.text, 'response text'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request .get() with no data or callback', (next) => { + request.get(`${uri}/echo-header/content-type`); + next(); + }); + + it('request .send() with no data only', (next) => { + request.post(`${uri}/user/5/pet`).type('urlencoded').send('pet=tobi'); + next(); + }); + + it('request .send() with callback only', (next) => { + request + .get(`${uri}/echo-header/accept`) + .set('Accept', 'foo/bar') + .end((error, res) => { + try { + assert.equal('foo/bar', res.text); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request .accept() with json', (next) => { + request + .get(`${uri}/echo-header/accept`) + .accept('json') + .end((error, res) => { + try { + assert.equal('application/json', res.text); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request .accept() with application/json', (next) => { + request + .get(`${uri}/echo-header/accept`) + .accept('application/json') + .end((error, res) => { + try { + assert.equal('application/json', res.text); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request .accept() with xml', (next) => { + request + .get(`${uri}/echo-header/accept`) + .accept('xml') + .end((error, res) => { + try { + // We can't depend on mime module to be consistent with this + assert(res.text == 'application/xml' || res.text == 'text/xml'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request .accept() with application/xml', (next) => { + request + .get(`${uri}/echo-header/accept`) + .accept('application/xml') + .end((error, res) => { + try { + assert.equal('application/xml', res.text); + next(); + } catch (err) { + next(err); + } + }); + }); + + // FIXME: ie6 will POST rather than GET here due to data(), + // but I'm not 100% sure why. Newer IEs are OK. + it('request .end()', (next) => { + request + .put(`${uri}/echo-header/content-type`) + .set('Content-Type', 'text/plain') + .send('wahoo') + .end((error, res) => { + try { + assert.equal('text/plain', res.text); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request .send()', (next) => { + request + .put(`${uri}/echo-header/content-type`) + .set('Content-Type', 'text/plain') + .send('wahoo') + .end((error, res) => { + try { + assert.equal('text/plain', res.text); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request .set()', (next) => { + request + .put(`${uri}/echo-header/content-type`) + .set('Content-Type', 'text/plain') + .send('wahoo') + .end((error, res) => { + try { + assert.equal('text/plain', res.text); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request .set(object)', (next) => { + request + .put(`${uri}/echo-header/content-type`) + .set({ 'Content-Type': 'text/plain' }) + .send('wahoo') + .end((error, res) => { + try { + assert.equal('text/plain', res.text); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('POST urlencoded', (next) => { + request + .post(`${uri}/pet`) + .type('urlencoded') + .send({ name: 'Manny', species: 'cat' }) + .end((error, res) => { + try { + assert.equal('added Manny the cat', res.text); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('POST json', (next) => { + request + .post(`${uri}/pet`) + .type('json') + .send({ name: 'Manny', species: 'cat' }) + .end((error, res) => { + try { + assert.equal('added Manny the cat', res.text); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('POST json array', (next) => { + request + .post(`${uri}/echo`) + .send([1, 2, 3]) + .end((error, res) => { + try { + assert.equal( + 'application/json', + res.header['content-type'].split(';')[0] + ); + assert.equal('[1,2,3]', res.text); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('POST json default', (next) => { + request + .post(`${uri}/pet`) + .send({ name: 'Manny', species: 'cat' }) + .end((error, res) => { + try { + assert.equal('added Manny the cat', res.text); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('POST json contentType charset', (next) => { + request + .post(`${uri}/echo`) + .set('Content-Type', 'application/json; charset=UTF-8') + .send({ data: ['data1', 'data2'] }) + .end((error, res) => { + try { + assert.equal('{"data":["data1","data2"]}', res.text); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('POST json contentType vendor', (next) => { + request + .post(`${uri}/echo`) + .set('Content-Type', 'application/vnd.example+json') + .send({ data: ['data1', 'data2'] }) + .end((error, res) => { + try { + assert.equal('{"data":["data1","data2"]}', res.text); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('POST multiple .send() calls', (next) => { + request + .post(`${uri}/pet`) + .send({ name: 'Manny' }) + .send({ species: 'cat' }) + .end((error, res) => { + try { + assert.equal('added Manny the cat', res.text); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('POST multiple .send() strings', (next) => { + request + .post(`${uri}/echo`) + .send('user[name]=tj') + .send('user[email]=tj@vision-media.ca') + .end((error, res) => { + try { + assert.equal( + 'application/x-www-form-urlencoded', + res.header['content-type'].split(';')[0] + ); + assert.equal( + res.text, + 'user[name]=tj&user[email]=tj@vision-media.ca' + ); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('POST with no data', (next) => { + request + .post(`${uri}/empty-body`) + .send() + .end((error, res) => { + try { + assert.ifError(error); + assert(res.noContent, 'response should be .noContent'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('GET .type', (next) => { + request.get(`${uri}/pets`).end((error, res) => { + try { + assert.equal('application/json', res.type); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('GET Content-Type params', (next) => { + request.get(`${uri}/text`).end((error, res) => { + try { + assert.equal('utf-8', res.charset); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('GET json', (next) => { + request.get(`${uri}/pets`).end((error, res) => { + try { + assert.deepEqual(res.body, ['tobi', 'loki', 'jane']); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('GET json-seq', (next) => { + request + .get(`${uri}/json-seq`) + .buffer() + .end((error, res) => { + try { + assert.ifError(error); + assert.deepEqual(res.text, '\u001E{"id":1}\n\u001E{"id":2}\n'); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('GET binary data', (next) => { + request + .get(`${uri}/binary-data`) + .buffer() + .end((error, res) => { + try { + assert.ifError(error); + assert.deepEqual(res.body, binData); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('GET x-www-form-urlencoded', (next) => { + request.get(`${uri}/foo`).end((error, res) => { + try { + assert.deepEqual(res.body, { foo: 'bar' }); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('GET shorthand', (next) => { + request.get(`${uri}/foo`, (error, res) => { + try { + assert.equal('foo=bar', res.text); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('POST shorthand', (next) => { + request.post(`${uri}/user/0/pet`, { pet: 'tobi' }, (error, res) => { + try { + assert.equal('added pet "tobi"', res.text); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('POST shorthand without callback', (next) => { + request.post(`${uri}/user/0/pet`, { pet: 'tobi' }).end((error, res) => { + try { + assert.equal('added pet "tobi"', res.text); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('GET querystring object with array', (next) => { + request + .get(`${uri}/querystring`) + .query({ val: ['a', 'b', 'c'] }) + .end((error, res) => { + try { + assert.deepEqual(res.body, { val: ['a', 'b', 'c'] }); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('GET querystring object with array and primitives', (next) => { + request + .get(`${uri}/querystring`) + .query({ array: ['a', 'b', 'c'], string: 'foo', number: 10 }) + .end((error, res) => { + try { + assert.deepEqual(res.body, { + array: ['a', 'b', 'c'], + string: 'foo', + number: 10 + }); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('GET querystring object with two arrays', (next) => { + request + .get(`${uri}/querystring`) + .query({ array1: ['a', 'b', 'c'], array2: [1, 2, 3] }) + .end((error, res) => { + try { + assert.deepEqual(res.body, { + array1: ['a', 'b', 'c'], + array2: [1, 2, 3] + }); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('GET querystring object', (next) => { + request + .get(`${uri}/querystring`) + .query({ search: 'Manny' }) + .end((error, res) => { + try { + assert.deepEqual(res.body, { search: 'Manny' }); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('GET querystring append original', (next) => { + request + .get(`${uri}/querystring?search=Manny`) + .query({ range: '1..5' }) + .end((error, res) => { + try { + assert.deepEqual(res.body, { search: 'Manny', range: '1..5' }); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('GET querystring multiple objects', (next) => { + request + .get(`${uri}/querystring`) + .query({ search: 'Manny' }) + .query({ range: '1..5' }) + .query({ order: 'desc' }) + .end((error, res) => { + try { + assert.deepEqual(res.body, { + search: 'Manny', + range: '1..5', + order: 'desc' + }); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('GET querystring with strings', (next) => { + request + .get(`${uri}/querystring`) + .query('search=Manny') + .query('range=1..5') + .query('order=desc') + .end((error, res) => { + try { + assert.deepEqual(res.body, { + search: 'Manny', + range: '1..5', + order: 'desc' + }); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('GET querystring with strings and objects', (next) => { + request + .get(`${uri}/querystring`) + .query('search=Manny') + .query({ order: 'desc', range: '1..5' }) + .end((error, res) => { + try { + assert.deepEqual(res.body, { + search: 'Manny', + range: '1..5', + order: 'desc' + }); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('GET shorthand payload goes to querystring', (next) => { + request.get( + `${uri}/querystring`, + { foo: 'FOO', bar: 'BAR' }, + (error, res) => { + try { + assert.deepEqual(res.body, { foo: 'FOO', bar: 'BAR' }); + next(); + } catch (err) { + next(err); + } + } + ); + }); + + it('HEAD shorthand payload goes to querystring', (next) => { + request.head( + `${uri}/querystring-in-header`, + { foo: 'FOO', bar: 'BAR' }, + (error, res) => { + try { + assert.deepEqual(JSON.parse(res.headers.query), { + foo: 'FOO', + bar: 'BAR' + }); + next(); + } catch (err) { + next(err); + } + } + ); + }); + + it('request(method, url)', (next) => { + request('GET', `${uri}/foo`).end((error, res) => { + try { + assert.equal('bar', res.body.foo); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request(url)', (next) => { + request(`${uri}/foo`).end((error, res) => { + try { + assert.equal('bar', res.body.foo); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request(url, fn)', (next) => { + request(`${uri}/foo`, (error, res) => { + try { + assert.equal('bar', res.body.foo); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('req.timeout(ms)', (next) => { + const request_ = request.get(`${uri}/delay/3000`).timeout(1000); + request_.end((error, res) => { + try { + assert(error, 'error missing'); + assert.equal(1000, error.timeout, 'err.timeout missing'); + assert.equal( + 'Timeout of 1000ms exceeded', + error.message, + 'err.message incorrect' + ); + assert.equal(null, res); + assert(request_.timedout, true); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('req.timeout(ms) with redirect', (next) => { + const request_ = request.get(`${uri}/delay/const`).timeout(1000); + request_.end((error, res) => { + try { + assert(error, 'error missing'); + assert.equal(1000, error.timeout, 'err.timeout missing'); + assert.equal( + 'Timeout of 1000ms exceeded', + error.message, + 'err.message incorrect' + ); + assert.equal(null, res); + assert(request_.timedout, true); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('request event', (next) => { + request + .get(`${uri}/foo`) + .on('request', (request_) => { + try { + assert.equal(`${uri}/foo`, request_.url); + next(); + } catch (err) { + next(err); + } + }) + .end(); + }); + + it('response event', (next) => { + request + .get(`${uri}/foo`) + .on('response', (res) => { + try { + assert.equal('bar', res.body.foo); + next(); + } catch (err) { + next(err); + } + }) + .end(); + }); + + it('response should set statusCode', (next) => { + request.get(`${uri}/ok`, (error, res) => { + try { + assert.strictEqual(res.statusCode, 200); + next(); + } catch (err) { + next(err); + } + }); + }); + + it('req.toJSON()', (next) => { + request.get(`${uri}/ok`).end((error, res) => { + try { + const index = (res.request || res.req).toJSON(); + for (const property of ['url', 'method', 'data', 'headers']) { + assert(index.hasOwnProperty(property)); + } + + next(); + } catch (err) { + next(err); + } + }); + }); +}); diff --git a/test/retry.js b/test/retry.js new file mode 100644 index 000000000..52c023418 --- /dev/null +++ b/test/retry.js @@ -0,0 +1,295 @@ +const assert = require('assert'); +const getSetup = require('./support/setup'); + +const request = require('./support/client'); + +function uniqid() { + return Math.random() * 10_000_000; +} + +describe('.retry(count)', function () { + let setup; + let base; + + before(async () => { + setup = await getSetup(); + base = setup.uri; + }); + + this.timeout(15_000); + + it('should not retry if passed "0"', (done) => { + request + .get(`${base}/error`) + .retry(0) + .end((error, res) => { + try { + assert(error, 'expected an error'); + assert.equal( + undefined, + error.retries, + 'expected an error without .retries' + ); + assert.equal(500, error.status, 'expected an error status of 500'); + done(); + } catch (err) { + done(err); + } + }); + }); + + it('should not retry if passed an invalid number', (done) => { + request + .get(`${base}/error`) + .retry(-2) + .end((error, res) => { + try { + assert(error, 'expected an error'); + assert.equal( + undefined, + error.retries, + 'expected an error without .retries' + ); + assert.equal(500, error.status, 'expected an error status of 500'); + done(); + } catch (err) { + done(err); + } + }); + }); + + it('should not retry if passed undefined', (done) => { + request + .get(`${base}/error`) + .retry(undefined) + .end((error, res) => { + try { + assert(error, 'expected an error'); + assert.equal( + undefined, + error.retries, + 'expected an error without .retries' + ); + assert.equal(500, error.status, 'expected an error status of 500'); + done(); + } catch (err) { + done(err); + } + }); + }); + + it('should handle server error after repeat attempt', (done) => { + request + .get(`${base}/error`) + .retry(2) + .end((error, res) => { + try { + assert(error, 'expected an error'); + assert.equal(2, error.retries, 'expected an error with .retries'); + assert.equal(500, error.status, 'expected an error status of 500'); + done(); + } catch (err) { + done(err); + } + }); + }); + + it('should retry if passed nothing', (done) => { + request + .get(`${base}/error`) + .retry() + .end((error, res) => { + try { + assert(error, 'expected an error'); + assert.equal(1, error.retries, 'expected an error with .retries'); + assert.equal(500, error.status, 'expected an error status of 500'); + done(); + } catch (err) { + done(err); + } + }); + }); + + it('should retry if passed "true"', (done) => { + request + .get(`${base}/error`) + .retry(true) + .end((error, res) => { + try { + assert(error, 'expected an error'); + assert.equal(1, error.retries, 'expected an error with .retries'); + assert.equal(500, error.status, 'expected an error status of 500'); + done(); + } catch (err) { + done(err); + } + }); + }); + + it('should handle successful request after repeat attempt from server error', (done) => { + request + .get(`${base}/error/ok/${uniqid()}`) + .query({ qs: 'present' }) + .retry(2) + .end((error, res) => { + try { + assert.ifError(error); + assert(res.ok, 'response should be ok'); + assert(res.text, 'res.text'); + done(); + } catch (err) { + done(err); + } + }); + }); + + it('should handle server timeout error after repeat attempt', (done) => { + request + .get(`${base}/delay/400`) + .timeout(200) + .retry(2) + .end((error, res) => { + try { + assert(error, 'expected an error'); + assert.equal(2, error.retries, 'expected an error with .retries'); + assert.equal( + 'number', + typeof error.timeout, + 'expected an error with .timeout' + ); + assert.equal('ECONNABORTED', error.code, 'expected abort error code'); + done(); + } catch (err) { + done(err); + } + }); + }); + + it('should handle successful request after repeat attempt from server timeout', (done) => { + const url = `/delay/1200/ok/${uniqid()}?built=in`; + request + .get(base + url) + .query('string=ified') + .query({ json: 'ed' }) + .timeout(600) + .retry(2) + .end((error, res) => { + try { + assert.ifError(error); + assert(res.ok, 'response should be ok'); + assert.equal(res.text, `ok = ${url}&string=ified&json=ed`); + done(); + } catch (err) { + done(err); + } + }); + }); + + it('should handle successful request after repeat attempt from server timeout when using .then(fulfill, reject)', (done) => { + const url = `/delay/1200/ok/${uniqid()}?built=in`; + request + .get(base + url) + .query('string=ified') + .query({ json: 'ed' }) + .timeout(600) + .retry(1) + .then((res, error) => { + try { + assert.ifError(error); + assert(res.ok, 'response should be ok'); + assert.equal(res.text, `ok = ${url}&string=ified&json=ed`); + done(); + } catch (err) { + done(err); + } + }); + }); + + it('should correctly abort a retry attempt', (done) => { + let aborted = false; + const request_ = request.get(`${base}/delay/400`).timeout(200).retry(2); + request_.end((error, res) => { + try { + assert(false, 'should not complete the request'); + } catch (err) { + done(err); + } + }); + + request_.on('abort', () => { + aborted = true; + }); + + setTimeout(() => { + request_.abort(); + setTimeout(() => { + try { + assert(aborted, 'should be aborted'); + done(); + } catch (err) { + done(err); + } + }, 150); + }, 150); + }); + + it('should correctly retain header fields', (done) => { + request + .get(`${base}/error/ok/${uniqid()}`) + .query({ qs: 'present' }) + .retry(2) + .set('X-Foo', 'bar') + .end((error, res) => { + try { + assert.ifError(error); + assert(res.body); + res.body.should.have.property('x-foo', 'bar'); + done(); + } catch (err) { + done(err); + } + }); + }); + + it('should not retry on 4xx responses', (done) => { + request + .get(`${base}/bad-request`) + .retry(2) + .end((error, res) => { + try { + assert(error, 'expected an error'); + assert.equal(0, error.retries, 'expected an error with 0 .retries'); + assert.equal(400, error.status, 'expected an error status of 400'); + done(); + } catch (err) { + done(err); + } + }); + }); + + it('should execute callback on retry if passed', (done) => { + let callbackCallCount = 0; + function retryCallback(request) { + callbackCallCount++; + } + + request + .get(`${base}/error`) + .retry(2, retryCallback) + .end((error, res) => { + try { + assert(error, 'expected an error'); + assert.equal(2, error.retries, 'expected an error with .retries'); + assert.equal(500, error.status, 'expected an error status of 500'); + assert.equal( + 2, + callbackCallCount, + 'expected the callback to be called on each retry' + ); + done(); + } catch (err) { + done(err); + } + }); + }); +}); diff --git a/test/support/client.js b/test/support/client.js new file mode 100644 index 000000000..af843103e --- /dev/null +++ b/test/support/client.js @@ -0,0 +1,7 @@ +const request = require('../..'); + +if (process.env.HTTP2_TEST) { + request.http2 = true; +} + +exports = module.exports = request; diff --git a/test/support/express/index.js b/test/support/express/index.js new file mode 100644 index 000000000..fed7e8632 --- /dev/null +++ b/test/support/express/index.js @@ -0,0 +1,30 @@ +const process = require('process'); +const express = require('express'); + +let http2Request; +let http2Res; +if (process.env.HTTP2_TEST) { + const http2 = require('http2'); + const requestDecorator = require('./requestDecorator'); + const resDecorator = require('./responseDecorator'); + http2Request = requestDecorator( + Object.create(http2.Http2ServerRequest.prototype) + ); + http2Res = resDecorator(Object.create(http2.Http2ServerResponse.prototype)); +} + +function createApp() { + const app = express(); + if (process.env.HTTP2_TEST) { + app.request = Object.create(http2Request, { + app: { configurable: true, enumerable: true, writable: true, value: app } + }); + app.response = Object.create(http2Res, { + app: { configurable: true, enumerable: true, writable: true, value: app } + }); + } + + return app; +} + +module.exports = createApp; diff --git a/test/support/express/requestDecorator.js b/test/support/express/requestDecorator.js new file mode 100644 index 000000000..196406b9c --- /dev/null +++ b/test/support/express/requestDecorator.js @@ -0,0 +1,502 @@ +/*! + * express + * Copyright(c) 2009-2013 TJ Holowaychuk + * Copyright(c) 2013 Roman Shtylman + * Copyright(c) 2014-2015 Douglas Christopher Wilson + * MIT Licensed + */ + +'use strict'; + +/** + * Module dependencies. + * @private + */ + +const { isIP } = require('net'); +const accepts = require('accepts'); +const typeis = require('type-is'); +const fresh = require('fresh'); +const parseRange = require('range-parser'); +const parse = require('parseurl'); +const proxyaddr = require('proxy-addr'); + +/** + * Request prototype. + * @public + */ + +/** + * Module exports. + * @public + */ + +module.exports = setMethods; + +function setMethods(request) { + /** + * Return request header. + * + * The `Referrer` header field is special-cased, + * both `Referrer` and `Referer` are interchangeable. + * + * Examples: + * + * req.get('Content-Type'); + * // => "text/plain" + * + * req.get('content-type'); + * // => "text/plain" + * + * req.get('Something'); + * // => undefined + * + * Aliased as `req.header()`. + * + * @param {String} name + * @return {String} + * @public + */ + + request.get = request.header = function header(name) { + if (!name) { + throw new TypeError('name argument is required to req.get'); + } + + if (typeof name !== 'string') { + throw new TypeError('name must be a string to req.get'); + } + + const lc = name.toLowerCase(); + + switch (lc) { + case 'referer': + case 'referrer': + return this.headers.referrer || this.headers.referer; + default: + return this.headers[lc]; + } + }; + + /** + * To do: update docs. + * + * Check if the given `type(s)` is acceptable, returning + * the best match when true, otherwise `undefined`, in which + * case you should respond with 406 "Not Acceptable". + * + * The `type` value may be a single MIME type string + * such as "application/json", an extension name + * such as "json", a comma-delimited list such as "json, html, text/plain", + * an argument list such as `"json", "html", "text/plain"`, + * or an array `["json", "html", "text/plain"]`. When a list + * or array is given, the _best_ match, if any is returned. + * + * Examples: + * + * // Accept: text/html + * req.accepts('html'); + * // => "html" + * + * // Accept: text/*, application/json + * req.accepts('html'); + * // => "html" + * req.accepts('text/html'); + * // => "text/html" + * req.accepts('json, text'); + * // => "json" + * req.accepts('application/json'); + * // => "application/json" + * + * // Accept: text/*, application/json + * req.accepts('image/png'); + * req.accepts('png'); + * // => undefined + * + * // Accept: text/*;q=.5, application/json + * req.accepts(['html', 'json']); + * req.accepts('html', 'json'); + * req.accepts('html, json'); + * // => "json" + * + * @param {String|Array} type(s) + * @return {String|Array|Boolean} + * @public + */ + + request.accepts = function () { + const accept = accepts(this); + return accept.types.apply(accept, arguments); + }; + + /** + * Check if the given `encoding`s are accepted. + * + * @param {String} ...encoding + * @return {String|Array} + * @public + */ + + request.acceptsEncodings = function () { + const accept = accepts(this); + return accept.encodings.apply(accept, arguments); + }; + + /** + * Check if the given `charset`s are acceptable, + * otherwise you should respond with 406 "Not Acceptable". + * + * @param {String} ...charset + * @return {String|Array} + * @public + */ + + request.acceptsCharsets = function () { + const accept = accepts(this); + return accept.charsets.apply(accept, arguments); + }; + + /** + * Check if the given `lang`s are acceptable, + * otherwise you should respond with 406 "Not Acceptable". + * + * @param {String} ...lang + * @return {String|Array} + * @public + */ + + request.acceptsLanguages = function () { + const accept = accepts(this); + return accept.languages.apply(accept, arguments); + }; + + /** + * Parse Range header field, capping to the given `size`. + * + * Unspecified ranges such as "0-" require knowledge of your resource length. In + * the case of a byte range this is of course the total number of bytes. If the + * Range header field is not given `undefined` is returned, `-1` when unsatisfiable, + * and `-2` when syntactically invalid. + * + * When ranges are returned, the array has a "type" property which is the type of + * range that is required (most commonly, "bytes"). Each array element is an object + * with a "start" and "end" property for the portion of the range. + * + * The "combine" option can be set to `true` and overlapping & adjacent ranges + * will be combined into a single range. + * + * NOTE: remember that ranges are inclusive, so for example "Range: users=0-3" + * should respond with 4 users when available, not 3. + * + * @param {number} size + * @param {object} [options] + * @param {boolean} [options.combine=false] + * @return {number|array} + * @public + */ + + request.range = function range(size, options) { + const range = this.get('Range'); + if (!range) return; + return parseRange(size, range, options); + }; + + /** + * Parse the query string of `req.url`. + * + * This uses the "query parser" setting to parse the raw + * string into an object. + * + * @return {String} + * @api public + */ + + defineGetter(request, 'query', function query() { + const queryparse = this.app.get('query parser fn'); + + if (!queryparse) { + // parsing is disabled + return Object.create(null); + } + + const querystring = parse(this).query; + + return queryparse(querystring); + }); + + /** + * Check if the incoming request contains the "Content-Type" + * header field, and it contains the give mime `type`. + * + * Examples: + * + * // With Content-Type: text/html; charset=utf-8 + * req.is('html'); + * req.is('text/html'); + * req.is('text/*'); + * // => true + * + * // When Content-Type is application/json + * req.is('json'); + * req.is('application/json'); + * req.is('application/*'); + * // => true + * + * req.is('html'); + * // => false + * + * @param {String|Array} types... + * @return {String|false|null} + * @public + */ + + request.is = function is(types) { + let array = types; + + // support flattened arguments + if (!Array.isArray(types)) { + array = Array.from({ length: arguments.length }); + for (let i = 0; i < array.length; i++) { + array[i] = arguments[i]; + } + } + + return typeis(this, array); + }; + + /** + * Return the protocol string "http" or "https" + * when requested with TLS. When the "trust proxy" + * setting trusts the socket address, the + * "X-Forwarded-Proto" header field will be trusted + * and used if present. + * + * If you're running behind a reverse proxy that + * supplies https for you this may be enabled. + * + * @return {String} + * @public + */ + + defineGetter(request, 'protocol', function protocol() { + const proto = this.connection.encrypted ? 'https' : 'http'; + const trust = this.app.get('trust proxy fn'); + + if (!trust(this.connection.remoteAddress, 0)) { + return proto; + } + + // Note: X-Forwarded-Proto is normally only ever a + // single value, but this is to be safe. + const header = this.get('X-Forwarded-Proto') || proto; + const index = header.indexOf(','); + + return index !== -1 ? header.slice(0, index).trim() : header.trim(); + }); + + /** + * Short-hand for: + * + * req.protocol === 'https' + * + * @return {Boolean} + * @public + */ + + defineGetter(request, 'secure', function secure() { + return this.protocol === 'https'; + }); + + /** + * Return the remote address from the trusted proxy. + * + * The is the remote address on the socket unless + * "trust proxy" is set. + * + * @return {String} + * @public + */ + + defineGetter(request, 'ip', function ip() { + const trust = this.app.get('trust proxy fn'); + return proxyaddr(this, trust); + }); + + /** + * When "trust proxy" is set, trusted proxy addresses + client. + * + * For example if the value were "client, proxy1, proxy2" + * you would receive the array `["client", "proxy1", "proxy2"]` + * where "proxy2" is the furthest down-stream and "proxy1" and + * "proxy2" were trusted. + * + * @return {Array} + * @public + */ + + defineGetter(request, 'ips', function ips() { + const trust = this.app.get('trust proxy fn'); + const addrs = proxyaddr.all(this, trust); + + // reverse the order (to farthest -> closest) + // and remove socket address + addrs.reverse().pop(); + + return addrs; + }); + + /** + * Return subdomains as an array. + * + * Subdomains are the dot-separated parts of the host before the main domain of + * the app. By default, the domain of the app is assumed to be the last two + * parts of the host. This can be changed by setting "subdomain offset". + * + * For example, if the domain is "tobi.ferrets.example.com": + * If "subdomain offset" is not set, req.subdomains is `["ferrets", "tobi"]`. + * If "subdomain offset" is 3, req.subdomains is `["tobi"]`. + * + * @return {Array} + * @public + */ + + defineGetter(request, 'subdomains', function subdomains() { + const { hostname } = this; + + if (!hostname) return []; + + const offset = this.app.get('subdomain offset'); + const subdomains = !isIP(hostname) + ? hostname.split('.').reverse() + : [hostname]; + + return subdomains.slice(offset); + }); + + /** + * Short-hand for `url.parse(req.url).pathname`. + * + * @return {String} + * @public + */ + + defineGetter(request, 'path', function path() { + return parse(this).pathname; + }); + + /** + * Parse the "Host" header field to a host. + * + * When the "trust proxy" setting trusts the socket + * address, the "X-Forwarded-Host" header field will + * be trusted. + * + * @return {String} + * @public + */ + + defineGetter(request, 'host', function host() { + const trust = this.app.get('trust proxy fn'); + let value = this.get('X-Forwarded-Host'); + + if (!value || !trust(this.connection.remoteAddress, 0)) { + value = this.get('Host'); + } + + return value || undefined; + }); + + /** + * Parse the "Host" header field to a hostname. + * + * When the "trust proxy" setting trusts the socket + * address, the "X-Forwarded-Host" header field will + * be trusted. + * + * @return {String} + * @api public + */ + + defineGetter(request, 'hostname', function hostname() { + const { host } = this; + + if (!host) return; + + // IPv6 literal support + const offset = host[0] === '[' ? host.indexOf(']') + 1 : 0; + const index = host.indexOf(':', offset); + + return index !== -1 ? host.slice(0, index) : host; + }); + + /** + * Check if the request is fresh, aka + * Last-Modified and/or the ETag + * still match. + * + * @return {Boolean} + * @public + */ + + defineGetter(request, 'fresh', function () { + const { method } = this; + const { res } = this; + const status = res.statusCode; + + // GET or HEAD for weak freshness validation only + if (method !== 'GET' && method !== 'HEAD') return false; + + // 2xx or 304 as per rfc2616 14.26 + if ((status >= 200 && status < 300) || status === 304) { + return fresh(this.headers, { + etag: res.get('ETag'), + 'last-modified': res.get('Last-Modified') + }); + } + + return false; + }); + + /** + * Check if the request is stale, aka + * "Last-Modified" and / or the "ETag" for the + * resource has changed. + * + * @return {Boolean} + * @public + */ + + defineGetter(request, 'stale', function stale() { + return !this.fresh; + }); + + /** + * Check if the request was an _XMLHttpRequest_. + * + * @return {Boolean} + * @public + */ + + defineGetter(request, 'xhr', function xhr() { + const value = this.get('X-Requested-With') || ''; + return value.toLowerCase() === 'xmlhttprequest'; + }); + + return request; +} + +/** + * Helper function for creating a getter on an object. + * + * @param {Object} obj + * @param {String} name + * @param {Function} getter + * @private + */ +function defineGetter(object, name, getter) { + Object.defineProperty(object, name, { + configurable: true, + enumerable: true, + get: getter + }); +} diff --git a/test/support/express/responseDecorator.js b/test/support/express/responseDecorator.js new file mode 100644 index 000000000..26535e879 --- /dev/null +++ b/test/support/express/responseDecorator.js @@ -0,0 +1,1017 @@ +/*! + * express + * Copyright(c) 2009-2013 TJ Holowaychuk + * Copyright(c) 2014-2015 Douglas Christopher Wilson + * MIT Licensed + */ + +'use strict'; + +/** + * Module dependencies. + * @private + */ + +const path = require('path'); +const { Buffer } = require('safe-buffer'); +const contentDisposition = require('content-disposition'); +const encodeUrl = require('encodeurl'); +const escapeHtml = require('escape-html'); +const onFinished = require('on-finished'); +const pathIsAbsolute = require('path-is-absolute'); +const statuses = require('statuses'); +const merge = require('utils-merge'); +const { sign } = require('cookie-signature'); +const cookie = require('cookie'); +const send = require('send'); +const { normalizeType } = require('./utils'); +const { normalizeTypes } = require('./utils'); +const { setCharset } = require('./utils'); + +const { extname } = path; +const { mime } = send; +const { resolve } = path; +const vary = require('vary'); +/** + * Module exports. + * @public + */ + +module.exports = setMethods; + +function setMethods(res) { + /** + * Module variables. + * @private + */ + + const charsetRegExp = /;\s*charset\s*=/; + + /** + * Set status `code`. + * + * @param {Number} code + * @return {ServerResponse} + * @public + */ + + res.status = function status(code) { + this.statusCode = code; + return this; + }; + + /** + * Set Link header field with the given `links`. + * + * Examples: + * + * res.links({ + * next: 'http://api.example.com/users?page=2', + * last: 'http://api.example.com/users?page=5' + * }); + * + * @param {Object} links + * @return {ServerResponse} + * @public + */ + + res.links = function (links) { + let link = this.get('Link') || ''; + if (link) link += ', '; + return this.set( + 'Link', + link + + Object.keys(links) + .map((rel) => { + return '<' + links[rel] + '>; rel="' + rel + '"'; + }) + .join(', ') + ); + }; + + /** + * Send a response. + * + * Examples: + * + * res.send(Buffer.from('wahoo')); + * res.send({ some: 'json' }); + * res.send('

some html

'); + * + * @param {string|number|boolean|object|Buffer} body + * @public + */ + + res.send = function send(body) { + let chunk = body; + let encoding; + const { req } = this; + let type; + + // settings + const { app } = this; + + switch (typeof chunk) { + // string defaulting to html + case 'string': + if (!this.get('Content-Type')) { + this.type('html'); + } + + break; + case 'boolean': + case 'number': + case 'object': + if (chunk === null) { + chunk = ''; + } else if (Buffer.isBuffer(chunk)) { + if (!this.get('Content-Type')) { + this.type('bin'); + } + } else { + return this.json(chunk); + } + + break; + } + + // write strings in utf-8 + if (typeof chunk === 'string') { + encoding = 'utf8'; + type = this.get('Content-Type'); + + // reflect this in content-type + if (typeof type === 'string') { + this.set('Content-Type', setCharset(type, 'utf-8')); + } + } + + // determine if ETag should be generated + const etagFn = app.get('etag fn'); + const generateETag = !this.get('ETag') && typeof etagFn === 'function'; + + // populate Content-Length + let length_; + if (chunk !== undefined) { + if (Buffer.isBuffer(chunk)) { + // get length of Buffer + length_ = chunk.length; + } else if (!generateETag && chunk.length < 1000) { + // just calculate length when no ETag + small chunk + length_ = Buffer.byteLength(chunk, encoding); + } else { + // convert chunk to Buffer and calculate + chunk = Buffer.from(chunk, encoding); + encoding = undefined; + length_ = chunk.length; + } + + this.set('Content-Length', length_); + } + + // populate ETag + let etag; + if ( + generateETag && + length_ !== undefined && + (etag = etagFn(chunk, encoding)) + ) { + this.set('ETag', etag); + } + + // freshness + if (req.fresh) this.statusCode = 304; + + // strip irrelevant headers + if (this.statusCode === 204 || this.statusCode === 304) { + this.removeHeader('Content-Type'); + this.removeHeader('Content-Length'); + this.removeHeader('Transfer-Encoding'); + chunk = ''; + } + + if (req.method === 'HEAD') { + // skip body for HEAD + this.end(); + } else { + // respond + this.end(chunk, encoding); + } + + return this; + }; + + /** + * Send JSON response. + * + * Examples: + * + * res.json(null); + * res.json({ user: 'tj' }); + * + * @param {string|number|boolean|object} obj + * @public + */ + + res.json = function json(object) { + // settings + const { app } = this; + const escape = app.get('json escape'); + const replacer = app.get('json replacer'); + const spaces = app.get('json spaces'); + const body = stringify(object, replacer, spaces, escape); + + // content-type + if (!this.get('Content-Type')) { + this.set('Content-Type', 'application/json'); + } + + return this.send(body); + }; + + /** + * Send JSON response with JSONP callback support. + * + * Examples: + * + * res.jsonp(null); + * res.jsonp({ user: 'tj' }); + * + * @param {string|number|boolean|object} obj + * @public + */ + + res.jsonp = function jsonp(object) { + // settings + const { app } = this; + const escape = app.get('json escape'); + const replacer = app.get('json replacer'); + const spaces = app.get('json spaces'); + let body = stringify(object, replacer, spaces, escape); + let callback = this.req.query[app.get('jsonp callback name')]; + + // content-type + if (!this.get('Content-Type')) { + this.set('X-Content-Type-Options', 'nosniff'); + this.set('Content-Type', 'application/json'); + } + + // fixup callback + if (Array.isArray(callback)) { + callback = callback[0]; + } + + // jsonp + if (typeof callback === 'string' && callback.length > 0) { + this.set('X-Content-Type-Options', 'nosniff'); + this.set('Content-Type', 'text/javascript'); + + // restrict callback charset + callback = callback.replace(/[^[\]\w$.]/g, ''); + + // replace chars not allowed in JavaScript that are in JSON + body = body.replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029'); + + // the /**/ is a specific security mitigation for "Rosetta Flash JSONP abuse" + // the typeof check is just to reduce client error noise + body = + '/**/ typeof ' + + callback + + " === 'function' && " + + callback + + '(' + + body + + ');'; + } + + return this.send(body); + }; + + /** + * Send given HTTP status code. + * + * Sets the response status to `statusCode` and the body of the + * response to the standard description from node's http.STATUS_CODES + * or the statusCode number if no description. + * + * Examples: + * + * res.sendStatus(200); + * + * @param {number} statusCode + * @public + */ + + res.sendStatus = function sendStatus(statusCode) { + const body = statuses(statusCode) || String(statusCode); + + this.statusCode = statusCode; + this.type('txt'); + + return this.send(body); + }; + + /** + * Transfer the file at the given `path`. + * + * Automatically sets the _Content-Type_ response header field. + * The callback `callback(err)` is invoked when the transfer is complete + * or when an error occurs. Be sure to check `res.sentHeader` + * if you wish to attempt responding, as the header and some data + * may have already been transferred. + * + * Options: + * + * - `maxAge` defaulting to 0 (can be string converted by `ms`) + * - `root` root directory for relative filenames + * - `headers` object of headers to serve with file + * - `dotfiles` serve dotfiles, defaulting to false; can be `"allow"` to send them + * + * Other options are passed along to `send`. + * + * Examples: + * + * The following example illustrates how `res.sendFile()` may + * be used as an alternative for the `static()` middleware for + * dynamic situations. The code backing `res.sendFile()` is actually + * the same code, so HTTP cache support etc is identical. + * + * app.get('/user/:uid/photos/:file', function(req, res){ + * var uid = req.params.uid + * , file = req.params.file; + * + * req.user.mayViewFilesFrom(uid, function(yes){ + * if (yes) { + * res.sendFile('/uploads/' + uid + '/' + file); + * } else { + * res.send(403, 'Sorry! you cant see that.'); + * } + * }); + * }); + * + * @public + */ + + res.sendFile = function sendFile(path, options, callback) { + let done = callback; + const { req } = this; + const res = this; + const { next } = req; + let options_ = options || {}; + + if (!path) { + throw new TypeError('path argument is required to res.sendFile'); + } + + // support function as second arg + if (typeof options === 'function') { + done = options; + options_ = {}; + } + + if (!options_.root && !pathIsAbsolute(path)) { + throw new TypeError( + 'path must be absolute or specify root to res.sendFile' + ); + } + + // create file stream + const pathname = encodeURI(path); + const file = send(req, pathname, options_); + + // transfer + sendfile(res, file, options_, (error) => { + if (done) return done(error); + if (error && error.code === 'EISDIR') return next(); + + // next() all but write errors + if (error && error.code !== 'ECONNABORTED' && error.syscall !== 'write') { + next(error); + } + }); + }; + + /** + * Transfer the file at the given `path` as an attachment. + * + * Optionally providing an alternate attachment `filename`, + * and optional callback `callback(err)`. The callback is invoked + * when the data transfer is complete, or when an error has + * ocurred. Be sure to check `res.headersSent` if you plan to respond. + * + * Optionally providing an `options` object to use with `res.sendFile()`. + * This function will set the `Content-Disposition` header, overriding + * any `Content-Disposition` header passed as header options in order + * to set the attachment and filename. + * + * This method uses `res.sendFile()`. + * + * @public + */ + + res.download = function download(path, filename, options, callback) { + let done = callback; + let name = filename; + let options_ = options || null; + + // support function as second or third arg + if (typeof filename === 'function') { + done = filename; + name = null; + options_ = null; + } else if (typeof options === 'function') { + done = options; + options_ = null; + } + + // set Content-Disposition when file is sent + const headers = { + 'Content-Disposition': contentDisposition(name || path) + }; + + // merge user-provided headers + if (options_ && options_.headers) { + const keys = Object.keys(options_.headers); + for (const key of keys) { + if (key.toLowerCase() !== 'content-disposition') { + headers[key] = options_.headers[key]; + } + } + } + + // merge user-provided options + options_ = Object.create(options_); + options_.headers = headers; + + // Resolve the full path for sendFile + const fullPath = resolve(path); + + // send file + return this.sendFile(fullPath, options_, done); + }; + + /** + * Set _Content-Type_ response header with `type` through `mime.lookup()` + * when it does not contain "/", or set the Content-Type to `type` otherwise. + * + * Examples: + * + * res.type('.html'); + * res.type('html'); + * res.type('json'); + * res.type('application/json'); + * res.type('png'); + * + * @param {String} type + * @return {ServerResponse} for chaining + * @public + */ + + res.contentType = res.type = function contentType(type) { + const ct = !type.includes('/') ? mime.lookup(type) : type; + + return this.set('Content-Type', ct); + }; + + /** + * Respond to the Acceptable formats using an `obj` + * of mime-type callbacks. + * + * This method uses `req.accepted`, an array of + * acceptable types ordered by their quality values. + * When "Accept" is not present the _first_ callback + * is invoked, otherwise the first match is used. When + * no match is performed the server responds with + * 406 "Not Acceptable". + * + * Content-Type is set for you, however if you choose + * you may alter this within the callback using `res.type()` + * or `res.set('Content-Type', ...)`. + * + * res.format({ + * 'text/plain': function(){ + * res.send('hey'); + * }, + * + * 'text/html': function(){ + * res.send('

hey

'); + * }, + * + * 'appliation/json': function(){ + * res.send({ message: 'hey' }); + * } + * }); + * + * In addition to canonicalized MIME types you may + * also use extnames mapped to these types: + * + * res.format({ + * text: function(){ + * res.send('hey'); + * }, + * + * html: function(){ + * res.send('

hey

'); + * }, + * + * json: function(){ + * res.send({ message: 'hey' }); + * } + * }); + * + * By default Express passes an `Error` + * with a `.status` of 406 to `next(err)` + * if a match is not made. If you provide + * a `.default` callback it will be invoked + * instead. + * + * @param {Object} obj + * @return {ServerResponse} for chaining + * @public + */ + + res.format = function (object) { + const { req } = this; + const { next } = req; + + const fn = object.default; + if (fn) delete object.default; + const keys = Object.keys(object); + + const key = keys.length > 0 ? req.accepts(keys) : false; + + this.vary('Accept'); + + if (key) { + this.set('Content-Type', normalizeType(key).value); + object[key](req, this, next); + } else if (fn) { + fn(); + } else { + const error = new Error('Not Acceptable'); + error.status = error.statusCode = 406; + error.types = normalizeTypes(keys).map((o) => { + return o.value; + }); + next(error); + } + + return this; + }; + + /** + * Set _Content-Disposition_ header to _attachment_ with optional `filename`. + * + * @param {String} filename + * @return {ServerResponse} + * @public + */ + + res.attachment = function attachment(filename) { + if (filename) { + this.type(extname(filename)); + } + + this.set('Content-Disposition', contentDisposition(filename)); + + return this; + }; + + /** + * Append additional header `field` with value `val`. + * + * Example: + * + * res.append('Link', ['', '']); + * res.append('Set-Cookie', 'foo=bar; Path=/; HttpOnly'); + * res.append('Warning', '199 Miscellaneous warning'); + * + * @param {String} field + * @param {String|Array} val + * @return {ServerResponse} for chaining + * @public + */ + + res.append = function append(field, value_) { + const previous = this.get(field); + let value = value_; + + if (previous) { + // concat the new and prev vals + value = Array.isArray(previous) + ? previous.concat(value_) + : Array.isArray(value_) + ? [previous].concat(value_) + : [previous, value_]; + } + + return this.set(field, value); + }; + + /** + * Set header `field` to `val`, or pass + * an object of header fields. + * + * Examples: + * + * res.set('Foo', ['bar', 'baz']); + * res.set('Accept', 'application/json'); + * res.set({ Accept: 'text/plain', 'X-API-Key': 'tobi' }); + * + * Aliased as `res.header()`. + * + * @param {String|Object} field + * @param {String|Array} val + * @return {ServerResponse} for chaining + * @public + */ + + res.set = res.header = function header(field, value_) { + if (arguments.length === 2) { + let value = Array.isArray(value_) ? value_.map(String) : String(value_); + + // add charset to content-type + if (field.toLowerCase() === 'content-type') { + if (Array.isArray(value)) { + throw new TypeError('Content-Type cannot be set to an Array'); + } + + if (!charsetRegExp.test(value)) { + const charset = mime.charsets.lookup(value.split(';')[0]); + if (charset) value += '; charset=' + charset.toLowerCase(); + } + } + + this.setHeader(field, value); + } else { + for (const key in field) { + this.set(key, field[key]); + } + } + + return this; + }; + + /** + * Get value for header `field`. + * + * @param {String} field + * @return {String} + * @public + */ + + res.get = function (field) { + return this.getHeader(field); + }; + + /** + * Clear cookie `name`. + * + * @param {String} name + * @param {Object} [options] + * @return {ServerResponse} for chaining + * @public + */ + + res.clearCookie = function clearCookie(name, options) { + const options_ = merge({ expires: new Date(1), path: '/' }, options); + + return this.cookie(name, '', options_); + }; + + /** + * Set cookie `name` to `value`, with the given `options`. + * + * Options: + * + * - `maxAge` max-age in milliseconds, converted to `expires` + * - `signed` sign the cookie + * - `path` defaults to "/" + * + * Examples: + * + * // "Remember Me" for 15 minutes + * res.cookie('rememberme', '1', { expires: new Date(Date.now() + 900000), httpOnly: true }); + * + * // save as above + * res.cookie('rememberme', '1', { maxAge: 900000, httpOnly: true }) + * + * @param {String} name + * @param {String|Object} value + * @param {Object} [options] + * @return {ServerResponse} for chaining + * @public + */ + + res.cookie = function (name, value, options) { + const options_ = merge({}, options); + const { secret } = this.req; + const { signed } = options_; + + if (signed && !secret) { + throw new Error('cookieParser("secret") required for signed cookies'); + } + + let value_ = + typeof value === 'object' ? 'j:' + JSON.stringify(value) : String(value); + + if (signed) { + value_ = 's:' + sign(value_, secret); + } + + if ('maxAge' in options_) { + options_.expires = new Date(Date.now() + options_.maxAge); + options_.maxAge /= 1000; + } + + if (options_.path == null) { + options_.path = '/'; + } + + this.append('Set-Cookie', cookie.serialize(name, String(value_), options_)); + + return this; + }; + + /** + * Set the location header to `url`. + * + * The given `url` can also be "back", which redirects + * to the _Referrer_ or _Referer_ headers or "/". + * + * Examples: + * + * res.location('/foo/bar').; + * res.location('http://example.com'); + * res.location('../login'); + * + * @param {String} url + * @return {ServerResponse} for chaining + * @public + */ + + res.location = function location(url) { + let loc = url; + + // "back" is an alias for the referrer + if (url === 'back') { + loc = this.req.get('Referrer') || '/'; + } + + // set location + return this.set('Location', encodeUrl(loc)); + }; + + /** + * Redirect to the given `url` with optional response `status` + * defaulting to 302. + * + * The resulting `url` is determined by `res.location()`, so + * it will play nicely with mounted apps, relative paths, + * `"back"` etc. + * + * Examples: + * + * res.redirect('/foo/bar'); + * res.redirect('http://example.com'); + * res.redirect(301, 'http://example.com'); + * res.redirect('../login'); // /blog/post/1 -> /blog/login + * + * @public + */ + + res.redirect = function redirect(url) { + let address = url; + let body; + let status = 302; + + // allow status / url + if (arguments.length === 2) { + status = arguments[0]; + address = arguments[1]; + } + + // Set location header + address = this.location(address).get('Location'); + + // Support text/{plain,html} by default + this.format({ + text() { + body = statuses(status) + '. Redirecting to ' + address; + }, + + html() { + const u = escapeHtml(address); + body = + '

' + + statuses(status) + + '. Redirecting to ' + + u + + '

'; + }, + + default() { + body = ''; + } + }); + + // Respond + this.statusCode = status; + this.set('Content-Length', Buffer.byteLength(body)); + + if (this.req.method === 'HEAD') { + this.end(); + } else { + this.end(body); + } + }; + + /** + * Add `field` to Vary. If already present in the Vary set, then + * this call is simply ignored. + * + * @param {Array|String} field + * @return {ServerResponse} for chaining + * @public + */ + + res.vary = function (field) { + vary(this, field); + + return this; + }; + + /** + * Render `view` with the given `options` and optional callback `fn`. + * When a callback function is given a response will _not_ be made + * automatically, otherwise a response of _200_ and _text/html_ is given. + * + * Options: + * + * - `cache` boolean hinting to the engine it should cache + * - `filename` filename of the view being rendered + * + * @public + */ + + res.render = function render(view, options, callback) { + const { app } = this.req; + let done = callback; + let options_ = options || {}; + const { req } = this; + const self = this; + + // support callback function as second arg + if (typeof options === 'function') { + done = options; + options_ = {}; + } + + // merge res.locals + options_._locals = self.locals; + + // default callback to respond + done = + done || + function (error, string_) { + if (error) return req.next(error); + self.send(string_); + }; + + // render + app.render(view, options_, done); + }; + + // pipe the send file stream + function sendfile(res, file, options, callback) { + let done = false; + let streaming; + + // request aborted + function onaborted() { + if (done) return; + done = true; + + const error = new Error('Request aborted'); + error.code = 'ECONNABORTED'; + callback(error); + } + + // directory + function ondirectory() { + if (done) return; + done = true; + + const error = new Error('EISDIR, read'); + error.code = 'EISDIR'; + callback(error); + } + + // errors + function onerror(error) { + if (done) return; + done = true; + callback(error); + } + + // ended + function onend() { + if (done) return; + done = true; + callback(); + } + + // file + function onfile() { + streaming = false; + } + + // finished + function onfinish(error) { + if (error && error.code === 'ECONNRESET') return onaborted(); + if (error) return onerror(error); + if (done) return; + + setImmediate(() => { + if (streaming !== false && !done) { + onaborted(); + return; + } + + if (done) return; + done = true; + callback(); + }); + } + + // streaming + function onstream() { + streaming = true; + } + + file.on('directory', ondirectory); + file.on('end', onend); + file.on('error', onerror); + file.on('file', onfile); + file.on('stream', onstream); + + if (options.headers) { + // set headers on successful transfer + file.on('headers', function headers(res) { + const object = options.headers; + const keys = Object.keys(object); + + for (const k of keys) { + res.setHeader(k, object[k]); + } + }); + } + + // pipe + file.pipe(res); + + onFinished(res, onfinish); + } + + return res; +} + +/** + * Stringify JSON, like JSON.stringify, but v8 optimized, with the + * ability to escape characters that can trigger HTML sniffing. + * + * @param {*} value + * @param {function} replaces + * @param {number} spaces + * @param {boolean} escape + * @returns {string} + * @private + */ + +function stringify(value, replacer, spaces, escape) { + // v8 checks arguments.length for optimizing simple call + // https://bugs.chromium.org/p/v8/issues/detail?id=4730 + let json = + replacer || spaces + ? JSON.stringify(value, replacer, spaces) + : JSON.stringify(value); + + if (escape) { + json = json.replace(/[<>&]/g, (c) => { + switch (c.charCodeAt(0)) { + case 0x3c: + return '\\u003c'; + case 0x3e: + return '\\u003e'; + case 0x26: + return '\\u0026'; + default: + return c; + } + }); + } + + return json; +} diff --git a/test/support/express/utils.js b/test/support/express/utils.js new file mode 100644 index 000000000..b3dbc7a65 --- /dev/null +++ b/test/support/express/utils.js @@ -0,0 +1,276 @@ +/*! + * express + * Copyright(c) 2009-2013 TJ Holowaychuk + * Copyright(c) 2014-2015 Douglas Christopher Wilson + * MIT Licensed + */ + +'use strict'; + +/** + * Module dependencies. + * @api private + */ + +const querystring = require('querystring'); +const { Buffer } = require('safe-buffer'); +const contentType = require('content-type'); +const { mime } = require('send'); +const etag = require('etag'); +const proxyaddr = require('proxy-addr'); +const qs = require('qs'); + +let isHttp2Supported = true; + +/** + * Test for http2 support + * @api private + */ +try { + require('http2'); +} catch { + isHttp2Supported = false; +} +/** + * Return strong ETag for `body`. + * + * @param {String|Buffer} body + * @param {String} [encoding] + * @return {String} + * @api private + */ + +exports.etag = createETagGenerator({ weak: false }); + +/** + * Return weak ETag for `body`. + * + * @param {String|Buffer} body + * @param {String} [encoding] + * @return {String} + * @api private + */ + +exports.wetag = createETagGenerator({ weak: true }); + +/** + * Normalize the given `type`, for example "html" becomes "text/html". + * + * @param {String} type + * @return {Object} + * @api private + */ + +exports.normalizeType = function (type) { + return ~type.indexOf('/') + ? acceptParameters(type) + : { value: mime.lookup(type), params: {} }; +}; + +/** + * Normalize `types`, for example "html" becomes "text/html". + * + * @param {Array} types + * @return {Array} + * @api private + */ + +exports.normalizeTypes = function (types) { + const returnValue = []; + + for (const element of types) { + returnValue.push(exports.normalizeType(element)); + } + + return returnValue; +}; + +/** + * Parse accept params `str` returning an + * object with `.value`, `.quality` and `.params`. + * also includes `.originalIndex` for stable sorting + * + * @param {String} str + * @return {Object} + * @api private + */ + +function acceptParameters(string_, index) { + const parts = string_.split(/ *; */); + const returnValue = { + value: parts[0], + quality: 1, + params: {}, + originalIndex: index + }; + + for (let i = 1; i < parts.length; ++i) { + const pms = parts[i].split(/ *= */); + if (pms[0] === 'q') { + returnValue.quality = Number.parseFloat(pms[1]); + } else { + returnValue.params[pms[0]] = pms[1]; + } + } + + return returnValue; +} + +/** + * Compile "etag" value to function. + * + * @param {Boolean|String|Function} val + * @return {Function} + * @api private + */ + +exports.compileETag = function (value) { + let fn; + + if (typeof value === 'function') { + return value; + } + + switch (value) { + case true: + fn = exports.wetag; + break; + case false: + break; + case 'strong': + fn = exports.etag; + break; + case 'weak': + fn = exports.wetag; + break; + default: + throw new TypeError('unknown value for etag function: ' + value); + } + + return fn; +}; + +/** + * Compile "query parser" value to function. + * + * @param {String|Function} val + * @return {Function} + * @api private + */ + +exports.compileQueryParser = function compileQueryParser(value) { + let fn; + + if (typeof value === 'function') { + return value; + } + + switch (value) { + case true: + fn = querystring.parse; + break; + case false: + break; + case 'extended': + fn = parseExtendedQueryString; + break; + case 'simple': + fn = querystring.parse; + break; + default: + throw new TypeError('unknown value for query parser function: ' + value); + } + + return fn; +}; + +/** + * Compile "proxy trust" value to function. + * + * @param {Boolean|String|Number|Array|Function} val + * @return {Function} + * @api private + */ + +exports.compileTrust = function (value) { + if (typeof value === 'function') return value; + + if (value === true) { + // Support plain true/false + return function () { + return true; + }; + } + + if (typeof value === 'number') { + // Support trusting hop count + return function (a, i) { + return i < value; + }; + } + + if (typeof value === 'string') { + // Support comma-separated values + value = value.split(/ *, */); + } + + return proxyaddr.compile(value || []); +}; + +/** + * Flag for http2 support + */ +exports.isHttp2Supported = isHttp2Supported; +/** + * Set the charset in a given Content-Type string. + * + * @param {String} type + * @param {String} charset + * @return {String} + * @api private + */ + +exports.setCharset = function setCharset(type, charset) { + if (!type || !charset) { + return type; + } + + // parse type + const parsed = contentType.parse(type); + + // set charset + parsed.parameters.charset = charset; + + // format type + return contentType.format(parsed); +}; + +/** + * Create an ETag generator function, generating ETags with + * the given options. + * + * @param {object} options + * @return {function} + * @private + */ + +function createETagGenerator(options) { + return function generateETag(body, encoding) { + const buf = !Buffer.isBuffer(body) ? Buffer.from(body, encoding) : body; + + return etag(buf, options); + }; +} + +/** + * Parse an extended query string with qs. + * + * @return {Object} + * @private + */ + +function parseExtendedQueryString(string_) { + return qs.parse(string_, { + allowPrototypes: true + }); +} diff --git a/test/support/server.js b/test/support/server.js index 337a3791e..840b4c2c4 100644 --- a/test/support/server.js +++ b/test/support/server.js @@ -1,184 +1,601 @@ -var express = require('express'); -var bodyParser = require('body-parser'); -var cookieParser = require('cookie-parser'); - -var app = express(); - -app.use(function(req, res, next) { +const fs = require('node:fs'); +const path = require('node:path'); +const process = require('node:process'); +const { Buffer } = require('node:buffer'); +let http = require('node:http'); +const multer = require('multer'); +const bodyParser = require('body-parser'); +const cookieParser = require('cookie-parser'); +const basicAuth = require('basic-auth-connect'); +const express = require('./express'); + +let isPseudoHeader; + +if (process.env.HTTP2_TEST) { + http = require('node:http2'); + const { + HTTP2_HEADER_AUTHORITY, + HTTP2_HEADER_METHOD, + HTTP2_HEADER_PATH, + HTTP2_HEADER_SCHEME, + HTTP2_HEADER_STATUS + } = http.constants; + isPseudoHeader = function (name) { + switch (name) { + case HTTP2_HEADER_STATUS: // :status + case HTTP2_HEADER_METHOD: // :method + case HTTP2_HEADER_PATH: // :path + case HTTP2_HEADER_AUTHORITY: // :authority + case HTTP2_HEADER_SCHEME: { + // :scheme + return true; + } + + default: { + return false; + } + } + }; +} + +const app = express(); + +app.use((request, res, next) => { res.set('Cache-Control', 'no-cache, no-store'); next(); }); -app.all('/echo', function(req, res){ - res.writeHead(200, req.headers); - req.pipe(res); +app.all('/url', (request, res) => { + res.send(request.url); +}); + +app.all('/echo', (request, res) => { + const { headers } = request; + if (process.env.HTTP2_TEST) { + for (const name of Object.keys(headers)) { + if (isPseudoHeader(name)) { + delete headers[name]; + } + } + } + + res.writeHead(200, headers); + request.pipe(res); +}); + +let uniq = 0; +app.all('/unique', (request, res) => { + res.send(`never the same ${uniq++}`); }); app.use(bodyParser.urlencoded({ extended: true })); +app.use(multer().none()); + +app.all('/formecho', (request, res) => { + if ( + !/application\/x-www-form-urlencoded|multipart\/form-data/.test( + request.headers['content-type'] + ) + ) { + return res.status(400).end('wrong type'); + } + + res.json(request.body); +}); + app.use(bodyParser.json()); app.use(cookieParser()); -app.use('/xdomain', function(req, res, next){ - if (!req.get('Origin')) return next(); - res.set('Access-Control-Allow-Origin', req.get('Origin')); +app.use('/xdomain', (request, res, next) => { + if (!request.get('Origin')) return next(); + res.set('Access-Control-Allow-Origin', request.get('Origin')); res.set('Access-Control-Allow-Credentials', 'true'); res.set('Access-Control-Allow-Methods', 'POST'); res.set('Access-Control-Allow-Headers', 'X-Requested-With, Content-Type'); - if ('OPTIONS' == req.method) return res.send(200); + if (request.method === 'OPTIONS') return res.send(200); next(); }); -app.get('/xdomain', function(req, res){ +app.get('/xdomain', (request, res) => { res.send('tobi'); }); -app.get('/login', function(req, res){ +app.get('/login', (request, res) => { res.status(200).send(''); }); -app.get('/json', function(req, res){ +app.get('/json', (request, res) => { res.status(200).json({ name: 'manny' }); }); -app.get('/ok', function(req, res){ +app.get('/json-hal', (request, res) => { + res.set('content-type', 'application/hal+json'); + res.send({ name: 'hal 5000' }); +}); + +app.get('/ok', (request, res) => { res.send('ok'); }); -app.get('/foo', function(req, res){ +app.get('/foo', (request, res) => { res .header('Content-Type', 'application/x-www-form-urlencoded') .send('foo=bar'); }); -app.get('/', function(req, res){ +app.get('/form-data', (request, res) => { + res.header('Content-Type', 'application/x-www-form-urlencoded'); + res.send('pet[name]=manny'); +}); + +app.post('/movie', (request, res) => { + res.redirect('/movies/all/0'); +}); + +app.get('/', (request, res) => { + res.set('QUERY', JSON.stringify(request.query)); res.redirect('/movies'); }); -app.get('/movies', function(req, res){ +app.get('/movies', (request, res) => { + res.set('QUERY', JSON.stringify(request.query)); res.redirect('/movies/all'); }); -app.get('/movies/all', function(req, res){ +app.get('/movies/all', (request, res) => { + res.set('QUERY', JSON.stringify(request.query)); res.redirect('/movies/all/0'); }); -app.get('/movies/all/0', function(req, res){ +app.get('/movies/all/0', (request, res) => { + res.set('QUERY', JSON.stringify(request.query)); res.status(200).send('first movie page'); }); -app.get('/links', function(req, res){ - res.header('Link', '; rel="next"'); +app.get('/movies/random', (request, res) => { + res.redirect('/movie/4'); +}); + +app.get('/movie/4', (request, res) => { + setTimeout(() => { + res.send('not-so-random movie'); + }, 1000); +}); + +app.get('/links', (request, res) => { + res.header( + 'Link', + '; rel="next"' + ); res.end(); }); -app.get('/xml', function(req, res){ +app.get('/xml', (request, res) => { res.type('xml'); res.status(200).send(''); }); -app.get('/custom', function(req, res){ +app.get('/custom', (request, res) => { res.type('application/x-custom'); res.status(200).send('custom stuff'); }); -app.put('/user/:id', function(req, res){ +app.put('/user/:id', (request, res) => { res.send('updated'); }); -app.patch('/user/:id', function(req, res){ +app.put('/user/:id/body', (request, res) => { + res.send(`received ${request.body.user}`); +}); + +app.patch('/user/:id', (request, res) => { res.send('updated'); }); -app.post('/user/:id/pet', function(req, res){ - res.send('added pet "' + req.body.pet + '"'); +app.post('/user/:id/pet', (request, res) => { + res.send(`added pet "${request.body.pet}"`); }); -app.post('/user', function(req, res){ +app.post('/user', (request, res) => { res.send('created'); }); -app.delete('/user/:id', function(req, res){ +app.delete('/user/:id', (request, res) => { res.send('deleted'); }); -app.post('/todo/item', function(req, res){ - var buf = ''; - req.on('data', function(chunk){ buf += chunk; }); - req.on('end', function(){ - res.send('added "' + buf + '"'); +app.post('/todo/item', (request, res) => { + let buf = ''; + request.on('data', (chunk) => { + buf += chunk; + }); + request.on('end', () => { + res.send(`added "${buf}"`); }); }); -app.get('/delay/const', function (req, res) { +app.get('/delay/const', (request, res) => { res.redirect('/delay/3000'); }); -app.get('/delay/:ms', function(req, res){ - var ms = ~~req.params.ms; - setTimeout(function(){ +app.get('/delay/zip', (request, res) => { + res.writeHead(200, { + 'Content-Type': 'text/plain', + 'Content-Encoding': 'gzip' + }); + setTimeout(() => { + res.end(); + }, 10_000); +}); + +app.get('/delay/json', (request, res) => { + res.writeHead(200, { 'Content-Type': 'application/json' }); + setTimeout(() => { + res.end(); + }, 10_000); +}); + +let slowBodyCallback; +app.get('/delay/slowbody', (request, res) => { + res.writeHead(200, { 'Content-Type': 'application/octet-stream' }); + + // Send lots of garbage data to overflow all buffers along the way, + // so that the browser gets some data before the request is done + const initialDataSent = new Promise((resolve) => { + res.write(Buffer.alloc(4000), () => { + res.write(Buffer.alloc(16_000)); + resolve(); + }); + }); + + // Make sure sending of request body takes over 1s, + // so that the test can't pass by accident. + const minimumTime = new Promise((resolve) => { + setTimeout(resolve, 1001); + }); + + new Promise((resolve) => { + // Waiting full 10 seconds for the test would be too annoying, + // so the remote callback is a hack to push the test forward + slowBodyCallback = resolve; + setTimeout(resolve, 10_000); + }) + .then(() => Promise.all([initialDataSent, minimumTime])) + .then(() => { + res.end('bye'); + }); +}); + +app.get('/delay/slowbody/finish', (request, res) => { + if (slowBodyCallback) slowBodyCallback(); + res.sendStatus(204); +}); + +app.get('/delay/:ms', (request, res) => { + const ms = Math.trunc(request.params.ms); + setTimeout(() => { res.sendStatus(200); }, ms); }); -app.get('/querystring', function(req, res){ - res.send(req.query); +app.get('/querystring', (request, res) => { + res.send(request.query); +}); + +app.get('/querystring-in-header', (request, res) => { + res.set('query', JSON.stringify(request.query)); + res.send(); +}); + +app.all('/echo-header/:field', (request, res) => { + res.send(request.headers[request.params.field]); }); -app.get('/echo-header/:field', function(req, res){ - res.send(req.headers[req.params.field]); +app.get('/echo-headers', (request, res) => { + res.json(request.headers); }); -app.post('/pet', function(req, res){ - res.send('added ' + req.body.name + ' the ' + req.body.species); +app.post('/pet', (request, res) => { + res.send(`added ${request.body.name} the ${request.body.species}`); }); -app.get('/pets', function(req, res){ +app.get('/pets', (request, res) => { res.send(['tobi', 'loki', 'jane']); }); -app.get('/text', function(req, res){ - res.send("just some text"); +app.get('/json-seq', (request, res) => { + res + .set('content-type', 'application/json-seq') + .send('\u001E{"id":1}\n\u001E{"id":2}\n'); +}); + +app.get('/invalid-json', (request, res) => { + res.set('content-type', 'application/json'); + // sample invalid json taken from https://github.com/swagger-api/swagger-ui/issues/1354 + res.send( + ")]}', {'header':{'code':200,'text':'OK','version':'1.0'},'data':'some data'}" + ); +}); + +app.get('/invalid-json-forbidden', (request, res) => { + res.set('content-type', 'application/json'); + res.status(403).send('Forbidden'); }); -app.post('/auth', function(req, res) { - var auth = req.headers.authorization, - parts = auth.split(' '), - credentials = new Buffer(parts[1], 'base64').toString().split(':'), - user = credentials[0], - pass = credentials[1]; +app.get('/text', (request, res) => { + res.send('just some text'); +}); + +app.get('/basic-auth', basicAuth('tobi', 'learnboost'), (request, res) => { + res.end('you win!'); +}); - res.send({ user : user, pass : pass }); +app.get('/basic-auth/again', basicAuth('tobi', ''), (request, res) => { + res.end('you win again!'); }); -app.get('/error', function(req, res){ +app.post('/auth', basicAuth('foo', 'bar'), (request, res) => { + const auth = request.headers.authorization; + const parts = auth.split(' '); + const credentials = Buffer.from(parts[1], 'base64').toString().split(':'); + const user = credentials[0]; + const pass = credentials[1]; + + res.send({ user, pass }); +}); + +app.get('/error', (request, res) => { res.status(500).send('boom'); }); -app.get('/unauthorized', function(req, res){ +app.get('/unauthorized', (request, res) => { res.sendStatus(401); }); -app.get('/bad-request', function(req, res){ +app.get('/bad-request', (request, res) => { res.sendStatus(400); }); -app.get('/not-acceptable', function(req, res){ +app.get('/not-acceptable', (request, res) => { res.sendStatus(406); }); -app.get('/no-content', function(req, res){ +app.get('/no-content', (request, res) => { res.sendStatus(204); }); -app.delete('/no-content', function(req, res){ +app.delete('/no-content', (request, res) => { res.set('content-type', 'application/json'); res.sendStatus(204); }); -app.get('/arraybuffer', function(req, res) { - var content = new ArrayBuffer(1000); +app.post('/created', (request, res) => { + res.status(201).send('created'); +}); + +app.post('/unprocessable-entity', (request, res) => { + res.status(422).send('unprocessable entity'); +}); + +app.get('/arraybuffer', (request, res) => { + const content = new ArrayBuffer(1000); res.set('Content-Type', 'application/vnd.superagent'); res.send(content); }); -app.listen(process.env.ZUUL_PORT); +app.get('/arraybuffer-unauthorized', (request, res) => { + res.set('Content-Type', 'application/json'); + res + .status(401) + .send('{"message":"Authorization has been denied for this request."}'); +}); + +app.post('/empty-body', bodyParser.text(), (request, res) => { + if ( + typeof request.body === 'object' && + Object.keys(request.body).length === 0 + ) { + res.sendStatus(204); + } else { + res.sendStatus(400); + } +}); + +app.get('/collection-json', (request, res) => { + res.set('content-type', 'application/vnd.collection+json'); + res.send({ name: 'chewbacca' }); +}); + +app.get('/invalid-json', (request, res) => { + res.set('content-type', 'application/json'); + // sample invalid json taken from https://github.com/swagger-api/swagger-ui/issues/1354 + res.send( + ")]}', {'header':{'code':200,'text':'OK','version':'1.0'},'data':'some data'}" + ); +}); + +app.options('/options/echo/body', bodyParser.json(), (request, res) => { + res.send(request.body); +}); + +app.get('/cookie-redirect', (request, res) => { + res.set('Set-Cookie', 'replaced=yes'); + res.append('Set-Cookie', 'from-redir=1', true); + res.redirect(303, '/show-cookies'); +}); + +app.get('/set-cookie', (request, res) => { + res.cookie('replaced', 'no'); + res.cookie('persist', '123'); + res.send('ok'); +}); + +app.get('/show-cookies', (request, res) => { + res.set('content-type', 'text/plain'); + res.send(request.headers.cookie); +}); + +app.put('/redirect-303', (request, res) => { + res.redirect(303, '/reply-method'); +}); + +app.put('/redirect-307', (request, res) => { + res.redirect(307, '/reply-method'); +}); + +app.put('/redirect-308', (request, res) => { + res.redirect(308, '/reply-method'); +}); + +app.all('/reply-method', (request, res) => { + res.send(`method=${request.method.toLowerCase()}`); +}); + +app.get('/tobi', (request, res) => { + res.send('tobi'); +}); + +app.get('/relative', (request, res) => { + res.redirect('tobi'); +}); + +app.get('/relative/sub', (request, res) => { + res.redirect('../tobi'); +}); + +app.get('/header', (request, res) => { + res.redirect('/header/2'); +}); + +app.post('/header', (request, res) => { + res.redirect('/header/2'); +}); + +app.get('/header/2', (request, res) => { + res.send(request.headers); +}); + +app.get('/bad-redirect', (request, res) => { + res.status(307).end(); +}); + +app.all('/ua', (request, res) => { + const { headers } = request; + if (process.env.HTTP2_TEST) { + for (const name of Object.keys(headers)) { + if (isPseudoHeader(name)) { + delete headers[name]; + } + } + } + + res.writeHead(200, headers); + request.pipe(res); +}); + +app.get('/manny', (request, res) => { + res.status(200).json({ name: 'manny' }); +}); + +function serveImageWithType(res, type) { + const img = fs.readFileSync( + path.join(__dirname, '../node/fixtures/test.png') + ); + res.writeHead(200, { 'Content-Type': type }); + res.end(img, 'binary'); +} + +app.get('/image', (request, res) => { + serveImageWithType(res, 'image/png'); +}); +app.get('/image-as-octets', (request, res) => { + serveImageWithType(res, 'application/octet-stream'); +}); + +app.get('/binary-data', (request, res) => { + const binData = fs.readFileSync( + path.join(__dirname, '../node/fixtures/test.aac') + ); + res.writeHead(200, { 'Content-type': 'audio/aac' }); + res.end(binData, 'binary'); +}); + +app.get('/chunked-json', (request, res) => { + res.set('content-type', 'application/json'); + res.set('Transfer-Encoding', 'chunked'); + + let chunk = 0; + const interval = setInterval(() => { + chunk++; + if (chunk === 1) res.write(`{ "name_${chunk}": "`); + if (chunk > 1) res.write(`value_${chunk}", "name_${chunk}": "`); + if (chunk === 10) { + clearInterval(interval); + res.write(`value_${chunk}"}`); + res.end(); + } + }, 10); +}); + +app.get('/if-mod', (request, res) => { + if (request.header('if-modified-since')) { + res.status(304).end(); + } else { + res.send(`${Date.now()}`); + } +}); + +const called = {}; +app.get('/error/ok/:id', (request, res) => { + if (request.query.qs !== 'present') { + return res.status(400).end('query string lost'); + } + + const { id } = request.params; + if (!called[id]) { + called[id] = true; + res.status(500).send('boom'); + } else { + res.send(request.headers); + delete called[id]; + } +}); + +app.get('/delay/:ms/ok/:id', (request, res) => { + const { id } = request.params; + if (!called[id]) { + called[id] = true; + const ms = Math.trunc(request.params.ms); + setTimeout(() => { + res.sendStatus(200); + }, ms); + } else { + res.send(`ok = ${request.url}`); + delete called[id]; + } +}); + +app.get('/error/redirect/:id', (request, res) => { + const { id } = request.params; + if (!called[id]) { + called[id] = true; + res.status(500).send('boom'); + } else { + res.redirect('/movies'); + delete called[id]; + } +}); + +app.get('/error/redirect-error:id', (request, res) => { + const { id } = request.params; + if (!called[id]) { + called[id] = true; + res.status(500).send('boom'); + } else { + res.redirect('/error'); + delete called[id]; + } +}); + +const server = http.createServer(app); +server.listen(process.env.ZUUL_PORT); diff --git a/test/support/setup.js b/test/support/setup.js new file mode 100644 index 000000000..ee251837f --- /dev/null +++ b/test/support/setup.js @@ -0,0 +1,36 @@ +require('should'); +require('should-http'); + +const getPort = require('get-port'); + +let NODE; +let uri; + +async function getSetup() { + if (NODE && uri) { + return { NODE, uri }; + } + + NODE = true; + if (typeof window !== 'undefined') { + NODE = false; + uri = `//${window.location.host}`; + } else { + try { + const port = await getPort(); + + // check that another call to the function hasn't set the uri already + if (!uri) { + process.env.ZUUL_PORT = port; + uri = `http://localhost:${process.env.ZUUL_PORT}`; + require('./server'); + } + } catch (err) { + console.error(err); + } + } + + return { NODE, uri }; +} + +module.exports = getSetup; diff --git a/test/timeout.js b/test/timeout.js new file mode 100644 index 000000000..7acf39b5c --- /dev/null +++ b/test/timeout.js @@ -0,0 +1,140 @@ +const assert = require('assert'); +const getSetup = require('./support/setup'); + +const request = require('./support/client'); + +describe('.timeout(ms)', function () { + let setup; + let base; + + before(async () => { + setup = await getSetup(); + base = setup.uri; + }); + + this.timeout(15_000); + + describe('when timeout is exceeded', () => { + it('should error', (done) => { + request + .get(`${base}/delay/500`) + .timeout(150) + .end((error, res) => { + assert(error, 'expected an error'); + assert.equal( + 'number', + typeof error.timeout, + 'expected an error with .timeout' + ); + assert.equal('ECONNABORTED', error.code, 'expected abort error code'); + done(); + }); + }); + + it('should error in promise interface ', (done) => { + request + .get(`${base}/delay/500`) + .timeout(150) + .catch((err) => { + assert(err, 'expected an error'); + assert.equal( + 'number', + typeof err.timeout, + 'expected an error with .timeout' + ); + assert.equal('ECONNABORTED', err.code, 'expected abort error code'); + done(); + }); + }); + + it('should handle gzip timeout', (done) => { + request + .get(`${base}/delay/zip`) + .timeout(150) + .end((error, res) => { + assert(error, 'expected an error'); + assert.equal( + 'number', + typeof error.timeout, + 'expected an error with .timeout' + ); + assert.equal('ECONNABORTED', error.code, 'expected abort error code'); + done(); + }); + }); + + it('should handle buffer timeout', (done) => { + request + .get(`${base}/delay/json`) + .buffer(true) + .timeout(150) + .end((error, res) => { + assert(error, 'expected an error'); + assert.equal( + 'number', + typeof error.timeout, + 'expected an error with .timeout' + ); + assert.equal('ECONNABORTED', error.code, 'expected abort error code'); + done(); + }); + }); + + it('should error on deadline', (done) => { + request + .get(`${base}/delay/500`) + .timeout({ deadline: 150 }) + .end((error, res) => { + assert(error, 'expected an error'); + assert.equal( + 'number', + typeof error.timeout, + 'expected an error with .timeout' + ); + assert.equal('ECONNABORTED', error.code, 'expected abort error code'); + done(); + }); + }); + + it('should support setting individual options', (done) => { + request + .get(`${base}/delay/500`) + .timeout({ deadline: 10 }) + .timeout({ response: 99_999 }) + .end((error, res) => { + assert(error, 'expected an error'); + assert.equal('ECONNABORTED', error.code, 'expected abort error code'); + assert.equal('ETIME', error.errno); + done(); + }); + }); + + it('should error on response', (done) => { + request + .get(`${base}/delay/500`) + .timeout({ response: 150 }) + .end((error, res) => { + assert(error, 'expected an error'); + assert.equal( + 'number', + typeof error.timeout, + 'expected an error with .timeout' + ); + assert.equal('ECONNABORTED', error.code, 'expected abort error code'); + assert.equal('ETIMEDOUT', error.errno); + done(); + }); + }); + + it('should accept slow body with fast response', (done) => { + request + .get(`${base}/delay/slowbody`) + .timeout({ response: 1000 }) + .on('progress', () => { + // This only makes the test faster without relying on arbitrary timeouts + request.get(`${base}/delay/slowbody/finish`).end(); + }) + .end(done); + }); + }); +}); diff --git a/test/use.js b/test/use.js new file mode 100644 index 000000000..541cffc88 --- /dev/null +++ b/test/use.js @@ -0,0 +1,95 @@ +const assert = require('assert'); +const getSetup = require('./support/setup'); + +const request = require('./support/client'); + +describe('request', function () { + let setup; + let uri; + + before(async function () { + setup = await getSetup(); + uri = setup.uri; + }); + + this.timeout(20_000); + describe('use', () => { + it('should use plugin success', (done) => { + const now = `${Date.now()}`; + function uuid(request_) { + request_.set('X-UUID', now); + return request_; + } + + function prefix(request_) { + request_.url = uri + request_.url; + return request_; + } + + request + .get('/echo') + .use(uuid) + .use(prefix) + .end((error, res) => { + assert.strictEqual(res.statusCode, 200); + assert.equal(res.get('X-UUID'), now); + done(); + }); + }); + }); +}); + +describe('subclass', () => { + let OriginalRequest; + beforeEach(() => { + OriginalRequest = request.Request; + }); + afterEach(() => { + request.Request = OriginalRequest; + }); + + it('should be an instance of Request', () => { + const request_ = request.get('/'); + assert(request_ instanceof request.Request); + }); + + it('should use patched subclass', () => { + assert(OriginalRequest); + + let constructorCalled; + let sendCalled; + function NewRequest(...args) { + constructorCalled = true; + OriginalRequest.apply(this, args); + } + + NewRequest.prototype = Object.create(OriginalRequest.prototype); + NewRequest.prototype.send = function () { + sendCalled = true; + return this; + }; + + request.Request = NewRequest; + + const request_ = request.get('/').send(); + assert(constructorCalled); + assert(sendCalled); + assert(request_ instanceof NewRequest); + assert(request_ instanceof OriginalRequest); + }); + + it('should use patched subclass in agent too', () => { + if (!request.agent) return; // Node-only + + function NewRequest(...args) { + OriginalRequest.apply(this, args); + } + + NewRequest.prototype = Object.create(OriginalRequest.prototype); + request.Request = NewRequest; + + const request_ = request.agent().del('http://test.com/'); + assert(request_ instanceof NewRequest); + assert(request_ instanceof OriginalRequest); + }); +});

SuperAgent

테스트 문서

기본 요청

HTTP/2 사용하기

헤더 필드 설정하기

GET 요청

HEAD 요청하기

POST / PUT 요청

Content-Type 설정하기

요청 본문 직렬화하기

요청 재시도하기

Accept 설정하기

Facebook과 Accept JSON

쿼리 문자열

TLS 옵션

응답 본문 파싱하기

JSON / Urlencoded

다중 파트

바이너리

응답 속성

응답 문자

응답 본문

응답 헤더 필드

응답 콘텐츠 타입

응답 상태

요청 중단하기

타임아웃

인증

다음 리다이렉션 따라가기

전역 상태를 위한 에이전트

쿠키 저장하기

+ 다중 요청을 위한 기본 옵션 +

데이터 전달 방식

다중 부분 요청

파일 첨부하기

필드 값

압축

응답 버퍼링

CORS

오류 처리하기

진행과정 추적하기

로컬 호스트에서 테스트하기

+ 특정 IP 주소 연결 설정하기 +

+ 로컬 호스트에서 깨지거나 보안되지 않은 HTTPS 무시하기 +

Promise 및 Generator 지원

브라우저와 node 버전

Agent

request

res.statusCode

should allow the send shorthand

with a callback

.end()

res.error

res.header

set headers

res.charset

res.statusType

res.type

req.set(field, val)

req.set(obj)

req.type(str)

req.accept(str)

req.send(str)

req.send(Object)

when called several times

.end(fn)

.then(fulfill, reject)

.catch(reject)

.abort()

req.toJSON()

req.options()

req.sortQuery()

req.set("Content-Type", contentType)

req.send(Object) as "form"

with req.type() set to form

when called several times

req.attach

req.field

req.send(Object) as "json"

when called several times

`GET` 요청

`HEAD` 요청하기

`POST` / `PUT` 요청

`Content-Type` 설정하기