MyGem.configure block

We recently enhanced Clearance with a configuration block that could be used in config/initializers/clearance.rb.

I liked the way Airbrake did it and wanted to implement the same pattern:

Airbrake.configure do |config|
  config.api_key = 'your_key_here'
end

Here’s the implementation:

module Clearance
  class << self
    attr_accessor :configuration
  end

  def self.configure
    self.configuration ||= Configuration.new
    yield(configuration)
  end

  class Configuration
    attr_accessor :mailer_sender

    def initialize
      @mailer_sender = 'donotreply@example.com'
    end
  end
end

The configure class method stores a Configuration object inside the Clearance module.

Anything set from the configure block is an attr_accessor on the Configuration class.

So now config/initializers/clearance.rb is possible:

Clearance.configure do |config|
  config.mailer_sender = 'donotreply@example.com'
end

Easy for the application developer to understand. Clean internal implementation:

Clearance.configuration.mailer_sender

In the library’s tests, set configuration attributes without worrying about undefining constants:

Clearance.configuration.mailer_sender= 'new.email@example.com'

Yay.

Written by <a rel=”author” href=”https://profiles.google.com/115463449660844194795”>Dan Croak.

Clearance: Rails authentication with email and password

Authentication is a common pattern in Rails apps. Thus, there have been many authentication plugins. We’ve tried acts_as_authenticated and restful_authentication over the years.

We found that user authentication is hard to generalize. Most abstracted authentication plugins had both too much and too little for us.

We then tried writing authentication from scratch on our clients’ Rails apps for about a year. We felt better about test coverage but it was still a pain to re-write similar code. App after app, we talked about extracting common code into a library. Each time we resisted.

After a while, we thought that maybe 60% of authentication could be re-used. We extracted Hoptoad’s authentication, then merged code from two of our clients’ apps. We named the gem Clearance.

On the first attempt, we went overboard on re-use. We backed off and wrote hooks in places we were finding logical extension points. For the past few months, patches have trickled in from Github and we’ve carefully included code that fits in the “60%”.

We recently started a new project. In the process, we’ve polished the gem and are happy to announce its official release.

Clearance

• Sign up
• Confirm email
• Sign in
• Sign out
• Reset password

Get it on Github.

Modules, Shoulda, and Factory Girl

Clearance is focused on maintainability of your application’s authentication code.

• Include comprehensive Shoulda and Factory Girl tests in your Rails app’s test suite
• Encapsulate authentication logic in modules which are included in your controllers, models, and tests.

This approach keeps your Rails application’s code clean and alerts you if you ever break your authentication code.

Due to the work we’ve been doing to make Shoulda test framework-agnostic, you will be able to use RSpec in the 0.5.0 release of Clearance.

Test::Unit and Cucumber features are also supported:

script/generate clearance
script/generate clearance_features

Conventions

To keep our approach simple, we made a series of design decisions:

• User model required.
• User model uses attr_accessible.
• Authenticate by email (not username) and password.
• Vocabulary restricted to a trinity: “sign up”, “sign in”, “sign out”

Beyond

Clearance does not try to be a Swiss Army knife but it does have some hooks if you want admin roles, sign up and sign in by username in addition to email, or something else.

Please report bugs and request features on GitHub Issues.

Written by Dan Croak.

shoulda 2.0

Lots of shoulda news to report. The 2.0.x gem has been released, which includes bug fixes, new features, and deprecations.

Rails 2.1+ install

The gem is being hosted at github.com/thoughtbot/shoulda

Rails::Initializer.run do |config|
  config.gem 'thoughtbot-shoulda', :lib => 'shoulda/rails', :source => "http://gems.github.com"
end

rake gems:install
rake gems:unpack

Now 100% gem

Listen… if you’re still a plugin, I look at you (I’m looking at you, Paperclip), shake my head, and say, “So much untapped potential. Could’ve been big.”

Why gems?

• Ruby comes with a packaging system. No need for another, especially with the gem support in Rails 2.1.
• It’s nice to scan the vendor/gems listing and see version numbers.
• github has excellent gem support.
• In shoulda’s case, it’s a project that can be used in and out of Rails. It’s a pain to have both a plugin and a gem.

Ryan McGeary and Josh Nichols did the bulk of this conversion and related refactoring. They deserve extra acclaim because they’ve made it easier for everyone to contribute to shoulda.

Improvements to current macros

should_assign_to :user, :equals => "@user"

should_assign_to :user, :class => User

should_have_one :address, :dependent => :destroy

ActiveRecord::Errors.default_error_messages is used instead of home-brewed regexes for all Active Record macros.

New Macros

context "Creating a post"
  setup { Post.create }
  should_change "Post.count", :by => 1
end

# :from and :to examples
should_change "Post.count", :from => 0, :to => 1
should_change "@post.title", :from => "old", :to => "new"

context "Updating a post"
  setup { @post.update_attributes(:title => "new") }
  should_not_change "Post.count"
end

should_filter_params :password, :ssn

should_render_with_layout # defaults to application 
should_render_with_layout 'special'
should_render_without_layout

should_route :get, "/posts", :controller => :posts, :action => :index
should_route :delete, "/posts/1", :action => :destroy, :id => 1
should_route :get, "/users/1/posts/1", 
  :action => :show, :id => 1, :user_id => 1

should_respond_with_content_type 'application/rss+xml'
should_respond_with_content_type :rss
should_respond_with_content_type /rss/

should_return_from_session :user_id, "@user.id"

Before statements

class UserControllerTest < Test::Unit::TestCase
  context "the index action" do
    setup do
      @users = [Factory(:user)]
      User.stubs(:find).returns(@users)
    end

    context "on GET" do
      setup { get :index }

      should_respond_with :success

      # runs before "get :index"
      before_should "find all users" do
        User.expects(:find).with(:all).returns(@users)
      end
    end
  end
end

Automatically load custom macros

Writing custom macros is a common practice for The Modern Shoulda Developer. For example, should_have_attached_file used to be a handy custom macro to have around when you’re using Paperclip.

There were a few problems with that, however. Where should that macro go? RAILS_ROOT/test/test_helper.rb? Why do we have the same macro in multiple apps for the same plugin?

Enter the new shoulda_macros directory. Shoulda will automatically load custom macros she finds in:

• RAILS_ROOT/test/shoulda_macros
• RAILS_ROOT/vendor/gems/#{gem_name}/shoulda_macros
• RAILS_ROOT/vendor/plugins/#{plugin_name}/shoulda_macros

Now, every Paperclip user can use the latest should_have_attached_file because it is where it belongs.

should_be_restful is being deprecated

should_be_restful will be removed in a future release. It is currently in a grace period where you’ll see a warning during your test runs. It will be added to the new woulda gem if you care to keep using it. Its problems:

• It dissuades the programmer from good TDD practice. It’s working at too high level of abstraction and encourages the programmer to take too many big steps.
• It is an attempt to be like Rails scaffolding, which is a good way to learn REST, but the syntax is so cryptic it doesn’t accomplish that goal.
• It’s near impossible to find the line in your test file that is actually failing or erroring.
• You have no idea how many tests it generates or how they’re implemented, which lulls the programmer into a false sense of security.

Removed

• load_all_fixtures (use fixtures :all instead)
• shoulda.conf and color support (use the redgreen gem instead)

Credit

Ryan McGeary, Matt Jankowski, Mike Boone, Tammer Saleh, Josh Nichols, Joe Ferris, Keith Morrison, Me