New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Fake docs improvement #2360
Fake docs improvement #2360
Conversation
docs/_releases/v10.0.1/fakes.md
Outdated
### When to use fakes? | ||
|
||
Fakes are alternatives to the Stubs and Spies, and they can fully replace all such use cases. | ||
|
||
They are intended to be simpler to use, and avoids many bugs by having immutable behaviour. | ||
|
||
The created `fake` `Function`, with or without behavior has the same API as a (`sinon.spy`)[spies]. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I thought adding this new lines to introduction would be too much for an introduction section. So moved one line from there to here.
docs/_releases/v10.0.1/fakes.md
Outdated
#### Using fakes instead of spies | ||
|
||
```js | ||
var foo = { | ||
bar: () => { | ||
return 'baz'; | ||
} | ||
}; | ||
// wrap existing method without changing its behaviour | ||
var fake = sinon.replace(foo, 'bar', sinon.fake(foo.bar)); | ||
|
||
fake(); | ||
// baz | ||
|
||
fake.callCount; | ||
// 1 | ||
``` | ||
|
||
#### Using fakes instead of stubs | ||
|
||
```js | ||
var foo = { | ||
bar: () => { | ||
return 'baz'; | ||
} | ||
}; | ||
// replace method with a fake one | ||
var fake = sinon.replace(foo, 'bar', sinon.fake.returns('fake value')); | ||
|
||
fake(); | ||
// fake value | ||
|
||
fake.callCount; | ||
// 1 | ||
``` | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this alternative use cases helps as I stated in the issue #2070
This is a great start, but the changes are in the wrong folder :) See https://github.com/sinonjs/sinon/blob/master/docs/CONTRIBUTING.md#documenting-the-next-release |
I moved the changes to latest docs. I wonder how I can run examples in the repo. I am asking because when I do the following I get an error:
The error
When I install The other error
Installing supports-color does not help here, same error happens if I do that. |
@srknzl You touch upon something that I was fiddling with just a few weeks back, but I was surprised to see that I have not committed any of those changes. I don't remember quite what I was doing even ... You can run the tests from the root easily:
That again only runs the same things you just did (from the
I did not get exactly the same errors as you did, but I think I fixed the issues up now. Try pulling and rebasing on top of master. In any case, the errors were just about the linting (no idea what the local rules thing was about), and the tests ran fine on my machine at least, even if eslint complained. |
I am trying to create fake examples with existing spy and stub examples. Is it a good approach? I can also add additional examples for methods that fake has but spy/stub does not have; what are they? I finished spy examples. There are two interesting things:
How many examples we will include for fake docs? Where we will put them? Any plans? I think it is better to plan this first. Am I supposed to write runkit examples only for existing snippets in the fake page? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How many examples we will include for fake docs? Where we will put them? Any plans? I think it is better to plan this first.
I think the way you did it looks just fine! But AFAIK, they are just in the examples source directory and they would also need to be included on the page for them to show, so that means editing the markdown as done for the other types.
Am I supposed to write runkit examples only for existing snippets in the fake page?
Yes. Not sure what else to do? Sinon is a collaborative effort, so if you think that something is missing, then feel free to add the changes you would like to see.
Converted all existing snippets to runkit + addressed your review points @fatso83 . I am open to another review at this point |
Thank you for all your efforts! Exemplary PR <3 |
I realized I did not used runkit snippets I wrote. Why did not you warn me :) Should I fix it in a separate pr? @fatso83 |
If you could, that would be great, @srknzl. Sorry, I did not check whether they were included in the markdown :( |
Purpose (TL;DR)
Tries to improve documentation for the fake API. Resolves #2070
Todo
I went over this comment, that has these bullet points:
yes, the list is complete except for usingPromise
I'm on it, I wanted open this pr so that you can check out current status.
Only
firstArg
was missing a reference, added that. Changed others' links so that they are linked to the exact same header.State that the listed props are just one of the many from the spies documentation and that you can refer to that for the complete list
Clarify the wording so that it becomes clear that 1. The Fakes API is an alternative to the Stubs and Spies API that can fully replace all such uses. 2. It is intended to be simpler to use, maintain and has a lot smaller API surface and avoids many bugs by having quazi-immutable Fake instances (the behavior cannot be changed after creation (unlike Stubs), but they do have internal state that changes when used, like the callCount and other stats) 3. A Fake instance has the API of a Spy (
I've done my best to make it clear.
How to verify
npm install
Checklist for author
npm run lint
passesMy Questions
Which versions should change? I changed v10.0.1 for now since I am not sure.