Add createStubInstance header in stubs.md #2576
Conversation
I kept scrolling past the parts of this page that explain `createStubInstance` so I created a section for it. I think the reason it didn't already exist is because it's considered a part of the utilities API, not the stub API. Even if that's the reasoning, I hope this PR is still a net positive, because personally, it makes it easier to find what I'm looking for.
| #### `var stubInstance = sinon.createStubInstance(MyConstructor, overrides);` | ||
|
|
||
| If you want to create a stub object of `MyConstructor`, but don't want the constructor to be invoked, use this utility function. |
There was a problem hiding this comment.
Maybe expose the fact that this method really is part of the sandbox? As in sandbox.createStubInstance.... Otherwise people might mix both sinon and sandbox invocations in the same file, I think.
Whatcha think?
There was a problem hiding this comment.
@fatso83 Yeah I wasn't even aware of that. Here's my knee-jerk thought: on this line, I think changing sinon to sandbox might confuse the reader more than it informs them: some readers may not know what sandbox is (yet) and assume they can't call this method on sinon. Maybe that's a good thing, but the sandbox docs say:
Unless you have a very advanced setup or need a special configuration, you probably only need to use that one in your tests for easy cleanup.
This could be far-fetched, but they might extrapolate that to mean createStubInstance is only for "very advanced setup or need a special configuration," too. For all I know, that's the intended interpretation, but I'm assuming it's not. I'm assuming it's used more often than non-sinon sandboxes.
That said, I do think this is useful information. Maybe it could be added as a detail below the header or in the link added by #2577 ?
I don't feel that strongly about anything I've said above: if you disagree with my take, I'm happy to make your suggested change.
There was a problem hiding this comment.
What about keeping the sinon.create... bits, but link to the sandbox.md docs for more elaborate examples?
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #2576 +/- ##
=======================================
Coverage 96.02% 96.02%
=======================================
Files 40 40
Lines 1912 1912
=======================================
Hits 1836 1836
Misses 76 76
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
|
I think this was mostly done, apart from a few tiny changes. Any chance you will get to complete this? Think it's less than 10 minutes of work. |
|
@DanKaplanSES ? should I move it over the finish line? |
Purpose (TL;DR) - mandatory
I kept scrolling past the parts of this page that explain
createStubInstanceso I created a section for it. I think the reason it didn't already exist is because it's considered a part of the utilities API, not the stub API. Even if that's the reasoning, I hope this PR is still a net positive, because personally, it makes it easier to find what I'm looking for.How to verify - mandatory
npm installThe documentation contribute in guide led me to believe that this doesn't apply to documentation changes. Let me know if I misinterpreted it, though.
Checklist for author
npm run lintpasses