judit-pickle 0.4.2

data/README.rdoc

@@ -0,0 +1,367 @@
+= pickle
+
+Pickle gives you cucumber steps that create your models easily from factory-girl or
+machinist factories/blueprints.  You can also just use ActiveRecord as a factory but it's not as cool.
+
+Pickle can make use of different ORMs for finding records.  Currently ActiveRecord, DataMapper, MongoID adapters are
+provided.  More adapters welcome!
+
+References to the models are stored in the current world, not necessarily for the purpose of checking the db
+(although you could use it for that), but for enabling easy reference to urls, and for
+building complex givens which require a bunch of models collaborating
+
+== Quickstart
+
+This is a quickstart guide for rails apps.  Firstly, install {cucumber-rails}[http://github.com/aslakhellesoy/cucumber-rails], and its dependencies.
+Then do the following:
+
+=== Rails 3:
+
+Add the gem to your Gemfile:
+
+  gem 'pickle'
+  
+Then install with:
+
+  bundle install
+  
+Discover the options for the generator:
+
+  rails g pickle --help
+
+Run the generator, e.g:
+
+  rails g pickle --paths --email
+  
+=== For Rails 2:
+
+Add the following to config/environments/cucumber:
+
+  config.gem 'pickle'
+
+Install the gem with
+
+  rake gems:install RAILS_ENV=cucumber
+  
+Run the generator with:
+
+  script/generate pickle [paths] [email]
+
+== Resources
+
+<b>Github</b> for code: http://github.com/ianwhite/pickle
+
+<b>Gemcutter</b> for the gem: http://gemcutter.org/gems/pickle
+
+<b>Rdoc.info</b> for docs: http://rdoc.info/projects/ianwhite/pickle
+
+<b>Google group</b> for questions: http://groups.google.com/group/pickle-cucumber
+
+<b>Lighthouse</b> for bugs: http://ianwhite.lighthouseapp.com/projects/25941-pickle
+
+<b>Railscast</b> presentation: http://railscasts.com/episodes/186-pickle-with-cucumber
+
+<b>Blog articles</b>: {dynamic50: Integration testing with cucumber and pickle}[http://blog.dynamic50.com/index.php/2009/04/integration-testing-with-cucumber-and-pickle/], {rubyflare: pickle my cucumber}[http://rubyflare.com/2009/10/28/pickle-my-cucumber/]
+
+
+== Using Pickle
+
+Now have a look at <tt>features/step_definitions/pickle_steps.rb</tt>
+
+If you want path steps and email steps then just add the 'paths' and/or 'email' options to the generator.
+The code/steps will be written to <tt>features/env/paths.rb</tt> and
+<tt>features/step_definitions/email_steps.rb</tt> respectively.
+
+=== Using with plain ole Active Record, DataMapper or Mongoid
+
+Pickle comes with ORM adapters for Active Record, DataMapper and Mongoid.
+
+If you have a model called 'Post', with required fields 'title', and 'body', then you can now write
+steps like this
+
+  Given a post exists with title: "My Post", body: "My body"
+
+=== Using with factory-girl or machinist
+
+But you're using Machinist or FactoryGirl right?!  To leverage all of the factories/blueprints
+you've written, you can just do stuff like
+
+  Given a user exists
+  And another user exists with role: "admin"
+
+  # later
+  Then a user should exist with name: "Fred"
+  And that user should be activated # this uses rspec predicate matchers
+
+==== Machinist: require your blueprints and reset Shams
+
+In your <tt>features/support/env.rb</tt> add the following lines at the bottom
+
+  require "#{Rails.root}/spec/blueprints" # or wherever they live
+  Before { Sham.reset } # reset Shams in between scenarios
+
+==== FactoryGirl: make sure factories are loaded
+
+In your config/environments/cucumber.rb file, make sure the factory-girl gem is included (unless it's installed as a plugin).
+
+If that doesn't solve loading issues then require your factories.rb file directly in a file called 'features/support/factory_girl.rb'
+
+  # example features/support/factory_girl.rb
+  require File.dirname(__FILE__) + '/../../spec/factories'
+
+=== Using with an ORM other than ActiveRecord, DataMapper, or Mongoid
+
+Pickle can be used with any modelling library provided there is an adapter written for it.
+
+Adapters are very simple and exist a module or class with the name "PickleAdapter" available to the class.  For example
+
+User.const_get(:PickleAdapter) #=> should return a pickle adapter
+
+The Active Record and DataMapper ones can be found at
+ActiveRecord::Base::PickleAdapter, DataMapper::Resource::PickleAdapter, Mongoid::Document::PickleAdapter respectively.
+
+See how to implement one by looking at the ones provided in the pickle source in lib/pickle/adapters/*
+
+=== Configuring Pickle
+
+You can tell pickle to use another factory adapter (see Pickle::Adapter), or
+create mappings from english expressions to pickle model names.  You can also
+override many of the options on the Pickle::Config object if you so choose.
+
+In: <tt>features/support/pickle.rb</tt>
+
+  require 'pickle/world'
+
+  Pickle.configure do |config|
+    config.adapters = [:machinist, :active_record, YourOwnAdapterClass]
+    config.map 'me', 'myself', 'my', 'I', :to => 'user: "me"'
+  end
+
+Out of the box pickle looks for machinist, factory-girl, then uses the ORM(s) that you're using to create models.
+
+If you find that your steps aren't working with your factories, it's probably the case that your factory setup is not being included in your cucumber environment (see comments above regarding machinist and factory-girl).
+
+== API
+
+=== Steps
+
+When you run <tt>script/generate pickle</tt> you get the following steps
+
+==== Given steps
+
+"Given <b>a model</b> exists",  e.g.
+
+  Given a user exists
+  Given a user: "fred" exists
+  Given the user exists
+
+"Given <b>a model</b> exists with <b>fields</b>",  e.g.
+
+  Given a user exists with name: "Fred"
+  Given a user exists with name: "Fred", activated: false
+  
+This last step could be better expressed by using Machinist/FactoryGirl to create an activated user.  Then you can do
+
+  Given an activated user exists with name: "Fred"
+
+You can refer to other models in the fields
+
+  Given a user exists
+  And a post exists with author: the user
+
+  Given a person "fred" exists
+  And a person "ethel" exists
+  And a fatherhood exists with parent: person "fred", child: person "ethel"
+  
+This last step is given by the default pickle steps, but it would be better written as:
+
+  And "fred" is the father of "ethel"
+  
+It is expected that you'll need to expand upon the default pickle steps to make your features readable.  To write the 
+above step, you could do something like:
+
+  Given /^"(\w+)" is the father of "(\w+)"$/ do |father, child|
+    Fatherhood.create! :father => model!("person: \"#{father}\""), :child => model!("person: \"#{child}\"")
+  end 
+
+"Given <b>n models</b> exist", e.g.
+
+  Given 10 users exist
+
+"Given <b>n models</b> exist with <b>fields</b>", examples:
+
+  Given 10 users exist with activated: false
+
+"Given the following <b>models</b> exist:", examples:
+
+  Given the following users exist
+    | name  | activated |
+    | Fred  | false     |
+    | Ethel | true      |
+
+===== Named machinist blueprints
+
+"Given <b> a <i>named</i> model</b> exists with <b>fields</b>"
+
+The latest version of pickle supports {named machinist blueprints}[http://github.com/notahat/machinist/commit/d6492e6927a8aa1819926e48b22377171fd20496].
+
+If you had the following blueprints:
+
+  User.blueprint do
+    name
+    email
+  end
+  
+  User.blueprint(:super_admin) do
+    role { "admin" }
+  end
+  
+  User.blueprint(:activated) do
+    activated { true }
+  end
+
+You could create a user with pickle by simply adding the name of the blueprint before the model:
+
+  Given a super admin user exists
+  And an activated user exists with name: "Fred"
+
+This is much nicer than having to set up common configurations in your steps all the time, and far more readable to boot.
+
+
+==== Then steps
+
+===== Asserting existence of models
+
+"Then <b>a model</b> should exist",  e.g.
+
+  Then a user should exist
+
+"Then <b>a model</b> should exist with <b>fields</b>", e.g.
+
+  Then a user: "fred" should exist with name: "Fred" # we can label the found user for later use
+
+You can use other models, booleans, numerics, and strings as fields
+
+  Then a person should exist with child: person "ethel"
+  Then a user should exist with activated: false
+  Then a user should exist with activated: true, email: "fred@gmail.com"
+
+"Then <b>n models</b> should exist", e.g.
+
+  Then 10 events should exist
+
+"Then <b>n models</b> should exist with <b>fields</b>", e.g.
+
+  Then 2 people should exist with father: person "fred"
+
+"Then the following <b>models</b> exist". This allows the creation of multiple models
+using a table syntax. Using a column with the singularized name of the model creates a referenceable model. E.g.
+
+  Then the following users exist:
+    | name   | activated |
+    | Freddy | false     |
+
+  Then the following users exist:
+    | user | name   | activated |
+    | Fred | Freddy | false     |
+
+===== Asserting associations
+
+One-to-one assocs: "Then <b>a model</b> should be <b>other model</b>'s <b>association</b>", e.g.
+
+  Then the person: "fred" should be person: "ethel"'s father
+
+Many-to-one assocs: "Then <b>a model</b> should be [in|one of] <b>other model</b>'s <b>association</b>", e.g.
+
+  Then the person: "ethel" should be one of person: "fred"'s children
+  Then the comment should be in the post's comments
+
+===== Asserting predicate methods
+
+"Then <b>a model</b> should [be|have] [a|an] <b>predicate</b>", e.g.
+
+  Then the user should have a status # => user.status.should be_present
+  Then the user should have a stale password # => user.should have_stale_password
+  Then the car: "batmobile" should be fast # => car.should be_fast
+
+"Then <b>a model</b> should not [be|have] [a|an] <b>predicate</b>", e.g.
+
+  Then person: "fred" should not be childless # => fred.should_not be_childless
+
+=== Regexps for use in your own steps
+
+By default you get some regexps available in the main namespace for use
+in creating your own steps: `capture_model`, `capture_fields`, and others (see lib/pickle.rb)
+
+(You can use any of the regexps that Pickle uses by using the Pickle.parser namespace, see
+Pickle::Parser::Matchers for the methods available)
+
+*capture_model*
+
+  Given /^#{capture_model} exists$/ do |model_name|
+    model(model_name).should_not == nil
+  end
+
+  Then /^I should be at the (.*?) page$/ |page|
+    if page =~ /#{capture_model}'s/
+      url_for(model($1))
+    else
+      # ...
+    end
+  end
+
+  Then /^#{capture_model} should be one of #{capture_model}'s posts$/ do |post, forum|
+    post = model!(post)
+    forum = model!(forum)
+    forum.posts.should include(post)
+  end
+
+*capture_fields*
+
+This is useful for setting attributes, and knows about pickle model names so that you
+can build up composite objects with ease
+
+  Given /^#{capture_model} exists with #{capture_fields}$/ do |model_name, fields|
+    create_model(model_name, fields)
+  end
+
+  # example of use
+  Given a user exists
+  And a post exists with author: the user # this step will assign the above user as :author on the post
+
+== Run the tests
+
+To get all the dependencies required for developing pickle, do the following
+
+  bundle install
+
+To run the specs do:
+
+  bundle exec rake spec
+
+To run the features (rails 2.3 only ATM):
+
+  bundle exec rake cucumber
+
+== Contributors
+
+The following people have made Pickle better:
+
+* {Marc Lee}[http://github.com/maleko]
+* {Sebastian Zuchmanski}[http://github.com/sebcioz]
+* {Paul Gideon Dann}[http://github.com/giddie]
+* {Tom Meier}[http://github.com/tommeier]
+* {Sean Hussey}[http://github.com/seanhussey]
+* Brian Rose & Kevin Olsen
+* {Christopher Darroch}[http://github.com/chrisdarroch]
+* {Szymon Nowak}[http://github.com/szimek]
+* {H.J. Blok}[http://github.com/hjblok]
+* {Daniel Neighman}[http://github.com/hassox]
+* {Josh Bassett}[http://github.com/nullobject]
+* {Nick Rutherford}[http://github.com/nruth]
+* {Tobi Knaup}[http://github.com/guenter]
+* {Michael MacDonald}[http://github.com/schlick]
+* {Michael Moen}[http://github.com/UnderpantsGnome]
+* {Myron Marston}[http://github.com/myronmarston]
+* {Stephan Hagemann}[http://github.com/xing]
+* {Chris Flipse}[http://github.com/cflipse]

data/Rakefile

@@ -0,0 +1,20 @@
+$:.unshift File.expand_path('lib')
+
+# load given tasks file, reporting errors without failing
+def load_tasks(tasks)
+  load tasks
+rescue Exception => exception
+  $stderr << "** loading #{tasks.sub(File.expand_path('.'),'')} failed: "
+  case exception
+  when LoadError
+    $stderr << "to use, install the gems it requires\n"
+  else
+    $stderr << ([exception.message] + exception.backtrace[0..2]).join("\n    ") << "\n\n"
+  end
+end
+
+Dir["Rakefile.d/*.rake"].sort.each {|t| load_tasks t}
+
+task :default => :spec
+
+task :ci => ['rcov:verify', 'cucumber']

data/Rakefile.d/cucumber.rake

@@ -0,0 +1,24 @@
+require 'cucumber/rake/task'
+
+desc "Run features"
+Cucumber::Rake::Task.new(:cucumber => [:cucumber_test_app]) do |t|
+  t.cucumber_opts = ['--format', 'pretty', '--require', 'features']
+end
+
+desc "setup a rails app for running cucumber"
+file "cucumber_test_app" do
+  puts "** setting up cucumber test app ** (rails 2.3 only at present)"
+  Rake::Task['cucumber:setup'].invoke
+end
+
+namespace :cucumber do
+  task :setup do
+    rm_rf "cucumber_test_app"
+    sh "rails cucumber_test_app"
+    cd "cucumber_test_app" do
+      sh "script/generate rspec"
+      sh "script/generate cucumber"
+    end
+    sh "ln -s #{File.expand_path('.')} cucumber_test_app/vendor/plugins/pickle"
+  end
+end

data/Rakefile.d/jeweler.rake

@@ -0,0 +1,23 @@
+require 'jeweler'
+require 'pickle/version'
+
+Jeweler::Tasks.new do |s|
+  s.name = "pickle"
+  s.version = Pickle::Version::String
+  s.summary = "Easy model creation and reference in your cucumber features"
+  s.description = "Easy model creation and reference in your cucumber features"
+  s.email = "ian.w.white@gmail.com"
+  s.homepage = "http://github.com/ianwhite/pickle/tree"
+  s.authors = ["Ian White"]
+  s.add_dependency('rspec', ">=1.3")
+  s.add_dependency('cucumber', ">=0.8")
+  s.add_dependency('yard')
+  s.add_dependency('rake')
+end
+
+Jeweler::GemcutterTasks.new
+
+namespace :release do
+  desc "release to github and gemcutter"
+  task :all => ['release', 'gemcutter:release']
+end

data/Rakefile.d/rcov.rake

@@ -0,0 +1,18 @@
+require 'spec/rake/spectask'
+require 'spec/rake/verify_rcov'
+
+desc "Generate RCov report"
+Spec::Rake::SpecTask.new(:rcov) do |t|
+  t.spec_files  = FileList['spec/**/*_spec.rb']
+  t.rcov        = true
+  t.rcov_dir    = 'doc/coverage'
+  t.rcov_opts   = ['--text-report', '--exclude', "gems/,features/,/Library,spec/,rcov.rb"] 
+end
+
+namespace :rcov do
+  desc "Verify RCov threshold"
+  RCov::VerifyTask.new(:verify => :rcov) do |t|
+    t.threshold = 98.12
+    t.index_html = 'doc/coverage/index.html'
+  end
+end

data/Rakefile.d/rspec.rake

@@ -0,0 +1,7 @@
+require 'spec/rake/spectask'
+
+desc "Run the specs"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.spec_opts  = ["--colour"]
+end

data/Rakefile.d/yard.rake

@@ -0,0 +1,5 @@
+require 'yard'
+  
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files   = ['lib/**/*.rb', 'rails_generators/**/*.rb']
+end

data/Todo.txt

@@ -0,0 +1,3 @@
+* add 'scope' steps see http://gist.github.com/239570
+* cleanup path_to_pickle and paths.rb (maybe have poly_pickle_path with same semantics as polymorphic_path, but accepting pickle refs)
+* Translations

data/VERSION

@@ -0,0 +1 @@
+0.4.2

data/features/app/app.rb

@@ -0,0 +1,122 @@
+# Routes
+ActionController::Routing::Routes.draw do |map|
+  map.resources :spoons, :controller => 'default'
+  map.resources :forks, :controller => 'default' do |fork|
+    fork.resources :tines, :controller => 'default' do |tine|
+      tine.resources :comments, :controller => 'default'
+    end
+  end
+  map.resources :users, :controller => 'default'
+end
+
+# Migrations
+ActiveRecord::Migration.suppress_messages do
+  ActiveRecord::Schema.define(:version => 0) do
+    create_table :forks, :force => true do |t|
+      t.string :name
+    end
+    
+    create_table :spoons, :force => true do |t|
+      t.string :name
+      t.boolean :round, :default => true, :null => false
+    end
+    
+    create_table :tines, :force => true do |t|
+      t.belongs_to :fork
+      t.boolean :rusty, :default => false, :null => false
+    end
+    
+    create_table :users, :force => true do |t|
+      t.string :name, :status, :email
+      t.decimal :attitude_score, :precision => 4, :scale => 2
+      t.boolean :has_stale_password, :default => false
+    end
+  end
+end
+
+
+# Factories for these Fork & Spoon
+class Fork < ActiveRecord::Base
+  validates_presence_of :name
+  has_many :tines
+  
+  def completely_rusty?
+    tines.map(&:rusty?).uniq == [true]
+  end
+  
+  def fancy?
+    name =~ /fancy/i
+  end
+end
+
+class Tine < ActiveRecord::Base
+  validates_presence_of :fork
+  belongs_to :fork
+end
+
+# Machinist blueprint for this
+class Spoon < ActiveRecord::Base
+  validates_presence_of :name
+end
+
+# we don't want abstract classes getting in there
+class AbstractUser < ActiveRecord::Base
+  self.abstract_class = true
+end
+
+# No factory or blueprint for this
+class User < AbstractUser
+  validates_presence_of :name
+  
+  def positive_person?
+    !no_attitude? && attitude_score > 0
+  end
+  
+  def no_attitude?
+    attitude_score.nil?
+  end
+end
+
+# controllers
+class DefaultController < ActionController::Base
+  def index
+    render :text => "index: I was invoked with #{request.path}"
+  end
+  
+  def show
+    render :text => "show: I was invoked with #{request.path}"
+  end
+  
+  def new
+    render :text => "new: I was invoked with #{request.path}"
+  end
+  
+  def edit
+    render :text => "edit: I was invoked with #{request.path}"
+  end
+end
+
+# notifiers
+class Notifier < ActionMailer::Base
+  include ActionController::UrlWriter
+  
+  # BC 2.1
+  if respond_to?(:view_paths)
+    view_paths << "#{File.dirname(__FILE__)}/views"
+  else
+    self.template_root = "#{File.dirname(__FILE__)}/views"
+  end
+  
+  def user_email(user)
+    @recipients  = user.email
+    @subject     = 'A user email'
+    @body[:user] = user
+    @body[:path] = user_path(user)
+  end
+  
+  def email(to, subject, body)
+    @recipients  = to
+    @subject     = subject
+    @body[:body] = body
+  end
+end

data/features/app/blueprints.rb

@@ -0,0 +1,11 @@
+# Blueprints
+require 'machinist/active_record'
+
+Sham.spoon_name { |i| "Spoon #{i}" }
+
+Spoon.blueprint do
+  name { Sham.spoon_name }
+end
+
+# reset shams between scenarios
+Before { Sham.reset }

data/features/app/factories.rb

@@ -0,0 +1,23 @@
+# Factories
+require 'factory_girl'
+
+Factory.sequence :fork_name do |n|
+  "fork %d04" % n
+end
+
+Factory.define :fork do |f|
+  f.name { Factory.next(:fork_name) }
+end
+
+Factory.define :tine do |t|
+  t.association :fork
+end
+
+Factory.define :rusty_tine, :class => Tine do |t|
+  t.association :fork
+  t.rusty true
+end
+
+Factory.define :fancy_fork, :class => Fork do |t|
+  t.name { "Fancy " + Factory.next(:fork_name) }
+end

data/features/app/views/notifier/email.erb

@@ -0,0 +1 @@
+<%= @body %>

data/features/app/views/notifier/user_email.erb

@@ -0,0 +1,6 @@
+Dear <%= @user.name %>,
+
+This is where you should go: <%= @path %>
+
+Cheers,
+The Pickle Team