next-test-api-route-handler • Docs
next-test-api-route-handler / NtarhInitAppRouter
The parameters expected by testApiHandler when using appHandler.
NtarhInit<NextResponseJsonType>
• NextResponseJsonType = unknown
appHandler:
Partial<Omit<AppRouteUserlandModule,"GET"|"HEAD"|"OPTIONS"|"POST"|"PUT"|"DELETE"|"PATCH"> &object>
The actual App Router route handler under test. It should be an object containing one or more async functions named for valid HTTP methods and/or a valid configuration option. See the Next.js documentation for details.
optionalpagesHandler:undefined
optionalparams:Record<string,string|string[]>
params is passed directly to the handler and represents processed dynamic
routes. This should not be confused with query string parsing, which is
handled by Request automatically.
params: { id: 'some-id' } is shorthand for paramsPatcher: (params) => { params.id = 'some-id' }. This is useful for quickly setting many params at
once.
optionalparamsPatcher: (params) =>Promisable<void|Record<string,string|string[]>>
A function that receives params, an object representing "processed"
dynamic route parameters. Modifications to params are passed directly to
the handler. You can also return a custom object from this function which
will replace params entirely.
Parameter patching should not be confused with query string parsing, which
is handled by Request automatically.
• params: Record<string, string | string[]>
Promisable<void | Record<string, string | string[]>>
optionalrejectOnHandlerError:boolean
If false, errors thrown from within a handler are kicked up to Next.js's
resolver to deal with, which is what would happen in production. If true,
the testApiHandler function will reject immediately instead.
You should use rejectOnHandlerError whenever you want to manually handle
an error that bubbles up from your handler (which is especially true if
you're using expect within your handler) or when you notice a false
negative despite exceptions being thrown.
falseNtarhInit.rejectOnHandlerError
optionalrequestPatcher: (request) =>Promisable<void|Request>
A function that receives a NextRequest object and returns a Request
instance. Use this function to edit the request before it's injected
into the handler.
If the returned Request instance is not also an instance of
NextRequest, it will be wrapped with NextRequest, e.g. new NextRequest(returnedRequest, { ... }).
• request: NextRequest
Promisable<void | Request>
optionalresponsePatcher: (res) =>Promisable<void|Response>
A function that receives the Response object returned from appHandler
and returns a Response instance. Use this function to edit the response
after your handler runs but before it's processed by the server.
Note that responsePatcher is called even in the case of exceptions,
including unhandled exceptions (for which Next.js returns an HTTP 500
response). The only time responsePatcher is not called is when an
unhandled exception occurs and rejectOnHandlerError is true.
• res: Response
Promisable<void | Response>
test: (
parameters) =>Promisable<void>
test is a function that runs your test assertions. This function receives
one destructured parameter: fetch, which is equivalent to
globalThis.fetch but with the first parameter omitted.
• parameters
• parameters.fetch
Promisable<void>
optionalurl:string
url: 'your-url' is shorthand for requestPatcher: (request) => new NextRequest('your-url', request)