bbq-core/README.md
# BBQ
[](http://travis-ci.org/drugpl/bbq-core) [](https://gemnasium.com/drugpl/bbq-core) [](https://codeclimate.com/github/drugpl/bbq-core) [](http://badge.fury.io/rb/bbq-core)
Object oriented acceptance testing using personas.
* Ruby (no Gherkin)
* Objects and methods instead of steps
* Test framework independent (RSpec and Test::Unit support)
* Thins based on Capybara.
* DCI (Data Context Interaction) for roles/personas
* Opinionated
## Setup
First, add BBQ to your apps `Gemfile`:
```ruby
gem "bbq", "0.2.1"
```
Run install generator:
```
bundle exec rails generate bbq:install
```
Require BBQ in test/test_helper.rb (in case of Test::Unit):
```ruby
require "bbq/test_unit"
```
Require BBQ in spec/spec_helper.rb (in case of RSpec):
```ruby
require "bbq/rspec"
```
## Feature generator
```
bundle exec rails g bbq:test MyFeatureName
```
## Running features
For Test::Unit flavour:
```
bundle exec rake test:acceptance
```
For RSpec flavour:
```
bundle exec rake spec:acceptance
```
## Examples
### Roles and Devise integration
```ruby
class TestUser < Bbq::TestUser
include Bbq::Devise
def update_ticket(summary, comment)
show_ticket(summary)
fill_in "Comment", :with => comment
click_on "Add update"
end
def open_application
visit '/'
end
module TicketReporter
def open_tickets_listing
open_application
click_link 'Tickets'
end
def open_ticket(summary, description)
open_tickets_listing
click_on "Open a new ticket"
fill_in "Summary", :with => summary
fill_in "Description", :with => description
click_on "Open ticket"
end
def show_ticket(summary)
open_tickets_listing
click_on summary
end
end
module TicketManager
def open_administration
visit '/admin'
end
def open_tickets_listing
open_administration
click_link 'Tickets'
end
def close_ticket(summary, comment = nil)
open_tickets_listing
click_on summary
fill_in "Comment", :with => comment if comment
click_on "Close ticket"
end
def show_ticket(summary)
open_tickets_listing
click_on summary
end
end
end
```
```ruby
class AdminTicketsTest < Bbq::TestCase
background do
admin = Factory(:admin)
@email, @password = admin.email, admin.password
end
scenario "admin can browse all user tickets" do
summaries = ["Forgot my password", "Page is not displayed correctly"]
descriptions = ["I lost my yellow note with password under the table!",
"My IE renders crap instead of crispy fonts!"]
alice = TestUser.new
alice.roles(:ticket_reporter)
alice.register_and_login
alice.open_ticket(summaries.first, descriptions.first)
bob = TestUser.new
bob.roles(:ticket_reporter)
bob.register_and_login
bob.open_ticket(summaries.second, descriptions.second)
charlie = TestUser.new(:email => @email, :password => @password)
charlie.login # charlie was already "registered" in factory as admin
charlie.roles(:ticket_manager)
charlie.open_tickets_listing
charlie.see!(*summaries)
charlie.click_on(summaries.second)
charlie.see!(summaries.second, descriptions.second)
charlie.not_see!(summaries.first, descriptions.first)
end
end
```
### RSpec integration
```ruby
class TestUser < Bbq::TestUser
def email
@options[:email] || "buyer@example.com"
end
module Buyer
def ask_question(question)
fill_in "question", :with => question
fill_in "email", :with => email
click_on("Ask")
end
def go_to_page_and_open_widget(page_url, &block)
go_to_page(page_url)
open_widget &block
end
def go_to_page(page_url)
visit page_url
wait_until { page.find("iframe") }
end
def open_widget
within_widget do
page.find("#widget h3").click
yield if block_given?
end
end
ef within_widget(&block)
within_frame(widget_frame, &block)
end
def widget_frame
page.evaluate_script("document.getElementsByTagName('iframe')[0].id")
end
end
end
```
```ruby
feature "ask question widget" do
let(:user) {
user = TestUser.new(:driver => :webkit)
user.roles('buyer')
user
}
scenario "as a guest user, I should be able to ask a question" do
user.go_to_page_and_open_widget("/widget") do
user.ask_question "my question"
user.see!("Thanks!")
end
end
end
```
## Testing REST APIs
Bbq provides `Bbq::TestClient`, similar to `Bbq::TestUser`, but intended for testing APIs.
It's a thin wrapper around `Rack::Test` which allows you to send requests and run assertions
against responses.
```ruby
class ApiTest < Bbq::TestCase
background do
headers = {'HTTP_ACCEPT' => 'application/json'}
@client = TestClient.new(:headers => headers)
end
scenario "admin can browse all user tickets" do
@client.get "/unicorn" do |response|
assert_equal 200, response.status
assert_equal "pink", response.body["unicorn"]["color"]
end
@client.post "/ponies", { :name => "Miracle" } do |response|
assert_equal 200, response.status
end
end
end
```
## Rails URL Helpers
Using url helpers from Rails in integration tests is not recommended.
Testing routes is part of integration test, so you should actually use only
```ruby
visit '/'
```
in your integration test. Use links and buttons in order to get to other pages in your app.
If you really need url helpers in your test user, just include them in your TestUser class:
```ruby
require 'bbq/rails/routes'
class TestUser < Bbq::TestUser
include Bbq::Rails::Routes
end
```
or just
```ruby
class TestUser < Bbq::TestUser
include ::ActionDispatch::Routing::UrlFor
include ::Rails.application.routes.url_helpers
include ::ActionDispatch::Routing::RouteSet::MountedHelpers unless ::Rails.version < "3.1"
end
```
## Devise support
```ruby
require "bbq/test_user"
require "bbq/devise"
class TestUser < Bbq::TestUser
include Bbq::Devise
end
```
After that TestUser have *login*, *logout*, *register*, *register_and_login* methods.
```ruby
test "user register with devise" do
user = TestUser.new # or TestUser.new(:email => "email@example.com", :password => "secret")
user.register_and_login
user.see!("Stuff after auth")
end
```
## Caveats
### Timeout::Error
If you simulate multiple users in your tests and spawn multiple browsers with selenium it might
be a good idea to use Thin instead of Webrick to create application server.
We have experienced some problems with Webrick that lead to `Timeout::Error` exception
when user/browser that was inactive for some time (due to other users/browsers
activities) was requested to execute an action.
Capybara will use Thin instead of Webrick when it's available, so you only need to add Thin to you Gemfile:
```ruby
# In test group if you want it to
# be used only in tests and not in your development mode
# ex. when running 'rails s'
gem 'thin', :require => false
```
## Additional information
* [2 problems with Cucumber](http://andrzejonsoftware.blogspot.com/2011/03/2-problems-with-cucumber.html)
* [Object oriented acceptance testing](http://andrzejonsoftware.blogspot.com/2011/04/object-oriented-acceptance-testing.html)