Class: RSpec::Core::FilterManager

Inherits:
Object
  • Object
show all
Defined in:
lib/rspec/core/filter_manager.rb

Overview

Manages the filtering of examples and groups by matching tags declared on the command line or options files, or filters declared via RSpec.configure, with hash key/values submitted within example group and/or example declarations. For example, given this declaration:

describe Thing, :awesome => true do
  it "does something" do
    # ...
  end
end

That group (or any other with :awesome => true) would be filtered in with any of the following commands:

rspec --tag awesome:true
rspec --tag awesome
rspec -t awesome:true
rspec -t awesome

Prefixing the tag names with ~ negates the tags, thus excluding this group with any of:

rspec --tag ~awesome:true
rspec --tag ~awesome
rspec -t ~awesome:true
rspec -t ~awesome

Options files and command line overrides

Tag declarations can be stored in .rspec, ~/.rspec, or a custom options file. This is useful for storing defaults. For example, let's say you've got some slow specs that you want to suppress most of the time. You can tag them like this:

describe Something, :slow => true do

And then store this in .rspec:

--tag ~slow:true

Now when you run rspec, that group will be excluded.

Overriding

Of course, you probably want to run them sometimes, so you can override this tag on the command line like this:

rspec --tag slow:true

RSpec.configure

You can also store default tags with RSpec.configure. We use tag on the command line (and in options files like .rspec), but for historical reasons we use the term filter in `RSpec.configure:

RSpec.configure do |c|
  c.filter_run_including :foo => :bar
  c.filter_run_excluding :foo => :bar
end

These declarations can also be overridden from the command line.

See Also:

Defined Under Namespace

Modules: BackwardCompatibility, Describable

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (FilterManager) initialize

A new instance of FilterManager



145
146
147
148
149
# File 'lib/rspec/core/filter_manager.rb', line 145

def initialize
  @exclusions = self.class.default_exclusions.dup.extend(Describable)
  @inclusions = {}.extend(Describable)
  extend(BackwardCompatibility)
end

Instance Attribute Details

- (Object) exclusions (readonly)

Returns the value of attribute exclusions



143
144
145
# File 'lib/rspec/core/filter_manager.rb', line 143

def exclusions
  @exclusions
end

- (Object) inclusions (readonly)

Returns the value of attribute inclusions



143
144
145
# File 'lib/rspec/core/filter_manager.rb', line 143

def inclusions
  @inclusions
end

Class Method Details

+ (Object) const_missing(name)



70
71
72
73
74
75
76
77
78
79
80
81
# File 'lib/rspec/core/filter_manager.rb', line 70

def const_missing(name)
  case name
  when :DEFAULT_EXCLUSIONS
    RSpec.deprecate("RSpec::Core::FilterManager::DEFAULT_EXCLUSIONS is deprecated")
    default_exclusions
  when :STANDALONE_FILTERS
    RSpec.deprecate("RSpec::Core::FilterManager::STANDALONE_FILTERS is deprecated")
    standalone_filters
  else
    super
  end
end

Instance Method Details

- (Object) add_location(file_path, line_numbers)



151
152
153
154
155
156
157
158
159
# File 'lib/rspec/core/filter_manager.rb', line 151

def add_location(file_path, line_numbers)
  # locations is a hash of expanded paths to arrays of line
  # numbers to match against. e.g.
  #   { "path/to/file.rb" => [37, 42] }
  locations = @inclusions.delete(:locations) || Hash.new {|h,k| h[k] = []}
  locations[File.expand_path(file_path)].push(*line_numbers)
  @inclusions.replace(:locations => locations)
  @exclusions.clear
end

- (Boolean) empty?

Returns:

  • (Boolean)


161
162
163
# File 'lib/rspec/core/filter_manager.rb', line 161

def empty?
  inclusions.empty? && exclusions.rules_empty?
end

- (Object) exclude(*args)



169
170
171
# File 'lib/rspec/core/filter_manager.rb', line 169

def exclude(*args)
  merge(@exclusions, @inclusions, *args)
end

- (Object) exclude!(*args)



173
174
175
176
# File 'lib/rspec/core/filter_manager.rb', line 173

def exclude!(*args)
  RSpec.deprecate("FilterManager#exclude! is deprecated. Use FilterManager#exclude_only")
  exclude_only(*args)
end

- (Boolean) exclude?(example)

Returns:

  • (Boolean)


186
187
188
# File 'lib/rspec/core/filter_manager.rb', line 186

def exclude?(example)
  @exclusions.empty? ? false : example.any_apply?(@exclusions)
end

- (Object) exclude_only(*args)



178
179
180
# File 'lib/rspec/core/filter_manager.rb', line 178

def exclude_only(*args)
  replace(@exclusions, @inclusions, *args)
end

- (Object) exclude_with_low_priority(*args)



182
183
184
# File 'lib/rspec/core/filter_manager.rb', line 182

def exclude_with_low_priority(*args)
  reverse_merge(@exclusions, @inclusions, *args)
end

- (Object) include(*args)



190
191
192
# File 'lib/rspec/core/filter_manager.rb', line 190

def include(*args)
  unless_standalone(*args) { merge(@inclusions, @exclusions, *args) }
end

- (Object) include!(*args)



194
195
196
197
# File 'lib/rspec/core/filter_manager.rb', line 194

def include!(*args)
  RSpec.deprecate("FilterManager#include! is deprecated. Use FilterManager#include_only")
  include_only(*args)
end

- (Boolean) include?(example)

Returns:

  • (Boolean)


207
208
209
# File 'lib/rspec/core/filter_manager.rb', line 207

def include?(example)
  @inclusions.empty? ? true : example.any_apply?(@inclusions)
end

- (Object) include_only(*args)



199
200
201
# File 'lib/rspec/core/filter_manager.rb', line 199

def include_only(*args)
  unless_standalone(*args) { replace(@inclusions, @exclusions, *args) }
end

- (Object) include_with_low_priority(*args)



203
204
205
# File 'lib/rspec/core/filter_manager.rb', line 203

def include_with_low_priority(*args)
  unless_standalone(*args) { reverse_merge(@inclusions, @exclusions, *args) }
end

- (Object) prune(examples)



165
166
167
# File 'lib/rspec/core/filter_manager.rb', line 165

def prune(examples)
  examples.select {|e| !exclude?(e) && include?(e)}
end