= Railscheck - The semi-static Q/A verification tool for your Ruby on Rails projects!
== DESCRIPTION
This project is (or will be) a best effort semi-static verifier for your Ruby on Rails projects. Delivered as a Ruby gem it provides a shell command task "railscheck" that you can run against your Rails projects to test for a number of typical bugs and inconsistencies.
It is a law of software development that the earlier you identify a problem the cheaper it is to fix. This project aims to help you quickly identify many bugs and inconsistencies as early as possible (thus avoiding unnecessary debugging work for you and your development team ; as well as avoiding unnecessary, negative "surprises" for your users).
Typical ruby/rails development tools does not provide ANY kind of static verification checks since the problem appears to be just about unsolvable in the general case (because of the dynamic nature of Ruby). However for a strictly limited domain such as Rails Web Applications, there are actually many potential bugs that can be identified statically, or at least (semi-)statically, without having to start the web server and actually run the application.
Furthermore because of the opinionated nature of Rails, there are many conventions that can be broken and that we can check for. Finally rails projects depends on much more than just ruby code - i.e. migrations, database schemas, erb, html, css, yaml etc... All of which needs to work for an application to fully function and which is therefore in the scope of this this gem.
However, this project can not - and does not attempt to - find all logical/programming errors. As such the gem supplements and does not replace existing testing practices such as automated rails tests.
== STATUS
This project is a working BETA. It works and is useful but has a very limited feature set. Much more to come. Currently the focus is on "low hanging fruits" (features that are easy to implement)
Use the rubyforge tracker function on the railscheck website to suggest features that you would like to be added (or bugs to fix)
== INSTALLATION
This project is hosted on rubyforge. Install latest version using:
"sudo gem install railscheck"
== RUNNING
First make sure this gem is installed, your project is configured and that all your migrations are run for the project(s) you want to check.
The gem contain "railscheck" executables for unix/linux/mac and windows. An alternative "jrailscheck" command is available for jruby users. The gem installation will place these executables on your PATH. Invoke the following command for more information.
"railscheck -h"
Usage examples:
"railscheck -h" - to get detailed information about command options etc.
"railscheck" - to check rails project in current directory.
"railscheck path-to-your-rails-project" - to check the rails project at the specified path.
"railscheck -i database path-to-your-rails-project" - to run database checks for the rails project at the specified path.
"railscheck -x html" - to run every test but html related ones against rails project in current directory.
== FEATURE SUMMARY
SYNTAX CHECKS & VALIDATION (static files)
* Syntax check of static *.rb, *.rake and *.rjs ruby files (in test tc_syntax_check_ruby.rb)
* Syntax check of *.yaml files (in test tc_config.rb)
* Syntax check of *.xml files (in test tc_xml.rb)
* Syntax check of *.erb, *.rhtml view files (in test tc_views.rb)
* Syntax check (online) of *.css files (in tc_html_and_css.rb) currently using W3C web services.
* Syntax check (online) of *.(x)html files (in tc_html_and_css.rb) currently using W3C web services.
CHECK FOR RAILS PROJECT CONSISTENCY (in test tc_project.rb):
* Validates Ruby On Rails project structure and existence of key files necessary to
develop, test and deploy rails projects successfully.
CHECK DATABASE (in test tc_database.rb):
* Checks that database is configured correct in project / ability to connect to database.
* Checks that database migration version corresponds to latest code migration version number in project.
* Checks that database drivers are fit for production use.
* Checks that test database does not overlap with development/production database.
CHECK MODELS (in test tc_models.rb):
* Validates that tables with correct names exist for all ActiveRecord model classes in project.
* Validates that has_many, has_one, belongs_to and has_and_belongs_to_many associations uses the correct pluralization for names (there are subtle problems with activerecord if this is not the case).
DEPRECATIONS (in test tc_rails_deprecations.rb)
* Warns if deprecated Rails constructs are used.
IN PROGRESS (NOT QUITE READY BUT DUE SOON):
* Syntax check of *.js javascript files (in test tc_javascript.rb)
== PROJECT SITE AND DOCUMENTATION
See "http://rubyforge.org/projects/railscheck/" for sourceforge project site.
See "http://railscheck.rubyforge.org/" for project intro page.
See "http://railscheck.rubyforge.org/rdoc/" for project RDOC.
+ visit "http://techblog.41concepts.com/" for blog postings about railscheck as well as other software R&D subjects.
== WARNINGS AND LIMITATIONS
This project assumes that normally safe code in rails projects such as enviroment.rb, intializers, yaml,
views, models etc. do NOT have dangerous (insane) side-effects that happen just by Ruby loading the
source file or Ruby retrieving state of objects. If you ever encounter such a bizarre rails project, which
is extremely unlikely, do NOT run railscheck on the project (and be very, very careful in general about
what you are doing with the project).
This project does generally not check dynamic behavior of the application and can as such not replace good testing
practices, unit-testing etc. Nor does this project (currently) test documentation and vendor plugins. The gem is
targeted for Rails v1.0+ running on Ruby 1.8.6+ / RubyGems 1.1 compliant implementations (no work will be done to ensure
compatibility with older Rails/ruby/gem versions). Some tests may require later versions of rails such as Rails v2.0+
== KNOWN BUGS
- The jrailscheck.bat file generated by rubygems on windows invoke ruby instead of jruby. Users have to manually change the bat file installed in the ruby bin directory until I find out how to make rubygem behave correctly here.
- Line numbers reported by ruby syntax check is +1 too large.
== CONTRIBUTING
You can easily add your test files to the "lib\test" folder. Checks are tests based on the ruby unit test framework and following the standard conventions they should be placed in Ruby files starting with "tc_" in order to be picked up by Railscheck automatically. All test classes should inherit from Railscheck::TestCase which in turns inherits from "Test::Unit::TestCase". See the existing test files for examples.
Any added code that you contribute will be given due credit! However make sure that you assign undersigned shared copyright so I am allowed to release and license your work together with this project.
The source code is available anonymously (readonly) using subversion at the path:
svn://rubyforge.org/var/svn/railscheck/trunk
Once you have added your tests write undersigned an email in order to get registered and get your contribution into Railscheck. Once you are registered as a project contributor you may access the source code from subversion with full read/write rights at the path:
svn+ssh://[email protected]/var/svn/railscheck/trunk
== SUPPORT
There is no formal support for this project. Please use railscheck.rubyforge.org tracker/forums to report problems/suggestions and the developer(s) will look at them in time.
== COPYRIGHT, ATTRIBUTIONS AND AUTHOR INFORMATION
Copyright (c) 2008 Morten Christensen, 41concepts (www.41concepts.com), Denmark
AUTHOR(S):
* Morten Christensen, am a software developer from the Danish software company 41concepts (www.41concepts.com). We do
Ruby/Rails/Java/.NET software development consultancy. Contact me at mmc[AT/NOSPAM]41concepts[dot]com for more
information. See also my blog postings at "http://techblog.41concepts.com/" about Railscheck as well as other software R&D subjects.
* ----> Submit your code additions and get your name added here!! <----
INSPIRATION, ATTRIBUTIONS AND SPECIAL CREDITS:
* Dr Nic Williams for newgem tool and basic css design of website (with theme extended from Paul Battley).
* Fail Early and MySQL driver Tasks written by Mike Naberezny for Advanced Rail Recipes and on his blog on maintainable.com
* DZone Snippet Rails task to find code typos in rhtml templates by Dmitry Severin (dseverin).
* Rails 2.0 deprecations snippet by Mislav Marohnić (http://mislav.caboo.se)
* Rails deprecations plugin by Geoffrey Grosenbach (http://topfunky.net/svn/plugins/deprecated/)
+ Aaron Patterson for the Johnson javascript gem, Alex Dunae for the W3C wrapper gem.
LICENSE INFORMATION:
This software is FREE for both public and commercial use - with the possible exception of commercial
software development tool makers that require a license (see License.txt file for details).
== DESCRIPTION
This project is (or will be) a best effort semi-static verifier for your Ruby on Rails projects. Delivered as a Ruby gem it provides a shell command task "railscheck" that you can run against your Rails projects to test for a number of typical bugs and inconsistencies.
It is a law of software development that the earlier you identify a problem the cheaper it is to fix. This project aims to help you quickly identify many bugs and inconsistencies as early as possible (thus avoiding unnecessary debugging work for you and your development team ; as well as avoiding unnecessary, negative "surprises" for your users).
Typical ruby/rails development tools does not provide ANY kind of static verification checks since the problem appears to be just about unsolvable in the general case (because of the dynamic nature of Ruby). However for a strictly limited domain such as Rails Web Applications, there are actually many potential bugs that can be identified statically, or at least (semi-)statically, without having to start the web server and actually run the application.
Furthermore because of the opinionated nature of Rails, there are many conventions that can be broken and that we can check for. Finally rails projects depends on much more than just ruby code - i.e. migrations, database schemas, erb, html, css, yaml etc... All of which needs to work for an application to fully function and which is therefore in the scope of this this gem.
However, this project can not - and does not attempt to - find all logical/programming errors. As such the gem supplements and does not replace existing testing practices such as automated rails tests.
== STATUS
This project is a working BETA. It works and is useful but has a very limited feature set. Much more to come. Currently the focus is on "low hanging fruits" (features that are easy to implement)
Use the rubyforge tracker function on the railscheck website to suggest features that you would like to be added (or bugs to fix)
== INSTALLATION
This project is hosted on rubyforge. Install latest version using:
"sudo gem install railscheck"
== RUNNING
First make sure this gem is installed, your project is configured and that all your migrations are run for the project(s) you want to check.
The gem contain "railscheck" executables for unix/linux/mac and windows. An alternative "jrailscheck" command is available for jruby users. The gem installation will place these executables on your PATH. Invoke the following command for more information.
"railscheck -h"
Usage examples:
"railscheck -h" - to get detailed information about command options etc.
"railscheck" - to check rails project in current directory.
"railscheck path-to-your-rails-project" - to check the rails project at the specified path.
"railscheck -i database path-to-your-rails-project" - to run database checks for the rails project at the specified path.
"railscheck -x html" - to run every test but html related ones against rails project in current directory.
== FEATURE SUMMARY
SYNTAX CHECKS & VALIDATION (static files)
* Syntax check of static *.rb, *.rake and *.rjs ruby files (in test tc_syntax_check_ruby.rb)
* Syntax check of *.yaml files (in test tc_config.rb)
* Syntax check of *.xml files (in test tc_xml.rb)
* Syntax check of *.erb, *.rhtml view files (in test tc_views.rb)
* Syntax check (online) of *.css files (in tc_html_and_css.rb) currently using W3C web services.
* Syntax check (online) of *.(x)html files (in tc_html_and_css.rb) currently using W3C web services.
CHECK FOR RAILS PROJECT CONSISTENCY (in test tc_project.rb):
* Validates Ruby On Rails project structure and existence of key files necessary to
develop, test and deploy rails projects successfully.
CHECK DATABASE (in test tc_database.rb):
* Checks that database is configured correct in project / ability to connect to database.
* Checks that database migration version corresponds to latest code migration version number in project.
* Checks that database drivers are fit for production use.
* Checks that test database does not overlap with development/production database.
CHECK MODELS (in test tc_models.rb):
* Validates that tables with correct names exist for all ActiveRecord model classes in project.
* Validates that has_many, has_one, belongs_to and has_and_belongs_to_many associations uses the correct pluralization for names (there are subtle problems with activerecord if this is not the case).
DEPRECATIONS (in test tc_rails_deprecations.rb)
* Warns if deprecated Rails constructs are used.
IN PROGRESS (NOT QUITE READY BUT DUE SOON):
* Syntax check of *.js javascript files (in test tc_javascript.rb)
== PROJECT SITE AND DOCUMENTATION
See "http://rubyforge.org/projects/railscheck/" for sourceforge project site.
See "http://railscheck.rubyforge.org/" for project intro page.
See "http://railscheck.rubyforge.org/rdoc/" for project RDOC.
+ visit "http://techblog.41concepts.com/" for blog postings about railscheck as well as other software R&D subjects.
== WARNINGS AND LIMITATIONS
This project assumes that normally safe code in rails projects such as enviroment.rb, intializers, yaml,
views, models etc. do NOT have dangerous (insane) side-effects that happen just by Ruby loading the
source file or Ruby retrieving state of objects. If you ever encounter such a bizarre rails project, which
is extremely unlikely, do NOT run railscheck on the project (and be very, very careful in general about
what you are doing with the project).
This project does generally not check dynamic behavior of the application and can as such not replace good testing
practices, unit-testing etc. Nor does this project (currently) test documentation and vendor plugins. The gem is
targeted for Rails v1.0+ running on Ruby 1.8.6+ / RubyGems 1.1 compliant implementations (no work will be done to ensure
compatibility with older Rails/ruby/gem versions). Some tests may require later versions of rails such as Rails v2.0+
== KNOWN BUGS
- The jrailscheck.bat file generated by rubygems on windows invoke ruby instead of jruby. Users have to manually change the bat file installed in the ruby bin directory until I find out how to make rubygem behave correctly here.
- Line numbers reported by ruby syntax check is +1 too large.
== CONTRIBUTING
You can easily add your test files to the "lib\test" folder. Checks are tests based on the ruby unit test framework and following the standard conventions they should be placed in Ruby files starting with "tc_" in order to be picked up by Railscheck automatically. All test classes should inherit from Railscheck::TestCase which in turns inherits from "Test::Unit::TestCase". See the existing test files for examples.
Any added code that you contribute will be given due credit! However make sure that you assign undersigned shared copyright so I am allowed to release and license your work together with this project.
The source code is available anonymously (readonly) using subversion at the path:
svn://rubyforge.org/var/svn/railscheck/trunk
Once you have added your tests write undersigned an email in order to get registered and get your contribution into Railscheck. Once you are registered as a project contributor you may access the source code from subversion with full read/write rights at the path:
svn+ssh://[email protected]/var/svn/railscheck/trunk
== SUPPORT
There is no formal support for this project. Please use railscheck.rubyforge.org tracker/forums to report problems/suggestions and the developer(s) will look at them in time.
== COPYRIGHT, ATTRIBUTIONS AND AUTHOR INFORMATION
Copyright (c) 2008 Morten Christensen, 41concepts (www.41concepts.com), Denmark
AUTHOR(S):
* Morten Christensen, am a software developer from the Danish software company 41concepts (www.41concepts.com). We do
Ruby/Rails/Java/.NET software development consultancy. Contact me at mmc[AT/NOSPAM]41concepts[dot]com for more
information. See also my blog postings at "http://techblog.41concepts.com/" about Railscheck as well as other software R&D subjects.
* ----> Submit your code additions and get your name added here!! <----
INSPIRATION, ATTRIBUTIONS AND SPECIAL CREDITS:
* Dr Nic Williams for newgem tool and basic css design of website (with theme extended from Paul Battley).
* Fail Early and MySQL driver Tasks written by Mike Naberezny for Advanced Rail Recipes and on his blog on maintainable.com
* DZone Snippet Rails task to find code typos in rhtml templates by Dmitry Severin (dseverin).
* Rails 2.0 deprecations snippet by Mislav Marohnić (http://mislav.caboo.se)
* Rails deprecations plugin by Geoffrey Grosenbach (http://topfunky.net/svn/plugins/deprecated/)
+ Aaron Patterson for the Johnson javascript gem, Alex Dunae for the W3C wrapper gem.
LICENSE INFORMATION:
This software is FREE for both public and commercial use - with the possible exception of commercial
software development tool makers that require a license (see License.txt file for details).