Skip to content
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/
@@ -0,0 +1,43 @@
# Analysis of lifecycle methods


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.

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('')` | 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.