Skip to content
Permalink
Browse files

docs: RFC 001: Analysis of lifecycle methods (#1474)

  • Loading branch information...
paulmelnikow committed Mar 13, 2019
1 parent 253cb65 commit 9e9e65d1f58a99cd13b3e83caab0e8fe4e16e95f
Showing with 43 additions and 0 deletions.
  1. +43 −0 rfcs/rfc-001.md
@@ -0,0 +1,43 @@
# Analysis of lifecycle methods

![](https://img.shields.io/badge/rfc-001-blue.svg)
![](https://img.shields.io/badge/status-draft-orange.svg)

Nock's lifecycle methods are confusingly named, and at times are inconvenient.
It can take a lot of studying to understand how to use them. It's also easy to
misunderstand what these methods are doing, and leave unwanted state in
`nock`. This RFC analyzes the most common use cases and the function calls
needed for each one.

Nock doesn't automatically have a way to assert that mocks have been
satisfied; it's the caller's responsibility to do this for each one.

See
https://github.com/paulmelnikow/icedfrisby-nock/blob/master/icedfrisby-nock.js
for an attempt at getting the lifecycle right.

Subsequent RFCs will propose changes to the lifecycle APIs which better
accommodate these use cases.

## Typical use cases

1. Assert that all mocks have been satisfied.
2. Completely reset `nock` after a test.
3. Allowing unmocked requests only to certain hosts.
4. Preventing unmocked requests entirely.
5. Simulating network connection failures.
6. Temporarily disabling http call interception while preserving registered mocks.
7. Turn `nock` all the way off and clean up its state (\*\* I've actually never
wanted to do this, but wanted to include it in the analysis)

## Analysis

| Use case | Code | Assessment |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Assert that all mocks have been satisfied | `scopes.forEach(scope => scope.done())`. When using `nockBack`, `assert.deepEqual(scope.pendingMocks(), [])` | `done()` could have a more explicit name, though otherwise this is fairly clear. However it requires the caller to keep track of all the scopes, which is not ideal. |
| Reset `nock` after a test to its initial post-`require()` state | `nock.restore(); nock.cleanAll(); nock.enableNetConnect(); nock.activate()` | This is too much typing. |
| Forbid unmocked requests | `nock.disableNetConnect()` | This _looks_ okay, but it doesn't have the desired effect. Errors are received by the client code and often swallowed up by the application (#884). |
| Allow unmocked requests, but only to certain hosts | `nock.disableNetConnect(); nock.enableNetConnect('example.com')` | This is a common use case, and should be possible to do more succintly, with a single call. |
| Simulate network connection failure | N/A | This is what `disableNetConnect()` does today. However from the function name, it's not really clear this is the intention. |
| Temporarily disable http interception while preserving registered mocks | `nock.restore()` | This is a confusing name, as it only cleans _part_ of nock's state. |
| Turn `nock` all the way off and clean up its state | `nock.restore(); nock.cleanAll()` | `restore()` is a confusing name. This isn't the most common use case, so it is probably okay that it requires two function calls. |

0 comments on commit 9e9e65d

Please sign in to comment.
You can’t perform that action at this time.