Michael Dowling's Whispers

This is the first part of many on how to use Spectacular, an open-source acceptance test / behavior driven development tool for development teams. This installment will focus on how to use Spectacular to create Executable Use Cases, and how those use cases can be executed using Selenese to drive a Selenium browser!

Part of why I wanted to write a tool like Spectacular is that I wanted to explore the possibility of using simplified Use Cases in the context of Epics in order to describe the overall requirement, in addition to using that Use Case to assist in creating stories during a story workshop. Of course, the one thing bugging me about the whole subject is that I would also want those Use Cases to be completely testable. Enter Executable Use Cases.

The idea works like this: Let’s say that during a story mapping workshop, an agile team identified an Epic/Activity for logging into a system as an existing user. They collaborated on a simple diagram showing how this would work:

Using this web-flow diagram as a guide, the team can now start to write a simplified use case in order to weed out some details and describe the user flow and interactions. In Spectacular, the requirement for a Use Case is to create a table with at least 2 columns (though 3 or more is typical, to describe ancillary details). The first row should be the title of the use case, with the word “Flow” in there (i.e. “Primary Flow: Log In” or “Alternate Flow: Remember Me Log In”). The next row are the column headers (“User Action”, “Expectation), followed by the use case itself. Additional columns are ignored by Spectacular:

Now that the team has written a use case, its time to make it executable. Many of the use cases I run into with my Agile teams are user-interaction based, which is what inspired me to giving user the ability to express a use case as a series of Selenese commands (in addition to writing the fixtures in Java, Ruby, and Groovy). Once the team has agreed to the use case details (and brainstormed user stories from this i.e. bad login, already logged in, etc.), the team opens up a text editor or IDE and writes the fixture in Selenese:

Flow: User navigates to system home page.
    open "/"
    waitForPageToLoad 5000

Expectation: User sees system home page with a header of "Home Page"
    verifyText "xpath://h1[class='mainHeader']" "Home Page"
    verifyText "id=loginLink" "Login"

Flow: User clicks login link
    click "id=loginLink"
    waitForPageToLoad 5000

Expectation: User sees a login form requesting credentials
    verifyElementPresent "id=usernameLogin"
    verifyElementPresent "id=passwordLogin"
    verifyElementPresent "xpath://input[@class='loginButton']"

Flow: User enters credentials and submits form
    type "id=usernameLogin" "myusername"
    type "id=passwordLogin" "mypassword"
    click "xpath://input[@class='loginButton']"
    waitForPageToLoad 5000

Expectation: User sees a landing page with a list of submitted articles
    verifyTitle "Welcome Michael!"
    verifyElementPresent "xpath://div[@class='article']"

Make sense? The Selenese code above in a text file in effect becomes the fixture code for our executable use case. Executing Spectacular would look like (assuming we named the Selenese file “login.selenese” and the spec as “SystemSpec.html”):

> Spectacular -fixtures ./login.selenese -specLocation ./SystemSpec.html
 -seleniumRCHost localhost -seleniumRCPort 4444
-seleniumRCInitialUrl http://system-uat/ -seleniumRCStartCommand *safari

(don’t worry, these commands can be stored in a project xml file so that running Spectacular doesn’t require such a long command line )

By default, results are output in the current directory as “TestResults.html”, which will be the same document the team wrote, but with annotated test results in the use case table. In our case, we haven’t written any implementation code yet, so it would look like this:

This is the essence of writing Executable Use Cases with Spectacular. For more details about how to write them or how to write the fixtures using other methods, visit the Spectacular EUC documentation.

Next in the “Using Spectacular” series, I’ll focus on how to document the executable use cases along with FIT and Gherkin/BDD tests and what they look like…

Boy, have I been busy the past couple months! And now, I’m comfortable enough to announce what I’ve been working on – my first major open-source project:

Spectacular: An Acceptance Test Driven Development tool for teams who like and/or must write official specs and who do not want to be constrained to a single ATDD tool.

Spectacular is an Acceptance Test Driven Development (ATDD) / Behavior Driven Development (BDD) tool that aggregates several different types of testing frameworks into 1, and it also introduces the idea of Executable Use Cases (EUC) – if you have to write use cases, you might as well make them Not Suck.

The idea is that a Business Analyst (BA), Quality Assurance engineer (QA), or Developer can write a spec in any way they feel comfortable with, including diagrams and business rules if necessary. They can write tests in the form of Executable Use Cases, BDD-style tests (Gherkin/Given-When-Then scenarios), and/or FIT-style tests all within the same document. The tool will run through the document, “detect” test cases, execute them, and print out the results in the same format as it was input.

Why build Spectacular?

I work at a large financial services company, where compliance with Sarbanes-Oxley (SOX) and Office of the Comptroller of the Currency (OCC) rules and regulations is of utmost importance, specifically with the audit requirements.

I suspect that there are many, many organizations out there who have to comply with the same set of rules, so I took what I learned about SOX and OCC audit requirements, combined them with what I learned at Elisabeth Hendrickson’s AMAZING ATDD course, and created Spectacular to make writing requirements more natural while also making those same documents executable, and not restricting any team to any single tool.

Also, I found through practical application of various ATDD tools that they are all pretty amazing and useful, but it was really annoying to use all these various tools to write specs and tests in different ways located in different locations depending on the tool being used. Plus, I would suspect that most teams would prefer to write story tests in a single document in a single format rather than having them live all over the place.

Isn’t this whole idea… un-Agile?

I don’t think so. Actually, I think something like Spectacular will help any large organization with an established corporate hierarchy and previous experience writing specifications in a use-case format adopt Agile more easily, especially those with “hardened” quality-assurance/quality-control groups. In my experience, these large organizations can be like “steering the Titanic with a small rudder” when it comes to transitioning to a more Agile process – allowing teams to continue writing requirements in the form of Use Case flows and documenting the tests in the same document will let them experiment with the various ATDD best-practices while remaining compliant with their regulatory bodies.

Spectacular helps those teams constrained with writing full-specs by allowing those teams to write the specs with tests embedded in them. Agility is introduced because those specs – written in a format they are used to – are now executable. A core Agile practice IMHO.

Use Cases? Really?

Yes, really. Use cases can tell a lot of the “story” if written well. Use cases, just like implementation code when written after a unit test is written, can be written well if there a constraint of execution behind it. Also, traditionally use cases have been taken to a far extreme of complicated. Not necessary IMHO.

To me, Use Cases fill the role of “Epic Spec” in an agile process. I’m a huge believer in the practice of Story Mapping and Persona Development (from Jeff Patton and Dave Hussman, respectively. Two of my personal geek-heroes). While doing your story mapping workshop, the high-level “activities” that you decompose into stories can very easily be Use Cases. In fact, in my experience writing Use Cases to explain the high-level activity (or “Epic”) can help to decompose it into discreet stories. And as such, each level of requirement-granularity (from Epic/Use Case to the Story) requires a different way to test it.

As such, I use Spectacular myself to execute Use Cases against Epics, and BDD/Gherkin and FIT tests to execute Stories.

Enough already. I get it. Show me how it works…

I don’t know about the rest of you, but I hate it when I stumble upon a useful open-source tool only to find that the documentation is poorly written. Now, I’m not saying Spectacular’s docs are amazing, but I did spend some time writing a good amount to make sure people could pick up Spectacular and use it relatively quickly. All of the docs are located at the Spectacular Wiki on Google Code. I welcome all feedback so that the documentation can be improved!

But here’s an example. Given a document:

Activity: Registration

(Executable Use Case)

Business Rules:

• Username must not exist in system already
• Email must not exist in system already
• User must be 18 years or older
• User must supply a username, email address (well formed), birth date, password.
• User must confirm password before proceeding

Story: As a new user not already registered I want to register myself so that I can use the system.

(BDD/Gherkin Executable Test)

Story: As a new user not already registered I should not be able to skip any data elements so that…

(FIT executable test)

With these requirements written, Spectacular will run through this document and parse out the tests (basically, anything contained in a table and fitting particular patterns) and execute test fixtures for each of these. While for version 1.0 Spectacular only supports Java (using JBehave) for the BDD/Gherkin and FIT tests, Executable Use Case fixtures can be written in Java, Groovy, Ruby (experimental – using JRuby), and Selenese (to directly drive a browser using SeleniumRC). The ability to write fixtures for BDD/Gherkin and FIT in other languages is coming soon! (I’d really like to be able to write BDD/Gherkin tests using Cucumber as the engine if possible)

• How to write a fixture for Executable Use Cases
• How to write a BDD/Gherkin fixture
• How to write a FIT fixture

In Conclusion…

Try it out! I hope the Agile community finds some use out of this tool like I have. If you have any questions, you can leave them here in comments or join the users & dev lists.

Attribution

Much of Spectacular is based in part or whole from the following projects:

• JBehave
• FIT
• Cucumber

As well as from the teaching/writing/works from the following people:

• Alistair Cockburn (Use Case guru)
• Aslak Hellesoy (original author of Cucumber)
• Elisabeth Hendrickson (amazing ATDD instructor and mentor)
• Dan North (the BDD guy at ThoughtWorks)
• Liz Keogh (the JBehave gal at ThoughtWorks)
• Dave Hussman (agile Persona development)
• Jeff Patton (Story Mapping)

I haven’t updated my blog in a while…  sorry for that.  Besides my day job, I’ve been busily working on a new open-source project that has been in my head for quite a while now and I finally decided to just go for it.  I’m almost close to “announcing” it more publicly, but for right now I am gathering some feedback from colleagues before I unleash my horrifying code for the world to consume.

More later…

Here I thought I was going to have to bite the bullet and learn more than a little bit of Ruby by way of Behavior Driven Development.  I thought I was going to have to actually put my head down and start active coding in Ruby in order to use the Cucumber BDD framework, specifically to parse the Given/When/Then clauses.

I thought about writing my own framework to do just that in Java, and actually started to.  Then I went to the magical Google and – wouldn’t you know it? – I found JBehave.  Of course!  I knew Dan wouldn’t have let me down by making me go the way of Ruby   (not that there’s anything wrong with Ruby, I just like to take my sweet time drinking kool-aid )

I love how it is just as easy to write JBehave tests as it is to write Cucumber tests:

Given a user with the email address “someone@something.com” has not already registered with the system
When a user tries to register in the system with the email of “someone@something.com”
And a name of “Michael Dowling”
And a date of birth of “1/1/1985″ (yeah right)
Then register the user with an access token of “Registered”

In JBehave, being clearly well-designed in an IoC manner, asks you write the Steps to execute the above spec:

package minderupt.scenarios.steps;
 
import org.jbehave.scenario.annotations.Given;
import org.jbehave.scenario.annotations.Then;
import org.jbehave.scenario.annotations.When;
import org.jbehave.scenario.steps.Steps;
 
public class CreateUserSteps extends Steps {
 
	private String email;
 
	@Given("a user with the email address \"$email\" has not already registered with the system")
	public void checkForRegisteredUser(String email) {
		// code to check for pre-existing email
	}
 
	@When("a user tries to register in the system with the email of \"$email\"")
	public void registerUserWithEmail(String email) {
		// code to register with email
	}
 
	@When("a name of \"$name\"")
	public void registerUserWithFullName(String name) {
		// code to register with name
	}
 
	@When("a date of birth of \"$dob\"")
	public void registerUserWithDateOfBirth(String dob) {
		// code to register with DOB
	}
 
	@Then("register the user with an access token of \"$token\"")
	public void checkForCreatedUser(String tokenExpected) {
		// register user and confirm returned token, blah blah
	}
 
}

…and then write the actual test case, specifying configuration options and the actual steps to execute during the test:

package minderupt.scenarios;
 
import org.jbehave.scenario.JUnitScenario;
import org.jbehave.scenario.Scenario;
 
import minderupt.scenarios.steps.CreateUserSteps;
 
public class CreateUser extends Scenario {
 
	public CreateUser() {
		super(new CreateUserSteps());
	}
 
}

I like this approach for multiple reasons, not the least because I can re-use the steps for different spec documents utilizing the same language, but also, I can change the test case configuration so that on my dev machine (local build) I can run all the tests and simply outputthe results to my console, but in my CI system, the output goes out to some kind of standard reporting system in pretty HTML.  Yay.

Like I mentioned in a previous post, one of the things I want to do is be able to fully spec out a requirement in a document (in Word, HTML, Wiki, etc) which will have a mix of business logic rules, FIT tests, and BDD tests.  Then as part of a build, split out the FIT tests and run FIT against those, parse out the BDD tests and run those, and then output a report back into the combined document for the entire team to see.  Can’t be too hard, just a matter of parsing Word/HTML, recognizing the type of tests, and running them.  Integration project, really.

But I think it would be immensely useful, especially for organizations that (still) communicate over such types of documentation;  a behavior that I feel isn’t going away anytime soon.  Might as well make the transition a little bit easier, I think.