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).
You can also use chaining methods if you do not pass the callback function. Check here for details.
// chaining methodsinject(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
File uploads (multipart/form-data) or form submit (x-www-form-urlencoded) can be achieved by using form-auto-content package as shown below:
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:
The declaration file exports types for the following parts of the API:
inject - standard light-my-request inject method
bindInject - creates a new inject function with pre-configured default options
BoundInjectFunction - the return type of bindInject
DispatchFunc - the fake HTTP dispatch function
InjectPayload - a union type for valid payload types
isInjection - standard light-my-request isInjection method
InjectOptions - options object for inject method
Request - custom light-my-request request object interface. Extends
Node.js stream.Readable type by default. This behavior can be changed by
setting the Request option in the inject method's options
dispatchFunc - listener function. The same as you would pass to Http.createServer when making a node HTTP server. Has the signature function (req, res) where:
req - a simulated request object. Inherits from Stream.Readable by
default. Optionally inherits from another class, set in
options.Request
res - a simulated response object. Inherits from node's Http.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 the url
does not include an authority component. Defaults to 'localhost'.
headers - an optional object containing request headers. A header value may be an array of strings to simulate the same header being sent multiple times; the values are aggregated exactly as a Node.js HTTP server would expose them on request.headers (set-cookie is kept as an array, cookie values are joined with '; ', other values with ', '), while every individual value is preserved in request.rawHeaders.
cookies - cookies to encode onto the Cookie request header. See Cookies.
remoteAddress - an optional string specifying the client remote address. Defaults to '127.0.0.1'.
Notes:
You can also pass a string in place of the options object as a shorthand
for {url: string, method: 'GET'}.
Beware when using the Request option. That might make light-my-request
slower. Sample benchmark result run on an i5-8600K CPU with Request set to
http.IncomingMessage:
Request x 155,018 ops/sec ±0.47% (94 runs sampled)Custom Request x 30,373 ops/sec ±0.64% (90 runs sampled)Request With Cookies x 125,696 ops/sec ±0.29% (96 runs sampled)Request With Cookies n payload x 114,391 ops/sec ±0.33% (97 runs sampled)ParseUrl x 255,790 ops/sec ±0.23% (99 runs sampled)ParseUrl and query x 194,479 ops/sec ±0.16% (99 runs sampled)
inject.isInjection(obj)
Checks if given object obj is a light-my-requestRequest object.
bindInject(dispatchFunc, defaults)
Creates a new inject function with pre-configured default options. This is useful when you want to reuse common options like authentication headers across multiple requests.
dispatchFunc - listener function. Same as inject.
defaults - default options object that will be merged with each request. Supports all options from inject. They are deeply merged with request's options, which take precedence.
Returns a function with the same signature as inject(options[, callback]).
const { bindInject } = require('light-my-request')// Create a bound inject function with default authorization headerconst boundInject = bindInject(dispatch, { headers: { authorization: 'Bearer my-token' }})// All requests will include the authorization headerconst res1 = await boundInject({ method: 'get', url: '/protected' })const res2 = await boundInject({ method: 'post', url: '/api/data', payload: { foo: 'bar' } })// You can still add additional headers per requestconst res3 = await boundInject({ method: 'get', url:
delete, get, head, options, patch, post, put, trace. They will set the HTTP request method and 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:
Note: The application would not respond multiple times. If you try to invoke any method after the application has responded, the application would throw an error.
Inspect if Request or Response orignated from light-my-request
Both request and response added isLightMyRequest property to inspect if it is originated by
light-my-request.
This project has been forked from hapi/shot because we wanted to support Node ≥ v4 and not only Node ≥ v8.
All credits prior to commit 00a2a82 go to the hapi/shot project contributors.
Since commit db8bced the project will be maintained by the Fastify team.
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. Otherwise, it is serialized with JSON.stringify forcing the request to have the Content-type equal to application/json
query - an optional object or string containing query parameters.
body - alias for payload.
simulate - an object containing flags to simulate various conditions:
end - indicates whether the request will fire an end event. Defaults to undefined, meaning an end event will fire.
split - indicates whether the request payload will be split into chunks. Defaults to undefined, meaning payload will not be chunked.
error - whether the request will emit an error event. Defaults to undefined, meaning no error event will be emitted. If set to true, the emitted error will have a message of 'Simulated'.
close - whether the request will emit a close event. Defaults to undefined, meaning no close event will be emitted.
validate - Optional flag to validate this options object. Defaults to true.
server - Optional http server. It is used for binding the dispatchFunc.
autoStart - Automatically start the request as soon as the method
is called. It is only valid when not passing a callback. Defaults to true.
signal - An AbortSignal that may be used to abort an ongoing request. Requires Node v16+.
Request - Optional type from which the request object should inherit
instead of stream.Readable
payloadAsStream - if set to true, the response will be streamed and not accumulated; in this case res.payload, res.rawPayload will be undefined.
callback - the callback function using the signature function (err, res) where:
err - error object
res - 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 a json response payload and returns an object.
stream - a function that provides a Readable stream of the response payload.
cookies - a getter that parses the set-cookie response header and returns an array with all the cookies and their metadata.
'/admin'
,
headers: { 'x-custom': 'value' } // authorization header is also included
})
// Method chaining also works, but it overwrites the default options