Daikini

For RoundHaus I needed to find a payment processor for collecting subscription payments and after doing a fair bit of research I found PaySimple. I was very impressed with their service and support. It is absolutely top notch and I highly recommend them.

There wasn’t anything out there in Rubyland for dealing with PaySimple though so I created the PaySimple plugin/gem. The library provides a simple interface to find, create, edit, delete, and query subscriptions using the PaySimple SOAP API.

Installation:

The simple way:

$ sudo gem install paysimple

Directly from repository:

$ svn co svn://svn.roundhaus.com/daikini/plugins/paysimple

Requirements:

• soap4r 1.5.6 or higher

Configuration:

When you signup for a PaySimple account you can setup a source key and optionally a pin and client ip address. These are your credentials when using the PaySimple API.

   1  PaySimple.key = "123456"
   2  PaySimple.pin = "topsecret"
   3  PaySimple.client_ip = "192.168.0.1"

Usage:

   1  require 'rubygems'
   2  require 'paysimple'
   3  
   4  # Bill Jennifer $12.00 monthly
   5  begin
   6    customer_number = PaySimple::Subscription.create(
   7      :CustomerID => 12345,
   8      :BillingAddress => {
   9        :FirstName => "Jennifer",
  10        :LastName => "Smith"
  11      },
  12      :CreditCardData => {
  13        :CardNumber => '4444555566667779',
  14        :CardExpiration => '0908'
  15      },
  16      :Schedule => :monthly,
  17      :Next => "2008-09-05",
  18      :Amount => 12.00
  19    )
  20  
  21    puts "Subscription created with Customer Number: #{customer_number}"
  22  rescue Exception => e
  23    puts "An error occurred: #{e.message}"
  24  end
  25  
  26  
  27  # Update subscription to use new credit card
  28  begin
  29    customer_number = 12345
  30    response = PaySimple::Subscription.update(
  31      customer_number,
  32      :CreditCardData => {
  33        :CardNumber => '4444555566667779',
  34        :CardExpiration => '0908'
  35      }
  36    )
  37  
  38    puts "Subscription updated"
  39  rescue Exception => e
  40    puts "An error occurred: #{e.message}"
  41  end
  42  
  43  
  44  # Delete subscription
  45  begin
  46    customer_number = 12345
  47    response = PaySimple::Subscription.delete(customer_number)
  48  
  49    puts "Subscription removed from active use."
  50  rescue Exception => e
  51    puts "An error occurred: #{e.message}"
  52  end
  53  
  54  
  55  # Find an existing subscription
  56  begin
  57    customer_number = 12345
  58    customer = PaySimple::Subscription.find(customer_number)
  59  
  60    puts "Found subscription for #{ [customer["BillingAddress"]["FirstName"], customer["BillingAddress"]["LastName"]].join(" ")}"
  61  rescue Exception => e
  62    puts "An error occurred: #{e.message}"
  63  end
  64  
  65  
  66  # Process one-time sale against existing subscription
  67  begin
  68    customer_number = 12345
  69    response = PaySimple::Subscription.charge(customer_number, :Amount => 34.56)
  70  
  71    if response['Response'] == "Approved"
  72      puts "One-time charge successful."
  73    else
  74      puts "An error occurred: #{response['Error']}"
  75    end
  76  rescue Exception => e
  77    puts "An error occurred: #{e.message}"
  78  end
  79  
  80  
  81  # Search for transactions
  82  begin
  83    response = PaySimple::Subscription.query(
  84      [ 
  85        { :Field => 'amount', :Type => 'gt', :Value => '5.0' }
  86      ]
  87    )
  88  
  89    response.transactions.each do |transaction|
  90      puts "CustomerID = #{transaction['CustomerID']}, Amount = #{transaction['Details']['Amount']}"
  91    end
  92  rescue Exception => e
  93    puts "An error occurred: #{e.message}"
  94  end

LICENSE:

paysimple is licensed under the MIT License.

Copyright (c) 2007 [Jonathan Younger], released under the MIT license

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

With the release of a several plugins and the announcement that RoundHaus allows for public access to projects, I’ve opened up the Daikini Plugins RoundHaus project so that you can keep up to date on the goings on of the plugins I’ve released.

Enjoy!

Jamis Buck posted a tip on using datetime columns in the database to represent boolean values. According to Jamis, this gives you the capability down the road to not only report whether the event occurred, but how frequently over various periods of time. I’ve been using this technique in many different project since I read his post and I must say that it has worked very well.

Jamis’ example was pretty simple and only provided read-only access to the attribute and no searching. I decided to kick this technique up a notch to provide read-write access as well as searching using dynamic finders. I’ve wrapped it all up in a Rails plugin that makes it easy to create boolean attributes from datetime columns.

To install the EventAttribute plugin you can:

./script/plugin install svn://svn.roundhaus.com/daikini/plugins/event_attribute

or if you prefer piston:

piston import svn://svn.roundhaus.com/daikini/plugins/event_attribute vendor/plugins/event_attribute

Here is an example of using the EventAttribute plugin to replicate Jamis’ example from his post:

   1  class Referral < ActiveRecord::Base
   2    event_attribute :applied_at, :attribute => 'pending', :nil_equals => true
   3    event_attribute :subscribed_on
   4  end

   1  referral = Referral.create(:applied_at => Time.now)
   2  referral.pending?           # => false
   3  referral.subscribed?        # => false
   4  
   5  referral.pending = true
   6  referral.applied_at         # => nil
   7  referral.pending?           # => true
   8  
   9  referral.subscribed = true
  10  referral.subscribed_at      # => Time.now
  11  referral.subscribed?        # => true
  12  
  13  
  14  # Dynamic finders are also added so that you can search on these boolean attributes.
  15  Referral.find_all_by_pending(true)  # => [Referral objects]
  16  
  17  # or
  18  Referral.find_by_name_and_pending_and_subscribed('John Smith', false, true)  # => Referral object
  19  

I’ve written a couple test helpers that I’ve found to be pretty useful when testing ActiveRecord validations. Just add them to your RAILS_ROOT/test/test_helper.rb file.

The assert_errors_on method takes an object and a hash of attributes and the validation errors that they should have.

The assert_no_errors_on method takes an object and a list of attributes that should not have any validation errors.

   1  def assert_errors_on(object, errors = {})
   2    assert !object.valid?
   3    errors.each do |attribute, error| 
   4      assert_equal error.to_a.sort, object.errors.on(attribute).to_a.sort, "Error on #{attribute}" 
   5    end
   6  end
   7    
   8  def assert_no_errors_on(object, *attributes)
   9    object.valid?
  10    attributes.each { |attribute| assert_nil object.errors.on(attribute), "Error on #{attribute}" }
  11  end

You can then use them like this:

   1  require File.dirname(__FILE__) + '/../test_helper'
   2  
   3  class PersonTest < Test::Unit::TestCase
   4    def test_should_require_unique_email_address
   5      # Using assert_errors_on method
   6      person = Person.new :email_address => "cosmo@sprockets.com"
   7      assert_errors_on person, :email_address => "has already been taken"
   8  
   9      # Doing the same thing but without the assert_errors_on method
  10      person = Person.new :email_address => "cosmo@sprockets.com"
  11      assert !person.valid?
  12      assert_equal "has already been taken", person.errors.on(:email_address)
  13  
  14      # Using assert_no_errors on method
  15      person = Person.new :email_address => "john.smith@example.com"
  16      assert_no_errors_on person, :email_address
  17      
  18      # Doing the same thing but without the assert_no_errors_on method
  19      person = Person.new :email_address => "john.smith@example.com"
  20      person.valid?
  21      assert_nil person.errors.on(:email_address)
  22    end
  23  
  24    # We can test other attributes independently as well
  25  
  26    def test_should_require_a_first_name
  27      person = Person.new
  28      assert_errors_on person, :first_name => "can't be blank"
  29  
  30      person = Person.new :first_name => "Jonathan"
  31      assert_no_errors_on :person, :first_name
  32    end
  33  
  34    def test_should_require_a_last_name
  35      person = Person.new
  36      assert_errors_on person, :last_name => "can't be blank"
  37  
  38      person = Person.new :last_name => "Younger"
  39      assert_no_errors_on :person, :last_name
  40    end
  41  
  42    def test_should_blah_blah_blah
  43      ...
  44    end
  45  end

Updated 2007-11-28: Added additional attribute tests to show that the attributes can be tested in isolation without regards to ensuring that all of the attributes have to be valid for testing to work.

Updated 2007-09-14: Added code for showing what the tests would look like by not using the test helpers.

Tom Preston-Werner outlined pretty well in his RailsConf 2007 presentation why fixtures suck so I’ll just repeat them here:

Why fixtures suck:

• swampy
• become an unmanageable mess
• hard to keep track of links between data
• things aren’t easy to refactor
• no namespacing – i.e. you need to have lots of users in different states for good testing
• brittleness – one day you add a new column to a table, and half of your tests fail
• no validation – there is no automatic way for ActiveRecord validation for fixture data
• contamination – tests pass independently, but fail when running all at once
• performance – fixtures can be slow

Tom came up with a possible solution to these problems but I’ve been kicking around a different solution. Let me just say that I’m not entirely sure there is a perfect solution to the fixture problem but the one I came up with works really well for me.

I’ve worked on two projects that took two approaches to the fixture problem. Project A used the Rails fixture files as intended. Project A pretty much experienced all of the problems above when dealing with the fixture data. The big kicker was that performance was absolutely horrible. The combined unit and functional tests took over 2 minutes to run. Needless to say less tests were being written as time went on.

Not wanting to repeat the testing hell that Project A suffered from Project B didn’t use a single fixture file. Instead Project B used the totally kick-ass Mocha library for all the tests. Objects were mocked or stubbed as needed. The big problem that Project B experienced was that there was easily twice the amount of test code than there was actual code because the test code was pretty much just duplicating all of the logic inside the regular code anyway. Every ActiveRecord find method was being mocked out and returned manually instead of letting the database do its job. The big benefit of not hitting the database was that the tests were super fast. Project B was tested very well but the tests were very brittle.

After thinking about the fixture problem for awhile it occurred to me that I really liked the Project B approach of specifying what data were being used for a given test. I just didn’t like the fact that I was having to write a lot of test code to do what the database should have been doing. The Project A approach allowed the database do what the database does best but sucked because of the fixture file problem in general.

So when it came time for Project C I needed an entirely new approach to testing. What if I could combine the benefits of each approach, Project A letting the database do what its best at and the Project B approach of specifying the data in the exact context it is needed? So I did just that and for me it solved the fixture problem very well. I converted Project A to use this new approach and the tests went down from over 2 minutes to run to just under 25 seconds. Still not great but way better than it was and it no longer suffered from the other fixture problems it was having. Needless to say, testing is going up and the code is getting better.

Okay, enough talking, let’s see some freakin’ code already. Let’s say that your application has a Person model and each person is required to have a unique email address.

   1  class Person < ActiveRecord::Base
   2    validates_uniqueness_of :email_address
   3  end

Using the normal fixture file in test/fixtures/people.yml you would add a person entry with an email address you could test against.

   1  first:
   2    id: 1
   3    name: Cosmo Spacely
   4    email_address: cosmo@sprockets.com

Then in your test/unit/person.rb unit test you would have a test something like this:

   1  require File.dirname(__FILE__) + '/../test_helper'
   2  
   3  class PersonTest < Test::Unit::TestCase
   4    fixtures :people
   5  
   6    def test_should_require_unique_email_address
   7      person = Person.new :email_address => "cosmo@sprockets.com"
   8      assert !person.valid?
   9      assert_equal "has already been taken", person.errors.on(:email_address)
  10  
  11      person = Person.new :email_address => "john.smith@example.com"
  12      person.valid?
  13      assert_nil person.errors.on(:email_address)
  14    end
  15  end

To change this example to use the fixture method you would simply remove the call to fixtures :people that loaded the yaml fixture file. Then in the test method you would add a call to the new fixture method and pass in the data that should be loaded.

   1  require File.dirname(__FILE__) + '/../test_helper'
   2  
   3  class PersonTest < Test::Unit::TestCase
   4    # We don't need to load the people fixtures anymore
   5    # fixtures :people
   6                     
   7    def test_should_require_unique_email_address
   8      # The fixture method will load in the data we need for this test
   9      fixture :person, :email_address => "cosmo@sprockets.com"
  10      
  11      person = Person.new :email_address => "cosmo@sprockets.com"
  12      assert !person.valid?
  13      assert_equal "has already been taken", person.errors.on(:email_address)
  14  
  15      person = Person.new :email_address => "john.smith@example.com"
  16      person.valid?
  17      assert_nil person.errors.on(:email_address)
  18    end
  19  end

If you think taking this approach would work for you then you can install the fixture plugin with:

script/plugin install svn://svn.roundhaus.com/daikini/plugins/fixture