Merge pull request #13 from ericclemmons/13-rebrand

v2 Readme

Author: ericclemmons

README.md

@@ -1,48 +1,204 @@
-![Back to the Fixture](./logo.jpg)
+<p align="center">
+  <img alt="node-recorder logo" src="./logo.gif" width="50%">
+</p>
 
-> Simple recording &amp; replaying of HTTP requests for predictable development &amp; testing.
+- Spend less time writing mocks & fixtures.
+- Automatically record new HTTP(s) requests.
+- Replay fixtures when testing.
+- Works well with [supertest](https://github.com/visionmedia/supertest).
+- Predictable, deterministic filepaths that match the URL:
 
-## Example
+  1. Call https://api.github.com/rate_limit.
+  1. `./__fixtures__/api.github.com/rate_limit/${hash}.json`
 
-Given a GraphQL server:
+     ```json
+     {
+       "request": {
+         "method": "GET",
+         "href": "https://api.github.com/rate_limit",
+         "headers": {...},
+         "body": ""
+       },
+       "response": {
+         "statusCode": 200,
+         "headers": {...},
+         "body": {...}
+       }
+     }
+     ```
+
+* Normalize the `request` & `response`.
+* Alias cookies & Oauth tokens to users, to avoid ambiguity.
+* Ignore requests you don't want to record.
+
+## Installation
+
+```shell
+$ yarn add node-recorder --dev
+# or
+$ npm install node-recorder --save-dev
+```
+
+## Getting Started
+
+- By simply including `node-recorder`, **all HTTP(s) requests are intercepted**.
+- By default, `RECORD` mode records new fixtures, and replays existing fixures.
+- When in `NODE_ENV=test` or `CI=true`, `REPLAY` mode replays existing fixtures, and throws an error when one doesn't exist.
+  _(So that local tests don't suddenly fail in CI)_
+
+### Recorder Modes
+
+- `bypass` - All network requests bypass the recorder and respond as usual.
+- `record` - Record only new network requests (i.e. those without fixtures), while replaying existing fixtures.
+- `replay` - Replay all network requests using fixtures. **If a fixture is missing, an error is thrown**.
+- `rerecord` - Re-record all network requests.
+
+### Using `node --require`
+
+```shell
+$ node -r node-recorder path/to/server.js
+```
+
+_(This also works with `mocha`!)_
+
+### Setting the `mode` via `RECORDER=...`
+
+```shell
+$ RECORDER=ignore node -r node-recorder path/to/server.js
+```
+
+### Using Jest
+
+Included is a `jest-preset` that will automatically include `node-recorder` and a custom plugin to make toggling modes easier.
 
 ```js
-import { recorder } from "back-to-the-fixture";
-import graphql from "express-graphql";
+// jest.config.js
+module.exports = {
+  preset: "node-recorder/jest-preset"
+};
+```
+
+Now, running `jest --watch` will add a new `r` option:
 
-export default graphql((req: Request, res: Response) => {
-  // 👇 Pull ?mode=record or ?mode=replay
-  const { mode } = req.query;
+```
+Watch Usage
+ › Press a to run all tests.
+ › Press f to run only failed tests.
+ › Press p to filter by a filename regex pattern.
+ › Press t to filter by a test name regex pattern.
+ › Press q to quit watch mode.
+ › Press r to change recording mode from "REPLAY".
+ › Press Enter to trigger a test run.
+```
 
-  // 👇 Create a recorder for this request
-  recorder.configure({ mode });
+Pressing `r` will toggle between the various modes:
 
-  return {
-    graphiql: true,
-    pretty: true,
-    schema
-  };
-});
+```
+  ╭─────────────────────────────╮
+  │                             │
+  │   node-recorder:  RECORD    │
+  │                             │
+  ╰─────────────────────────────╯
 ```
 
-- **Record** network calls – <http://localhost:3000/?mode=record>
-- **Replay** network calls - <http://localhost:3000/?mode=replay>
+### Configuring `recorder.config.js`
 
-Fixtures are stored based on their URL with the name `${hash}.${user}.json`:
+Within your project, you can create a `recorder.config.js` that exports:
 
+```js
+// recorder.conig.js
+module.exports = {
+  identify(request, response) {...},
+  ignore(request) {...},
+  normalize(request, response) {...}
+}
 ```
-.
-└── __fixtures__
-    └── api.github.com
-        └── rate_limit
-            └── 4280543676.all.json
+
+- `request` is the same as the fixture (e.g. `body`, `headers`, `href`, `method`), but
+  with an additional `url` property from https://github.com/unshiftio/url-parse to simplify conditional logic.
+- `response` contains `body`, `headers`, & `statusCode`.
+
+#### `identify` a `request` or `response
+
+This is useful when network requests are stateful, in that they rely on an authorization call first, then they pass along a token/cookie to subsequent calls:
+
+1. Suppose you login by calling `/login?user=foo&password=bar`.
+2. The response contains `{ "token": "abc123" }3. Now, to get data, you call`/api?token=abc123`.
+
+When recording fixtures, the token `abc123` isn't clearly associated with the user `foo`.
+
+To address this, you can `identify` the `request` and `response`, so that the fixtures are aliased accordingly:
+
+```js
+identify(request, response) {
+  const { user, token } = request.query
+
+  if (request.href.endsWith("/login")) {
+    // We know the user, but not the token yet
+    if (!response) {
+      return user
+    }
+
+    // Upon login, associate this `user` with the `token`
+    return [user, response.body.token]
+  }
+
+  // API calls supply a `token`, which has been associated with a `user`
+  if (request.href.endsWith("/api")) {
+    return token
+  }
+}
 ```
 
-This way, similar requests for different users/logins in your testing can be
-easily found.
+Now, when recorded fixtures will look like:
 
-## Installation
+- `127.0.0.1/login/${hash}.${user}.json`
+- `127.0.0.1/api/${hash}.${user}.json`
 
-```shell
-yarn add --dev back-to-the-fixture
+This way, similar-looking network requests (e.g. login & GraphQL) can be differentiated and easily searched for.
+
+#### `ignore` a `request`
+
+Typically, you don't want to record fixtures for things like analytics or reporting.
+
+```js
+// recorder.conig.js
+module.exports = {
+  ignore(request) {
+    if (request.href.includes("www.google-analytics.com")) {
+      return true;
+    }
+
+    return false;
+  }
+};
 ```
+
+#### `normalize` a `request` or `response`
+
+Fixtures are meant to make development & testing _easier_, so modification is necessary.
+
+- **Changing `request` changes the filename `hash` of the fixture**. You may need to `record` again.
+- `normalize` is called **before** the network request and **after**. This means that `response` may be `undefined`!
+- You can **change `response` by hand, or via `normalize` without affecting the filename `hash` of the fixture**.
+
+```js
+module.exports = {
+  normalize(request, response) {
+    // Suppose you never care about `user-agent`
+    delete request.headers["user-agent"];
+
+    // We may not have a response (yet)
+    if (response) {
+      // ...or the `date`
+      delete response;
+    }
+  }
+};
+```
+
+## MIT License
+
+## Author
+
+- Eric Clemmons

example/__tests__/graphql.test.ts

@@ -27,7 +27,7 @@ describe("/logout", () => {
       .get("/logout")
       .expect(
         "set-cookie",
-        "back-to-the-fixture-example=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT"
+        "node-recorder-example=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT"
       )
       .expect(302, "Found. Redirecting to /");
   });

example/routes/logout/index.ts

@@ -5,6 +5,6 @@ import session from "../session";
 export default express()
   .use(session)
   .use((req: express.Request, res: express.Response, next) => {
-    res.clearCookie("back-to-the-fixture-example");
+    res.clearCookie("node-recorder-example");
     res.redirect("/");
   });

example/routes/session.ts

@@ -4,7 +4,7 @@ import * as session from "express-session";
 export default express()
   .use(
     session({
-      name: "back-to-the-fixture-example",
+      name: "node-recorder-example",
       resave: false,
       saveUninitialized: false,
       secret: "secret"
@@ -13,10 +13,7 @@ export default express()
   .use((req, res, next) => {
     const cookie = req.get("cookie") || "";
 
-    if (
-      !cookie.includes("back-to-the-fixture-example") &&
-      req.path !== "/login"
-    ) {
+    if (!cookie.includes("node-recorder-example") && req.path !== "/login") {
       return res.status(403).send(`<a href="/login">Login</a>`);
     }
 

src/jest-preset.ts jest-preset.jssrc/jest-preset.ts renamed to jest-preset.js

@@ -1,11 +1,11 @@
 module.exports = {
   // ! Required for recorder to run across all tests
-  setupFiles: [require.resolve("./")],
+  setupFiles: [require.resolve("./dist")],
 
   // ! Required to prevent `rerecord` from triggering builds
   // ? Commenting this out, since it doesn't seem to be a problem
   // watchPathIgnorePatterns: [recorder.fixturesPath],
 
   // ! Required for `r` shortcut
-  watchPlugins: [require.resolve("./JestWatchPlugin")]
+  watchPlugins: [require.resolve("./dist/JestWatchPlugin")]
 };

jest.config.js

@@ -6,12 +6,12 @@ module.exports = merge(
   {
     moduleNameMapper: {
       // ! Don't use this, because Jest messes up polydev's require(...)
-      // "back-to-the-fixture": "<rootDir>/dist"
+      // "node-recorder": "<rootDir>/dist"
     },
     testEnvironment: "node"
   },
   require("ts-jest/jest-preset"),
 
   // @ts-ignore
-  require("./src/jest-preset")
+  require("./jest-preset")
 );

logo.gif

@@ -0,0 +1,90 @@
+<!DOCTYPE html>
+
+<head>
+  <link href="https://cdn.jsdelivr.net/npm/tailwindcss/dist/tailwind.min.css" rel="stylesheet" />
+  <style>
+    blink {
+      animation: blinking 1s infinite alternate-reverse ease-in-out;
+    }
+
+    /* http://brenna.github.io/csshexagon/ */
+    .hexagon {
+      position: relative;
+      width: 24px;
+      height: 13.86px;
+      background-color: #659f63;
+      margin: 6.93px 0;
+
+      top: 1px;
+    }
+
+    .hexagon:before,
+    .hexagon:after {
+      content: "";
+      position: absolute;
+      width: 0;
+      border-left: 12px solid transparent;
+      border-right: 12px solid transparent;
+    }
+
+    .hexagon:before {
+      bottom: 100%;
+      border-bottom: 6.93px solid #659f63;
+    }
+
+    .hexagon:after {
+      top: 100%;
+      width: 0;
+      border-top: 6.93px solid #659f63;
+    }
+
+    .play {
+      display: none;
+    }
+
+    .hexagon {
+      display: none;
+    }
+
+    @keyframes blinking {
+      0% {
+        opacity: 1;
+      }
+
+      49% {
+        opacity: 1;
+      }
+
+      50% {
+        opacity: 0;
+      }
+
+      100% {
+        opacity: 0;
+      }
+    }
+  </style>
+</head>
+
+<body>
+  <main class="flex h-screen justify-center items-center p-32 bg-grey">
+    <code class="bg-white rounded p-32 text-grey-darkest text-5xl flex justify-center items-center">
+      <blink class="rounded-full h-4 w-4 bg-red mr-2"></blink>
+      <span class="underline">Re</span>c<span
+        class="play text-white h-6 w-6 bg-grey-darkest rounded-full flex items-center justify-center text-2xl pl-1"
+        style="margin-top: 2px;">
+        <span class="-ml-px">►</span>
+      </span><span class="hexagon"></span><span class="hidden mt-1 text-green">⬡</span><span
+        class="h-6 w-6 -mt-6 mx-px relative" style="top: -1px;">
+        <svg version="1.1" viewBox="0 0 18 20" xmlns="http://www.w3.org/2000/svg">
+          <g fill="none" fill-rule="evenodd">
+            <g fill="#44883E">
+              <path
+                d="m18 14v-8c-7.321e-4 -0.7138-0.38183-1.3731-1-1.73l-7-4c-0.6188-0.35727-1.3812-0.35727-2 0l-7 4c-0.61817 0.3569-0.99927 1.0162-1 1.73v8c7.3215e-4 0.7138 0.38183 1.3731 1 1.73l7 4c0.6188 0.35727 1.3812 0.35727 2 0l7-4c0.61817-0.3569 0.99927-1.0162 1-1.73z" />
+            </g>
+          </g>
+        </svg>
+      </span>rder
+    </code>
+  </main>
+</body>