Replies: 1 comment
-
Thank you for sharing your feedback! I'm one of the nock maintainers, and I've been working on a big refactoring that I couldn't complete due to several life events, but I hope to get back to it soon! I'm just catching up with 100s of notifications now, it will take me a while to get back on top of things. So be assured I'll get back to you on the discussion and your PRs, I just need some time |
Beta Was this translation helpful? Give feedback.
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
Hi!
I've been using nock for a couple years now and I have gone through its README a few times. It's pretty good and complete! Every time I do, I learn something new 😁 I thought I'd share some feedback and ideas for improvements that can help people better understand how to set up and use nock properly to maximize its value.
Suggestion: clarify distinction between scope and interceptor
I find that the distinction between "scope" and "interceptor" isn't clear in the docs. It's only deep under "Recording", in the warning in https://github.com/nock/nock#removeinterceptor, that I really figured it out. Instead, and because this is crucial to understanding the manual, I would suggest clarifying it up-front, explaining the difference - and relationship - between Scope and Interceptor. It's subtle, but a crucial difference.
Suggestion: document functions with Scope or Interceptor
Then each function could be documented more clearly with two things: which object (Scope or Interceptor) they belong to, and what type of object they return (Scope or Interceptor). E.g.
.get
is a Scope function that returns an Interceptor;.persist
is a Scope function that returns a Scope object;.times
is an Interceptor function that returns an Interceptor;.reply
is an Interceptor function that returns a Scope.I understand that you have type definitions, but our project is still written in vanilla JavaScript, so we didn't really benefit from Typescript definitions. 😮 (At least, it didn't catch errors like
nock.removeInterceptor(somethingThatsActuallyAScope)
😄 )Closing words
I eventually ended up "getting it right", but it took a while, and a couple of mistakes (like using
persist(false)
thinking it could be used to remove a persistent interceptor, or usingremoveInterceptor
on a scope! 😅). I think it's simple things like this which can make a pretty good and thorough manual even better.Wait, what about mocks?
PS: And I did not mention "mocks", but that also added to the confusion. By my understanding, it is a synonym for "interceptors"; if so, I think it wouldn't hurt to standardize the documentation and use "interceptor" where "mock" is used to designate one, such as in the
nock.cleanAll()
documentation:Beta Was this translation helpful? Give feedback.
All reactions