Running easyb

easyb can be invoked via:

Command line

easyb comes with a command line runner that takes the name of a particular behavior or story you wish to run. You can optionally pass in a few different flag options to output various report formats as well.


  c:>java io.easyb.BehaviorRunner my/path/to/MyStory.groovy

If no additional arguments are specified, you'll see a report printed to System.out that looks something like this:


Running your story (Your.story)
Scenarios run: 1, Failures: 0, Pending: 0, Time Elapsed: 0.454 sec

1 behavior run with no failures

Want to run multiple behaviors or stories in a single run? Yep, easyb supports that too. Just pass multiple stories on the command line.


  c:>java io.easyb.BehaviorRunner my/path/to/MyStory.groovy my/path/to/MySecondStory.groovy

Note, the runner doesn't care if you run a specification or a story-- they are run the same either way! Easy, eh?

easyb supports a few command line arguments -- namely, you can pass in a -ef or a -e for exception reporting. The -ef filters an exception trace to remove a lot of the noise Groovy inserts in a call stack.

Story reporting via the command line

You can generate a story printout of an easyb story by passing in the -txtstory flag as follows:


  c:>java io.easyb.BehaviorRunner my/path/to/MyStory.groovy \
  -txtstory ./target/mystory.txt

Note, the line break in the above example is for formatting purposes only.

HTML reporting via the command line

To produce an HTML report, which lists the status and summaries of all stories and specifications executed during an easyb run, type:


  c:>java io.easyb.BehaviorRunner my/path/to/MyStory.groovy \
  -html my/path/report.html

The path to and name of the report is optional as easyb will attempt to create a default one if neither is provided.

XML reporting via the command line

If you'd rather produce an XML report, just pass in the -xml flag and provide a path where the xml report should be written. For instance, using the same example from earlier, if you'd rather have an XML report, simply type:


  c:>java io.easyb.BehaviorRunner my/path/to/MyStory.groovy \
  -xml my/path/report.xml

Note, the line break in the above example is for formatting purposes only.

Colored command line output

You can also show the executed stories by the command line, just pass in the -prettyprint flag as follows:


  $ java io.easyb.BehaviorRunner my/path/to/MyTestStory.groovy -prettyprint

Produces the output:


  1 scenario executed, but status is failure! Total failures: 1
    Story: myTest

      scenario show colored output
        given a string
        then it should be null
        given a number
        then it shouldn't be 0 [FAILURE: expected values to differ but both were 0]
        given an array
        then it should be pending [PENDING]

Additional command line arguments

easyb offers the ability to see exception stack traces via two flags.

  • For viewing exception traces, easyb offers two options:
    • -e for a full exception stack trace
    • -ef for exception stack trace filtering — that is, a lot of the noise associated with a Groovy exception stack is filtered out
  • You can run behavior tags by passing the -tags flag along with a single or comma-delimited list of tag names.

Ant

You can run your behaviors and stories via easyb's Ant task. It's easy:

  1. load the task (via Ant's taskdef)-- the class name is io.easyb.ant.BehaviorRunnerTask
  2. provide a location for a report (or series of reports) and then provide a fileset with the location(s) of your behaviors and stories

Defining the task looks like this:


  <taskdef name="easyb" classname="io.easyb.ant.BehaviorRunnerTask">
    <classpath>
      <pathelement location="${lib.dir}/release/easyb-xx.jar"/>
    </classpath>
  </taskdef>

Running the task looks like:


    <easyb>
      <classpath>
         <path refid="build.classpath" />
		 <pathelement path="target/classes" />
      </classpath>
     <report location="target/story.txt" format="txtstory" />
     <behaviors dir="${mybehaviors.dir}">
       <include name="**/*Story.groovy"/>
     </behaviors>
    </easyb>

The easyb task takes a number of options including:

  • failureFile -- path to file which will contain any failed behaviors
  • noExecute -- boolean, which allows you to generate a report without executing any stories
  • tags -- a single or comma-delimited list of tags to execute

Please note, report's have numerous formats, including html, xml, txtstory, and txtspecification.

Produces output:


    [easyb] Running story listener story (StoryListener.story)
	[easyb] Scenarios run: 2, Failures: 0, Pending: 0, Time Elapsed: 0.06 sec
	[easyb] 2 total behaviors run with no failures
	[easyb] easyb execution passed

  BUILD SUCCESSFUL
  Total time: 3 seconds

Failures

The point of having your behaviors run as part of your build is to notify you when they catch possible code problems. easyb also allows a user specified property to be set to true if the build fails.

This property is called failureProperty and using it would look like this


  <easyb failureProperty="easyb.failed">

That alone doesn't fail the build but puts the flexibility in your hands to fail it, print it or do nothing with it as you please. Here is a common example of using that property to fail a build:


  <fail if="easyb.failed" message="Execution halted as behaviors failed"/>

Now when a behavior fails our build will halt with output like so:


 [easyb] easyb is preparing to process 1 file(s)
 [easyb] 9 behavior steps run , but status is failure! Total failures: 1
 [easyb]   Failure -> then the dealer should win in BlackjackStory.groovy
 [easyb]   VerificationException: expected lossss but was loss:
 ....
 ....
 [easyb] specification failures detected!
 [easyb] easyb execution FAILED

BUILD FAILED
/blah/blah/build.xml:75: easyb reported a failure

Total time: 3 seconds

Now you can be more confident that your build hasn't been broken by a change since you get instant feedback on behavior failures.

Story Printing

easyb embraces the idea that stories are a link between the business requirements and your code. To help use those stories when talking to your clients about requirements, easyb provides a way to print out just the stories without a lot of geeky code.

To print out a story report via Ant, simply create a report element with its format attribute set to txtstory as follows:


  <report location="target/stories.txt" format="txtstory"/>

Here is some sample output:


9 behavior steps executed successfully  
 Story: blackjack
  scenario tie game when cards are dealt but dealer gets higher card
    given a game a blackjack game and both players have a score of 10
    when the dealer gets an Ace and you get a 10
    then the dealer should win
  scenario tie game when cards are dealt but player gets higher card
    given a game a blackjack game and both players have a score of 10
    when the dealer gets a 10 and you get an Ace
    then the player should win

That looks like something business users (or management) could understand-- they might even be able to *gasp* write them!

Maven

You can also run your behaviors and stories via easyb's Maven plugin as well as generate HTML story reports. It's easy as fully explained on the maven-easyb-plugin site. The latest versions of the easyb Maven plugin are available at Maven central, so you shouldn't need to configure anything beyond the plugin in your POM.

If you like living on the edge (or just want the latest features and don't mind that there might be some rough edges), then you can point your POM to the easyb snapshot repository:


  <project>
  ...
    <repositories>
      <repository>
        <id>sonatype-snapshots</id>
        <url>http://oss.sonatype.org/content/repositories/snapshots</url>
      </repository>
    </repositories>
    <pluginRepositories>
      <pluginRepository>
        <id>sonatype-plugin-snapshots</id>
        <url>http://oss.sonatype.org/content/repositories/snapshots</url>
      </pluginRepository>
    </pluginRepositories>
  ...
  </project>

IntelliJ

We have created an easyb plugin for IntelliJ that makes it super easyb to work with easyb specifications and to run and debug them. This plugin can be downloaded from the IntelliJ IDEA plug-in repository -- just check within your IDE's settings.

Eclipse

We have created an easyb plugin for Eclipse that makes it super easyb to work with easyb specifications and to run them.

Installing the plugin works as follows:

  1. Go to the Help menu and then select Software Updates...
  2. Hit the Add Site.. button and in the resulting dialog, for the location type: http://easyb.googlecode.com/svn/trunk/eclipse-plugins/io.easyb.eclipse.updatesite/
  3. Hit the Ok button
  4. Select the easyb Eclipse Update Site in the list box and then hit the Install... button