backdoorthen

Visit the v2 demo site here (v3 update to come)

Backdoor 🚪

Implement cheat codes in your apps.

With 1 input, control a promise's pending time, whether it resolves or rejects, and the data it returns.

It's especially convenient for working on functions that are lower in the promise chain.

Implementing this yourself on the fly is not hard work, but it can get messy and time consuming. Backdoor offers a plug-and-play approach that preserves the readability of your code.

Example:

You're working on a function called "doMoreAsyncThings" which relies on the output of a "createUser" call:

const createUser = (formData) => axios.post('/user', formData);

createUser(formData)
  .then(doMoreAsyncThings)
  .catch(handleError);

You don't want createUser to make an http request to the /user endpoint every single time you test the changes you make to doMoreAsyncThings.

At the same time, it'd be nice if you could maintain your ability to do so without having to update the code yet again...

This is possible by simply adding a backdoor to "createUser" (without changing "createUser" itself):

const backdoor = require('backdoorthen');

// unchanged
const createUser = (formData) => axios.post('/user', formData);

const withBackdoor = backdoor({
  // the variable influencing the outcome
  input: formData.firstName,
  // mocked data returned on success
  resolvedValue: { userName: 'pparker' },
  // mocked data returned on error
  rejectedValue: { error: 'kaboom', message: 'oh no' },
  // object to override the library's defaults
  config: { /* omitted for brevity */ }
});

withBackdoor(createUser)(formData)
  .then(doMoreAsyncThings)
  .catch(handleError);

This allows you to control the behaviour of createUser just by typing different values in the firstName input field of your form. If you type "Peter", createUser will make a request to the server and actually create a user with "Peter" as a first name. If you type "backdoor", createUser will not be called, and doMoreAsyncThings will fire 5s later with { userName: 'pparker' } as its argument.

Note:

withBackdoor(createUser)(formData)
  .then(doMoreAsyncThings)
  .catch(handleError);

is so close to what your code would look like if you hadn't backdoored your promise. This makes it very easy to remove backdoor once you're ready for your final commit:

createUser(formData)
  .then(doMoreAsyncThings)
  .catch(handleError);

params

input | resolvedValue | rejectedValue | config

input

input required

This is the variable backdoor evaluates to decide the outcome.

By default a string is expected, and only the following values are recognized as meaningful triggers:

INPUT                    PROMISE
___________________________________________
"backdoor"            -> resolves slow (5s)
"backdoor-fast"       -> resolves fast (1s)
"backdoor-error"      -> rejects slow  (5s)
"backdoor-error-fast" -> rejects fast  (1s)

If your use case needs to rely on different values or different types entirely, you must configure an assessor in config.

resolvedValue

resolvedValue This is anything you want the mocked promise to return when it resolves (settles with success).

rejectedValue

rejectedValue This is anything you want the mocked promise to return when it rejects (settles with error).

params.config

const backdoor = require('backdoorthen');

const withBackdoor = backdoor({
  // ...params,
  config: { // optional
    fast, // delay in ms before the mocked promise settles
    slow, // delay in ms before the mocked promise settles
    separator, // string character separating keywords in the input (eg: "-" in "backdoor-fast")
    assessor, // function assessing the input to determine whether real or mocked data should be returned
    enabledInProd // boolean driving whether backdoor should continue to work in production (false by default)
  }
});

withBackdoor(thenable)().then().catch();

fast | slow | separator | assessor | enabledInProd (non-boolean values ignored)

Name           Required  Type      Default  Notes
________________________________________________________
fast           no        integer   1000     ms
slow           no        integer   5000     ms
separator      no        string    -
assessor       no        function
enabledInProd  no        boolean   false    boolean only

fast

fast default: 1000

Delay in ms before the mocked promise settles (0 is recognized)

slow

slow default: 5000

Delay in ms before the mocked promise settles (0 is recognized)

separator

separator default: "-"

String character separating the keywords backdoor looks for.

Eg: When the input is "backdoor-error-fast", by default backdoor recognizes the "backdoor", "error" and "fast" keywords because they're separated by a "-" character.

assessor

assessor If your use-case does not rely on strings or if you'd rather implement your own logic, you can define an assessor function that must have the following signature:

const assessor = (input, separator) => ({
  isBackdoor: boolean,
  doResolve: boolean,
  isFast: boolean
});

which you would then pass as a property of the config object:

const withBackdoor = backdoor({
  // ...omitted for brevity,
  config: { assessor: yourTailoredAssessor }
});
withBackdoor(thenable)().then(...);

Example:

const assessor = digit => ({
  isBackdoor: digit < 5,
  doResolve: digit <= 2,
  isFast: digit === 2 || digit === 4
});

isBackdoor

• true: skip the actual promise and return mocked data
• false: return the actual promise

doResolve

• true: the mocked promise will resolve with the mocked response
• false: the mocked promise will reject with the mocked error

isFast

• true: wait 1000ms by default (override with config.fast)
• false: wait 5000ms by default (override with config.slow)

enabledInProd

enabledInProd default: false

When set to true, backdoor will continue to work in a production environment.

When false and in a production environment, the actual thenable is always executed regardless of the input value.

Only the boolean true is valid. Anything else is interpreted as false.

Installation

npm i -D backdoorthen
# yes, the name "backdoor" was already taken...

Usage

const backdoor = require('backdoorthen');

or

import backdoor from 'backdoorthen';

(!) Note:

• For readability's sake this readme sometimes uses the words promise and thenable interchangeably.
• For accuracy's sake: this readme uses "promise" as a shortcut for function that returns a promise.