technical.pickles - josh on technical stuff

Jeweler turns 1.0.0

Wed May 06 00:00:00 -0400 2009

There’s always a certain amount of stigma, fear, and uncertainty around the doing the big 1.0 release. I finally got over that for Jeweler. So, be hold! Jeweler 1.0.0.

For the uninitiated, Jeweler is a tool for creating and managing RubyGems projects. It lets you quickly go from 0 to released gem. It also simplifies managing your gem after you create it.

There are two main components to jeweler: the generator for creating an initial project, and the rake tasks for managing versioning and releases.

Install it


sudo gem install jeweler

The generator

The simplest incantation of the jeweler is this:


jeweler your-awesome-gem

This creates a local git repository with a basic skeleton for your project. It includes things like a Rakefile, a template to put your gem’s code in, a test helper, a failing test case, and a LICENSE. It also setup to be pushed to GitHub and includes a reasonable gitignore file.

By default, you’ll get Shoulda flavored tests, but you can opt to go with test/unit, minitest, rspec, bacon, or micronaut. For example:


jeweler —micronaut your-awesome-gem

If you want to use cucumber, you can have that too. It’ll be setup for whichever testing framework you choose:


jeweler —micronaut —cucumber your-awesome-gem

You can also choose to have a repository created for you on GitHub, with RubyGem creation enabled:


jeweler —create-repo your-awesome-gem

While originally intended specifically to work with GitHub’s gem support, it eventually was realized that it’d be nice to release to RubyForge too. You can add support to your project:


jeweler —rubyforge your-awesome-gem

If you look at your Rakefile, you’ll notice that a number of tasks were generated for you. Jeweler itself provides a number of tasks, as mentioned, but it also tasks for rdoc, test or spec, and rcov. However, your Rakefile doesn’t depend specifically on jeweler. This means that someone randomly cloning your project, and messing around with patching/testing it, then they don’t need to have jeweler installed.

The tasks

When you are ready to do a release, you first create the version. It is stored in VERSION (formerly VERSION.yml, but both work). This only updates what jeweler thinks the version is, and doesn’t actually release anything. It defaults to 0.0.0, but you can choose to specify your own:


rake version:write
rake version:write MAJOR=1 MINOR=5 PATCH=3

You’d typically release after this initial version created. Releasing involves generating a gemspec based on your version, and pushing it to GitHub, and tagging the release:


rake release

After your initial release, you can bump the version easily. You can choose to do the major, minor, or patch version. For 1.5.3, 1 is the major, 5 is the minor, and 3 is the patch:


rake version:bump:patch
rake version:bump:minor
rake version:bump:major

Version bumping only updates what version jeweler thinks you are using. You’ll need to do a release to actually release:


rake release

If you’ve configured your project for releasing to RubyForge, and you’ve registered your project, you can prepare RubyForge for it:


rake rubyforge:setup

Then you can release the docs and gem:


rake rubyforge:release

More resources

This has been a pretty high level overview and scant on details, so you might want to check out:

The README
The Wiki
The RDoc
The Issues
The Source

Tumbling away

Fri Apr 24 00:00:00 -0400 2009

Blog posts are hard. Tweets are easy. Tumblr is somewhere in between.

I’ve began a new tumblr, Technical Pickle Jar. The general intent is that it captures my current softwarey thoughts, that haven’t quite matured to full blog post status.

So, if you’re dying to know what’s on my mind, check it out

Ruby stubbing and mocking with rr

Tue Apr 14 00:00:00 -0400 2009

Double Ruby, or rr for short, is a “test double framework” for Ruby. According to the rr README, “A Test Double is a generalization of something that replaces a real object to make it easier to test another object. It’s like a stunt double for tests. The following are test doubles: Mocks, Stubs, Fakes, Spies, Proxies”. It is in the same niche as frameworks like mocha, flexmock, and the mocking support built into RSpec.

So why bother with another framework when the others have been well established and work well? I have two main reasons:

* Terser syntax that’s more rubyish (you call the methods you want to mock, with the parameters you want) * More advanced functionality (test spies are my particular favorite)

I’m going go over the functionality I’ve been using, with a few asides when it’s much different than mocha and RSpec.

Installation

The rr gem is, well, rr:


sudo gem install rr

Then you must update your helper to use rr. In test/unit, you’d update test/test_helper.rb to include:

require 'rr'

class Test::Unit::TestCase
  include RR::Adapters::TestUnit
end

For RSpec, you’d want to update spec/spec_helper.rb to include:

require 'rr'

Spec::Runner.configure do |config|
  config.mock_with RR::Adapters::Rspec
end

Gotchas

If after installing RR, you get errors like “stack level too deep (SystemStackError)” coming from inside RR, there’s a good chance your helper is being loaded multiple times from different paths.

For example, test/test_foo.rb does require File.join(File.dirname(__FILE__), 'test_helper'), and test/foo/test_bar.rb does require File.join(File.dirname(__FILE__), '..', 'test_helper'). This means that test/test_helper and test/bar/../test_helper are both being required. They have have different paths even though they refer to same file because the ruby interpreter isn’t smart enough to normalize it.

Doing a proper fix for this multiple-require problem in your project is beyond the scope of this article, but here’s a quick fix:

class Test::Unit::TestCase
  include RR::Adapters::TestUnit unless include?(RR::Adapters::TestUnit)
end

Stubbing

Stubbing lets you replace the implementation of an object, no strings attached.

This will stub away any all calls to trogdor.burninate, regardless of the values and number of arguments.

stub(trogdor).burninate

You’ll often want to make a stub return a specific value. You can specify this with a block or returns. I’ve generally found the former to be more readable.

stub(countryside).burninated? { true }
stub(peasants).burninated?.returns(true)

If you need to stub a method to raise an exception, you can use the same mechanic for returning a value. Just use a block to define a return value, raise something instead of returning.

stub(trogdor).come_in_the_day { raise "the Trogdor comes in the NIIIIIIIIIIIIGHT!!!!!" }

As I mentioned, all these examples will match any invocation of stubbed method. You can be pickier though, and give the arguments you expected it to be called with. You can just pass the values you want to the stub. You can also fallback to using with:

stub(trogdor).burninate(countryside)
stub(trogdor).burninate.with(peasants)

Mocking

Mocking is similar to stubbing, except it adds an expectation. If you mock something, and it isn’t called, then your test will fail.

You can mostly take the examples above, and replace stub with mock, and away you go.

mock(trogdor).burninate
mock(countryside).burninated? { true }

There is one difference that I’ve seen though. If you mock a method without any arguments… it will only match being called without any arguments. This is different than how mocha/rspec work.

mock(inbox).from_a_female? { false }
inbox.from_a_female?(email) # ERROR! expected no args, but got one arg!

One way around this is to use rr’s wildcard matchers. I’m not going to detail all the possibilities, but I’ll just say we can use anything to match any argument passed to it. Check the README for other matchers.

mock(inbox).from_a_female?(anything) { false }
inbox.from_a_female?(email) # No error, but still not from a female

Don’t allow method calls

rr lets you indicate a method should never be called, and will raise an error if it does. You can use the same style above for specifying argument.

dont_allow(strong_sad).improve_on_methods_of(strong_bad)

Mock and stub objects

Sometimes you might want to make a pure mock object, without using a specific implementation. rr doesn’t support this as well as mocha or rspec. You can create bare @Object@s, and stub or mock as necessary.

cottage = Object.new
stub(cottage).burninated? { true }

(There is a mock! helper for making pure mock objects, but I haven’t had consistently good experiences with it.)

Instances of

Want all your peasants to be burninated in one fell swoop?

stub.instance_of(Peasant).burninated? { true }

You can mock it as well, and specify arguments.

Test spies

Test spies let you stub a method, and then latter assert the values it was called with.

stub(trogdor).burninate(countryside)
stub(trogdor).burninate(peasant)

trogdor.come_in_the_night

assert_received(trogdor) {|trogdor| trogdor.burninate(countryside) } # test/unit
trogdor.should have_received.burninate(countryside) # rspec
trogdor.should have_received(:burninate).with(countryside) # rspec, same thing

A more detailed example

I have found this extremely useful with rspec and shoulda, where you might stub in a before/setup block, and then have tests that add expectations on those being called. Consider this example using shoulda and mocha:

context "coming in the night" do
  setup do
    trogdor.stubs(:burninate).with(countryside).returns(true)
    trogdor.stubs(:burninate).with(peasants).returns(true)
    
    trogdor.come_in_the_night
  end

  before_should "burninate the countryside" do
    trogdor.expects(:burninate).with(countryside).returns(true)
  end

  before_should "burninate the peasants" do
    trogdor.expects(:burninate).with(countryside).returns(true)
  end
end

before_should is used to set an expectation before the setup block actually gets called. This is kind of annoying because you have specify the return values each time. We’re able to express this with RR much more concisely, and without having to rely on before_should:

context "coming in the night" do
  setup do
    stub(trogdor).burninate { true }
    
    trogdor.come_in_the_night
  end

  should "burninate the countryside" do
    assert_received(trogdor) {|trogdor| trogdor.burninate(countryside) } 
  end

  should "burninate the peasants" do
    assert_received(trogdor) {|trogdor| trogdor.burninate(peasants) } 
  end
end

Rails

There’s nothing special about using rr for Rails. If you’re using rspec, though, you may want to checkout rspec-rr which provides an rr-ified mock_model and stub_model. It does not seem to support :null_object => true though.

Gotchas

Method missing

rr doesn’t always play nice with stubbing/mocking methods that are provided by method_missing. I’ve had particularly bad times with ActionMailer::Base subclasses.

The issue is that rr works by doing alias_method down in its inner bowls, and you can’t alias a method that doesn’t exist. rr works around this by trying to send to the non-existent method, hoping that the act of sending will define it before trying to send again. It does so without any arguments, so if you are stubbing a method that has any arguments, you are going to see some funky @ArgumentError@s.

One work around for this is to stub out method missing itself, and pass it the name of the method you care about. I found the slightly alternative syntax works best:

stub(PeasantMailer, :deliver_burnination).with(peasant)

You should be able to use test spies on this too:

PeasantMailer.should have_received.method_missing.with(:deliver_burnination, peasant)

Test spies for assignment

There’s a possibility you would want to use test spies for while testing assignments:

stub(trogdor).species = 'dragon'

If you were using test/unit, you’d verify it like:

assert_received(trogdor) {|trogdor| trogdor.species = 'dragon' }

There’s a good chance you’ll get a message to the effect call isn’t defined on the String ‘dragon’. This is caused because inside the block, rr is doing some trickery with method_missing to record what methods you call on trogdor. I’m told that when you do assignment, the ruby interpreter will always return the assigned value, so rr gets confused when it gets a string, rather than it’s own objects to track method calls.

The ugly fix for this is to use it’s method_missing more directly.

assert_received(trogdor) {|trogdor| trogdor.method_missing(:species=, 'dragon') }

Anything else?

I came In reality, I’m only beginning to scratch the surface of rr. The terse syntax and test spies are the things that got me hook, but there are other features that look promising, like proxying and stubbing method chains.

Debugging Cucumber

Mon Mar 30 00:00:00 -0400 2009

Cucumber has been the new hotness when it comes to acceptance and integration testing. But, like any other tool testing tool, your test cases can fail in unexpected ways.

This article covers a couple I tricks I found to uncover the cause of cucumber failures.

ruby-debug

breakpoint

I’m a big fan a ruby-debug. To get started, you have to add a little setup to features/support/env.rb.

require 'ruby-debug'

Then, you can place breakpoint anywhere in your code, such as in your application code, or somewhere in a step definition

Then /^the process should exit cleanly$/ do
  breakpoint
  assert @exited_cleanly, "Process did not exit cleanly: #{@stdout}"
end

Note, that if you put the breakpoint at the end of a block, you need to add another statement after breakpoint. If you don’t, then ruby-debug will drop into the calling block, which can be very confusing.

Then /^the process should exit cleanly$/ do
  assert @exited_cleanly, "Process did not exit cleanly: #{@stdout}"
  breakpoint; 0
end

Then I debug

I found it convenient to have a debug step like “Then I debug”, which I put in features/step_definitions/debug_steps.rb:

Then /^I debug$/ do
  breakpoint
  0
end

The main benefit I found to having this step is that you can place it exactly where you want in a problematic feature. If you were to just put it in the step definition you are having problems with, and you use the step in multiple place, then it take more effort to debug to the exact place you want to.

Webrat

Webrat is the default tool for doing cucumber testing with Rails. It lets you do things like click links, type and submit forms, and so on.

There will be times where you try to click on something, for example, and it’s not there. You’ll get a big blob of HTML thrown back, and figuring out what that exactly means can be a real drag.

save_and_open_page

Webrat provides a method save_and_open_page which captures the current HTML, saves it, and then will open it in a browser for you. Extremely useful.

When /^I follow "(.*)"$/ do |link|
  save_and_open_page
  click_link(link)
end

This can get a little out of hand if you use this in a lot of places. Dozens of pages getting opened, even if things aren’t failing.

When /^I follow "(.*)"$/ do |link|
  begin
    click_link(link)
  rescue
    save_and_open_page
    raise
  end  
end

This will only open the page if something actually went wrong.

Conclusion

Cucumber is still a very young tool. Better ways of debugging will be found, but until then, ruby-debug and save_and_open_page will treat you well.

Escape Ruby Regular Expressions

Fri Feb 27 00:00:00 -0500 2009

If you’re doing any work with cucumber, it would do you well to become more familiar with Ruby regular expressions.

One useful piece of regular expression functionality is that you can interpolate variables inside an regular expression just like you would in a string. In cucumber, we could write a step like this:

Then /^I should see "(.*)"$/ do |text|
  assert_match /#{text}/, @response.body
end

There is a problem though. If text = 'Push Push (Lady Lightning) and @response_body = 'Push Push (Lady Lightning), the assertion would fail!

This is because there are some characters that have special meaning to regular expressions. Here, parentheses indicate capture groups which lets you extracted matched values. The net effect is the expression would match ‘Push Push Lady Lightning’ and capture “Lady Lighning”, but would not match ‘Push Push (Lady Lightning)’.

You can get around this by escaping characters with \ easily enough if we were doing it by hand. That won’t do for since we have a variable though. Fortunately, there is method Regexp.escape which takes a string and escapes any special characters.

We can update our step to look like:

Then /^I should see "(.*)"$/ do |text|
  assert_match /#{Regexp.escape(text)}/, @response.body
end

This assertion will now be successful if text = 'Push Push (Lady Lightning) and @response_body = 'Push Push (Lady Lightning) as you’d expected.

Using method_missing and respond_to? to create dynamic methods

Tue Feb 17 00:00:00 -0500 2009

method_missing is a well-known tool in the Ruby metaprogramming toolbox. It’s callback method you can implement that gets called when a object tries to call a method that’s, well, missing. A well known example of this is ActiveRecord dynamic finders. For example, if your User has an email attribute, you can User.find_by_email('joe@example.com') even though User nor ActiveRecord::Base have defined it.

method_missing’s cousin, respond_to?, is often forgotten though. respond_to? is used to determine if an object responds to a method. It is often used to check that an object knows about a method before actually calling it, in order to avoid an error at runtime about the method existing.

To have a consistent API when using method_missing, it’s important to implement a corresponding respond_to?.

Example

Imagine we have a Legislator class. We want a dynamic finder that will translate find_by_first_name('John') to find(:first_name => 'John'). Here’s a first pass:

class Legislator
  # Pretend this is a real implementation
  def find(conditions = {})
  end
  
  # Define on self, since it's  a class method
  def self.method_missing(method_sym, *arguments, &block)
    # the first argument is a Symbol, so you need to_s it if you want to pattern match
    if method_sym.to_s =~ /^find_by_(.*)$/
      find($1.to_sym => arguments.first)
    else
      super
    end
  end
end

That seems to do the trick. But Legislator.respond_to?(:find_by_first_name) would return false. Let’s add respond_to? to fix it.

class Legislator
  # ommitted
  
  # It's important to know Object defines respond_to to take two parameters: the method to check, and whether to include private methods
  # http://www.ruby-doc.org/core/classes/Object.html#M000333
  def self.respond_to?(method_sym, include_private = false)
    if method_sym.to_s =~ /^find_by_(.*)$/
      true
    else
      super
    end
  end
end

As commented, respond_to? takes two parameters. If you don’t do this, there’s a chance some library may expect to be able to invoke respond_to? with 2 parameters, resulting in an ArgumentError. In particular, the RSpec mocking library does this exactly this, and caused me a bit of befuddlement until I turned on full backtraces.

Possible refactorings

DRY

You might notice it’s not very DRY. We use the same pattern matching twice. This particular logic is simple, but it could be grow to be more complicated.

We can again look to ActiveRecord for inspiration. It encapsulates the logic in ActiveRecord::DynamicFinderMatch, to avoid repetition between method_missing and respond_to?, in addition to simplifying the methods.

class LegislatorDynamicFinderMatch
  attr_accessor :attribute
  def initialize(method_sym)
    if method_sym.to_s =~ /^find_by_(.*)$/
      @attribute = $1.to_sym
    end
  end
  
  def match?
    @attribute != nil
  end
end

class Legislator
  def self.method_missing(method_sym, *arguments, &block)
    match = LegislatorDynamicFinderMatch.new(method_sym)
    if match.match?
      find(match.attribute => arguments.first)
    else
      super
    end
  end

  def self.respond_to?(method_sym, include_private = false)
    if LegislatorDynamicFinderMatch.new(method_sym).match?
      true
    else
      super
    end
  end
end

Caching `method_missing`

Always passing through method_missing can be slow.

Another lesson we can take from is ActiveRecord is defining the method during method_missing, and then send to the now-defined method.

class Legislator    
  def self.method_missing(method_sym, *arguments, &block)
    match = LegislatorDynamicFinderMatch.new(method_sym)
    if match.match?
      define_dynamic_finder(method_sym, match.attribute)
      send(method_sym, arguments.first)
    else
      super
    end
  end
  
  protected
  
  def self.define_dynamic_finder(finder, attribute)
    class_eval <<-RUBY
      def self.#{finder}(#{attribute})        # def self.find_by_first_name(first_name)
        find(:#{attribute} => #{attribute})   #   find(:first_name => first_name)
      end                                     # end
    RUBY
  end
end

Testing

Being the test-minded individual that I am, no code would be complete without some testing.

Creating the LegislatorDynamicFinderMatch makes it straight forward to test your matching logic. An example using RSpec could look like:

describe LegislatorDynamicFinderMatch do
  describe 'find_by_first_name' do
    before do
      @match = LegislatorDynamicFinderMatch.new(:find_by_first_name)
    end
      
    it 'should have attribute :first_name' do
      @match.attribute.should == :first_name
    end
    
    it 'should be a match' do
      @match.should be_a_match
    end
  end
  
  describe 'zomg' do
    before do
      @match = LegislatorDynamicFinderMatch(:zomg)
    end
    
    it 'should have nil attribute' do
      @match.attribute.should be_nil
    end
    
    it 'should not be a match' do
      @match.should_not be_a_match
    end
  end
end

If you are creating dynamic methods which are just syntactic sugar around another method, like our finder, I think it is sufficient to use mocking to ensure the main method gets called with the correct arguments. Here’s an RSpec example:

describe Legislator, 'dynamic find_by_first_name' do
  it 'should call find(:first_name => first_name)' do
    Legislator.should_receive(:find).with(:first_name => 'John')
    
    Legislator.find_by_first_name('John')
  end
end

Summary

If you’re going to use method_missing, be sure to implement respond_to? in kind.

You can improve the DRYness of these methods by encapsulating the matching logic in a separate class, and you can improve performance by defining methods when they are missing.

Autoloading factory_girl definitions

Sun Feb 15 00:00:00 -0500 2009

I’d like to point out a feature that silently made it into factory_girl as of 1.1.4: autoloading of factory definitions.

If you create test/factories.rb, spec/factories.rb, they will automatically be required, making your factories available to your tests or specs.

Additionally, you can create directories named test/factories and spec/factories, and any .rb files will be required as well. I generally prefer this way, and name factories like urmodel_factory.rb, such that fuzzy finding files makes it easy to open up a specific factory.

This functionality was part the factory_girl_on_rails plugin I wrote several months ago before there was any autoloading. Once I got annoyed by having to install a plugin in addition to a gem, I found a way to do it inside of factory_girl herself, and you can now benefit from that work.

Relatedly, you can consider factory_girl_on_rails deprecated in favor of the built-in factory_girl functionality.

Adding Cucumber to a Ruby project

Fri Feb 13 00:00:00 -0500 2009

I had announced recently that jeweler now supports generating the files needed to use cucumber in your project. Personally, I’ve always been annoyed when looking for documentation about, for example, adding cucumber to your project, and then come across stuff that is like “Oh hai, just generate a project with jeweler, lol.”

I don’t want to be that guy, so here’s the process I used for adding Cucumber to the testing mix of jeweler.

Background

I’m not going to go any details about actually using Cucumber, so you’ll want to do a little reading ahead of time. I’d recommend the Cucumber website, the Cucumber Wiki on GitHub, and The RSpec Book (currently in beta).

File layout

Everything cucumber should live in features directory.
Features describing your project live in this features directory
features/support/env.rb sets up the world that the features will be run under
Steps live in the features/step_definitions directory

Here’s some convient bash one-liner for making the directories:

mkdir -p features/{support,step_definitions}

env.rb

You do have one choice to make here… what framework do you want to use implement your steps? The wiki has instructions for using Test::Unit, MiniTest, and RSpec.

It’s also worth noting that env.rb is the cucumber-equivalent of test_helper.rb or spec_helper.rb, so do any configuration or requireing here. For example you probably want to require your main ruby file from the lib directory. For jeweler, I did:

$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../../lib')
require 'jeweler'

Rake configuration

You do have a Rakefile, right? Given the file layout above, you can add this snippet:

begin
  require 'cucumber/rake/task'
  Cucumber::Rake::Task.new(:features)
rescue LoadError
  puts "Cucumber is not available. In order to run features, you must: sudo gem install cucumber"
end

Summary

Adding cucumber to a project is pretty straightforward, but all the info was never in one place. Hopefully, this article addresses that. Now you can have fun writing your features and step definitions.

Jeweler, now with support for test/unit, minitest, rspec, and cucumber

Tue Feb 03 00:00:00 -0500 2009

I had announced jeweler a few weeks ago, and it’s been very well received. It’s even the GitHub recommended way of managing your gems, which is pretty awesome.

Things haven’t been sitting still though. Version 0.8.1 is now released. Highlights include:

Support for generating projects with test/unit, minitest, and rspec in addition to shoulda and bacon.
Support for cucumber stories

You can get it using the usual gem install command:

# Run the following if you haven't already:
gem sources -a http://gems.github.com
# Install the gem:
sudo gem install technicalpickles-jeweler

See the jeweler command for possible arguments:

Usage: jeweler [options] reponame
e.g. jeweler the-perfect-gem
        --bacon                      generate bacon specs
        --shoulda                    generate shoulda tests
        --testunit                   generate test/unit tests
        --miniunit                   generate mini/unit tests
        --rspec                      generate rspec tests
        --create-repo                create the repository on GitHub
        --summary [SUMMARY]          specify the summary of the project
    -h, --help                       display this help and exit

That is all for now, so get crafting!

Craft the perfect gem with Jeweler

Mon Jan 19 00:00:00 -0500 2009

I’ve been working on Jeweler for some time now, but never announced it officially. That changes now. This is kind of a long winded intro, so if you want to get to just jump into the action without the explanation, check out the latest README.

Intro

Rubygems are the awesome way of distributing your code to others. GitHub and git are the best tools for version control of your project. GitHub can even generate a Rubygem if you include a gemspec.

The trouble is when developing your Rubygems on GitHub, you generally do one of the following:

Manage the gemspec by hand * … why bother doing something by hand when you can automate it?
Write your own Rake stuff to create the Gem::Specification and output it to a gemspec file, and deal with keeping the Rakefile and gemspec in sync * … why keep reinventing the wheel for each project?
Use hoe or echoe for generating the gemspec
- … why use tools made for the days before GitHub existed?
- … why have extra stuff you aren’t going to use or want?
- … what’s with the weird configuration that’s not particularly well documented except by example?

Jeweler was created with a few goals in mind:

Only use a Gem::Specification as configuration
Be one command away from version bumping and releasing
Store version information in one place
Only concern itself with git, gems, and versioning
Not be a requirement for using your Rakefile (you just wouldn’t be able to use its tasks)
Use Jeweler to manage Jeweler. Oh the meta!

Installation

Run the following if you haven’t already:

gem sources -a http://gems.github.com

Install the gem:

sudo gem install technicalpickles-jeweler

Configuration for an existing project

Armed with the gem, we can begin diving into an example. the-perfect-gem was setup as a simple example and showcase:

begin
  require 'jeweler'
  Jeweler::Tasks.new do |s|
    s.name = "jeweler"
    s.executables = "jeweler"
    s.summary = "Simple and opinionated helper for creating Rubygem projects on GitHub"
    s.email = "josh@technicalpickles.com"
    s.homepage = "http://github.com/technicalpickles/jeweler"
    s.description = "Simple and opinionated helper for creating Rubygem projects on GitHub"
    s.authors = ["Josh Nichols"]
    s.files =  FileList["[A-Z]*", "{bin,generators,lib,test}/**/*", 'lib/jeweler/templates/.gitignore']
    s.add_dependency 'schacon-git'
  end
rescue LoadError
  puts "Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
end

Here’s a rundown of what’s happening:

Wrap everything in a begin block, and rescue from LoadError * This lets us degrade gracefully if jeweler isn’t installed
Create an instance of Jeweler::Tasks
- It gets yielded a new Gem::Specification
- This is where all the configuration happens
- Things you definitely need to specify: * name
- Things you probably want to specify:
  - summary
  - email
  - homepage
  - description
  - authors
- Things you can specify, but have defaults * files, defaults to FileList["[A-Z]*.*", "{bin,generators,lib,test,spec}/**/*"]
- Things you shouldn’t specify: * version, because Jeweler takes care of this for you
- Other things of interest
  - executables, if you have any scripts
  - add_dependency, if you have any dependencies
- Keep in mind that this is a Gem::Specification, so you can do whatever you would need to do to get your gem in shape. See the reference for more details.
Bootstrap a new project

Before proceeding, take a minute to setup your git environment, specifically setup your name and email for git and your username and token for GitHub:

$ git config --global user.email johndoe@example.com
$ git config --global user.name 'John Doe'
$ git config --global github.user johndoe
$ git config --global github.token 55555555555555

Jeweler provides a generator, jeweler. It requires only one argument, the name of a repo you want to create. It also takes a few options:

–shoulda: generate shoulda-based tests (this is the default)
–bacon: generate bacon-based tests
–summary SUMMARY: specify the summary to use
–create-repo: create the repo on GitHub and enable rubygems for it

Putting it all together looks like:

$ jeweler --create-repo --summary "Oh so perfect" the-perfect-gem

The effect is this:

Creates the the-perfect-gem directory
Seeds it with some basic files:
- .gitignore, with the usual suspects predefined
- Rakefile, setup with tasks for jeweler, test, rdoc, and rcov
- README, with your project name
- LICENSE, MIT, with your name prefilled
- test/test_helper, setup with shoulda, mocha, and a re-opened Test::Unit::TestCase
- test/the_perfect_gem.rb, placeholder failing test
- lib/the_perfect_gem.rb, placeholder library file
Initializes a git repository
Sets up git@github.com:johndoe/jeweler.git as the origin git remote
Makes an initial commit
Creates up a new repository on GitHub and pushes to it (omit –create-repo to skip this)
Enables RubyGems for the repository

Overview of Jeweler workflow

Here’s the general idea:

Hack, commit, hack, commit, etc, etc
Version bump
Release
Have a delicious scotch

The hacking and the scotch are up to you, but Jeweler provides rake tasks for the rest.

Versioning

Versioning information is stored in VERSION.yml. It’s a plain YAML file which contains three things:

major
minor
patch

Consider 1.5.3. This maps to:

major == 1
minor == 5
patch == 3

Your first time

When you first start using Jeweler, there won’t be a VERSION.yml, so it’ll assume 0.0.0.

If you need some arbitrary version, you can do one of the following:

rake version:write MAJOR=6 MINOR=0 PATCH=3
Write VERSION.yml by hand (lame)

After that

You have a few rake tasks for doing the version bump:

$ rake version:bump:patch # 1.5.1 -> 1.5.2
$ rake version:bump:minor # 1.5.1 -> 1.6.0
$ rake version:bump:major # 1.5.1 -> 2.0.0

If you need to do an arbitrary bump, use the same task you used to create VERSION.yml:

$ rake version:write MAJOR=6 MINOR=0 PATCH=3

The process of version bumping does a commit to your repo, so make sure your repo is in a clean state (ie nothing uncommitted).

Release it

It’s pretty straight forward:

$ rake release

This takes care of:

Generating a .gemspec for you project, with the version you just bumped to
Commit and push the updated .gemspec
Create a versioned tag
Push the tag

Play the waiting game

How do you know when your gem is built? Has My Gem Built Yet was specifically designed to answer that question.

If it happens to be down, you can also check out the GitHub Gem repo’s list. Just search for yourname-yourrepo.

Putting it all together

# hack, hack, hack, commit, etc
$ rake version:bump:patch release

Now browse to http://hasmygembuiltyet.org/yourname/yourproject, and wait for it to be built.

Finale

You should have a good idea of what Jeweler is all about by now. It makes gem creation an impulse action. It makes managing versions of gems nice and automated.

Oh, and did I mention it is the GitHub recommended way for maintaining your gem?

Now go forth, and craft the perfect gem.

technical.pickles - josh on technical stuff

Jeweler turns 1.0.0

Install it

The generator

The tasks

More resources

Tumbling away

Ruby stubbing and mocking with rr

Installation

Gotchas

Stubbing

Mocking

Don’t allow method calls

Mock and stub objects

Instances of

Test spies

A more detailed example

Rails

Gotchas

Method missing

Test spies for assignment

Anything else?

Debugging Cucumber

ruby-debug

breakpoint

Then I debug

Webrat

save_and_open_page

Conclusion

Escape Ruby Regular Expressions

Using method_missing and respond_to? to create dynamic methods

Example

Possible refactorings

DRY

Caching method_missing

Testing

Summary

Autoloading factory_girl definitions

Adding Cucumber to a Ruby project

Background

File layout

env.rb

Rake configuration

Summary

Jeweler, now with support for test/unit, minitest, rspec, and cucumber

Craft the perfect gem with Jeweler

Intro

Installation

Configuration for an existing project

Bootstrap a new project

Overview of Jeweler workflow

Versioning

Your first time

After that

Release it

Play the waiting game

Putting it all together

Finale

Caching `method_missing`