Comments (12)
40 characters is totally arbitrary. A description should be as long as it needs to be to convey the information it needs to convey. Be concise, sure. But don't hold yourself to some magical limit, IMHO.
from betterspecs.
"not valid" conveys a lot less useful information than "has unexpected parameters"
I think it is bad practice to encourage vague specifications.
I shouldn't have to go searching for the subject or setup to find out what "not valid" means.
See also: http://xunitpatterns.com/Obscure%20Test.html#Mystery%20Guest
from betterspecs.
IMHO, 40 characters is really limiting -- may even result to much more confusion for the sake of meeting the 40 char limit. Conciseness is key though.
It's better if rephrased like this:
A spec description ideally should never be longer than 40 characters. If this happens you should split it using a context.
from betterspecs.
I think the example context here is vague and unhelpful compared to the original description. I like the 40 characters guideline, but the example is weak.
context 'when not valid' do
it { is_expected.to respond_with 422 }
end
I think it'd be better to recommend a clear context:
context 'with unexpected params' do
it { is_expected.to respond_with 422 }
end
from betterspecs.
Also, be careful with automatic spec descriptions. Consider this spec:
let(:user) { FactoryGirl.create(:user) }
its(:owner) { should eq user }
When you run this with the formatter doc
, or when the spec fails, the spec name is completely unreadable.
from betterspecs.
I think the output formatter is somewhat verbose. Because, in the example it doesn't matter whether it responses with 422 or not. It should response correctly, that's all matters. Telling about the output values are verbose.
from betterspecs.
I believe the "good" example should use is_expected.to
instead of should
as mentioned in the section "Expect vs Should syntax"
from betterspecs.
Yes, I fixed this with #115 and it was merged but @andreareginato has been slow pushing the new version to live.
from betterspecs.
Great news, thanks.
from betterspecs.
I've read the first three best practices now (describe, context, description length), and in 2/3, I agree to the counter arguments in the discussion:
Maybe I'm just missing something, it could possibly be because of my lack of experience.
from betterspecs.
I agree @ChaelCodes, your suggestion is much more descriptive of the actual context
from betterspecs.
I also agree with @ChaelCodes because I prefer specificity and try to write code in a dont-make-future-me-have-to-think-too-hard-about-this kind of way.
Along those lines, I could argue that some well-named variables could reduce more cognitive overhead when reading the various expected values that don't have obvious meaning (such as http response status codes from these examples). This allows us to keep our descriptions concise while also making each it
statement easier to instantly understand.
# I hoisted these because I'm pretending that there are more scenarios
let(:unauthorized) { 401 }
let(:unprocessable_content) { 422 }
context 'when logged out' do
it { is_expected.to respond_with unauthorized }
end
context 'with unexpected params' do
it { is_expected.to respond_with unprocessable_content }
end
This is a small side-step from the conversation directly about context copy, but still covers ways in which organic documentation can make code easier to read -- and I haven't seen that elsewhere in the docs.
from betterspecs.
Related Issues (20)
- Move from Heroku to Github Pages HOT 50
- Question / Possible addition HOT 5
- Adapt all "translation pages" to the new layout HOT 1
- Use an i18n tool to maintain translations HOT 9
- Merge latest PR changes into gh-pages HOT 14
- Bring back "Resources" section to gh-pages HOT 1
- Move translated texts to corresponding YAML file HOT 3
- Homepage stored in GitHub metadata is not a URL HOT 3
- one-liner `should` syntax should be 'GOOD' HOT 5
- Usage of described_class HOT 2
- Our very first issue! Yay! #1
- Provide a version for Chai.js HOT 4
- Feature / integration / acceptance spec styles HOT 2
- Invalid SSL certificate for https://www.betterspecs.org HOT 2
- Old Content HOT 1
- Call for maintainer HOT 11
- Help needed to launch the new version of Betterspecs HOT 9
- Broken link on "Here a nice presentation explaining how to mix them together."
- Integration specs: what about of using expectations inside "let" blocks
- Link to self-hosted, non-Relishapp RSpec documentation
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from betterspecs.