mockaton 8.2.17 → 8.2.19

package/README.md

@@ -4,7 +4,7 @@
 ![NPM Version](https://img.shields.io/npm/l/mockaton)
 
 
-_Mockaton_ is a mock server for developing and testing frontend apps.
+_Mockaton_ is a mock server for improving the frontend development and testing experience.
 
 With Mockaton, you don’t need to write code for wiring your mocks. Instead, it
 scans a given directory for filenames following a convention similar to the
@@ -12,17 +12,26 @@ URL paths. For example, the following file will be served on `/api/user/1234`
 ```
 my-mocks-dir/api/user/[user-id].GET.200.json
 ```
-Also, you don’t need to mock everything. Mockaton can request from your backend
-the routes you don’t have mocks for. See `Config.proxyFallback` below.
 
 By the way, [this browser
 extension](https://github.com/ericfortis/devtools-ext-tar-http-requests)
 can create a TAR of your requests following that convention.
 
+Nonetheless, you don’t need to mock all your APIs. Mockaton can request from your backend
+the routes you don’t have mocks for. That’s done with `config.proxyFallback = 'http://mybackend'`
+
+## Multiple Mock Variants
+Each route can have many mocks, which could either be:
+- Different response __status code__. For example, for triggering errors.
+- __Comment__ on the filename, which is anything within parentheses.
+  For example, `api/login(locked out user).POST.423.json`
+
+
 ## Dashboard UI
 
-In the dashboard, you can manually select which mock variant to serve for a particular
-route. So you can test different scenarios without changing code or the database state.
+In the dashboard, you can select a mock variant for a particular
+route, among other options. But there’s also a programmatic API,
+which is handy for setting up tests  (see **Commander API** below).
 
 <picture>
   <source media="(prefers-color-scheme: light)" srcset="./README-dashboard-light.png">
@@ -64,7 +73,7 @@ This demo uses the [sample-mocks/](./sample-mocks) directory of this repository.
 
 Experiment with the Dashboard:
 
-- Pick a mock variant from the _Mock dropdown_ (we’ll discuss them later)
+- Pick a mock variant from the _Mock dropdown_ 
 - Toggle the 🕓 _Delay Responses_ button, (e.g. for testing spinners)
 - Toggle the _500_ button, which sends and _Internal Server Error_ on that endpoint
 
@@ -91,7 +100,7 @@ allows for checking out long-lived branches with old API contracts.
 ### Deterministic Standalone Demo Server
 Perhaps you need to demo your app, but the ideal flow is too complex to
 simulate from the actual backend. In this case, compile your frontend app and
-put its built assets in `Config.staticDir`. Then, from the Mockaton dashboard
+put its built assets in `config.staticDir`. Then, from the Mockaton dashboard
 you can "Bulk Select" mocks to simulate the complete states you want to demo.
 For bulk-selecting, you just need to add a comment to the mock
 filename, such as `(demo-part1)`, `(demo-part2)`.
@@ -99,8 +108,8 @@ filename, such as `(demo-part1)`, `(demo-part2)`.
 
 ## Motivation
 - Avoids spinning up and maintaining hefty backends when developing UIs.
-- For a deterministic and comprehensive backend state. For example, having all the possible
-  state variants of a collection helps for spotting inadvertent bugs.
+- For a deterministic, comprehensive, and consistent backend state. For example, having
+  a collection with all the possible state variants helps for spotting inadvertent bugs.
 - Sometimes, frontend progress is blocked waiting for some backend API. Similarly,
   it’s often delayed due to missing data or inconvenient contracts. Therefore,
   many meetings can be saved by prototyping frontend features with mocks, and
@@ -112,17 +121,7 @@ filename, such as `(demo-part1)`, `(demo-part2)`.
 - [Mock Server Worker](https://mswjs.io)
 
 ---
-
-## Multiple Mock Variants
-Each route can have many mocks, which could either be:
-- Different response __status code__. For example, for triggering errors.
-- __Comment__ on the filename, which is anything within parentheses.
-  - e.g. `api/login(locked out user).POST.423.json`
-
-Those alternatives can be manually selected on the dashboard, or
-programmatically (see **Commander API** section), for instance, for setting up tests.
-
-### Default Mock for a Route
+## Default Mock for a Route
 You can add the comment: `(default)` to a filename.
 Otherwise, the first file in **alphabetical order** wins.
 
@@ -147,7 +146,8 @@ export default [{ foo: 'bar' }]
 Return a `string | Buffer | Uint8Array`, but don’t call `response.end()`
 
 ```js
-export default (request, response) => JSON.stringify({ foo: 'bar' })
+export default (request, response) => 
+  JSON.stringify({ foo: 'bar' })
 ```
 
 Think of these functions as HTTP handlers, so you can
@@ -192,7 +192,7 @@ export default function listColors() {
 ---
 
 If you are wondering, what if I need to serve a static `.js`?
-Put it in your `Config.staticDir` without the mock filename convention.
+Put it in your `config.staticDir` without the mock filename convention.
 
 ---
 
@@ -239,13 +239,13 @@ permitted](https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file)
 For instance, if you have `api/foo/bar` and
 `api/foo`. For the latter you have two options:
 
-**Option A.** Place it outside the directory:
+**Option A.** 
 ```
-api/foo/
 api/foo.GET.200.json
+api/foo/bar.GET.200.json
 ```
 
-**Option B.** Omit the filename:
+**Option B.** Omit the filename.
 ```text
 api/foo/.GET.200.json
 ```
@@ -270,12 +270,12 @@ Defaults to `/(\.DS_Store|~)$/`
 
 ### `delay?: number` 🕓
 The clock icon next to the mock selector is a checkbox for delaying a particular
-response. The delay is globally configurable via `Config.delay = 1200` (milliseconds).
+response. The delay is globally configurable via `config.delay = 1200` (milliseconds).
 
 
 ### `proxyFallback?: string`
 Lets you specify a target server for serving routes you don’t have mocks for.
-For example, `Config.proxyFallback = 'http://example.com:8080'`
+For example, `config.proxyFallback = 'http://example.com'`
 
 
 ### `staticDir?: string`
@@ -283,8 +283,8 @@ For example, `Config.proxyFallback = 'http://example.com:8080'`
 - Use Case 2: For a standalone demo server. For example,
   build your frontend bundle, and serve it from Mockaton.
 
-Files under `Config.staticDir` don’t use the filename convention.
-They take precedence over the `GET` mocks in `Config.mocksDir`.
+Files under `config.staticDir` don’t use the filename convention.
+They take precedence over the `GET` mocks in `config.mocksDir`.
 For example, if you have two files for `GET /foo/bar.jpg`
 ```
 my-static-dir/foo/bar.jpg
@@ -293,18 +293,11 @@ my-mocks-dir/foo/bar.jpg.GET.200.jpg // Unreacheable
 
 
 ### `cookies?: { [label: string]: string }`
-The selected cookie is sent in every response in the `Set-Cookie` header.
-The key is just a label used for selecting a particular cookie in the
-dashboard. In the dashboard, only one cookie can be selected. If you need more
-cookies you can inject additional cookies globally in `Config.extraHeaders`.
-
-By the way, there’s a `jwtCookie` helper, which has a hardcoded header and
-signature. In other words, it’s useful if you only care about its payload.
 
 ```js
 import { jwtCookie } from 'mockaton'
 
-Config.cookies = {
+config.cookies = {
   'My Admin User': 'my-cookie=1;Path=/;SameSite=strict',
   'My Normal User': 'my-cookie=0;Path=/;SameSite=strict',
   'My JWT': jwtCookie('my-cookie', {
@@ -313,13 +306,21 @@ Config.cookies = {
   })
 }
 ```
+The selected cookie is sent in every response in a `Set-Cookie` header.
+
+By the way, the `jwtCookie` helper has a hardcoded header and signature.
+In other words, it’s useful only if you care about the payload.
+
+If you need to send more than one cookie,
+inject them globally in `config.extraHeaders`.
+
 
 
 ### `extraHeaders?: string[]`
 Note it’s a unidimensional array. The header name goes at even indices.
 
 ```js
-Config.extraHeaders = [
+config.extraHeaders = [
   'Server', 'Mockaton',
   'Set-Cookie', 'foo=FOO;Path=/;SameSite=strict',
   'Set-Cookie', 'bar=BAR;Path=/;SameSite=strict'
@@ -329,7 +330,7 @@ Config.extraHeaders = [
 
 ### `extraMimes?: { [fileExt: string]: string }`
 ```js
-Config.extraMimes = {
+config.extraMimes = {
   jpe: 'application/jpeg'
 }
 ```
@@ -361,7 +362,7 @@ import { parse } from 'yaml'
 import { readFileSync } from 'node:js'
 import { jsToJsonPlugin } from 'mockaton'
 
-Config.plugins = [
+config.plugins = [
   [/\.(js|ts)$/, jsToJsonPlugin], // Default 
   [/\.yml$/, yamlToJsonPlugin],
   [/foo\.GET\.200\.txt$/, capitalizePlugin], // e.g. GET /api/foo would be capitalized
@@ -385,14 +386,14 @@ function capitalizePlugin(filePath) {
 
 
 ### `corsAllowed?: boolean`
-Defaults to `corsAllowed = false`. When `Config.corsAllowed === true`, these are the default options:
+Defaults to `corsAllowed = false`. When `config.corsAllowed === true`, these are the default options:
 ```js
-Config.corsOrigins = ['*']
-Config.corsMethods = ['GET', 'PUT', 'DELETE', 'POST', 'PATCH', 'HEAD', 'OPTIONS', 'TRACE', 'CONNECT']
-Config.corsHeaders = ['content-type']
-Config.corsCredentials = true
-Config.corsMaxAge = 0 // seconds to cache the preflight req
-Config.corsExposedHeaders = [] // headers you need to access in client-side JS
+config.corsOrigins = ['*']
+config.corsMethods = ['GET', 'PUT', 'DELETE', 'POST', 'PATCH', 'HEAD', 'OPTIONS', 'TRACE', 'CONNECT']
+config.corsHeaders = ['content-type']
+config.corsCredentials = true
+config.corsMaxAge = 0 // seconds to cache the preflight req
+config.corsExposedHeaders = [] // headers you need to access in client-side JS
 ```
 
 
@@ -401,12 +402,12 @@ This defaults to trying to open the dashboard in your default browser in macOS a
 Windows. For a more cross-platform utility, you could `npm install open` and pass it.
 ```js
 import open from 'open'
-Config.onReady = open
+config.onReady = open
 ```
 
 If you don’t want to open a browser, pass a noop:
 ```js
-Config.onReady = () => {}
+config.onReady = () => {}
 ```
 
 
@@ -440,7 +441,7 @@ await mockaton.setRouteIsDelayed('GET', '/api/foo', true)
 ```
 
 ### Select a cookie
-In `Config.cookies`, each key is the label used for selecting it.
+In `config.cookies`, each key is the label used for selecting it.
 ```js
 await mockaton.selectCookie('My Normal User')
 ```
@@ -454,7 +455,7 @@ Pass an empty string to disable it.
 ### Reset
 Re-initialize the collection. So if you added or removed mocks they will
 be considered. The selected mocks, cookies, and delays go back to default,
-but `Config.proxyFallback` and `Config.corsAllowed` are not affected.
+but `config.proxyFallback` and `config.corsAllowed` are not affected.
 ```js
 await mockaton.reset()
 ```

package/package.json

@@ -2,7 +2,7 @@
 	"name": "mockaton",
 	"description": "A deterministic server-side for developing and testing frontend clients",
 	"type": "module",
-	"version": "8.2.17",
+	"version": "8.2.19",
 	"main": "index.js",
 	"types": "index.d.ts",
 	"license": "MIT",