== Preparation == === Create the basic app === The examples in this guide require that you have a working rails application. To create a simple rails app execute: ------------------------------------------------ gem install rails rails yaffle_guide cd yaffle_guide script/generate scaffold bird name:string rake db:migrate script/server ------------------------------------------------ Then navigate to http://localhost:3000/birds. Make sure you have a functioning rails app before continuing. .Editor's note: NOTE: The aforementioned instructions will work for sqlite3. For more detailed instructions on how to create a rails app for other databases see the API docs. === Generate the plugin skeleton === Rails ships with a plugin generator which creates a basic plugin skeleton. Pass the plugin name, either 'CamelCased' or 'under_scored', as an argument. Pass `\--with-generator` to add an example generator also. This creates a plugin in 'vendor/plugins' including an 'init.rb' and 'README' as well as standard 'lib', 'task', and 'test' directories. Examples: ---------------------------------------------- ./script/generate plugin yaffle ./script/generate plugin yaffle --with-generator ---------------------------------------------- To get more detailed help on the plugin generator, type `./script/generate plugin`. Later on this guide will describe how to work with generators, so go ahead and generate your plugin with the `\--with-generator` option now: ---------------------------------------------- ./script/generate plugin yaffle --with-generator ---------------------------------------------- You should see the following output: ---------------------------------------------- create vendor/plugins/yaffle/lib create vendor/plugins/yaffle/tasks create vendor/plugins/yaffle/test create vendor/plugins/yaffle/README create vendor/plugins/yaffle/MIT-LICENSE create vendor/plugins/yaffle/Rakefile create vendor/plugins/yaffle/init.rb create vendor/plugins/yaffle/install.rb create vendor/plugins/yaffle/uninstall.rb create vendor/plugins/yaffle/lib/yaffle.rb create vendor/plugins/yaffle/tasks/yaffle_tasks.rake create vendor/plugins/yaffle/test/core_ext_test.rb create vendor/plugins/yaffle/generators create vendor/plugins/yaffle/generators/yaffle create vendor/plugins/yaffle/generators/yaffle/templates create vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb create vendor/plugins/yaffle/generators/yaffle/USAGE ---------------------------------------------- === Setup the plugin for testing === In this guide you will learn how to test your plugin against multiple different adapters using Active Record. This guide will not cover how to use fixtures in plugin tests. To setup your plugin to allow for easy testing you'll need to add 3 files: * A 'database.yml' file with all of your connection strings. * A 'schema.rb' file with your table definitions. * A test helper that sets up the database before your tests. *vendor/plugins/yaffle/test/database.yml:* ---------------------------------------------- sqlite: :adapter: sqlite :dbfile: yaffle_plugin.sqlite.db sqlite3: :adapter: sqlite3 :dbfile: yaffle_plugin.sqlite3.db postgresql: :adapter: postgresql :username: postgres :password: postgres :database: yaffle_plugin_test :min_messages: ERROR mysql: :adapter: mysql :host: localhost :username: rails :password: :database: yaffle_plugin_test ---------------------------------------------- For this guide you'll need 2 tables/models, Hickwalls and Wickwalls, so add the following: *vendor/plugins/yaffle/test/schema.rb:* [source, ruby] ---------------------------------------------- ActiveRecord::Schema.define(:version => 0) do create_table :hickwalls, :force => true do |t| t.string :name t.string :last_squawk t.datetime :last_squawked_at end create_table :wickwalls, :force => true do |t| t.string :name t.string :last_tweet t.datetime :last_tweeted_at end end ---------------------------------------------- *vendor/plugins/yaffle/test/test_helper.rb:* [source, ruby] ---------------------------------------------- ENV['RAILS_ENV'] = 'test' ENV['RAILS_ROOT'] ||= File.dirname(__FILE__) + '/../../../..' require 'test/unit' require File.expand_path(File.join(ENV['RAILS_ROOT'], 'config/environment.rb')) config = YAML::load(IO.read(File.dirname(__FILE__) + '/database.yml')) ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/debug.log") db_adapter = ENV['DB'] db_adapter ||= begin require 'rubygems' require 'sqlite' 'sqlite' rescue MissingSourceFile begin require 'sqlite3' 'sqlite3' rescue MissingSourceFile end end if db_adapter.nil? raise "No DB Adapter selected. Pass the DB= option to pick one, or install Sqlite or Sqlite3." end ActiveRecord::Base.establish_connection(config[db_adapter]) load(File.dirname(__FILE__) + "/schema.rb") require File.dirname(__FILE__) + '/../init.rb' class Hickwall < ActiveRecord::Base end class Wickwall < ActiveRecord::Base end ---------------------------------------------- === Run the plugin tests === Once you have these files in place, you can write your first test to ensure that your plugin-testing setup is correct. By default rails generates a file in 'vendor/plugins/yaffle/test/yaffle_test.rb' with a sample test. Replace the contents of that file with: *vendor/plugins/yaffle/test/yaffle_test.rb:* [source, ruby] ---------------------------------------------- require File.dirname(__FILE__) + '/test_helper.rb' class YaffleTest < Test::Unit::TestCase def test_active_record_classes_from_test_helper assert_kind_of Hickwall, Hickwall.new assert_kind_of Wickwall, Wickwall.new end end ---------------------------------------------- To run this, go to the plugin directory and run `rake`: ---------------------------------------------- cd vendor/plugins/yaffle rake ---------------------------------------------- You should see output like: ---------------------------------------------- /opt/local/bin/ruby -Ilib:lib "/opt/local/lib/ruby/gems/1.8/gems/rake-0.8.3/lib/rake/rake_test_loader.rb" "test/yaffle_test.rb" -- create_table(:hickwalls, {:force=>true}) -> 0.0220s -- create_table(:wickwalls, {:force=>true}) -> 0.0077s -- initialize_schema_migrations_table() -> 0.0007s -- assume_migrated_upto_version(0) -> 0.0007s Loaded suite /opt/local/lib/ruby/gems/1.8/gems/rake-0.8.3/lib/rake/rake_test_loader Started . Finished in 0.002236 seconds. 1 test, 1 assertion, 0 failures, 0 errors ---------------------------------------------- By default the setup above runs your tests with sqlite or sqlite3. To run tests with one of the other connection strings specified in database.yml, pass the DB environment variable to rake: ---------------------------------------------- rake DB=sqlite rake DB=sqlite3 rake DB=mysql rake DB=postgresql ---------------------------------------------- Now you are ready to test-drive your plugin!