Introduction
============

This plugin allows you to integrate cucumber with Trac. It will allow you to enter User Stories in a wiki page and execute them as part of a continuous integration build. The results of the story execution will then be displayed in the wiki page.


Example
=======

The following example will create a story named user_login with the tags wiki and login:
{{{
  #!CucumberStory
  #name: manage_login

  Feature: User login
    In order to use the site
    as an unauthenticated visitors
    i want to be able to login
  
    Scenario: Logging in
      Given I am on the homepage
      When I enter my login details
      And press "Login"
      Then I should see my name
}}}

If, when opening the page, the story has already been run and its output is present in the database


Use Cases
=========

The following is a list of possible interactions of the user with the plugin

New Feature is entered
----------------------

 * User edits page
 * User adds new story
 * new story is extracted and saved in a .feature file
   * the name for the file is taken from the macro parameters
 * callback to observers is made


Existing Feature (which has been run before) is displayed
---------------------------------------------------------

 * User visits a page with an embedded story
 * The story database is queried for the story
   * the key is taken from the macro parameters
 * result of story execution is displayed
   * scenarios are collapsed and coloured according to their status
   * error messages for failed steps are shown in a popup


New Feature (which has not been run before) is displayed
---------------------------------------------------------

 * User visits a page with an embedded story
 * The story database is queried for the story
   * the key is taken from the macro parameters
 * the database returns a record_not_found
 * a pending execution message is displayed


Existing Feature is edited
--------------------------

 * User edits page
 * User changes an existing story
 * new story is extracted and saved in a .feature file, overwriting the existing
   * the name for the file is taken from the macro parameters
 * callback to observers is made



Trac-Macros
===========

 * CucumberStory - wraps a story
   * Arguments:
     - name: name of the story, this must be unique
     - tags (optional): a number of tags to be associated with this story

Components
==========

CucumberPlugin
--------------
represents the plugin

Extension points:
 - observer: receives callbacks on add and edit of stories
 - database: interfaces with the story database
 - story_renderer: renders a story


CucumberDatabase
----------------
interface to the story database
 - saves and updates stories extracted from the wiki
 - returns the output for stories
 - maintains the mapping of story names to page names
   (this is required to be able to remove stories)

Configuration:
 - location: location of the story database


CucumberStoryRenderer
---------------------
renders story output to HTML


CucumberStoryMacro
------------------
macro for rendering a single story



Interfaces
==========

class ICucumberDatabase:
  def save_story(name, story, tags):
    """Save the given story under the given name with the given tags"""

  def get_story(name):
    """retrieve the output for given story, None if story has not yet executed"""


class ICucumberStoryRenderer:
  def render_story_output(story):
    """turn the output of the given story into HTML"""


class ICucumberObserver:
  def story_added(story_name, story, tags):
    """called when a new story is added"""

  def story_edited(story_name, story, tags):
    """called when an existing story is edited"""