In-browser editor for RSpec stories

Posted by aslak.hellesoy

Try it out here, but please read on…

David (with the help from Pat Maddox and the RSpec list) has done some absolutely phenomenal work on RSpec lately, allowing executable user stories to be expressed in plain text. The plain text format of user stories is so simple that it should be easy to train non-programmers to write them. This is what has made Fit and FitNesse such useful and popular tools.

RSpec user stories are built up by scenarios, which again are built up of “canned steps” – or Givens, Whens and Thens. When the number of canned steps grows, it can be hard to edit a text file, because it can be hard to remember the exact wording of a step (and if the wording isn’t exact, it won’t work).

I’ve created a prototype for a browser based story editor. It has autocompletion for adding of new steps and in-place editing of parameters to existing steps. Steps can also be reordered.

The idea is that domain experts can work with this tool to add more stories, scenarios and steps and save them. The same tool would also allow users to run the stories and get the results back. Very much like FitNesse does, but adapted to RSpec and with a (hopefully) better user interface.

So far I’ve only fiddled with the browser/Ajax side of things. You can’t actually use this thing yet – but it’s a start.

Comments

Leave a response

  1. Scott TaylorOctober 24, 2007 @ 09:41 AM

    Wow. This looks great! Can’t wait until something functional is out.

  2. Aslak HellesøyOctober 24, 2007 @ 01:48 PM

    Try to add some steps, edit some values, reorder some steps and see how the plain text story is generated by the browser. This is what will be POSTed back to the server (where RSpec can parse it and run it again).

  3. Luis LavenaOctober 24, 2007 @ 02:14 PM

    Aslak, great work! (even for a prototype!).

    This will really help create user stories from customer POV… Also maybe another kind of Story (besides Rails).

    Looking forward for the release! ;-)

    Regards and thanks for your work on RSpec… all the contributors! :-)

    Luis

  4. Bryan HelmkampOctober 24, 2007 @ 04:15 PM

    Great work, Aslak!

    Starting on an Ajax editor for these was going to be my weekend project. Now hopefully I can spend that time building on what you’ve started.

    My brain has been racing with ideas for what this could do in the future…

    • Integrate with Subversion for committing test updates
    • Incorporate continuous build functionality (allowing both SVN commit triggered and manual builds, and of course auto-building w/ feedback as you edit your story)
    • Track story progress (both creation and results) history in a “dashboard” format. (e.g. “Bryan added scenario Foo”, “Story Bar now passes.”, “Joe updated Story Bar”, etc.)
    • Intelligent browsing of scenarios (“Show me all scenarios that use this step”)
    • Save the HTML from scenario steps to be inspected on the fly
    • Trigger runs of scenarios in a frame so you can watch them execute
    • TextMate links to relevant code everywhere
    • Pass/fail counts by feature (product backlog item)
    • Drill-down pass/fail history for everything (did this ever work? when has it been broken before?)

    The mind races on…

  5. Ben MabeyOctober 24, 2007 @ 07:04 PM

    This rocks! I have been playing around with doing something like this for a while, and it looks like you actually did it! What are your thoughts for server side? Bryan has lots of good ideas that would necessitate a specific server-side app for this and that would be really cool.

    However, I was thinking that a simple interface like what you have would be good enough if it could interface with Lighthouse and/or Trac. Have you seen jester by thoughtbot? http://thoughtbot.com/projects/jester It makes it easy to interface with RESTful APIs in JS much like ActiveResource. So, what I am suggesting is that this interface could connect to Lighthouse for all story tickets, parse them and post back appropriately. This also goes back to David’s idea (from the mailing list) about having rspec read stories from the Lighhouse API. I think this would have the advantage of being really light weight and avoid the need for another backend app… Because, we would really want these stories to be fed into our project management tool anyways- why not just have the browser send it direct?

    What are your thoughts?

  6. Bryan HelmkampOctober 24, 2007 @ 09:51 PM

    Ben—Not sure what you mean by “another backend app”, as RSpec currently doesn’t have any backend apps. :D

    I worry about a Trac or Lighthouse dependent approach for a few reasons:

    • After using both Lighthouse and Trac on real projects recently, they are both less than ideal ticket systems for both developers and clients
    • Even if one or both of those ticket systems were (close to) ideal, lots of people for one reason or another will not use them (personal preference, corporate standardization on something else, etc.)
    • Third, and I think most significantly, we’d have to seriously curtail the cool stuff this tool could potentially have due to the constraints of whatever ticketing system it is dependent on. A truly rich acceptance test workbench just simply will not fit into the confines of existing ticket systems, nor should it.

    I do think some ticketing system integration would be a nice feature, but I don’t think should be the system.

  7. Ben MabeyOctober 24, 2007 @ 10:37 PM

    Hey Brian, By “another” app I mean just one more app you need to setup, configure, and worry about to help you manage the project. So, instead of having customers having a login to lighthouse and a separate story app you could just host a static JS app that would interface with lighthouse. Don’t get me wrong though… I would love to have all the features you suggested and was thinking along the same lines. I just thought that more people would adopt such a app if it just overlayed there current system.

    But, I agree with you on all points and think a “truly rich acceptance test workbench” would be preferable.

    -Ben

  8. Aslak HellesøyOctober 24, 2007 @ 11:47 PM

    What I have created in the prototype is:

    • An example of what the HTML structure must look like (mostly dl, p, ul and li) plus a few class names
    • CSS and Javascript that can turn that simple HTML into a snazzy UI that modifies the DOM
    • Javascript that can turn the DOM (at any time) into RSpec’s current plain text format for stories

    My next step would be to implement a simple server side app that can receive requests for various things. I’m most likely going to use WEBrick (because it’s in Ruby’s stdlib and good enough for what it needs to do). This webapp would implement a RESTful API that could serve as the “standard” for other server side backends. The API I’m thinking of would be something like:

    • A POST (or GET request maybe) to get the HTML. In my implementation this would also run the stories, but all the client cares about really is getting back some HTML.
    • A POST or PUT request to ask for an edited (or new) story to be saved. This would just POST/PUT the plain text story. My implementation would write this to file (typically the same file that was “run” to generate the original HTML). The server side could also do svn commits.

    I am not going to make the client side AJAX stuff depend on anything in particular – it will just use this simple REST API. If someone wants to tie this into other apps like Lighthouse or Trac, that’s cool – but I think that should happen on the server. Either via a plugin mechanism in “my” server (which might be bundled with RSpec) or via some 3rd party server.

    Anyway – I appreciate all the ideas here – it’s great feedback. I’ll do the simplest things first, and we’ll take it from there…

    Currently my “app” lives in my private svn, but anyone is free to pull down the HTML and js. It’s not much – the rest is the latest beta of scriptaculous.

  9. VenkatNovember 01, 2007 @ 12:48 PM

    Hello Aslak:

    Sorry for the off the topic comment. I just wanted to let you know about a patch to Spec::UI that I had put in in the tracker for Rspec-ext Rubyforge project.

    Let me know if it would be useful to checkin or any modifications required.

    Regards, Venkat.

  10. Andre FoekenNovember 06, 2007 @ 04:06 PM

    Until then check my Langugae grammer and syntax highlighting for the plain text stories in TextMate :)

    http://www.movesonrails.com

  11. Aslak HellesøyNovember 16, 2007 @ 05:02 PM

    I’ve done some updates:

    • It now works on Safari. I haven’t even tried IE6/7 yet.
    • When you add steps that are not in the autocomplete, they get added the next time.
    • The initial stock steps are now in a hidden
        instead of the Javascript

      If you check out the application.js file, you’ll see that I’ve commented out some Droppable code. The intent is that steps can be deleted by dragging them onto the ‘Add step’ line (whether that’s intuitive or not is a different question). The delete part works fine, but adding the droppable has an unwanted sideeffect: Now the suggestions in the autocomplete are hidden underneath the drop zone! I’ll need help from some Scriptaculous wizzes to solve that.

  12. Aslak HellesøyNovember 19, 2007 @ 01:54 PM

    Ha! I just tried it in IE6 and it isn’t even close to working in that “browser”. Well, I’ll get there…

  13. Chris ParsonsDecember 12, 2007 @ 02:30 PM

    Hi Aslak,

    Very nice work. I’d be interested in submitting patches and helping develop this if you got a repository out for it….

    Thanks Chris