Here's a post I wrote after having an "aha moment" about how to efficiently keep my living documentation up-to-date and easily accessible. Enjoy!
The Importance of "Living Documentation" in BDD
I'm been trying to really get deep into CucumberJS recently and have been reading a few BDD books (BDD in Action and Specification by Example are my favorites). One thing that really stood out to me was how much emphasis they put on the output of your automated tests. These are far more than just a recording of "what happened" in your tests runs. These are the single source of truth for your requirements, a live page for anyone on the team to see, and a common language for your team to communicate efficiently. Gojko Adzic, author of Specification by Example, writes his book about how these reports increase in value with age and how incredibly useful they were to the "business as usual" team making small changes long after the original developers had moved on.
Hosting Your Reports Alongside Your Project
When I set my Angular projects live, I usually have a dist directory with all my minified files that are to be hosted. The contents of this dist folder get pushed to my gh-pages branch (a way to host sites for free on Github). The key thing to remember is that you can always add a folder directly inside of dist called something like, "living-documentation". In it you can put all of your generated reports, and viola. Now your reports are live! (or as we say in BDD land, living). You may even find it nice to set your karma and protractor config files to dump the reports directly into their respective subfolders under a main "living-documentation" folder that lives in the dist directory.
Eugene-sea himself, creator of the karma-cucumber-js project, responded to an issue I opened with a great comment explaining how his project is set up. He also gives a link to his cucumber report hosted on the gh-pages along with the project itself, noting that this was the most useful report in his project and that it is, "used by all parties (business, technical, non-technical) involved in projects to discover current state of business requirements".
Eugene-sea himself, creator of the karma-cucumber-js project, responded to an issue I opened with a great comment explaining how his project is set up. He also gives a link to his cucumber report hosted on the gh-pages along with the project itself, noting that this was the most useful report in his project and that it is, "used by all parties (business, technical, non-technical) involved in projects to discover current state of business requirements".
Living Doumentation == Automated Test Reports
As Eugene-sea states in his comment above, the reports ARE the living documentation. They are organically evolving in sync with the source code, and at any time any member of the team can take a look at them by visiting the url in a browser. They represent the automated tests and how your source code aligns with what the tests are expecting. Without hosting your test output, the non-programmers would have to go into the git repo, dig into the source code, find all the feature files and juggle them somehow... it just becomes too inconvenient and people stop using them. This is the way. This setup that I am recommending makes it so effortlessly easy and so in-your-face available that your team should want to read the reports and borderline enjoy reading the reports (I mean it's still work, right!).
Putting It In A Pipeline
Doing all of this manually is the first step to seeing how it all works, but having to regenerate all of your living documentation reports every time you want to push your code can get annoying very quickly! The best way, and really the right way, is to have a continuous integration pipeline in place that will build your project, run all the tests, host the reports, and host the project itself.
Open-Source Vs. Commercial
If you're new to BDD, automated testing, or continuous integration I highly recommend trying to set up your own CI pipeline with Github and Travis CI. It's totally free and gives you the power to really customize the steps in your pipeline any way you want. For commercial projects, almost all the companies I've seen were using Jenkins for CI. The implementation details of setting up each one will differ of course, but overall you're really doing the same thing in both cases: running the tests, building the project, hosting all the things, etc. In an open-source project it might be totally fine to have your living documentation public (then you can show it off to the world!). However, if you have a commercial project or just want to keep it on the low you can always add an authentication step to your living documentation pages or even host them at a different web address entirely. It's just html so can do whatever you want with it. You could even create a whole SPA dashboard for your living documentation!
RSS Feed