Installation, Setup and Usage documentation missing from README and wiki

[kristianmandrup]

Please provide more information on how to install it.

I assume that I should first create a Rails 2.3.8 or 3.0 application. Then install it as a plugin, but then what? What to do from here is not described. I imagine there would be a special Dashboard page at localhost:3000/documentation/features But this is not entirely clear. Please update the README and create some Wiki pages with more info on how to set it up and configure it.

Oh, I just discovered some info here:

http://cs3b.github.com/cucumber_fm/installation.html

But it was just random luck that I found it. I think many potential users won't understand that this is a demo and documentation site. We are used to having such information also presented in the main README and the github Wiki.

I will see if there is enough info there to get started ;)

Another thing: How do I tell it about team members, or is this gathered from git somehow? In the demo, team members have initials such as 'mc', but on a larger project such initials could easily conflict with either predefined special tags or names of application components etc.

The project looks really great and I would really like to use it and maybe help move it forward, if only there was more info on how to get started. Looking forward to some better documentation ;)

Thanks :)

Kristian

[cs3b]

Thanks for your suggestion.

I know that documentation is poor and i have to improve it - first the installation instructions - but I'm running out of time.

Another couse is that - inside Selleo - this tool is use by three different teams and projects so there is also need of adding functionalities. I'm very happy of this iterative work - we add small amount of functionality, we using it, and ajust it, and so on ...

Next thing is that i wann finish milestone 2 and make some refactoring and tests in different version of rails, and then update documentation so it would be fresh for version 0.2.0, status is here - http://bit.ly/bI0EtT - this list is not closed but just i said before i want to finish this before i get deeper in docs and screencasts

each tag that use only small a-z and it's long of 2 or 3 character is treat as developer tag - mean that he/she is responsible for that scenario, feature, below is link that show full configuration, and how you would see it's not complicated.

http://github.com/cs3b/cucumber_fm/blob/master/lib/cucumber_f_m/feature_element/component/tags.rb#L8 http://github.com/cs3b/cucumber_fm/blob/master/lib/cucumber_f_m/feature_element/component/tags.rb#L80

for now it's static, but in future it would be dynamic so every team could customize this (not every type, but most of them), and it would be ordered list so even tham more then one reqex would be able to catch the same tag, the priority of rules would fixed this

so for example the first regex (in ordered hash) could be:

:developer => /@(ben|tom|john)\z/

there will be yml config file to store this kind of information - that is on vcs

There a lot to explain in this project, and customization is cool but it never comes first - i have it in mind but i not able to implement it now - so be patient.

I hope that i will finish milestone two until end of week and update installation instructions.

I always value feedback, so thx once again that you share this suggestion

[kristianmandrup]

Thanks for the info :)

I sent a message last night to aslakhellesoy, asking why tags are esentially in the form of a symbols list, which really limits the options for a framework like cucumber FM.

Instead Gherkin should allow tags to be stated more like a hash IMO.

@wip @3 @mc => [:wip, :3, :mc]

My suggestion (hash tags)

@wip @estimate:3 @author:mc @author:krm => {:wip => true, estimate => 3, @author => [ 'mc', 'krm'] }

Find all not a wip, created by mc and estimate > 2

$ cucumber --tags author=mc, ~wip, estimate>2

What do you think? Would be awesome if you could get this into cucumber, or perhaps even look at implementing this yourself. I would like to take a look at it as well. You have any knowledge on the Gherkin language?

There is also the framework 'meat', which I think is a way to define cucumber features as pure ruby code using a ruby DSL. Perhaps would be a good way to start from here to see how it works behind the covers ;)

Would love to hear what you think about these ideas. Looking forward to v. 0.2. Thanks!

BTW: I had a similar idea as cucumber FM to get an overview of local projects. Check out my 'Odin' project. Would allow you to search/filter your local developer projects using tags etc. to fx find all rails3 projects using cucumber and so on.

[kristianmandrup]

I created this little issue with a feature suggestion:

http://github.com/aslakhellesoy/gherkin/issues/issue/74

Maybe you can work out something from there with the assistance of aleks?

[kristianmandrup]

I also just posted a lot of code to get started on this. I think it could almost work with the code refactoring I submitted for that issue (74). Good luck ;)

[kristianmandrup]

The code I submitted for this feature in the issue should mostly be working. My gherkin code passes the specs ;)

[cs3b]

I see that you have plenty of ideas

Tagging as you suggest would make defined tags more meaningful (although require more characters :) ) But issues is that you would have make it backward compatibility (it should not be very hard), otherwise it would be hard to put it to cucumber mainline.

What is - maybe - more important we have to or should defined scenario for each usage. When you look at cucumber itself it use tags for:

• defining specific technical requirements for test execution
• grouping features/scenarios - so we can run only what is important now
• there is also minor functionality as limiting tags but i have naver used it

If you look at Cucumber FM then tags are user for much more things ( some of them will never have value for test executing )

• it also group feature but in more dimension (component, bucket, responsibility)
• status that describe flow ( it also allow to build kanban view )
• estimation
• value
• scheduling and priority ( milestone, iteration, priority )
• for tracking dependencies (@need-wireframe, @:::mc @:::fv)

I still not sure how i would balance this but i'm experimenting - and from my perspective is too early to suggest changes in Gherkin - because i'm not sure about a lot of stuff. I probobaly change schema of tags, but i don't know how, it's glad to see ideas like yours, becuase it open my mind for new options.

But how i said before i wonna finish 0.2.0 and make refactoring and documentation, and take more feedback just like i get it from you, and then i will think what next.

[cs3b]

The code I submitted for this feature in the issue should mostly be working. My gherkin code passes the specs ;)

I'm realy wish you luck, but i'm unable to help you now with this

[kristianmandrup]

I think I can get the new tags working for Gherkin and cucumber tmrw. Almost there! It is backwards compatible so it won't interfere with any existing tags. In fact, looking inside Gherkin you will see that the list of tags IS translated to a hash, like {'@wip' => true, '@3' => true} in the current code!

With a few changes it could become

{'@state' => 'wip '@estimate' => 3} and so on...

And then

cucumber --tags @estimate>=3,@state:in:wip,done

Stay tuned!

Kristian

[kristianmandrup]

I have now created a Gherkin patch which allows for tag hashes and is completely backwards compatible!

http://github.com/kristianmandrup/gherkin/tree/tags_hash

kristian-mandrups-macbook-pro:gherkin kristianconsult$ rspec spec/gherkin/tag_hash_expression_spec.rb ........................

Finished in 0.03386 seconds 24 examples, 0 failures

kristian-mandrups-macbook-pro:gherkin kristianconsult$ rspec spec/gherkin/tag_expression_spec.rb ....................

Finished in 0.02649 seconds 20 examples, 0 failures

I will now make a pull request to aslak ;)

[cs3b]

nice job !!!

after i finish 0.2.0 a will think about putting it on cucumber fm

[kristianmandrup]

http://github.com/kristianmandrup/cucumber

Now supports the Tags hash feature in Cucumber. Was tested with my version of Gherkin that had it added and it now works perfectly!

Looking forward to see it in action sometime :) Should make cucumber FM much more simple and yet much more powerful!

Cheers!

[kristianmandrup]

In my solution it's a bit inconvenient that tags in Gherkin seem to be split by '\s+' instead of by '\s+@'. The latter would allow tags in the form of:

@wip @authors: mike_c sally_k brian_m @estimate: 3

And parse like

['wip', 'authors: mike_c sally_k brian_m', 'estimate: 3']

Translated into hash tags

{'wip' => true, 'authors' => ['mike_c', 'sally_k', 'brian_m'], 'estimate' => 3]

And still work the same...

[cs3b]

shame on me that i don't have time to try it :P - i will have time tommorow but your split regex is better, less strict for tags writing, and you really done great work with this, thx

[kristianmandrup]

Yeah, but I don't know how to do that split regex in Gherkin. Can't find the place where this is performed! I asked about it on Cucumber google group and sent a message to Aleks. I hope I will get an answer soon ;) But for now it works in the strict format... I'm sure we will find a solution for the split before the week is over!

No worry, no hurry!

[kristianmandrup]

You might wanna check this out ;)

http://blog.davidchelimsky.net/2010/06/14/filtering-examples-in-rspec-2/ http://github.com/rspec/rspec-core/issues/#issue/37 http://github.com/cavalle/steak

With steak and rspec 2, I think it is much easier and flexible to write your specs and here you have tag hashes naturally built-in :)

I think it would be pretty easy to have steak and rspec2 print out the specs as text files similar to Cucumber feature files for an overview. Maybe this could be integrated in cucumber FM in a future release?

I've so far had no response to my questions regarding how to tweak gherkins way of parsing the tag lines.

[kristianmandrup]

Improved gherkin tags parser. Now has support for some separators:

@status:..wip @authors:--brian_m;--sally_k @estimate:..3

I looked into the Gherkin parser to see if I could tweak it to allow spaces in the tag values, but to no avail. This fix however is almost as good. Makes it much more readable!

[kristianmandrup]

I have a solution for this now:

s = %{@authors: kristian_m, sally_k @wip}
ruby-1.9.2-rc2 > s.gsub(/(@\w+):\s+(\w+)/, '\1:\2').gsub(/(@\w+.*?),\s+(\w+)/, '\1;\2')
 => "@authors:kristian_m;sally_k @wip"

So essentially, you could have the Business Analyst features in a 'BA_features' folder which is read by cucumber fm. Here the BA can edit the features in the editor provided by cucumber fm. Then when saved, the text of the feature is run through the above gsub converter, to convert it to a valid feature that can be parsed by Gherkin. This 'Gherkin valid' feature could then be saved in the normal 'features' folder.

Alternatively (and better I think), the features could still be saved in the /features folder and then just perform the reverse gsub when reading it into cucumber FM.

ruby-1.9.2-rc2 > x = "@authors:kristian_m;sally_k @wip"
 => "@authors:kristian_m;sally_k @wip"
ruby-1.9.2-rc2 > x.gsub(/(@\w+):(\w+)/, '\1: \2').gsub(/(@\w+.*?);(\w+)/, '\1, \2')
 => "@authors: kristian_m, sally_k @wip"

That would do the trick!

[kristianmandrup]

I created a small gem that collects all the functionality in one place, and is independent of any evolution in Gherkin and Cucumber. Just a few small 'monkey patches'. Also includes the two-way feature converter as described. Now cucumber tags are finally just as powerful as in steak.

http://github.com/kristianmandrup/cucumber-hash-tags

[cs3b]

my job was consumed all my time (included sunday, saturday) so i'm not doing anything with now, but when i find some time i will follow up this toppic.

thx for your good job

[cs3b]

so far i will not be changing Gherkin, but this tags idea - I've to think about