---
title: Clearance Is A Rails Engine
teaser:
tags: news,web,ruby,rails,open source,clearance
author: Dan Croak
published_on: 2009-04-22
---

Clearance is now a Rails engine...BLAOW!

### Why

Clearance has served us well for many months. Our only complaints were shared by
others:

* [lots of includes](http://twitter.com/hasmanyjosh/status/1243860761)
* too much generated code
* too many tests to maintain
* sometimes awkward to override functionality

<object width="425" height="344">
  <param name="movie" value="http://www.youtube.com/v/21OH0wlkfbc&amp;hl=en&amp;fs=1"
    />
  <embed src="http://www.youtube.com/v/21OH0wlkfbc&amp;hl=en&amp;fs=1"
    type="application/x-shockwave-flash" width="425" height="344" />
</object>

With the re-institution of Rails engines in Rails 2.3, we decided to convert
Clearance to engine. The process was relatively painless, the code is far
cleaner, and we think we were able to scratch all our itches.

### Philosophy

We **highly recommend** that you use the [Cucumber](http://cukes.info) features
that come with Clearance to test the integration of the engine with your app:

    script/generate clearance_features

You no longer run Clearance's generated Shoulda &amp; Factory Bot tests within
your test suite. That code is unit tested internally. Use the Cucumber features
to test integration. If and when you override functionality, write your own unit
tests.

Read [Mixing Cucumber with
Test::Unit/Shoulda](https://thoughtbot.com/blog/2009/2/20/mixing-cucumber-with-test-unit)
if you're getting started with Cucumber and not using RSpec.

### Overriding

We haven't and probably won't ever move Clearance beyond email and password
authentication, despite frequent requests. We're focused on clean code that
works for the baseline authentication we've written over and over again for
clients.

A **huge** part of clean code that works means that overriding
Clearance needs to be painless. The change to an engine helps achieve that
goal.

```ruby
class UsersController < Clearance::UsersController
  def edit
    ...
  end
end

ActionController::Routing::Routes.draw do |map|
  map.resources :users
end
```

That's it.

* Write your tests for whatever action you want to add or override.
* Subclass one of Clearance's controllers (`Users`, `Sessions`, `Passwords`, and
  `Confirmations`).
* Update your routes (by default, the routes will point to the namespaced
  Clearance controllers).

### The Royal Library of Alexandria

All knowledge pertaining to Clearance can be found on its [Github
wiki](http://wiki.github.com/thoughtbot/clearance), where you'll find such
articles as:

* [Upgrading to Rails
  engine](http://wiki.github.com/thoughtbot/clearance/upgrading-to-rails-engine)
* [Organization](http://wiki.github.com/thoughtbot/clearance/organization) of
  modules, routes, & flashes
* Extending Clearance with
  [usernames](http://wiki.github.com/thoughtbot/clearance/sign-up-sign-in-with-user-name),
  [admins](http://wiki.github.com/thoughtbot/clearance/admin), or [invite
  codes](http://wiki.github.com/thoughtbot/clearance/invites-and-clearance)

.. and much more.

Enjoy!

Visit our [Open Source page](https://thoughtbot.com/open-source) to learn more about our team's contributions.