vendor/rails/railties/doc/guides/source/creating_plugins/test_setup.txt

   1 == Preparation ==
   2
   3 === Create the basic app ===
   4
   5 The examples in this guide require that you have a working rails application.  To create a simple rails app execute:
   6
   7 ------------------------------------------------
   8 gem install rails
   9 rails yaffle_guide
  10 cd yaffle_guide
  11 script/generate scaffold bird name:string
  12 rake db:migrate
  13 script/server
  14 ------------------------------------------------
  15
  16 Then navigate to http://localhost:3000/birds.  Make sure you have a functioning rails app before continuing.
  17
  18 .Editor's note:
  19 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.
  20
  21
  22 === Generate the plugin skeleton ===
  23
  24 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.
  25
  26 This creates a plugin in 'vendor/plugins' including an 'init.rb' and 'README' as well as standard 'lib', 'task', and 'test' directories.
  27
  28 Examples:
  29 ----------------------------------------------
  30 ./script/generate plugin yaffle
  31 ./script/generate plugin yaffle --with-generator
  32 ----------------------------------------------
  33
  34 To get more detailed help on the plugin generator, type `./script/generate plugin`.
  35
  36 Later on this guide will describe how to work with generators, so go ahead and generate your plugin with the `\--with-generator` option now:
  37
  38 ----------------------------------------------
  39 ./script/generate plugin yaffle --with-generator
  40 ----------------------------------------------
  41
  42 You should see the following output:
  43
  44 ----------------------------------------------
  45 create  vendor/plugins/yaffle/lib
  46 create  vendor/plugins/yaffle/tasks
  47 create  vendor/plugins/yaffle/test
  48 create  vendor/plugins/yaffle/README
  49 create  vendor/plugins/yaffle/MIT-LICENSE
  50 create  vendor/plugins/yaffle/Rakefile
  51 create  vendor/plugins/yaffle/init.rb
  52 create  vendor/plugins/yaffle/install.rb
  53 create  vendor/plugins/yaffle/uninstall.rb
  54 create  vendor/plugins/yaffle/lib/yaffle.rb
  55 create  vendor/plugins/yaffle/tasks/yaffle_tasks.rake
  56 create  vendor/plugins/yaffle/test/core_ext_test.rb
  57 create  vendor/plugins/yaffle/generators
  58 create  vendor/plugins/yaffle/generators/yaffle
  59 create  vendor/plugins/yaffle/generators/yaffle/templates
  60 create  vendor/plugins/yaffle/generators/yaffle/yaffle_generator.rb
  61 create  vendor/plugins/yaffle/generators/yaffle/USAGE
  62 ----------------------------------------------
  63
  64 To begin just change one thing - move 'init.rb' to 'rails/init.rb'.
  65
  66 === Setup the plugin for testing ===
  67
  68 If your plugin interacts with a database, you'll need to setup a database connection.  In this guide you will learn how to test your plugin against multiple different database adapters using Active Record.  This guide will not cover how to use fixtures in plugin tests.
  69
  70 To setup your plugin to allow for easy testing you'll need to add 3 files:
  71
  72  * A 'database.yml' file with all of your connection strings
  73  * A 'schema.rb' file with your table definitions
  74  * A test helper method that sets up the database
  75
  76 *vendor/plugins/yaffle/test/database.yml:*
  77
  78 ----------------------------------------------
  79 sqlite:
  80   :adapter: sqlite
  81   :dbfile: vendor/plugins/yaffle/test/yaffle_plugin.sqlite.db
  82
  83 sqlite3:
  84   :adapter: sqlite3
  85   :dbfile: vendor/plugins/yaffle/test/yaffle_plugin.sqlite3.db
  86
  87 postgresql:
  88   :adapter: postgresql
  89   :username: postgres
  90   :password: postgres
  91   :database: yaffle_plugin_test
  92   :min_messages: ERROR
  93
  94 mysql:
  95   :adapter: mysql
  96   :host: localhost
  97   :username: root
  98   :password: password
  99   :database: yaffle_plugin_test
 100 ----------------------------------------------
 101
 102 For this guide you'll need 2 tables/models, Hickwalls and Wickwalls, so add the following:
 103
 104 *vendor/plugins/yaffle/test/schema.rb:*
 105
 106 [source, ruby]
 107 ----------------------------------------------
 108 ActiveRecord::Schema.define(:version => 0) do
 109   create_table :hickwalls, :force => true do |t|
 110     t.string :name
 111     t.string :last_squawk
 112     t.datetime :last_squawked_at
 113   end
 114   create_table :wickwalls, :force => true do |t|
 115     t.string :name
 116     t.string :last_tweet
 117     t.datetime :last_tweeted_at
 118   end
 119   create_table :woodpeckers, :force => true do |t|
 120     t.string :name
 121   end
 122 end
 123 ----------------------------------------------
 124
 125 *vendor/plugins/yaffle/test/test_helper.rb:*
 126
 127 [source, ruby]
 128 ----------------------------------------------
 129 ENV['RAILS_ENV'] = 'test'
 130 ENV['RAILS_ROOT'] ||= File.dirname(__FILE__) + '/../../../..'
 131
 132 require 'test/unit'
 133 require File.expand_path(File.join(ENV['RAILS_ROOT'], 'config/environment.rb'))
 134
 135 def load_schema
 136   config = YAML::load(IO.read(File.dirname(__FILE__) + '/database.yml'))
 137   ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/debug.log")
 138
 139   db_adapter = ENV['DB']
 140
 141   # no db passed, try one of these fine config-free DBs before bombing.
 142   db_adapter ||=
 143     begin
 144       require 'rubygems'
 145       require 'sqlite'
 146       'sqlite'
 147     rescue MissingSourceFile
 148       begin
 149         require 'sqlite3'
 150         'sqlite3'
 151       rescue MissingSourceFile
 152       end
 153     end
 154
 155   if db_adapter.nil?
 156     raise "No DB Adapter selected. Pass the DB= option to pick one, or install Sqlite or Sqlite3."
 157   end
 158
 159   ActiveRecord::Base.establish_connection(config[db_adapter])
 160   load(File.dirname(__FILE__) + "/schema.rb")
 161   require File.dirname(__FILE__) + '/../rails/init.rb'
 162 end
 163 ----------------------------------------------
 164
 165 Now whenever you write a test that requires the database, you can call 'load_schema'.
 166
 167 === Run the plugin tests ===
 168
 169 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:
 170
 171 *vendor/plugins/yaffle/test/yaffle_test.rb:*
 172
 173 [source, ruby]
 174 ----------------------------------------------
 175 require File.dirname(__FILE__) + '/test_helper.rb'
 176
 177 class YaffleTest < Test::Unit::TestCase
 178   load_schema
 179
 180   class Hickwall < ActiveRecord::Base
 181   end
 182
 183   class Wickwall < ActiveRecord::Base
 184   end
 185
 186   def test_schema_has_loaded_correctly
 187     assert_equal [], Hickwall.all
 188     assert_equal [], Wickwall.all
 189   end
 190
 191 end
 192 ----------------------------------------------
 193
 194 To run this, go to the plugin directory and run `rake`:
 195
 196 ----------------------------------------------
 197 cd vendor/plugins/yaffle
 198 rake
 199 ----------------------------------------------
 200
 201 You should see output like:
 202
 203 ----------------------------------------------
 204 /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"
 205 -- create_table(:hickwalls, {:force=>true})
 206    -> 0.0220s
 207 -- create_table(:wickwalls, {:force=>true})
 208    -> 0.0077s
 209 -- initialize_schema_migrations_table()
 210    -> 0.0007s
 211 -- assume_migrated_upto_version(0)
 212    -> 0.0007s
 213 Loaded suite /opt/local/lib/ruby/gems/1.8/gems/rake-0.8.3/lib/rake/rake_test_loader
 214 Started
 215 .
 216 Finished in 0.002236 seconds.
 217
 218 1 test, 1 assertion, 0 failures, 0 errors
 219 ----------------------------------------------
 220
 221 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:
 222
 223 ----------------------------------------------
 224 rake DB=sqlite
 225 rake DB=sqlite3
 226 rake DB=mysql
 227 rake DB=postgresql
 228 ----------------------------------------------
 229
 230 Now you are ready to test-drive your plugin!