To be honest, I find them pretty hard to read and unhelpful. If the four types of documentation are tutorials, how-to guides, concept discussion, and reference, these rspec-as-documentation docs occupy an uncomfortable position between how-to guides and reference: they're neither detailed enough to act as a reference, nor narrative enough to act as a guide to solving any problem. They're slower to parse quickly than a equivalent prose and more complex than an equivalent code sample with a description.
They probably offer some value - I suppose I'd rather have literate tests than not, but they should be in addition to proper documentation, not instead of.
(disclaimer: I only really interact with that one example - rspec on relish - and I may be conflating flaws in that example with flaws in the whole technique)
Ward Cunningham gave us FIT which begat Fitnesse which eventually begat many flavors of Cucumber. This deserves more wailing and moaning from all of us than what we give to the wiki or the technical debt. For it is truly evil.
It's hard enough to get business folks to explain to us what they actually want. Trying to get them to code is a step too far.
And business-friendly frameworks are generally a PITA for us to maintain. And ugly. And wasteful.
RSpec, on the other hand, and the spec-like frameworks it's inspired in many languages, are intended as literate test programming, not as a business translation layer. They're tools for us to think and talk about software differently. They help us talk about behaviors while still being in our code.
Now if only PyTest folks could copy the "good parts" of RSpec instead of the output.
Or if someone would figure out a succinct, repeatable, reliable way to do more of our testing in Jupyter.
It wasnt meant to be written by business folks but it was meant to be at least semi-readable by them, but more importantly it was to serve as a template to generate documentation that was A) truly readable B) kept in sync with the code.
I dogfooded it in sessions where I would "pair" with business folks looking over my shoulder and they would read/speak and I would edit. This worked well.
I don't believe it's possible to get business folks to write this kind of document but I think it's both reasonable and valuable to A) use it as a tool to go back and forth on specs and B) decouple executable specification from code that executes tests.
I had a similar issue when I first picked rspec up over a decade ago. At first I was drawn to the allure of an approach that would have the tests better match the intention of a customer (more general BDD, and not just rspec). You’d sit down with the customer and write down what they wanted to happen in natural prose, the tests would (almost) write themselves, and the opportunity for misalignment or miscommunication would vanish!
Except it wasn’t natural prose. It ended up being ham-fisted attempts to write “as a user, when I…” style paragraphs that most closely matched whatever marchers already existed. Then there’s be nuance in the differences so you’d have to write specific assertions anyway. In the end it rarely felt like magic to me, and that I spent just as much time if not more writing and maintaining the test implementation as I’d always done. Just now with an extra layer of abstraction and misdirection.
At some point I realised the value wasn’t in BDD, it was just the conversations it was forcing. Nobody outside our team cared if the tests were green if it didn’t actually give them the outcome they wanted. There was no pointing feeling like you’d won on a technicality. So I switched back to implementing tests the way that was quickest and easiest for us. And writing the other forms of documentation others needed, in the formats that were best for them.
I remember struggling with this also. But if anything good came out of that era, it was
Given..
When..
Then..
which is the template I still use to this day. It works for developers writing the specs, new devs reading them and surprisingly it also works for non-techie types who request features. If a request comes in that doesn't state those three things, I'll walk the person through it. And occasionally they will have an epiphany of sorts.
An enlightening moment where they finally "get it". They get where communication has suffered in the past. I really love that part of my job. It's like being a translator between humans and aliens where previously they both just wanted to eat each other. But due to G/W/T they now want to build interstellar highways together and have hybrid babies.
https://relishapp.com/rspec/rspec-core/docs/helper-methods/a...
To be honest, I find them pretty hard to read and unhelpful. If the four types of documentation are tutorials, how-to guides, concept discussion, and reference, these rspec-as-documentation docs occupy an uncomfortable position between how-to guides and reference: they're neither detailed enough to act as a reference, nor narrative enough to act as a guide to solving any problem. They're slower to parse quickly than a equivalent prose and more complex than an equivalent code sample with a description.
They probably offer some value - I suppose I'd rather have literate tests than not, but they should be in addition to proper documentation, not instead of.
(disclaimer: I only really interact with that one example - rspec on relish - and I may be conflating flaws in that example with flaws in the whole technique)