diff --git a/rfcs/rfc-001.md b/rfcs/rfc-001.md index 3df904462..0ba2bf7fc 100644 --- a/rfcs/rfc-001.md +++ b/rfcs/rfc-001.md @@ -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