Class: RSpec::Expectations::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/rspec/expectations/configuration.rb

Overview

Provides configuration options for rspec-expectations. If you are using rspec-core, you can access this via a block passed to RSpec::Core::Configuration#expect_with. Otherwise, you can access it via RSpec::Expectations.configuration.

Examples:

RSpec.configure do |rspec|
  rspec.expect_with :rspec do |c|
    # c is the config object
  end
end

# or

RSpec::Expectations.configuration

Constant Summary collapse

NullBacktraceFormatter =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Null implementation of a backtrace formatter used by default when rspec-core is not loaded. Does no filtering.

Module.new do
  def self.format_backtrace(backtrace)
    backtrace
  end
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Returns a new instance of Configuration.



29
30
31
32
 
# File 'lib/rspec/expectations/configuration.rb', line 29

def initialize
  @on_potential_false_positives = :warn
  @strict_predicate_matchers = false
end

Instance Attribute Details

#backtrace_formatter ⇒ Object

Sets or gets the backtrace formatter. The backtrace formatter should implement #format_backtrace(Array<String>). This is used to format backtraces of errors handled by the raise_error matcher.

If you are using rspec-core, rspec-core's backtrace formatting will be used (including respecting the presence or absence of the --backtrace option).



133
 
# File 'lib/rspec/expectations/configuration.rb', line 133

attr_writer :backtrace_formatter

#color=(value) ⇒ Object (writeonly)

:nocov: Indicates whether or not diffs should be colored. Delegates to rspec-core's color option if rspec-core is loaded; otherwise you can set it here.



96
97
98
 
# File 'lib/rspec/expectations/configuration.rb', line 96

def color=(value)
  @color = value
end

#include_chain_clauses_in_custom_matcher_descriptions=(value) ⇒ Object (writeonly)

Sets if custom matcher descriptions and failure messages should include clauses from methods defined using chain.

Parameters:

  • value (Boolean) 


145
146
147
 
# File 'lib/rspec/expectations/configuration.rb', line 145

def include_chain_clauses_in_custom_matcher_descriptions=(value)
  @include_chain_clauses_in_custom_matcher_descriptions = value
end

#on_potential_false_positives ⇒ Symbol #on_potential_false_positives=(value) ⇒ Symbol

Configures what RSpec will do about matcher use which would potentially cause false positives in tests. Defaults to :warn since this is generally the desired behavior, but can also be set to :raise or :nothing.

Overloads:

  • #on_potential_false_positives ⇒ Symbol

    Returns the behavior setting.

    Returns:

    • (Symbol) —

      the behavior setting

  • #on_potential_false_positives=(value) ⇒ Symbol

    Returns the behavior setting.

    Parameters:

    • behavior (Symbol) —

      can be set to :warn, :raise or :nothing

    Returns:

    • (Symbol) —

      the behavior setting



192
193
194
 
# File 'lib/rspec/expectations/configuration.rb', line 192

def on_potential_false_positives
  @on_potential_false_positives
end

#strict_predicate_matchers ⇒ Boolean #strict_predicate_matchers? ⇒ Boolean #strict_predicate_matchers=(value) ⇒ Object

Configures RSpec to check predicate matchers to be(true) / be(false) (strict), or be_truthy / be_falsey (not strict). Historically, the default was false, but true is recommended.

Overloads:

  • #strict_predicate_matchers ⇒ Boolean

    Returns:

    • (Boolean)
  • #strict_predicate_matchers? ⇒ Boolean

    Returns:

    • (Boolean)
  • #strict_predicate_matchers=(value) ⇒ Object

    Parameters:

    • value (Boolean) 


211
212
213
 
# File 'lib/rspec/expectations/configuration.rb', line 211

def strict_predicate_matchers
  @strict_predicate_matchers
end

Instance Method Details

#add_should_and_should_not_to(*modules) ⇒ Object

:nocov: Because this is only really useful on 1.8, and hard to test elsewhere.

Adds should and should_not to the given classes or modules. This can be used to ensure should works properly on things like proxy objects (particular Delegator-subclassed objects on 1.8).

Parameters:

  • modules (Array<Module>) —

    the list of classes or modules to add should and should_not to.



116
117
118
119
120
 
# File 'lib/rspec/expectations/configuration.rb', line 116

def add_should_and_should_not_to(*modules)
  modules.each do |mod|
    Expectations::Syntax.enable_should(mod)
  end
end

#color? ⇒ Boolean

Indicates whether or not diffs should be colored. Delegates to rspec-core's color option if rspec-core is loaded; otherwise you can set it here.

Returns:

  • (Boolean) 


101
102
103
 
# File 'lib/rspec/expectations/configuration.rb', line 101

def color?
  ::RSpec.configuration.color_enabled?
end

#include_chain_clauses_in_custom_matcher_descriptions? ⇒ Boolean

Indicates whether or not custom matcher descriptions and failure messages should include clauses from methods defined using chain. It is false by default for backwards compatibility.

Returns:

  • (Boolean) 


150
151
152
 
# File 'lib/rspec/expectations/configuration.rb', line 150

def include_chain_clauses_in_custom_matcher_descriptions?
  @include_chain_clauses_in_custom_matcher_descriptions ||= false
end

#max_formatted_output_length=(length) ⇒ Object

Configures the maximum character length that RSpec will print while formatting an object. You can set length to nil to prevent RSpec from doing truncation.

Examples:

RSpec.configure do |rspec|
  rspec.expect_with :rspec do |c|
    c.max_formatted_output_length = 200
  end
end

Parameters:

  • length (Fixnum) —

    the number of characters to limit the formatted output to.



70
71
72
 
# File 'lib/rspec/expectations/configuration.rb', line 70

def max_formatted_output_length=(length)
  RSpec::Support::ObjectFormatter.default_instance.max_formatted_output_length = length
end

#strict_predicate_matchers? ⇒ Boolean

Returns:

  • (Boolean) 


218
219
220
 
# File 'lib/rspec/expectations/configuration.rb', line 218

def strict_predicate_matchers?
  @strict_predicate_matchers
end

#syntax ⇒ Array<Symbol>

The list of configured syntaxes.

Examples:

unless RSpec::Matchers.configuration.syntax.include?(:expect)
  raise "this RSpec extension gem requires the rspec-expectations `:expect` syntax"
end

Returns:

  • (Array<Symbol>) —

    the list of configured syntaxes.



80
81
82
83
84
85
 
# File 'lib/rspec/expectations/configuration.rb', line 80

def syntax
  syntaxes = []
  syntaxes << :should if Expectations::Syntax.should_enabled?
  syntaxes << :expect if Expectations::Syntax.expect_enabled?
  syntaxes
end

#syntax=(values) ⇒ Object

Configures the supported syntax.

Examples:

RSpec.configure do |rspec|
  rspec.expect_with :rspec do |c|
    c.syntax = :should
    # or
    c.syntax = :expect
    # or
    c.syntax = [:should, :expect]
  end
end

Parameters:

  • values (Array<Symbol>, Symbol) —

    the syntaxes to enable



46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/rspec/expectations/configuration.rb', line 46

def syntax=(values)
  if Array(values).include?(:expect)
    Expectations::Syntax.enable_expect
  else
    Expectations::Syntax.disable_expect
  end

  if Array(values).include?(:should)
    Expectations::Syntax.enable_should
  else
    Expectations::Syntax.disable_should
  end
end

#warn_about_potential_false_positives=(boolean) ⇒ Object

Configures whether RSpec will warn about matcher use which will potentially cause false positives in tests.

Parameters:

  • boolean (Boolean) 


173
174
175
176
177
178
179
180
181
 
# File 'lib/rspec/expectations/configuration.rb', line 173

def warn_about_potential_false_positives=(boolean)
  if boolean
    self.on_potential_false_positives = :warn
  elsif warn_about_potential_false_positives?
    self.on_potential_false_positives = :nothing
  else
    # no-op, handler is something else
  end
end

#warn_about_potential_false_positives? ⇒ Boolean

Indicates whether RSpec will warn about matcher use which will potentially cause false positives in tests, generally you want to avoid such scenarios so this defaults to true.

Returns:

  • (Boolean) 


225
226
227
 
# File 'lib/rspec/expectations/configuration.rb', line 225

def warn_about_potential_false_positives?
  on_potential_false_positives == :warn
end