
My project about BDD tests to Living Documentation - skyfantom
Hello, I&#x27;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.<p>I&#x27;m on the very start stage, but you know when you work on something that you feel cool, you always can&#x27;t wait to share it.<p>Here few links:
How Reek&#x27;s documentation looks - https:&#x2F;&#x2F;documentation.world&#x2F;public&#x2F;projects&#x2F;2<p>P.S. If you have BDD tests, and want to try don&#x27;t hesitate.
======
Davidvdb1
Would have loved this tool for JVM! At the moment we use PicklesUI for
(Living) documentation, quick and easy.

------
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...](https://github.com/cloudfoundry/cloud_controller_ng/blob/master/spec/integration/v2_perm_spec.rb)

~~~
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

