Ideas about better documentation / comments in screen casts

[ZeusTheTrueGod]

I watched screencasts and noticed that it is paid no attention why the certain unit test is required. Also some developers don't get an idea which unit test help a lot and which is just does something and doesn't help anything to the reader.

So I just guess that this code on a screencast

//Ensure that a handler is properly attached to the div and updates its content
//Given:
var div = myHelper.createDiv('Foo');
div.on('click', {div.update('Bar');});
//Act:
t.click('div');
//Assert:
t.hasContent('Bar');

may create a bit better understanding what is tested with a certain test.

There are also some BDD style test frameworks for javascript, which make the test also a documentation itself, for example - https://github.com/SteveSanderson/knock ... haviors.js
I really like the rpsec syntax myself, it looks like one step further compared to a conventional unit tests:

describe "Class1 created without any parameters" do
    c = Class1.new
    it "does feature1" do
        c.do1(5).should_return 10
        
    end
    it "allow to do feature2" do
        c.do2().should be_empty
        ...
    end
end

This way tests , as I think, provide more values because they describe the behavior of certain classes.

So main idea here is that for examples and screencasts it worths to find a really good case when it is clear what exactly are we testing, what is a test case, what are steps and what do we check. At this moment screencasts are focusing on the testing framework itself, Siesta, and it is expected that a user is very good in tests himself and understands their purpose. I think a lot of Siesta users have no idea what to test.

[nickolay]

Yes, you made a good point about readability and clarification of tester's intent. Generally its up to developer - one can just provide good comments about what is happening in the test, but having some BDD syntax in place will be good too. We'll probably add some BDD sugar soon.