Generate documentation from tests

[schleifenkauz]

What I really like with Spek is, that it does not only serve as a testing framework but also as a way of documenting code. Wouldn't it be cool, if one could extract some kind of documentation from a Spek. I think a good target format would be markdown. For example the following Specification

class CalculatorSpec: Spek({
    Feature("Calculator") {
        Scenario("addition") {
            When("adding numbers") {
                 // test code   
            } 
            Then("it should add") {
                 //test code
            }
        }
        Scenario("subtraction") {
            When("subtracting numbers") {
                 // test code   
            } 
            Then("it should subtract") {
                 //test code
            }
        }
    }
})

would generate the following markdown:

• Feature: Calculator
  • Scenario: addition
    • When adding numbers
      • it should add
  • Scenario: subtraction
    • When subtracting numbers
      • it should subtract

I could also imagine generating HTML in JavaDoc format, where Features would be analog to classes, Scenarios would be methods and the test code in the scenarios would be the description of the method. Of course one would need to name Features and Scenarios exactly like the classes and methods being documented. Probably there should be some annotation like @Specification(format: DocumentationFormat) to opt-in for the feature. Would do you think of it?

[raniejade]

Thanks for the report! Is this different from a test result? What benefit do we get from the generated doc?

[schleifenkauz]

It could be a kind of documentation, which would be used as a way of getting to know the code base by specific examples. The main advantage over the test results report is that to generate documentation one would not actually have to run the tests. For example in TDD you could write the Specification with Spek first. Then you could use the documentation generated from the test to guide the process of implementing the actual features.

[corlaez]

Maybe not the same thing but you could grep those with something like: Feature\(|Scenario\(|When\(|Then\(:

    Feature("Calculator") {
        Scenario("addition") {
            When("adding numbers") {
            Then("it should add") {
        Scenario("subtraction") {
            When("subtracting numbers") {
            Then("it should subtract") {