@mockyeah/fetch
Configuration
Logging
We use the debug
utility, so to see logs
in Node you can set environment variable DEBUG=mockyeah:*
, or in the browser
set localStorage.setItem('debug', 'mockyeah:*')
.
Options
The Mockyeah
constructor accepts a configuration object.
Defaults
{
"name": "default",
"noProxy": false,
"prependServerURL": false,
"noPolyfill": false,
"noWebSocket": false,
"host": "localhost",
"port": 4001,
"portHttps": undefined,
"adminHost": "localhost",
"adminPort": 4777,
"suiteHeader": "x-mockyeah-suite",
"suiteCookie": "mockyeahSuite",
"ignorePrefix": `http${portHttps ? 's' : ''}://${host}:${portHttps || port}/`,
"aliases": [],
"responseHeaders": true,
"latency": undefined,
"fetch": global.fetch,
"fileResolver": undefined,
"fixtureResolver": undefined,
"mockSuiteResolver": undefined,
"devTools": false,
"devToolsTimeout": 2000,
"devToolsInterval": 100,
"serviceWorker": false,
"serviceWorkerRegister": true,
"serviceWorkerURL": "/__mockyeahServiceWorker.js",
"serviceWorkerScope": "/"
}
name
Used to identify the origin of logged output.
noProxy
Boolean to disable proxying.
The proxy will transparently forward all non-matching requests onto their original URL. Proxying enables working with real APIs by default but partially mocking responses for some requests.
In a browser, for dynamic suites,
it will also pass any mockyeahSuite
cookie value as a x-mockyeah-suite
header,
since setting a cookie is often easier for users than setting a header.
Then you can hit your mockyeah
server's URLs like:
https://localhost:4001/https://api.example.com?foo=bar
https://localhost:4001/https://service.example.com/foo/bar
and allow the first to pass through to the actual origin by not defining any mocks, but mock the second with:
mockyeah.get('https://service.example.com/foo/bar', {
json: {
hello: 'there'
}
});
prependServerURL
For use with @mockyeah/server
, automatically prepend the mockyeah
server URL to outgoing fetch
requests.
This can be used for apps that don't have complex configuration mechanisms or control over re-wiring
all their code or configuration to use URLs with the mockyeah
server URL prefix.
noPolyfill
Boolean to disable mockyeah
polyfill from installing itself to replace the global fetch
.
You can still call mockyeah.fetch()
manually without polyfilling.
noWebSocket
Boolean to disable the attempt to connect to the admin server in a @mockyeah/server
(including the one included in @mockyeah/cli
) over WebSockets.
Keeping this enabled allows us to initiate recordings for requests going through @mockyeah/fetch
in the browser
from the @mockyeah/cli
or @mockyeah/server
(programmatically).
host
Host on which you're running @mockyeah/server
if you wish to integrate with that.
port
Port on which your @mockyeah/server
runs HTTP (or use portHttps
) if you wish to integrate with that.
portHttps
Port on which your @mockyeah/server
runs over HTTPS (instead of port
) if you wish to integrate with that.
adminHost
Host on which your @mockyeah/server
admin server runs if you wish to integrate with that.
adminPort
Port on which your @mockyeah/server
admin server runs if you wish to integrate with that.
suiteHeader
String for the header name to use to opt-in to suites dynamically.
suiteCookie
String for the cookie name to use to opt-in to suites dynamically.
ignorePrefix
A URL prefix that will always be stripped off of the request URLs before trying to match against mocks.
aliases
Aliases for match URLs, so that mocks for any of the URL prefixes in an alias set work for any of the others in its set too, to support sharing suites across various environments where service domains and base path endpoints may change. So with this configuration:
{
"aliases": [
[
"https://demo.api.example.com",
"https://test.api.example.com",
"https://api.example.com"
],
// more sets of aliases...
]
}
So now a mock like this:
mockyeah.get('https://api.example.com/some/endpoint', { text: 'hello' });
Would be able to respond identically to calls to:
https://demo.api.example.com/some/endpoint
https://test.api.example.com/some/endpoint
https://api.example.com/some/endpoint
modifyRequest
An optional function that can modify incoming requests before they are matched.
This lets you define custom rules for how requests are matched against your mocks,
giving you more power than aliases
or ignorePrefix
.
You can return a single request object to be matched, or an array of multiple requests against each of which a match attempt is made in order.
Say you wanted to strip a proxy prefix URL and remove a cookie:
{
modifyRequest: req => ({
...req,
url: req.url.replace('https://proxy.example.com/', 'https://'),
cookies: {
...req.cookies,
nope: ''
}
});
}
Or maybe support multiple API environments:
{
modifyRequest: req => [
req,
{
...req,
url: req.url.replace('https://api.example.com/', 'https://api.stage.example.com')
},
{
...req,
url: req.url.replace('https://api.example.com/', 'https://api.test.example.com')
}
];
}
The req
object looks like this:
{
url: string;
method: Method;
query?: DeepObjectOfStrings;
headers?: Record<string, string>;
cookies?: Record<string, string>;
body?: any;
}
responseHeaders
Boolean to disable mockyeah
's custom response headers:
x-mockyeah-mocked: true
Indicates the request matched a mock and responded with it.x-mockyeah-missed: true
Indicates the request missed all mocks.x-mockyeah-proxied: true
Indicates a missed request was proxied.
latency
A default latency for all mock responses. Can override per mock.
fetch
The fecth
API function you want to use to make requests. Can be window.fetch
or a polyfill you import and pass in.
fileResolver
An async function that loads files, receiving the fixture name/path as a first argument.
fixtureResolver
An async function that loads fixtures, receiving the fixture name/path as a first argument.
mockSuiteResolver
An async function that loads mock suites, receiving the suite name as a first argument.
devTools
Enable connecting to the mockyeah
DevTools Web Extension.
devToolsTimeout
Time in milliseconds after which requests blocked by polling for a DevTools connection will give up and proceed.
devToolsInterval
Time in milliseconds indicating how often to check for a DevTools connection during the devToolsTimeout
period.
serviceWorker
Whether to enable the service worker that mockyeah can use to echo client-side mocked requests to the Network tab in your browser's Dev Tools.
serviceWorkerRegister
Whether to auto-register the service worker file at serviceWorkerURL
.
You can ignore this if you're manually registering the mockyeah
route handlers in your own custom service worker.
serviceWorkerURL
Path to where you're hosting the mockyeah service worker file.
Should be somewhere you publish a script file that imports
@mockyeah/fetch/dist/serviceWorker
.
You can ignore this if you're manually registering the mockyeah
route handlers in your own custom service worker.
serviceWorkerScope
Scope path for which you want the service worker to apply.
Default of /
should work unless your app is
at a sub-path and you don't want the service worker
to interfere with other apps at different paths on the same host.