HN Explorer

My project about BDD tests to Living Documentation

12 points by skyfantom ↗ HN
Hello, I'm working on the small project which dedicated to convert BDD tests to Living Documentation. I know there is similar projects, but i want to concentrate not on quality of tests, rather than how your product works.

I'm on the very start stage, but you know when you work on something that you feel cool, you always can't wait to share it.

Here few links: How Reek's documentation looks - https://documentation.world/public/projects/2

P.S. If you have BDD tests, and want to try don't hesitate.

7 comments

[ 3.2 ms ] story [ 14.5 ms ] thread
bionhoward
Love the idea to generate docs from BDD tests, as this can help with document driven development.

Since this is a tool for engineers, if you put install and usage examples in code in the docs, then it’s gonna help new users see how to get started quickly and how to use the features. Right now, it looks like a nice way to list features and see a green if the test passes, but it’s not helping the reader/user of the docs to use those tested behaviors from their perspective.

if the test code were automatically snippet’d inside those test blocks, then the reader who wants to use some behavior, can find that section, click on the test, and look at how you wrote the code to test it. Then all we have to do is write the test code the same way the user would write their code to use a service, and the docs will automatically have usage examples (the test code snippets)

A search box can help to filter the behaviors, especially since they’re nested, because nesting can reduce visual clutter but force you to spend time expanding many sections. Links to the repo code for both the tests and the implementation can help us jump into the process faster.

Cool project keep it up!

skyfantom
Thank you for ideas. Yes, search box and tags are going to be implemented in the next release.

I love that idea, about snippets, and it may works as 'fork this project into my account'.

anyway, thank you

ojhughes
BDD is a great idea in theory. In practice, the tests often become deeply nested in contexts, rely on shared state and can be very difficult to read. xUnit style tests are not perfect but the best choice for readability and maintainability
skyfantom
I have not used xUint, and can't compare, thanks for mention I will look. But there is always some ways to improve messed tests, like page objects or page components and so on.

BDD methodology in opinion serves to business goals. And it is not only about syntax, but about whole way to make projects.

ojhughes
I don't think BDD scales well with complex requirements, the end result gets quite messy in my opinion, here is an example [1]. xUnit tests usually have a method per test, much easy to reason about. Not to put you off, just that has been my experience and I usually try and steer people away from BDD test frameworks

1: https://github.com/cloudfoundry/cloud_controller_ng/blob/mas...

2rsf
While I agree that BDD doesn't scale well I don't understand how xUnit (which is a unit tests framework hacked into BDD if I understand correctly) can help with that ?

BDD is BDD regardless of the framework, you want to use the same syntax

Davidvdb1
Would have loved this tool for JVM! At the moment we use PicklesUI for (Living) documentation, quick and easy.