Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: Revise and accept RFC-001 (#1753)
- Loading branch information
1 parent
e1461a2
commit 921eacf
Showing
1 changed file
with
31 additions
and
22 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,43 +1,52 @@ | ||
# Analysis of lifecycle methods | ||
# Analysis of lifecycle methods (RFC-001) | ||
|
||
![](https://img.shields.io/badge/rfc-001-blue.svg) | ||
![](https://img.shields.io/badge/status-draft-orange.svg) | ||
![](https://img.shields.io/badge/status-accepted-brightgreen.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. | ||
In Nock v10/v11, the lifecycle methods are confusingly named, difficult to | ||
understand, and at times inconvenient. Unless they are studied carefully, it | ||
is easy to inadvertantly leave unwanted state in Nock. | ||
|
||
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. | ||
Nock doesn't automatically provide a way to assert that mocks have been | ||
satisfied; it's the caller's responsibility to do this for each mock. | ||
|
||
This RFC analyzes the most common use cases and the function calls | ||
currently needed for each one. Subsequent RFCs will propose changes to the | ||
lifecycle APIs which better afford these use cases. | ||
|
||
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) | ||
2. Completely reset Nock after a test. | ||
3. Allow unmocked requests only to certain hosts. | ||
4. Prevent unmocked requests entirely. | ||
5. Simulate network connection failures. | ||
6. Temporarily disable http call interception while preserving registered mocks. | ||
7. Turn Nock all the way off and clean up its state. (I haven't experienced | ||
a need for 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). | | ||
| Reset Nock after a test to its initial post-`require()` state | `nock.restore(); nock.cleanAll(); nock.enableNetConnect(); nock.activate()` | This is a lot of typing. Some developers may wish to abort response playback that is in flight. ([#1118][]) | | ||
| 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. | | ||
| 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. | | ||
|
||
## References | ||
|
||
- [#1441][] | ||
- [#1474][] | ||
|
||
[#884]: https://github.com/nock/nock/issues/884 | ||
[#1118]: https://github.com/nock/nock/issues/1118 | ||
[#1441]: https://github.com/nock/nock/issues/1441 | ||
[#1447]: https://github.com/nock/nock/issues/1474 |