Tuesday, April 26, 2011

Events in acceptance tests

I've been recently experimenting with the idea of events in the acceptance tests.

With the current approach based on Cucumber-like tools I see the following problems:

  • Short scenarios share the same state but they prepare the state every time.
  • Long scenarios are hard to follow
  • Fixtures/Factories are in use, which makes the tests dependent on the implementation
  • Slow builds

The idea is to solve some of the problems by using events.

As "events" I mean the following concept:

  • Split tests into base scenarios and side scenarios
  • Base scenarios can trigger certain events
  • Side scenarios can declare which events they're interested in
  • When the base scenario triggers an event all the side scenarios are executed

In practice it means that some tests depend on other tests. However scary it sounds I believe the reward is worth the risk.

This is going to require more discipline than "normal" tests, you need to find out what are the best base scenarios and which are fine as side scenarios. In my opinion it comes down to better understanding the business domain - which is always critical to the success of the project.

It's important to note that the side scenarios have to leave the application state unchanged, they may create some new content, but it needs to be destroyed at the end of the tests or it must be a content that doesn't influence other tests.

Let's look at an example. In an e-commerce app I think this would be a base scenario.

admin.create_new_product("a book")
user. visit_main_page
user. add_to_cart("a book")
user. confirm_order
admin.should_see_new_order("a book")
This is the core scenario without looking at any side effects/side scenarios. The shop exists so that admin can sell products.
What are the possible side scenarios here? Several of them come to my mind:

  • user can find the product using the search box
  • google bot can find the product page
  • admin can edit the product data
  • user can recommend the product to his friend
  • the product is in the "recently added" box

As you see, all of the above require that the product is already created.

Here are some tests that require an order to be created by the user:

  • admins receive an email
  • the user data exist in the admin panel
  • the user receives an email

One way to look at it is that the requirements are implemented as events, so that:

admin.create_new_product("a book")
trigger("product:created", "a book")

user. visit_main_page
user. add_to_cart("a book")
user. confirm_order

admin.should_see_new_order("a book")
How can we implement an example side scenario?

With my current implementation it looks like this.

class SearchProductScenario

  def initialize(test_framework)
    test_framework.subscribe("product:created", self)

  def execute(options)
    product_name = options[:product_name]
    user         = options[:user]

    user.fills_in "query", :with => product_name
I've got a simple TestFramework class that is responsible for instantiating all of the scenarios. It's not fully automated yet. It works with RSpec now, but it's framework independent.

We use this approach in one of our projects. It's too early to say if it works well in development. In my opinion it will help with most of the problems stated at the beginning of this post. Scenarios should be shorter and focused on the core of the feature in test. Tests should run quicker as they can share the state with their base scenarios. Fixtures or factories are no longer needed. It's all at the cost of being disciplined in writing scenarios in a certain way.

What do you think about this approach?

Some good news for people interested in this concept! We've been discussing the ideas with other DRUG (Wroclaw Ruby User Group) people and we're going to release a gem which will include this idea. The gem will contain the best things from Cucumber and Steak, so the name is natural: bbq :)

Thanks for reading!

If you read this far you should Follow andrzejkrzywda on Twitter and subscribe to my RSS

Thursday, April 7, 2011

Object oriented acceptance testing

In my last blog post I highlighted the two problems that I have with Cucumber for acceptance testing:

  1. It's difficult to get the customer to write/read Cucumber scenarios
  2. Cucumber scenarios most of the time are procedural programming.

The story

Being aware of the problems mentioned above I started experimenting with my side project to find a better way. I prefer trying out new ways on my side project instead of on the client work. The project is a social network app for board game geeks. As with every social app the interaction between users is quite high. People can vote for good games, comment on other people votes, write game reviews etc. I started writing tests in the following format:

user = TestUser.new
user.click "Login"
user.fills_in :login, :with ="andrzej"

As you see it's a fairly normal Ruby code with API similar to what Capybara/Webrat offers out of the box. In fact, I use Steak with Capybara.

Ruby code

When you compare it to the Cucumber style, the main difference is that it's Ruby code. If it's so hard to convince the customers to write scenarios then I see no point in inventing and using a new language. We all love Ruby.


If it's mostly programmers who read the scenarios, then Ruby is the best choice. It's programmer-friendly and I think many programmers would parse the Ruby code above more easily than the Cucumber way:
Given a new user
When he visits the main page
And he follows "Login"
And he fills in "Login" with "Andrzej"

User object

In most apps the concept of User is very important. Why not making it an object? It simplifies a lot and you can hide some implementation details in the (Test)User class. You can create methods and reuse the implementation in an easier (IMO) way than reusing step definitions in Cucumber.

Everything is an object

In fact when you start working this way, you quickly realize that there are more objects appearing in your test world. You will probably have a Website object which can keep some implementation details, like the path to admin panel or methods responsible for setting up the application state.

You can also have objects encapsulating certain pages, if it's useful, or objects for some of your website widgets - sidebar, search_box etc.

Object oriented programming

As you see it's all about the good old OOP that we use in our production code. This solves my problem with Cucumber being too procedural. I can write code like:
user.should_see("Popular games", :inside => sidebar)
Whatever OOP style you like, you can use in your tests. Sounds good to have all pages being subclasses of Page? Write it so.

Human readable

I complain about the fact that it's hard to get customers read/write the scenarios. Cucumber is human readable, no doubts about it. However, if you look at the OOP code - is it not human readable? It takes discipline to have all your methods well named, but it's so worth it. 

I claim that this kind of code is still readable to our non-programmers stakeholders.


If you agree that it's readable, then you can actually think of your scenarios as the documentation. Nothing different here, as compared to Cucumber. If you organize your test objects nicely then you not only have a scenario view but also you can see what are the widgets responsible for or what is possible for the Guest user and what is possible for the logged-in User.


I found it hard to implement interaction between users in a Cucumber style of testing. I mean things like this:
andrzej = TestUser("andrzej", "password")
john = TestUser("john", "password")
andrzej.writes_a_review("Agricola", "content")
john.should_see "content"
john.comments("nice review!")
andrzej.should_receive_email("nice review!",  "john")

I think it's readable and if you hide the details in methods then the scenario reads very well. You can easily introduce new users into the interaction.


Personas is a concept in which you find the different types of users who interact with your app. You can give them names, describe what they do, what matters to them etc. This concept can help you think about new features in terms of which persona would use the feature in what way.

In your scenarios you can then use the persona to highlight which aspect of the feature you test. If you worry about security of the new feature then have a user in mind who can hack into your website and write scenarios to ensure it's not possible.
little_bobby_tables.fills_in :login, :with => "Robert'); DROP TABLE Users;--")


When I started with this kind of acceptance testing I didn't think it was so useful at first. When I showed it to my colleagues they quickly started using it as well. Special thanks to Paweł Pacana, who used it in our Ruby User Group website and published it to Github. Since then we started using this approach in our client projects and it works really well. I think it brings back the joy of writing acceptance tests.

I call this approach "object oriented acceptance testing" but my friends started calling it "common.rb" as the main test file that I used. Here is an excerpt from the first version of my common.rb file:
class TestUser
  attr_accessor :steak
  attr_accessor :email
  attr_accessor :password
  attr_accessor :login

  def initialize(steak)
    @steak = steak
    yield if block_given?

  def click(*args);     steak.click_link_or_button(*args) end
  def choose(*args);    steak.choose(*args) end
  def select(*args);    steak.select(*args) end
  def fill_in(*args);   steak.fill_in(*args) end
  def visit(path);      steak.visit(path) end
  def attach_file(*args);      steak.attach_file(*args) end
  def should_see(text); steak.page.body.include?(text).should == true end
  def should_not_see(text); steak.page.should_not(steak.have_content(text)) end
  def should_receive_email(text) 
    steak.find_email(@email, :with_text => text).should_not == nil
If you want to see more, look here:

All of the scenarios are kept in spec/acceptance, so look around how it works.

Not a gem, an approach

I was asked to release it as a gem. After some thinking I decided not to do that, as this would make it limiting. I prefer to think about it as an approach, not a specific technology. It all comes down to: Use object in your acceptance tests

The technology I choose is Capybara + Steak. Steak is a very simple DSL around RSpec. Since I started Capybara already provided a replacement for Steak, so it's no longer needed.

This approach is not web specific. In fact, we have a project which consists of a server written in Ruby with EventMachine which has no views but just exposes an API. We write test scenarios using objects that simulate clients connecting to the API. It works very well with typical acceptance tests but also with load testing.


As you see the approach is not revolutionary and I know that I'm not the first developer who uses it. There are not so many articles about it and I hope it can become more popular. Obviously, it doesn't solve all of the problems that exist in acceptance testing.

We still need to think how to make acceptance tests run quickly or solve the problem of preparing the application state for testing. I think we can do better than using Factories or Fixtures in acceptance tests and I have some ideas for simplifying it. I will present how it works in my next blog posts. Stay tuned. Thanks for reading.

If you read this far you should Follow andrzejkrzywda on Twitter and subscribe to my RSS