

Predictors

Basic usage

By default Crystalball uses Crystalball::RSpec::StandardPredictionBuilder which uses just two strategies for prediction ModifiedExecutionPaths and ModifiedSpecs. This is more than enough for first time use.

Advanced usage

If you want to squeeze out the most out of Crystalball you might want to add additional available prediction strategies or even add your own. To do that you should create a class inherited from Crystalball::RSpec::PredictionBuilder and overload predictor method with your custom predictor setup similar to what we have in StandardPredictionBuilder

E.g.

class MyPredictionBuilder < Crystalball::RSpec::PredictionBuilder
    def predictor
      super do |p|
        p.use Crystalball::Predictor::ModifiedSpecs.new
        p.use Crystalball::Predictor::ModifiedExecutionPaths.new
        p.use Crystalball::Predictor::ModifiedSupportSpecs.new
      end
    end
end

creates a predictor with additional ModifiedSupportSpecs strategy enabled.

You also must let our runner know about your new prediction builder by adding it to configuration. Please see runner configuration page for details.

Strategies

AssociatedSpecs

Needs to be configured with rules for detecting which specs should be on the prediction.

predictor.use Crystalball::Predictor::AssociatedSpecs.new(
  from: %r{models/(.*).rb}, 
  to: "./spec/models/%s_spec.rb"
  )

will add ./spec/models/foo_spec.rb to prediction when models/foo.rb changes. This strategy does not depend on a previously generated example group map.

ModifiedExecutionPaths

Checks the example group map and the diff to see which specs are affected by the new or modified files.

ModifiedSpecs

As the name implies, checks for modified specs. The scope can be modified by passing a regex as argument, which defaults to %r{spec/.*_spec\.rb\z}. This strategy does not depend on a previously generated example group map.

ModifiedSupportSpecs

Checks for modified support files used in specs and predicts full spec file. The scope can be modified by passing a regex as argument, which defaults to %r{spec/support/.*\.rb\z}. Mostly usable for shared_contexts and shared_examples.

ModifiedSchema

Checks for modified db schema in rails application. You need to specify a path to a file with tables map generated by TablesMapGenerator. It checks schema diff to see which models are affected by modified tables and which specs are affected by this models.

predictor.use Crystalball::Rails::Predictor::ModifiedSchema.new(
  tables_map_path: './tables_map.yml'
  )

Note: You may meet a warning like "WARNING: there are no model files for changed table ...". Usually, such tables are leftovers or a relation table for has-and-belongs-to-many associations. For the first case - nothing to worry about. For the second case - it means you want to change the default relation table.

Custom strategies

As with the map generator you may define custom strategies for prediction. It must be an object that responds to #call(diff, example_group_map) (where diff is a Crystalball::SourceDiff and example_group_map is a Crystalball::ExampleGroupMap) and returns an array of paths.

Check out default strategies implementation for examples.