Very nice narrative conversion example

[Douglas Squirrel]

Thanks to Eric for posting a nice example of improving test readability with narrative - the second version is _much_ more readable especially to a non-domain expert!

 

https://gist.github.com/665399

 

Think we should link to this on the welcome page (would that be OK Eric? Don't want to overexpose your source code).

[Eric Lefevre-Ardant]

Thanks. There is in fact some debate with my colleagues as to whether it is actually more readable. (remember: we are all technical guys; there are no analysts in our company)

I'm also still wondering what the appropriate level of abstraction would be for us. Should we show the URLs? the user-readable names of the buttons?

Final thoughts: I wonder what would happen if we were to generate documentation with your coming generator... and show that to all our users.

Eric

[Douglas Squirrel]

As Andy explained at CITCON we found the narrative versions much more readable for our own technologists, and that was the main motivator for us! (BAs and customers also find the readable tests useful, but not nearly so much as we do ourselves.)

 

Your experience may differ - for example

    beginAtAsQuant("/users/backtestHistory.html");

may be more readable to some techies familiar with the code and the meaning of the app's URLs than

    was_able_to(visitPage("backtest history"));

hence I think your question about what level of abstraction to use.

 

Am I missing something though in thinking that surely

    getBackTestStore().storeStrategy(QUANT, ENDED_SOLUTION_ID, ZipUtils.zip("import com.algodeal.marketrunner.strategies.*;\n @Instruments(futures=com.algodeal.marketData.instruments.Futures.CAC_40)\npublic class MyStrategy extends AbstractStrategy {}", "MyStrategy.java"));

    beginAtAsQuant("/users/paperTradeSolution.do?solutionId=" + ENDED_SOLUTION_ID + "&paperTrading=true"); // clicks on link executing javascript

is much less readable (it even needs an explanatory comment!) than  

    Given.the(quant).was_able_to(postStrategy(ENDED_SOLUTION_ID))

                    .was_able_to(startPaperModeOnThatStrategy())  

Right?

 

One audience for the scriptwriter output is definitely customers - there is one in particular who really like to see exactly what tests we are running.

[Eric Lefevre-Ardant]

You nailed it.

The part with the sample source code for a strategy is a good example of something that might be abstracted away to (at least) a constant, since it does not do anything interesting. A reason for it being here could be that there are no real penalties, in the sense that it does not make the (old-style) test much less readable.

However, in the context of using Narrative, it becomes a hurdle when trying to read the test as a story.

Some people will prefer sacrificing a little readability for seeing more of the test context gathered in the same method. Others will prefer the Narrative approach that encourage leaving only the important bits in the test method, to the expense of having to click around to see the detailed context.

Eric