dev guide
This little guide will help you develop for rails-ajax.
rails-ajax's source code is hosted in the following repositories:
- Github - The main one
- SourceForge
- RubyForge
You can use Github's pull requests features to contribute code to Rails-Ajax.
If you want to get the complete source code using GIT, you can use the following command:
git clone https://github.com/Muriel-Salvan/rails-ajax.git
Rails-Ajax uses the following frameworks/libraries for its tests:
- Rails (~>3.2.1)
- RSpec
- Cucumber
- Capybara
- Capybara-webkit
In order to install those dependencies on your host, execute the bundle command:
bundle
Once you have the source code and dependencies, next thing to check is how to run tests. This is done using the following rake command from Rails-ajax's root directory:
rake test
This should execute cucumber testing in dummy Rails applications. If everything is ok, the output should end with something similar to:
127 scenarios (127 passed)
779 steps (779 passed)
3m5.327s
The command "bundle exec rake" exited with 0.
If for some reasons some scenarios failed, it is likely your environment or gems not being setup correctly.
If the test passes 100%, you are then ready to modify the source code, add new tests and check they still run smoothly.
Time to dive into the source.
Rails-Ajax defines a Railtie to plug its functionality into Rails applications: lib/rails-ajax/railtie.rb.
This Railtie declares a rake tasks file that is responsible for generating Rails-Ajax configuration files in a Rails application: tasks/rails-ajax_tasks.rake.
The Railtie also loads all Rails-Ajax library files during its initialization. Those libraries augment some Rails functionality, and also override others.
Last thing Railtie's initialization does is adding a new assets path (along with app/assets, lib/assets, vendor/assets): assets/javascripts. This allows Rails applications to include Rails-Ajax's javascript files without having to copy them manually into their application.
Rails-Ajax libraries augment Rails by including Rails-Ajax specific modules into basic Rails modules:
- RailsAjax::Controller is included in ActionController::Base
- RailsAjax::UrlHelper and RailsAjax::FormTagHelper are included in ActionView::Base
This module overrides 2 ActionController methods to add Rails-Ajax functionalities: render and redirect_to.
It also defines helpers (parts of the [Rails-Ajax API](Rails-Ajax API "wikilink")): refresh_dom_with_partial and execute_javascript. Those helpers work the same way: they remember actions to take in a staging area, in order to include them later during the rendering stage (handled by render and redirect_to).
This module overrides the link_to method to mark links as remote when needed.
This module overrides the form_tag method to mark forms as remote when needed.
This defines the configuration object that can be then accessed in Rails applications using RailsAjax::config method. The configuration is stored in a singleton linked to the RailsAjax module. This singleton is defined in lib/rails-ajax/rails-ajax.rb.
Configuration files are generated using the rails-ajax:install rake target. They are stored in the gen/ directory, and are simply copied to the Rails application when the target is invoked.
All the code related to tests is stored in the test/ directory (except the gem dependencies declared in Gemfile).
Tests are done using several dummy Rails application:
- One for Rails 3 in test/dummy_rails3 directory.
- One for Rails 4 in test/dummy_rails4 directory.
These Rails applications contain controllers and views that test each Rails-Ajax functionality. A good way to test it live using a real browser is to launch the Rails application manually from test/dummy_rails4:
rails s
And then visit http://localhost:3000 using your browser. This way you can live test Rails-Ajax functionality.
Automating tests using the dummy Rails applications is done using Cucumber, RSpec and Capybara (with its engine webkit). Here is a brief overview of each of those frameworks:
-
RSpec] is used to get some more readable helpers in writing tests (such as
my_value.should == 5). - Cucumber] is used to run the test suite itself and express it using natural language.
-
Capybara is used to pilot the Rails application in the tests. It defines helpers to handle navigation, parsing, JavaScript... (such as
visit '/page1'orpage.should have_content('My content')) - Capybara/Webkit is the engine used internally by Capybara to browse (including running JavaScript).
Please note that Capybara/webkit needs Qt installed in your system to work. If you don't want or can't install webkit, it is also possible to use other Capybara engines. For this, change the Capybara.javascript_driver property in file test/dummy/features/support/env.rb. Rails-Ajax has also been tested successfully using the selenium engine.
Once dependencies are installed, cucumber can be run directly from the dummy Rails application (test/dummy directory):
cucumber
This is exactly what is run by the rake test command.
Test cases files are setup in test/dummy/features directory:
- Files in test/dummy/features/test_cases contain all the test cases run by cucumber.
- test/dummy/festures/step_definitions/main_steps.rb contains translations from the natural language into actions taken (using Capybara and RSpec DSL).
Adding tests is simple: add new test cases in existing files (if they fit in), or create new feature files in test/dummy/features/test_cases. If you need to define new translations from natural language, just edit file test/dummy/festures/step_definitions/main_steps.rb and add your new definitions.
A very good Cucumber feature is to first write the features without definitions, then run Cucumber once (of course it will end in error), and grab the output of Cucumber: it has already given the missing definitions, ready to be pasted into the definitions file.
Packaging Rails-Ajax is done using RubyPackager. The details of the distribution are stored in Distribution/ReleaseInfo.rb file.
Creating a new gem of Rails-Ajax can be done using the following command:
Release -v<Version> -t<Tag> -iGem Distribution\ReleaseInfo.rb
This will create the gem in a directory called Releases///Normal//Installer/rails-ajax-.gem. It will also generate the documentation (using RDoc) in Releases///Normal//Documentation.
If you have privileges on the SourceForge repository, you can also add option -dSourceForge and the gem will be published automatically on SourceForge along with its documentation.
If you have privileges to push on RubyGems, you can also add option -dRubyGems to automatically push the gem to rubygems.org
If this guide is not enough to get you started, don't hesitate to ask for help in the forums or by contacting Muriel directly.