3 === Create the basic app ===
5 The examples in this guide require that you have a working rails application. To create a simple rails app execute:
7 ------------------------------------------------
11 script/generate scaffold bird name:string
14 ------------------------------------------------
16 Then navigate to http://localhost:3000/birds. Make sure you have a functioning rails app before continuing.
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.
22 === Generate the plugin skeleton ===
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.
26 This creates a plugin in 'vendor/plugins' including an 'init.rb' and 'README' as well as standard 'lib', 'task', and 'test' directories.
29 ----------------------------------------------
30 ./script/generate plugin yaffle
31 ./script/generate plugin yaffle --with-generator
32 ----------------------------------------------
34 To get more detailed help on the plugin generator, type `./script/generate plugin`.
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:
38 ----------------------------------------------
39 ./script/generate plugin yaffle --with-generator
40 ----------------------------------------------
42 You should see the following output:
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 ----------------------------------------------
64 To begin just change one thing - move 'init.rb' to 'rails/init.rb'.
66 === Setup the plugin for testing ===
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.
70 To setup your plugin to allow for easy testing you'll need to add 3 files:
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
76 *vendor/plugins/yaffle/test/database.yml:*
78 ----------------------------------------------
81 :dbfile: vendor/plugins/yaffle/test/yaffle_plugin.sqlite.db
85 :dbfile: vendor/plugins/yaffle/test/yaffle_plugin.sqlite3.db
91 :database: yaffle_plugin_test
99 :database: yaffle_plugin_test
100 ----------------------------------------------
102 For this guide you'll need 2 tables/models, Hickwalls and Wickwalls, so add the following:
104 *vendor/plugins/yaffle/test/schema.rb:*
107 ----------------------------------------------
108 ActiveRecord::Schema.define(:version => 0) do
109 create_table :hickwalls, :force => true do |t|
111 t.string :last_squawk
112 t.datetime :last_squawked_at
114 create_table :wickwalls, :force => true do |t|
117 t.datetime :last_tweeted_at
119 create_table :woodpeckers, :force => true do |t|
123 ----------------------------------------------
125 *vendor/plugins/yaffle/test/test_helper.rb:*
128 ----------------------------------------------
129 ENV['RAILS_ENV'] = 'test'
130 ENV['RAILS_ROOT'] ||= File.dirname(__FILE__) + '/../../../..'
133 require File.expand_path(File.join(ENV['RAILS_ROOT'], 'config/environment.rb'))
136 config = YAML::load(IO.read(File.dirname(__FILE__) + '/database.yml'))
137 ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/debug.log")
139 db_adapter = ENV['DB']
141 # no db passed, try one of these fine config-free DBs before bombing.
147 rescue MissingSourceFile
151 rescue MissingSourceFile
156 raise "No DB Adapter selected. Pass the DB= option to pick one, or install Sqlite or Sqlite3."
159 ActiveRecord::Base.establish_connection(config[db_adapter])
160 load(File.dirname(__FILE__) + "/schema.rb")
161 require File.dirname(__FILE__) + '/../rails/init.rb'
163 ----------------------------------------------
165 Now whenever you write a test that requires the database, you can call 'load_schema'.
167 === Run the plugin tests ===
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:
171 *vendor/plugins/yaffle/test/yaffle_test.rb:*
174 ----------------------------------------------
175 require File.dirname(__FILE__) + '/test_helper.rb'
177 class YaffleTest < Test::Unit::TestCase
180 class Hickwall < ActiveRecord::Base
183 class Wickwall < ActiveRecord::Base
186 def test_schema_has_loaded_correctly
187 assert_equal [], Hickwall.all
188 assert_equal [], Wickwall.all
192 ----------------------------------------------
194 To run this, go to the plugin directory and run `rake`:
196 ----------------------------------------------
197 cd vendor/plugins/yaffle
199 ----------------------------------------------
201 You should see output like:
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})
207 -- create_table(:wickwalls, {:force=>true})
209 -- initialize_schema_migrations_table()
211 -- assume_migrated_upto_version(0)
213 Loaded suite /opt/local/lib/ruby/gems/1.8/gems/rake-0.8.3/lib/rake/rake_test_loader
216 Finished in 0.002236 seconds.
218 1 test, 1 assertion, 0 failures, 0 errors
219 ----------------------------------------------
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:
223 ----------------------------------------------
228 ----------------------------------------------
230 Now you are ready to test-drive your plugin!