From 124afd3aa4cb7321e10c800674d08a66ea2d0a10 Mon Sep 17 00:00:00 2001 From: Paul Melnikow Date: Sat, 19 Oct 2019 12:20:58 +0200 Subject: [PATCH 1/9] docs: Gently revise and accept RFC-001 --- rfcs/rfc-001.md | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/rfcs/rfc-001.md b/rfcs/rfc-001.md index 3df904462..1d25d2fee 100644 --- a/rfcs/rfc-001.md +++ b/rfcs/rfc-001.md @@ -1,7 +1,7 @@ # Analysis of lifecycle methods ![](https://img.shields.io/badge/rfc-001-blue.svg) -![](https://img.shields.io/badge/status-draft-orange.svg) +![](https://img.shields.io/badge/status-acccepted-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 @@ -19,25 +19,37 @@ for an attempt at getting the lifecycle right. Subsequent RFCs will propose changes to the lifecycle APIs which better accommodate these use cases. +The analysis here is based on the APIs in Nock v10 and v11. + ## 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) +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'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). | +| 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. | + +## 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 From 3fd3d6d568efbba5f08e01219a5179973decacaa Mon Sep 17 00:00:00 2001 From: Paul Melnikow Date: Sat, 19 Oct 2019 12:22:51 +0200 Subject: [PATCH 2/9] acccepted --- rfcs/rfc-001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/rfc-001.md b/rfcs/rfc-001.md index 1d25d2fee..d2981b65a 100644 --- a/rfcs/rfc-001.md +++ b/rfcs/rfc-001.md @@ -1,7 +1,7 @@ # Analysis of lifecycle methods ![](https://img.shields.io/badge/rfc-001-blue.svg) -![](https://img.shields.io/badge/status-acccepted-brightgreen.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 From 1dd05d5e4cb30ba1eea313ae3a4103569e36be60 Mon Sep 17 00:00:00 2001 From: Paul Melnikow Date: Sat, 19 Oct 2019 12:30:55 +0200 Subject: [PATCH 3/9] More edits --- rfcs/rfc-001.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/rfcs/rfc-001.md b/rfcs/rfc-001.md index d2981b65a..14f9dc35b 100644 --- a/rfcs/rfc-001.md +++ b/rfcs/rfc-001.md @@ -1,15 +1,15 @@ -# Analysis of lifecycle methods +# RFC-001: Analysis of lifecycle methods ![](https://img.shields.io/badge/rfc-001-blue.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 +In Nock v10/v11, Nock's lifecycle methods are confusingly named, and at times +are inconvenient. They are difficult to understand, and it is easy to +inadvertantly leave unwanted state in `nock` unless they are studied +carefully. 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 +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 one. See @@ -19,8 +19,6 @@ for an attempt at getting the lifecycle right. Subsequent RFCs will propose changes to the lifecycle APIs which better accommodate these use cases. -The analysis here is based on the APIs in Nock v10 and v11. - ## Typical use cases 1. Assert that all mocks have been satisfied. From 7387637539ee67b496214bb19a7c2b811c63a0ac Mon Sep 17 00:00:00 2001 From: Paul Melnikow Date: Sat, 19 Oct 2019 12:32:23 +0200 Subject: [PATCH 4/9] Tweak --- rfcs/rfc-001.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/rfc-001.md b/rfcs/rfc-001.md index 14f9dc35b..148d19b28 100644 --- a/rfcs/rfc-001.md +++ b/rfcs/rfc-001.md @@ -1,4 +1,4 @@ -# RFC-001: 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-accepted-brightgreen.svg) From ad4d1d6c33385ce8f788abfd92dd61e460b32f55 Mon Sep 17 00:00:00 2001 From: Paul Melnikow Date: Sat, 19 Oct 2019 12:34:02 +0200 Subject: [PATCH 5/9] More updates --- rfcs/rfc-001.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/rfcs/rfc-001.md b/rfcs/rfc-001.md index 148d19b28..a256598d6 100644 --- a/rfcs/rfc-001.md +++ b/rfcs/rfc-001.md @@ -3,22 +3,23 @@ ![](https://img.shields.io/badge/rfc-001-blue.svg) ![](https://img.shields.io/badge/status-accepted-brightgreen.svg) -In Nock v10/v11, Nock's lifecycle methods are confusingly named, and at times -are inconvenient. They are difficult to understand, and it is easy to -inadvertantly leave unwanted state in `nock` unless they are studied -carefully. 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, at times +inconvenient, and difficult to understand. Unless they are studied +carefully, it is easy to inadvertantly leave unwanted state in `nock`. 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 one. -See -https://github.com/paulmelnikow/icedfrisby-nock/blob/master/icedfrisby-nock.js -for an attempt at getting the lifecycle right. +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 accommodate these use cases. +See +https://github.com/paulmelnikow/icedfrisby-nock/blob/master/icedfrisby-nock.js +for an attempt at getting the lifecycle right. + ## Typical use cases 1. Assert that all mocks have been satisfied. From ec0918de48562ca8cce45fbdd74e920f45073542 Mon Sep 17 00:00:00 2001 From: Paul Melnikow Date: Sat, 19 Oct 2019 12:34:43 +0200 Subject: [PATCH 6/9] Styling --- rfcs/rfc-001.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/rfcs/rfc-001.md b/rfcs/rfc-001.md index a256598d6..933dee6b8 100644 --- a/rfcs/rfc-001.md +++ b/rfcs/rfc-001.md @@ -5,7 +5,7 @@ In Nock v10/v11, the lifecycle methods are confusingly named, at times inconvenient, and difficult to understand. Unless they are studied -carefully, it is easy to inadvertantly leave unwanted state in `nock`. +carefully, it is easy to inadvertantly leave unwanted state in Nock. 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 one. @@ -23,12 +23,12 @@ for an attempt at getting the lifecycle right. ## Typical use cases 1. Assert that all mocks have been satisfied. -2. Completely reset `nock` after a test. +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've actually never +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 @@ -36,12 +36,12 @@ for an attempt at getting the lifecycle right. | 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 a lot of typing. Some developers may wish to abort response playback that is in flight. ([#1118][]) | +| 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 From dbcfc235b74e6b0852bf5c3d1874d726036dd5b4 Mon Sep 17 00:00:00 2001 From: Paul Melnikow Date: Sat, 19 Oct 2019 12:35:31 +0200 Subject: [PATCH 7/9] Grammar --- rfcs/rfc-001.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rfcs/rfc-001.md b/rfcs/rfc-001.md index 933dee6b8..04e37c6cb 100644 --- a/rfcs/rfc-001.md +++ b/rfcs/rfc-001.md @@ -3,9 +3,9 @@ ![](https://img.shields.io/badge/rfc-001-blue.svg) ![](https://img.shields.io/badge/status-accepted-brightgreen.svg) -In Nock v10/v11, the lifecycle methods are confusingly named, at times -inconvenient, and difficult to understand. Unless they are studied -carefully, it is easy to inadvertantly leave unwanted state in Nock. +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 provide a way to assert that mocks have been satisfied; it's the caller's responsibility to do this for each one. From 482211a592189f9fe480f8e76e0c1e338c3d3469 Mon Sep 17 00:00:00 2001 From: Paul Melnikow Date: Sat, 19 Oct 2019 12:36:43 +0200 Subject: [PATCH 8/9] More copyedits --- rfcs/rfc-001.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/rfcs/rfc-001.md b/rfcs/rfc-001.md index 04e37c6cb..d0abb15d8 100644 --- a/rfcs/rfc-001.md +++ b/rfcs/rfc-001.md @@ -8,13 +8,11 @@ understand, and at times inconvenient. Unless they are studied carefully, it is easy to inadvertantly leave unwanted state in Nock. 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 one. +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 -accommodate these use cases. +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 From 9b8e8a5caccc47465784e95af8c81c3a271d3d59 Mon Sep 17 00:00:00 2001 From: Paul Melnikow Date: Sat, 19 Oct 2019 12:37:57 +0200 Subject: [PATCH 9/9] More copyedits --- rfcs/rfc-001.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/rfc-001.md b/rfcs/rfc-001.md index d0abb15d8..0ba2bf7fc 100644 --- a/rfcs/rfc-001.md +++ b/rfcs/rfc-001.md @@ -26,8 +26,8 @@ for an attempt at getting the lifecycle right. 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've actually never - wanted to do this, but wanted to include it in the analysis.) +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