Running Specs

Because flex_columns manipulates the data in an application's database, and therefore any bugs can have long-term, potentially catastrophic effects, it is very thoroughly tested. There are two different kinds of specs for it:

Unit Specs

These live in spec/flex_columns/unit, and test each class in isolation, independent of any other classes. To run them, simply do:

bundle exec rspec spec/flex_columns/unit

...and you're done. No database is necessary, since these are unit tests.

The unit specs alone, however, would miss a lot of very important design — the interaction between the classes, which, after all, is what causes the entire system to behave correctly (or not behave correctly).

System Specs

The system specs test the entire flex_columns Gem at once; each spec tests a different aspect of its functionality, but they also all use the entire stack, all the way down to a database.

In order to run these specs, you must have access to a database you can use. It's best if the database is dedicated to running these specs. The tests create and destroy their own tables, and make every effort to clean up anything they created at the end — so it should be possible to piggyback on top of an existing database you also use for other things. However, it's always much safer to use a dedicated database. (Note that this is intentional use of the word "database", as opposed to "database server"; you don't need, for example, an entirely separate instance of mysqld — just a separate database that you can switch to using USE .....)

Once you have this set up, simply create a file at the root level of the Gem (i.e., inside the root flex_columns directory) called spec_database_config.rb, and define a constant FLEX_COLUMNS_SPEC_DATABASE_CONFIG as so:

FLEX_COLUMNS_SPEC_DATABASE_CONFIG = {
  :database_gem_name => 'mysql2',
  :require => 'mysql2',
  :config => {
    :adapter => 'mysql2',
    :database => 'flex_columns_specs_db',
    :username => 'root'
  }
}

The keys are as follows:

• :database_gem_name is the name of the RubyGem that provides access to the database — exactly as you'd put it in a Gemfile;
• :require is whatever should be passed to Ruby's built-in require statement to require the Gem — typically this is the same as :database_gem_name, but not always (this is the same as a Gemfile's :require => ... syntax);
• :config is exactly what gets passed to ActiveRecord::Base.establish_connection, and so you can pass any options that it accepts (which are the same as what goes in Rails' database.yml).

Once you've done this, you can run the system specs using bundle exec rspec spec/flex_columns/system. (Or run them along with the unit specs with a simple bundle exec rspec spec.)

Note that there's also support deep in the code (in flex_columns/spec/flex_columns/helpers/database_helper.rb) for defining connections to Travis CI's database options, so that Travis can run the tests automatically. Generally, you don't need to worry about this, but it's worth noting.