Ever used a rubygem, found a bug, and just wanted to quickly bust out the big guns and fix it quickly?
The gem command doesn’t come packed with a way to find the original source repository for a gem. At best, most gems at least come bundled with the complete source, tests and documentation. Some gems don’t. Fair enough, since having access to the complete source via the gem still doesn’t allow you to fix a bug and share it with the world.
For that you access to the repo, a quick way to fork it, and a post-github way to share a gem version from yours truly.
The github gem and gemcutter are the modern day tools of master hackermanship.
Instant forking fun
Let’s say you find a bug in a gem, say rails, and you want to go to town on its source.
You know the gem is called rails but you’ve no idea what the github repo is called. Never fear.
$ gem sources -a http://gemcutter.org
$ sudo gem install github
$ gh clone --search rails
Select a repository to clone:
1. rails/rails # Ruby on Rails
2. technoweenie/restful-authentication # Generates common user ...
3. justinfrench/formtastic # A Rails form builder plugin ...
?
Press 1 and you’ll get a clone of rails/rails.
Alternately, if you want a fork or you know the exact user/repo already:
$ gh clone rails/rails
Now, fork your own version:
$ cd rails
$ gh fork
You now have your own fork. The origin remote also now points to your fork rather than the rails/rails repository:
$ git remote show origin
* remote origin
Fetch URL: git@github.com:drnic/rails.git
Push URL: git@github.com:drnic/rails.git
So, make your changes, push them. Send a pull request or github issue or lighthouse ticket or what have you.
Want to get to the github project home page for your fork?
$ gh home
Instant gem sharing
Let’s say you patched the rails gem itself but you want to share your changes via your own gem.
In the olden days, github did this for you. Now you use gemcutter, and a little manual effort to do your own renaming.
First, install the gems locally, use them, and make sure all is good.
For rails, you install the edge gems (3.0.pre) with:
$ rake install
You can’t see ‘rake install’ in the rake -T list (hence my patch), but I think the following expression displays all tasks regardless if they have a description or not:
$ rake -P | grep "^r"
Rails is composed of several gems, unlike most projects that are distributed as a single gem. Here we want to share our commit within a new drnic-rails gem, but not touch the others.
Edit the railties/rails.gemspec file from:
Gem::Specification.new do |s|
s.platform = Gem::Platform::RUBY
s.name = 'rails'
s.version = '3.0.pre'
...
and give your personal gem a new name:
Gem::Specification.new do |s|
s.platform = Gem::Platform::RUBY
s.name = 'drnic-rails'
s.version = '3.0.pre'
To build and distribute the new gem:
$ gem build railties/rails.gemspec
$ sudo gem install gemcutter
$ gem push drnic-rails-3.0.pre.gem
Pushing gem to Gemcutter...
Successfully registered gem: drnic-rails (3.0.pre)
Follow any first-time gemcutter instructions and SUCCESS! Now I have my own drnic-rails gem.
Summary
To find, clone, and fork any rubygem that is hosted on github:
$ sudo gem install drnic-github
$ gh clone --search rails
$ gh fork
To personalise the gem and share it on gemcutter:
> edit the project.gemspec to have a unique name, e.g. yourname-project
$ gem build project.gemspec
$ sudo gem install gemcutter
$ gem push yourname-project-1.0.0.gem
I think this makes it much easier, faster and more fun to hack other people’s stuff.
Today I had my first look at rails 3.0.pre and below are the sequence of steps I had to take to create a rails 3.0.pre application, and get it’s generators to work.
Why was I looking at the top-secret, yet open-source Rails 3.0? Their generators are being migrated over to Thor and I wanted to see them in action. I was thinking I might migrate newgem to use Thor too.
Here’s a quick poke around of getting started and interesting things I found. Any hiccups and workarounds are meant as a guide to pre-pre-3.0 users/developers and not as a criticism of rails-core. Rails 3.0 is looking shiny and awesome.
NOTE: Since this is a “how to install and use” rails 3.0 edge, which is still in heavy development, this set of instructions might break. Let’s hope not.
Getting Started
As of today, you cannot install 3.0.pre from rubygems [1]. So, let’s install them from source. Which is handy, you might like to patch something.
$ cd ~/gems
$ git clone git://github.com/rails/rails.git
use_ruby_191 *
[*] If you are on OS X Snow Leopard I think you can ignore this. Otherwise, since you don’t have the 3.0.pre gems installed, you’re about to hit bump #1. Ruby 1.8.6 doesn’t have Symbol#to_proc but it’s required to create a rails app. This means you’ll need to be able to switch to another version of ruby temporarily if you’re on ruby 1.8.6 [2].
cd ~/Sites
ruby ~/gems/rails/railties/bin/rails
Oooh, look at all the new options! Some new ones are:
-F, [--freeze] # Freeze Rails in vendor/rails from the gems
-O, [--skip-activerecord] # Skip ActiveRecord files
-T, [--skip-testunit] # Skip TestUnit files
-J, [--skip-prototype] # Skip Prototype files
The -D, --with-dispatchers flags have been removed. --freeze isn’t new, but -F is.
So, to create an app, I dutifully used:
ruby ~/gems/rails/railties/bin/rails edgerailsapp -F
BAM! Fail. The -F option to freeze/vendor rails fails without the gems installed. So don’t use it.
ruby ~/gems/rails/railties/bin/rails edgerailsapp
ln -s ~/gems/rails vendor/rails
If you’re on Windows without the symlink command ln, then copy the downloaded rails source into vendor/rails.
Fetch Rails’ dependencies
Rails 3.0 source uses the new bundler project to describe its own dependencies. From Nick Quaranto’s article on bundler, get the latest:
cd ~/gems
git clone git://github.com/wycats/bundler
cd bundler
sudo rake install
Now, back in your app, you need to install some rails dependencies here too. It’s a good chance to see how you’ll bundle gem dependencies in the future.
$ cd ~/Sites/edgerailsapp
Change the Gemfile in your project to the following:
gem "rack", "1.0.1"
gem "rack-mount", :git => "git://github.com/rails/rack-mount.git"
gem "rack-test", "~> 0.5.0"
gem "erubis", "~> 2.6.0"
gem "arel", :git => "git://github.com/rails/arel.git"
gem "sqlite3-ruby"
gem "rails", "3.0.pre", :git => "git://github.com/rails/rails.git"
Welcome to the future of gem dependencies for rails apps. Ultimately you won’t need to manually add these lines yourself. When rails is distributed as gems it will automatically install these for you, I assume/hope/guess. But for today, you seem to need them.
Now locally (within your app) install these gems:
$ gem bundle
If you get “can’t convert Pathname into String” then revert to ruby 1.8.X and reinstall bundler into your 1.8 gem cache.
Phew. Ooh, my god. Phew. Only now will script/generate work.
$ script/generate
For me, this outputs:
Please select a generator.
Builtin: app, controller, generator, helper, integration_test, mailer, metal, migration, model, model_subclass, observer, performance_test, plugin, resource, scaffold, scaffold_controller, session_migration, stylesheets.
Others: app_layout:app_layout, check_migration_version:check_migration_version, home_route:home_route.
The “Builtin” generators are the latest and greatest in Thor technology. Rails 3.0 no longer uses its own generator but is built upon Thor.
For example, our old favourite model generator works thusly:
$ script/generate model Post title:string --no-fixture
invoke active_record
create db/migrate/20091103030824_create_posts.rb
create app/models/post.rb
invoke test_unit
create test/unit/post_test.rb
Interestingly, --no-fixture isn’t mentioned in the usage information for script/generate model. It mentions the --fixture flag, but I had to guess that --no-fixture was also supported.
Hmm, I want to use rspec. So, let’s destroy these files:
$ script/destroy model Post title:string
invoke active_record
.../vendor/gems/dirs/rails/railties/lib/rails/generators/active_record.rb:14:in
`next_migration_number': uninitialized constant ActiveRecord::Base (NameError)
Oh well.
What if I wanted to run rspec and cucumber generators, for example, against an edge rails app?
Rails 2 generators
The “Others” generators are my own local generators from ~/.rails/generators. Amusingly, instead of app_layout it is called app_layout:app_layout. Not surprisingly at all, if I try to run the rails 2 generator it fails:
$ script/generate app_layout:app_layout
[WARNING] Could not load generator at "/Users/drnic/.rails/generators/app_layout/app_layout_generator.rb". Error: uninitialized constant Rails::Generator
Could not find generator app_layout:app_layout.
Poop.
Note, I have rspec, rspec-rails and cucumber gems installed locally but I cannot see their rails generators above. Rails 3 doesn’t look for generators in the same way and old Rails 2 generators don’t work anymore.
That’s the news: every rails 2 generator is broken.
When I start to migrate some of mine I’ll post about it. In the meantime, José Valim has written some introduction thoughts on using Thor as a generator.
You can also probably learn about how to write rails 3.0 generators by looking at the source code for the new generators like rails, model (see main and test_unit), and scaffold/resource.
Finally, José Valim has a sample Rails 3 app with some vendored generators in it.
These are the things I’m researching now.
Summary
This article is long, mostly because rails 3.0.pre hasn’t been released as a set of RubyGems. If it had, then all the dependencies would be installed automatically.
It also introduces gem/plugin writers to the first upgrade issue: your current generators are neither discovered nor work by a rails 3.0 app. We’re all clever cookies, so here’s hoping we can figure out the upgrade path and that it’s simple enough to not be the topic of Dan Brown’s next book.
[1] Two portions of rails 3.0.pre are available as pre-release gems: activesupport (which is now very modularised and only loads up the parts that you require) and activemodel (which is shiny and new and hence completely safe for rails-core to release).
[2] There are two popular ways to have easy, non-intrusive access to alternate versions of ruby: rvm and ruby_switcher.sh.
“this article shows how I used test-driven development tools and processes on a Greasemonkey script.” Though it also includes free ninjas.
When I do online banking I need to select from a large list of other people’s bank accounts to which I might like to transfer money too. It is the massive drop down list that I must scroll through that I wish to raise issue with today. The problem of having to give other people money is probably a different discussion.
And take those time-zone selector drop down lists, for example, the massively long list rendered by Rails’ time_zone_select helper. Granted, I am thankful for you letting me choose my timezone in your web app. Though for those of us not living in the USA we must hunt for our closest city in the list. Dozens of locations, ordered by time zone and not the name of the city (see adjacent image). Unfortunately you can’t easily type a few letters of your current city to find it. Rather, you have to scroll. And if you live in the GMT+1000 time zone group (Eastern Australia), you have to scroll all the way to the bottom.
So I got to thinking I’d like a Greasemonkey (for Firefox) or GreaseKit (for Safari) script that automatically converted all ridiculously long HTML drop down lists into a sexy, autocompletion text field. You could then type in “bris” and be presented with “(GMT+1000) Brisbane”, or given the less amusing banking scenario then I could type “ATO” and get the bank account details for the Australian Tax Office.
I mean, how hard could it be?
This article is two things: an introduction to Ninja Search JS which gives a friendly ninja for every drop down field to solve the above problem. Mostly, the rest of this article shows how I used test-driven development tools and processes on a Greasemonkey script.
Introducing Ninja Search JS
Click the banner to learn about and install the awesome Ninja Search JS. It includes free ninjas.
Currently it is a script for Greasemonkey (FireFox) or GreaseKit (Safari). It could be dynamically installed as necessary via a bookmarklet. I just haven’t done that yet. It could also be a FireFox extension so it didn’t have to fetch remote CSS and JS assets each time.
Ninja Search JS uses liquidmetal and jquery-flexselect projects created by Ryan McGeary.
Most importantly of all, I think, is that I wrote it all using TDD. That is, tests first. I don’t think this is an erroneous statement given the relatively ridiculous, and unimportant nature of Ninja Search JS itself.
TDD for Greasemonkey scripts
I love the simple idea of Greasemonkey scripts: run a script on a subset of all websites you visit. You can’t easily do this on desktop apps, which is why web apps are so awesome – its just HTML inside your browser, and with Greasemoney or browser extensions you can hook into that HTML, add your own DOM, remove DOM, add events etc.
But what stops me writing more of them is that once you cobble together a script, you push it out into the wild and then bug reports start coming back. Or feature requests, preferably. I’d now have a code base without any test coverage, so each new change is likely to break something else. Its also difficult to isolate bugs across different browsers, or in different environments (running Ninja Search JS in a page that used prototypejs originally failed), without a test suite.
And the best way to get yourself a test suite is to write it before you write the code itself. I believe this to be true because I know it sucks writing tests after I’ve writing the code.
I mostly focused on unit testing this script rather than integration testing. With integration testing I’d need to install the script into Greasemonkey, then display some HTML, then run the tests. I’ve no idea how’d I’d do that.
But I do know how to unit test JavaScript, and if I can get good coverage of the core libraries, then I should be able to slap the Greasemonkey specific code on top and do manual QA testing after that. The Greasemonkey specific code shouldn’t ever change much (it just loads up CSS and more JS code dynamically) so I feel ok about this approach.
For this project I used Screw.Unit for the first time (via a modified version of the blue-ridge rails plugin) and it was pretty sweet. Especially being able to run single tests or groups of tests in isolation.
Project structure
All the JavaScript source – including dependent libraries such as jquery and jquery-flexselect – was put into the public folder. This is because I needed to be able to load the files into the browser without using file:// protocol (which was failing for me). So, I moved the entire project into my Sites folder, and added the project as a Passenger web app. I’m ahead of myself, but there is a reason I went with public for the JavaScript + assets folder.
In vendor/plugins, The blue-ridge rails plugin is a composite of several JavaScript libraries, including the test framework Screw.Unit, and a headless rake task to run all the tests without browser windows popping up everywhere. In my code base blue-ridge is slightly modified since my project doesn’t look like a rails app.
Our tests go in spec. In a Rails app using blue-ridge, they’d go in spec/javascripts, but since JavaScript is all we have in this project I’ve flattened the spec folder structure.
The website folder houses the github pages website (a git submodule to the gh-pages branch) and also the greasemonkey script and its runtime JavaScript, CSS, and ninja image assets.
A simple first test
For the Ninja Search JS I wanted to add the little ninja icon next to every <select> element on every page I ever visited. When the icon is clicked, it would convert the corresponding <select> element into a text field with fantastical autocompletion support.
For Screw.Unit, the first thing we need is a spec/ninja_search_spec.js file for the tests, and an HTML fixture file that will be loaded into the browser. The HTML file’s name must match to the corresponding test name, so it must be spec/fixtures/ninja_search.html.
For our first test we want the cute ninja icon to appear next to <select> drop downs.
require("spec_helper.js");
require("../public/ninja_search.js"); // relative to spec folder
Screw.Unit(function(){
describe("inline activation button", function(){
it("should display NinjaSearch image button", function(){
var button = $('a.ninja_search_activation');
expect(button.size()).to(be_gte, 1);
});
});
});
The Blue Ridge textmate bundle makes it really easy to create the describe (des) and it (it) blocks, and ex expands into a useful expects(...).to(matcher, ...) snippet.
The two ellipses are values that are compared by a matcher. Matchers are available via global names such as equals, be_gte (greater than or equal) etc. See the matchers.js file for the default available matchers.
The HTML fixture file is important in that it includes the sample HTML upon which the tests are executed.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Ninja Search | JavaScript Testing Results</title>
<link rel="stylesheet" href="screw.css" type="text/css" charset="utf-8" />
<script src="../../vendor/plugins/blue-ridge/lib/blue-ridge.js"></script>
</head>
<body>
<div>
<label for="person_user_time_zone_id">Main drop down for tests</label>
<select name="person[user][time_zone_id]" id="person_user_time_zone_id" style="display: inline;">
<option value="Hawaii">(GMT-10:00) Hawaii</option>
<option value="Alaska">(GMT-09:00) Alaska</option>
<option value="Pacific Time (US & Canada)">(GMT-08:00) Pacific Time (US & Canada)</option>
<option value="Arizona">(GMT-07:00) Arizona</option>
<option value="Mountain Time (US & Canada)">(GMT-07:00) Mountain Time (US & Canada)</option>
<option value="Central Time (US & Canada)">(GMT-06:00) Central Time (US & Canada)</option>
<option value="Eastern Time (US & Canada)">(GMT-05:00) Eastern Time (US & Canada)</option>
</select>
</div>
</body>
</html>
In its header it loads the blue-ridge JavaScript library, which in turn loads Screw.Unit and ultimately our spec.js test file (based on corresponding file name), so ninja_search.html will cause a file spec/ninja_search_spec.js to be loaded.
To run our first test just load up the spec/fixtures/ninja_search.html file into your browser.
Your first test will fail. But that’s ok, that’s the point of TDD. Red, green, refactor.
Simple passing code
So now we need some code to make the test pass.
Create a file public/ninja_search.js and something like the following should work:
(function($){
$(function() {
$('select').each(function(index) {
var id = $(this).attr('id');
// create the Ninja Search button, with rel attribute referencing corresponding >select id="...">
$('> class="ninja_search_activation" rel="' + id + '">ninja search>/a>')
.insertAfter($(this));
});
});
})(jQuery);
Reload your test fixtures HTML file and the test should pass.
Now rinse and repeat. The final suite of tests and fixture files for Ninja Search JS are on github.
Building a Greasemonkey script
Typically Greasemonkey scripts are all-inclusive affairs. One JavaScript file, named my_script.user.js, typically does the trick.
I decided I wanted a thin Greasemonkey script that would dynamically load my ninja-search.js, and any stylesheets and dependent libraries. This would allow people to install the thin Greasemonkey script once, and I can deploy new versions of the actual code base over time without them having to re-install anything.
Ultimately in production, the stylesheets, images, and JavaScript code would be hosted on the intertubes somewhere. Though during development that would be long-winded and painful to push the code to a remote host just to run tests.
So I have three Greasemonkey scripts:
public/ninja_search.dev.user.js – loads each dependent library and asset from the local file systempublic/ninja_search.local.user.js – loads compressed library and asset from the local file systempublic/ninja_search.user.js – loads compressed library and assets from remote server
Let’s ignore the optimisation of compressing dependent JavaScript libraries for the moment and just look at the dev.user.js and user.js files.
The two scripts differ in the target host from which they load assets and libraries. ninja_search.dev.user.js loads them from the local machine and ninja_search.user.js loads them from a remote server.
For example ninja_search.dev.user.js loads local dependencies like this:
require("http://ninja-search-js.local/jquery.js");
require("http://ninja-search-js.local/ninja_search.js");
And ninja_search.user.js loads remote dependencies like this:
require("http://drnic.github.com/ninja-search-js/dist/jquery.js");
require("http://drnic.github.com/ninja-search-js/dist/ninja_search.js");
In the final version of ninja_search.user.js we load a simple, conpressed library containing jquery, our code, and other dependencies, called ninja_search_complete.js.
Using Passenger to server local libraries
The problem with loading local JavaScript libraries using the file:// protocol, inferred earlier, is that it doesn’t work. So if I can’t load libraries using file:// then I must use the http:// protocol. That means I must route the requests through Apache/Ningx.
Fortunately there is a very simple solution: use Phusion Passenger which serves a “web app’s” public folder automatically. That’s why all the javascript, CSS and image assets have been placed in a folder public instead of src or lib or javascript.
On my OS X machine, I moved the repository folder into my Sites folder and wired up the folder as a Passenger web app using PassengerPane. It took 2 minutes and now I had http://ninja-search.local as a valid base URL to serve my JavaScript libraries to my Greasemonkey script.
Testing the Greasemonkey scripts
I can only have one of the three Greasemonkey scripts installed at a time, so I install the ninja-search.dev.user.js file to check that everything is basically working inside a browser on interesting, foreign sites (outside of the unit test HTML pages).
Once I’ve deployed the JavaScript files and assets to the remote server I can then install the ninja-search.user.js file (so can you) and double check that I haven’t screwed anything up.
Deploying via GitHub Pages
The normal, community place to upload and share Greasemonkey scripts is userscripts.org. This is great for one file scripts, though if your script includes CSS and image assets, let alone additional JavaScript libraries, then I don’t think its as helpful, which is a pity.
So I decided to deploy the ninja-search-js files into the project’s own GitHub Pages site.
After creating the GitHub Pages site using Pages Generator, I then pulled down the gh-pages branch, and then linked (via submodules) that branch into my master branch as website folder.
Something like:
git checkout origin/gh-pages -b gh-pages
git checkout master
git submodule add -b gh-pages git@github.com:drnic/ninja-search-js.git website
Now I can access the gh-pages branch from my master branch (where the code is).
Then to deploy our Greasemonkey script we just copy over all the public files into website/dist, and then commit and push the changes to the gh-pages branch.
mkdir -p website/dist
cp -R public/* website/dist/
cd website
git commit -a "latest script release"
git push origin gh-pages
cd ..
Then you wait very patiently for GitHub to deploy your latest website, which now contains your Greasemonkey script (dist/ninja-search.user.js) and all the libraries (our actual code), stylesheets and images.
Summary
Greasemonkey scripts might seem like small little chunks of code. But all code starts small and grows. At some stage you’ll wish you had some test coverage. And later you’ll hate yourself for ever having release the bloody thing in the first place.
I wrote all this up to summarise how I’d done TDD for the Ninja Search JS project, which is slightly different from how I added test cases to _why’s the octocat’s pajamas greasemonkey script when I first started hacking with unit testing Greasemonkey scripts. The next one will probably be slightly different again.
I feel good about the current project structure, I liked Screw.Unit and blue-ridge, and I’m amused by my use of GitHub Pages to deploy the application itself.
If anyone has any ideas on how this could be improved, or done radically differently, I’d love to hear them!
Polish your Rails project with Mocra
I want to help you, your business, your boss and your project reach delightful levels of wickedly awesomeness. I’m so proud of the small team of ace Rails developers here at Mocra and what I know we can do for you.
Send an email to rails@mocra.com about your current/future projects. Dare us to be more awesome!
While you wait for a reply perhaps you’d like to learn more about How we do it at Mocra?
How to write helper libraries for your Cucumber step definitions and how to upgrade your support libraries from Cucumber 0.2 to 0.3 (released today).
In cucumber, each scenario step in a .feature file matches to a Given, When, Then step definition. The step definitions are normal Ruby code. First class, bonnified, honky-tonk Ruby code. And what’s the one thing we love to do to Ruby code on a rainy Sunday afternoon? Refactor it. Turn messy code into readable “return in 50 years, on the time capsule, and get back to work quickly” code.
In Cucumber we use a special, until-now unknown, magic technique for refactoring step definitions. They are called “Ruby methods”. Oooh, feel the magic. You take some code in a step definition and you refactor it into a method. And you’re done. For example:
When /I fill in the Account form/ do
fill_in("account_name", :with => "Mocra")
fill_in("account_abn", :with => "12 345 678 901")
click_button("Submit")
end
Could be refactored into:
When /I fill in the Account form/ do
fill_in_account_form
end
def fill_in_account_form
fill_in("account_name", :with => "Mocra")
fill_in("account_abn", :with => "12 345 678 901")
click_button("Submit")
end
Good work. Or is it? No, we’ve done something a little naughty. We’ve polluted the global object space with our method and turns out it just isn’t necessary. There’s a nicer way and a clean idiom for how/where to write helper methods.
Annoyingly, that idiom broke with the release of Cucumber 0.3. So I’ll introduce both so you can fix any bugs that you spot and know how to fix them.
The solution is to understand the existence of the World object and the clean technique for writing features/support/foobar_helpers.rb libraries of helper methods.
Introducing the World object
To ensure that each cucumber scenario starts with a clean slate, your scenarios are run upon a blank Object.new object. Or in a Rails project its a new Rails test session ActionController::IntegrationTest.
These are called World objects (see cucumber wiki). You pass in a specific World object you’d like to use, else it defaults to Object.new For a Rails project, you’re using Cucumber::Rails::World.new for your world object each time, which is a subclass of ActionController::IntegrationTest.
The benefit of a World object starting point for each scenario is that you can add methods to it, that won’t affect the rest of the Ruby world you live in: which will be the Cucumber runner. That is, you cannot accidently blow up Cucumber.
Extending the World object
Step 1, put methods in a module. Step 2, add the module to your World object.
So that we’re all extending Cucumber in the same way, there is a folder for where your helper methods should be stored, and a programming idiomatic way to do it. It has changed slight from Cucumber 0.2 to 0.3 so I’ll show both.
For our helper method fill_in_account_form above:
- Create features/support/form_submission_helpers.rb (its automatically loaded)
- Wrap the helper method in a module
module FormSubmissionHelpers ... end
- Tell Cucumber to include the module into each World object for each Scenario
In Cucumber 0.3+ your complete helper file would look like:
module FormSubmissionHelpers
def fill_in_account_form
fill_in("account_name", :with => "Mocra")
fill_in("account_abn", :with => "12 345 678 901")
click_button("Submit")
end
end
World(FormSubmissionHelpers)
For Cucumber 0.2 your complete helper file might have looked like:
module FormSubmissionHelpers
def fill_in_account_form
fill_in("account_name", :with => "Mocra")
fill_in("account_abn", :with => "12 345 678 901")
click_button("Submit")
end
end
World do |world|
world.extend FormSubmissionHelpers
end
Where the difference is the last part of the file. This mechanism is deprecated and results in the following error message after upgrading to Cucumber 0.3:
/Library/Ruby/Gems/1.8/gems/cucumber-0.3.0/bin/../lib/cucumber/step_mother.rb:189:in `World': You can only pass a proc to #World once, but it's happening (Cucumber::MultipleWorld)
in 2 places:
vendor/plugins/cucumber/lib/cucumber/rails/world.rb:72:in `World'
vendor/plugins/email-spec/lib/email_spec/cucumber.rb:18:in `World'
Summary
Refactor step definitions. Put it in features/support/…_helpers.rb files, inside modules that are assigned to the World object.
And a word from our sponsor
Starting a new Rails project and need the team that is up-to-date with all the latest and greatest gadgetry, plugins and gems, styles and processes for enterprise and web2.0 web applications? Ask us at Mocra.
Need professionals to help your Rails project burst over the finish line? Ask us at Mocra.
Got a simple app you want to build? Allocate 5 minutes for initial code generation, slice setup, and initial deployment. All from the command line. In one command. Booya!
How long does it take to start a new Rails project? Surely just a moment? rails new_project -m path/to/some/template.rb
But your application isn’t deployed yet. The DNS isn’t ready, the remote slice doesn’t exist or the config for this new application isn’t setup. Heck, the code hasn’t even been pushed to a non-existent remote repository yet.
And what if you’re going to use something like twitter_auth for authentication? You’ll need to register your application with Twitter at http://twitter.com/oauth_clients.
All these things could be automated, surely. Surely?
If they were then you’d have a “one click” command. A new Rails app, pushed into production, and ready to rock and roll. Complete with either restful_authentication or twitter-based oauth integration.
What does a “one click” rails and deploy command look like?
cd Sites
rails -m rails-templates/mocra.rb default-twitter-auth-app
1. restful_authentication
2. twitter_auth
Which user authentication system? 2
1. mocra-primary
2. mocra-secondary
3. crazy-pron-sites
Install http://default-twitter-auth-app.mocra.com application on which slice? 3^H1
1. drnic
2. mocra
Which twitter user? 1
Then you wait 3 minutes and 53 seconds.
Then you visit http://default-twitter-auth-app.mocra.com and it is working. You click the “Protected” link and you are redirected to Twitter to click the “Allow” link. You return to the app. You are registered with an account and logged in. You see your own face. You rock.
The rest of the article shows you how to test run it yourself, explain the dependencies and how to install them, and how to unit test your own templates to do similarly fancy things. Hopefully its helpful.
WAITING A MINUTE – is this tutorial destructive to my precious slices?
It is safe. IF you have an existing slicehost slice that was created with the latest deprec gem.
Perhaps backup your slice anyway. But it should be safe.
Deprec installs each application in its own folder and the apache settings are in their own file etc. But when deprec installs apache, passenger, etc it may put them in places you aren’t expecting. It might not. I just can’t promise anything.
Testimonial that the tutorial works
Ryan Bigg offers the following testimonial to encourage you to actually try out the tutorial:
“I have, dear readers, with as little effort as a few keystrokes, an an application base that allows my users to sign up using their twitter credentials. I have my code base here on my machine, and the running application in production over there at http://ryan.mocra.com” Ryan Bigg (radar)
Required gems for the template
There are a couple of one-time-only steps to run to install some gems and setup github and slicehost API keys locally.
gem install highline
gem install deprec
gem install defunkt-github --source http://gems.github.com
gem install booster-slicehost-tools --source=http://gems.github.com
To setup the github gem with your API key:
* login to [http://github.com/](http://github.com/)
* click [account](https://github.com/account)
* click "Global Git Config"
* copy and paste the two lines of config into the terminal to install the config
The github gem will now use this configuration automatically.
To setup the slicehost gem with your API key:
slicehost-slice list
Please enter your API key since you did not provide one:
To get your slicehost API:
Required gems and steps for using twitter_auth
My fork of the twitter gem includes a twitter register_oauth ... command. If John integrates the code, or writes his own, I’ll drop my fork and rewrite my template to use his gem. Til then use this one.
gem install drnic-twitter --source=http://gems.github.com
twitter install
twitter add
And enter your twitter account details. You can run the last command any number of times to add personal and corporate/product twitter accounts. I am really impressed with the internals of this gem – it stores your data in a sqlite3 gem and uses ActiveRecord models to retrieve it. Might create a generator for this in newgem. I also liked the use of the main gem for its command definition. Anyway, we’re off the topic.
Cloning and running the rails-templates
Imagine the above steps were “Buy an Xbox 360. Buy Guitar Hero.” Now its the final step. It’s time to rock.
cd ~/Sites
git clone git://github.com/drnic/rails-templates.git
DOMAIN=yourdomain.com ORGANIZATION="Your Company of Legends" rails -m rails-templates/mocra.rb my_app
A few minutes later you can open http://my-app.yourdomain.com in a browser. It will have restful_authentication or twitter oauth integration all setup and working (except email settings for restful_authentication).
It makes me very happy watching it work.
If the above command has stalled after printing ‘executing slicehost-slice list’ then you haven’t set up your slicehost API key. See the instructions above.
Dirty, nasty assumptions?
How can you deploy an entire app and have it up and running without some more configuration? Surely… surely I’ve made some nasty assumptions and come up with some dirty defaults?
Yes.
Your application url will be my-app-name.mocra.com. The subdomain is a dasherized version of your application’s folder name. Use DOMAIN=mycompany.com to change the domain.
Your local and remote database is mysql, accessible with user root and no password. I… look… you see there was this dog… and he ate my homework… it wasn’t me… there was an earthquate, a volcano, a flood… it wasn’t me!
You are deploying to slicehost. I do. It has command-line applications to manage slices and DNS. Since I’m deploying to a subdomain of mocra.com I use slicehost to create a CNAME in the DNS.
Your target slice already exists and has been built using the latest deprec. The template let’s you select an existing slicehost slice to use. If you don’t have one that was built with deprec, perhaps create a new one.
Gems? Plugins? Yes this template installs the ones that I want. That’s the point of rails templates – you create your own set of defaults.
What do I do to get my own uber-template?
Copy + paste the mocra.rb template and hack in your configuration. Fork the github project and push up your file so others can see your awesomeness.
See the section on unit testing templates too.
What’s missing?
The primary thing that I want that I haven’t gotten around to writing/fixing/finding a solution is the creation of private, company github projects. That is, instead of public/open-source, personal projects using github create-from-local.
I guess I would want a github create-from-local --private flag to create a private repo instead of a public repo.
Then I’d want the github gem to know that I live in a world of multiple github accounts: my personal account (drnic) and my company’s account (mocra). That is, I’ll want new private company projects to go on the company account.
And then I’ll want it to add me (drnic) as a collaborator. Or a whole group of people.
Since the github gem currently derives its user + API token information from your global git config (git config --get github.user), instead of a nice external sqlite3 database like the twitter gem, I’m not sure what the best/correct data structure would be to add multiple user support to the github gem.
Or perhaps the github create-from-local mechanism should be extracted out of the github gem all together into a github-admin gem which would have multiple users, create public/private repos, add collaborators etc. Yeah, that might be better.
Want a default application theme?
The template will attempt to invoke a generator app_layout if it can find it. Watch the railscast on generators for an example of how to create a local generator and he gives an example of creating a default application theme generator. That’s why all the railscasts applications look the same!
Bonus section: unit testing a Rails template
If you look in the rails-templates project you cloned you’ll see a spec folder. There is a mock template_runner.rb which is used by the spec/mocra/template_spec.rb. This way I can stub out calls to command-line tools like slicehost-slice list and twitter register_oauth and check that the template installs the correct plugins, creates the correct files, etc without actually installing or creating anything.
More importantly its a lot bloody faster to run than the full template.
If you’re creating Rails templates with interesting logic in them then writing some unit tests for your template might be a helpful idea to save time.
