RSpec Site: "RSpec provides a framework for writing what we call executable specifications of program behaviour. Since that’s rather wordy, we usually just call them specs. Some other people call these things examples."
If I take a look at the examples on the RSpec site, I cannot help but wonder if just doing this (which they term "behaviour-driven development"), misses out on an important aspect of API documentation and the thought processes that should go into an API design. The missing element is explanation. In my experience, unless I force myself to explain my decisions to an audience (even a hypothetical one), I come up with too complex designs, inconsistent naming, and just generally too much hassle for the users of the API. Sometimes, complexity is warranted. But then, I believe it is important to justify it to your users. Show them why it's there.
The RSpec approach is, as I see it, simply a very concise way to write your tests twice: once in natural language, then in code. In the docs, they presumably cite the natural language version. Which is not checked at all. So I still much prefer the approach I took with JCite. Although I must say I like improved readability of RSpec's condition checking method names.
If I take a look at the examples on the RSpec site, I cannot help but wonder if just doing this (which they term "behaviour-driven development"), misses out on an important aspect of API documentation and the thought processes that should go into an API design. The missing element is explanation. In my experience, unless I force myself to explain my decisions to an audience (even a hypothetical one), I come up with too complex designs, inconsistent naming, and just generally too much hassle for the users of the API. Sometimes, complexity is warranted. But then, I believe it is important to justify it to your users. Show them why it's there.
The RSpec approach is, as I see it, simply a very concise way to write your tests twice: once in natural language, then in code. In the docs, they presumably cite the natural language version. Which is not checked at all. So I still much prefer the approach I took with JCite. Although I must say I like improved readability of RSpec's condition checking method names.
Comments
At the same time nothing prevents you from creating a "true" unit test with RSpec though.
I have been in software devt for many years now and I see that even after all the diktats and goading programmers cut corners on writing tests. It's like encouraging teenagers to embrace chastity: you just don't get high compliance and it is very hard to enforce it. The "pushback" always is that there are too many tests to write. Which is true; you really need to write much more test code than production code if you want to cover all the permutations of possible failure; many experts say 2:1 ratio is more like it. All the additional Test writing has a dollar cost associated with it and it is not lost on the money-watchers.
So it comes down to this - if you have to deal with the realistic scenario where fewer that ideal tests are written, which ones are the most crucial (the 'must not miss' variety)? The answer is the ones that ensure meeting the customer's request most directly. So there BDD is a great help.
And like I said, you can still use an RSpec like tool to go the extra distance to explain your logic to the user if you wish.