Björn
b963b3396c
|
5 years ago | |
---|---|---|
.. | ||
.dependabot | 5 years ago | |
lib | 5 years ago | |
test | 5 years ago | |
.travis.yml | 5 years ago | |
LICENSE | 5 years ago | |
README.md | 5 years ago | |
index.d.ts | 5 years ago | |
index.js | 5 years ago | |
package.json | 5 years ago | |
tsconfig.json | 5 years ago |
README.md
Light my Request
Injects a fake HTTP request/response into a node HTTP server for simulating server logic, writing tests, or debugging.
Does not use a socket connection so can be run against an inactive server (server not in listen mode).
Example
const http = require('http')
const inject = require('light-my-request')
const dispatch = function (req, res) {
const reply = 'Hello World'
res.writeHead(200, { 'Content-Type': 'text/plain', 'Content-Length': reply.length })
res.end(reply)
}
const server = http.createServer(dispatch)
inject(dispatch, { method: 'get', url: '/' }, (err, res) => {
console.log(res.payload)
})
Note how server.listen
is never called.
Async await and promises are supported as well!
// promises
inject(dispatch, { method: 'get', url: '/' })
.then(res => console.log(res.payload))
.catch(console.log)
// async-await
try {
const res = await inject(dispatch, { method: 'get', url: '/' })
console.log(res.payload)
} catch (err) {
console.log(err)
}
You can also use chaining methods if you do not pass the callback function. Check here for details.
// chaining methods
inject(dispatch)
.get('/') // set the request method to GET, and request URL to '/'
.headers({ foo: 'bar' }) // set the request headers
.query({ foo: 'bar' }) // set the query parameters
.end((err, res) => {
console.log(res.payload)
})
inject(dispatch)
.post('/') // set the request method to POST, and request URL to '/'
.payload('request payload') // set the request payload
.body('request body') // alias for payload
.end((err, res) => {
console.log(res.payload)
})
// async-await is also supported
try {
const chain = inject(dispatch).get('/')
const res = await chain.end()
console.log(res.payload)
} catch (err) {
console.log(err)
}
File uploads (multipart/form-data
) or form submit (x-www-form-urlencoded
) can be achieved by using form-auto-content package as shown below:
const formAutoContent = require('form-auto-content')
const fs = require('fs')
try {
const form = formAutoContent({
myField: 'hello',
myFile: fs.createReadStream(`./path/to/file`)
})
const res = await inject(dispatch, {
method: 'post',
url: '/upload',
...form
})
console.log(res.payload)
} catch (err) {
console.log(err)
}
This module ships with a handwritten TypeScript declaration file for TS support. The declaration exports a single namespace LightMyRequest
. You can import it one of two ways:
import * as LightMyRequest from 'light-my-request'
const dispatch: LightMyRequest.DispatchFunc = function (req, res) {
const reply = 'Hello World'
res.writeHead(200, { 'Content-Type': 'text/plain', 'Content-Length': reply.length })
res.end(reply)
}
LightMyRequest.inject(dispatch, { method: 'get', url: '/' }, (err, res) => {
console.log(res.payload)
})
// or
import { inject, DistpatchFunc } from 'light-my-request'
const dispatch: DispatchFunc = function (req, res) {
const reply = 'Hello World'
res.writeHead(200, { 'Content-Type': 'text/plain', 'Content-Length': reply.length })
res.end(reply)
}
inject(dispatch, { method: 'get', url: '/' }, (err, res) => {
console.log(res.payload)
})
The declaration file exports types for the following parts of the API:
inject
- standard light-my-requestinject
methodDispatchFunc
- the fake HTTP dispatch functionInjectPayload
- a union type for valid payload typesisInjection
- standard light-my-requestisInjection
methodInjectOptions
- options object forinject
methodRequest
- custom light-my-requestrequest
object interface. Extends Node.jsstream.Readable
typeResponse
- custom light-my-requestresponse
object interface. Extends Node.jshttp.ServerResponse
type
API
inject(dispatchFunc[, options, callback])
Injects a fake request into an HTTP server.
dispatchFunc
- listener function. The same as you would pass toHttp.createServer
when making a node HTTP server. Has the signaturefunction (req, res)
where:req
- a simulated request object. Inherits fromStream.Readable
.res
- a simulated response object. Inherits from node'sHttp.ServerResponse
.
options
- request options object where:url
|path
- a string specifying the request URL.method
- a string specifying the HTTP request method, defaulting to'GET'
.authority
- a string specifying the HTTP HOST header value to be used if no header is provided, and theurl
does not include an authority component. Defaults to'localhost'
.headers
- an optional object containing request headers.cookies
- an optional object containing key-value pairs that will be encoded and added tocookie
header. If the header is already set, the data will be appended.remoteAddress
- an optional string specifying the client remote address. Defaults to'127.0.0.1'
.payload
- an optional request payload. Can be a string, Buffer, Stream or object. If the payload is string, Buffer or Stream is used as is as the request payload. Oherwise it is serialized withJSON.stringify
forcing the request to have theContent-type
equal toapplication/json
query
- an optional object containing query parameters.body
- alias for payload.simulate
- an object containing flags to simulate various conditions:end
- indicates whether the request will fire anend
event. Defaults toundefined
, meaning anend
event will fire.split
- indicates whether the request payload will be split into chunks. Defaults toundefined
, meaning payload will not be chunked.error
- whether the request will emit anerror
event. Defaults toundefined
, meaning noerror
event will be emitted. If set totrue
, the emitted error will have a message of'Simulated'
.close
- whether the request will emit aclose
event. Defaults toundefined
, meaning noclose
event will be emitted.
validate
- Optional flag to validate this options object. Defaults totrue
.server
- Optional http server. It is used for binding thedispatchFunc
.autoStart
- Automatically start the request as soon as the method is called. It is only valid when not passing a callback. Defaults totrue
.
callback
- the callback function using the signaturefunction (err, res)
where:err
- error objectres
- a response object where:raw
- an object containing the raw request and response objects where:req
- the simulated request object.res
- the simulated response object.
headers
- an object containing the response headers.statusCode
- the HTTP status code.statusMessage
- the HTTP status message.payload
- the payload as a UTF-8 encoded string.body
- alias for payload.rawPayload
- the raw payload as a Buffer.trailers
- an object containing the response trailers.json
- a function that parses theapplication/json
response payload and returns an object. Throws if the content type does not containapplication/json
.cookies
- a getter that parses theset-cookie
response header and returns an array with all the cookies and their metadata.
Note: You can also pass a string in place of the options
object as a shorthand for {url: string, method: 'GET'}
.
inject.isInjection(obj)
Checks if given object obj
is a light-my-request Request
object.
Method chaining
There are following methods you can used as chaining:
delete
,get
,head
,options
,patch
,post
,put
,trace
. They will set the HTTP request method and also the request URL.body
,headers
,payload
,query
,cookies
. They can be used to set the request options object.
And finally you need to call end
. It has the signature function (callback)
.
If you invoke end
without a callback function, the method will return a promise, thus you can:
const chain = inject(dispatch).get('/')
try {
const res = await chain.end()
console.log(res.payload)
} catch (err) {
// handle error
}
// or
chain.end()
.then(res => {
console.log(res.payload)
})
.catch(err => {
// handle error
})
By the way, you can also use promises without calling end
!
inject(dispatch)
.get('/')
.then(res => {
console.log(res.payload)
})
.catch(err => {
// handle error
})
Note: The application would not respond multiple times. If you try to invoking any method after the application has responded, the application would throw an error.
Acknowledgements
This project has been forked from hapi/shot
because we wanted to support Node ≥ v4 and not only Node ≥ v8.
All the credits before the commit 00a2a82 goes to the hapi/shot
project contributors.
Since the commit db8bced the project will be maintained by the Fastify team.
License
Licensed under BSD-3-Clause.