Class: RSpec::Expectations::Configuration

Relationships & Source Files
Inherits:	Object
Defined in:	rspec-expectations/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 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

FALSE_POSITIVE_BEHAVIOURS = Internal use only
# File 'rspec-expectations/lib/rspec/expectations/configuration.rb', line 22

{
  :warn    => lambda { |message| RSpec.warning message },
  :raise   => lambda { |message| raise ArgumentError, message },
  :nothing => lambda { |_| true },
}

NullBacktraceFormatter = Internal use only

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

# File 'rspec-expectations/lib/rspec/expectations/configuration.rb', line 163
```
Module.new do
  def self.format_backtrace(backtrace)
    backtrace
  end
end
```

Class Method Summary

.new ⇒ Configuration constructor

Instance Attribute Summary

#backtrace_formatter rw

Sets or gets the backtrace formatter.
#backtrace_formatter=(value) rw

Sets or gets the backtrace formatter.
#color=(value) rw

:nocov: Indicates whether or not diffs should be colored.
#color? ⇒ Boolean rw

Indicates whether or not diffs should be colored.
#include_chain_clauses_in_custom_matcher_descriptions=(value) rw

Sets if custom matcher descriptions and failure messages should include clauses from methods defined using chain.
#include_chain_clauses_in_custom_matcher_descriptions? ⇒ Boolean rw

Indicates whether or not custom matcher descriptions and failure messages should include clauses from methods defined using chain.
#max_formatted_output_length=(length) writeonly

Configures the maximum character length that ::RSpec will print while formatting an object.
#on_potential_false_positives rw

Indicates what ::RSpec will do about matcher use which will potentially cause false positives in tests, generally you want to avoid such scenarios so this defaults to true.
#on_potential_false_positives=(behavior) rw

Configures what ::RSpec will do about matcher use which will potentially cause false positives in tests.
#strict_predicate_matchers rw
#strict_predicate_matchers=(flag) rw

Configures RSpec to check predicate matchers to ‘be(true)` / be(false) (strict), or be_truthy / be_falsey (not strict).
#strict_predicate_matchers? ⇒ Boolean rw
#syntax ⇒ Array<Symbol> rw

The list of configured syntaxes.
#syntax=(values) rw

Configures the supported syntax.
#warn_about_potential_false_positives=(boolean) rw

Configures whether ::RSpec will warn about matcher use which will potentially cause false positives in tests.
#warn_about_potential_false_positives? ⇒ Boolean rw

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.

Instance Method Summary

#add_should_and_should_not_to(*modules)

:nocov: Because this is only really useful on 1.8, and hard to test elsewhere.
#false_positives_handler Internal use only Internal use only
#reset_syntaxes_to_default Internal use only Internal use only

Constructor Details

.new ⇒ `Configuration`

[ GitHub ]

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


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

Instance Attribute Details

#backtrace_formatter (rw)

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).

[ GitHub ]

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


def backtrace_formatter
  @backtrace_formatter ||= if defined?(::RSpec.configuration.backtrace_formatter)
                             ::RSpec.configuration.backtrace_formatter
                           else
                             NullBacktraceFormatter
                           end
end

#backtrace_formatter=(value) (rw)

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).

[ GitHub ]

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


attr_writer :backtrace_formatter

#color=(value) (rw)

: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.

[ GitHub ]

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


attr_writer :color

#color? ⇒ `Boolean` (rw)

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.

[ GitHub ]

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


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

#include_chain_clauses_in_custom_matcher_descriptions=(value) (rw)

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

Parameters:

value (Boolean)

[ GitHub ]

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


attr_writer :include_chain_clauses_in_custom_matcher_descriptions

#include_chain_clauses_in_custom_matcher_descriptions? ⇒ `Boolean` (rw)

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.

[ GitHub ]

# File 'rspec-expectations/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) (writeonly)

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.

[ GitHub ]

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


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

#on_potential_false_positives (rw)

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

[ GitHub ]

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


attr_reader :on_potential_false_positives

#on_potential_false_positives=(behavior) (rw)

Configures what ::RSpec will do about matcher use which will potentially cause false positives in tests.

Parameters:

behavior (Symbol) —

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

[ GitHub ]

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


def on_potential_false_positives=(behavior)
  unless FALSE_POSITIVE_BEHAVIOURS.key?(behavior)
    raise ArgumentError, "Supported values are: #{FALSE_POSITIVE_BEHAVIOURS.keys}"
  end
  @on_potential_false_positives = behavior
end

#strict_predicate_matchers (rw)

[ GitHub ]

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


attr_reader :strict_predicate_matchers

#strict_predicate_matchers=(flag) (rw)

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.

Raises:

(ArgumentError)

[ GitHub ]

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


def strict_predicate_matchers=(flag)
  raise ArgumentError, "Pass `true` or `false`" unless flag == true || flag == false
  @strict_predicate_matchers = flag
end

#strict_predicate_matchers? ⇒ `Boolean` (rw)

[ GitHub ]

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


def strict_predicate_matchers?
  @strict_predicate_matchers
end

#syntax ⇒ `Array`<`Symbol`> (rw)

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.

[ GitHub ]

# File 'rspec-expectations/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) (rw)

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

[ GitHub ]

# File 'rspec-expectations/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) (rw)

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

Parameters:

boolean (Boolean)

[ GitHub ]

# File 'rspec-expectations/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` (rw)

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.

[ GitHub ]

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


def warn_about_potential_false_positives?
  on_potential_false_positives == :warn
end

Instance Method Details

#add_should_and_should_not_to(*modules)

: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.

[ GitHub ]

# File 'rspec-expectations/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

#false_positives_handler

This method is for internal use only.

[ GitHub ]

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


def false_positives_handler
  FALSE_POSITIVE_BEHAVIOURS.fetch(@on_potential_false_positives)
end

#reset_syntaxes_to_default

This method is for internal use only.

[ GitHub ]

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


def reset_syntaxes_to_default
  self.syntax = [:should, :expect]
  RSpec::Expectations::Syntax.warn_about_should!
end

Class: RSpec::Expectations::Configuration

Overview

Constant Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new ⇒ Configuration

Instance Attribute Details

#backtrace_formatter (rw)

#backtrace_formatter=(value) (rw)

#color=(value) (rw)

#color? ⇒ Boolean (rw)

#include_chain_clauses_in_custom_matcher_descriptions=(value) (rw)

#include_chain_clauses_in_custom_matcher_descriptions? ⇒ Boolean (rw)

#max_formatted_output_length=(length) (writeonly)

#on_potential_false_positives (rw)

#on_potential_false_positives=(behavior) (rw)

#strict_predicate_matchers (rw)

#strict_predicate_matchers=(flag) (rw)

#strict_predicate_matchers? ⇒ Boolean (rw)

#syntax ⇒ Array<Symbol> (rw)

#syntax=(values) (rw)

#warn_about_potential_false_positives=(boolean) (rw)

#warn_about_potential_false_positives? ⇒ Boolean (rw)

Instance Method Details

#add_should_and_should_not_to(*modules)

#false_positives_handler

#reset_syntaxes_to_default

.new ⇒ `Configuration`

#color? ⇒ `Boolean` (rw)

#include_chain_clauses_in_custom_matcher_descriptions? ⇒ `Boolean` (rw)

#strict_predicate_matchers? ⇒ `Boolean` (rw)

#syntax ⇒ `Array`<`Symbol`> (rw)

#warn_about_potential_false_positives? ⇒ `Boolean` (rw)