Class: RSpec::Core::Example
- Inherits:
-
Object
- Object
- RSpec::Core::Example
- Defined in:
- lib/rspec/core/example.rb
Overview
Example blocks are evaluated in the context of an instance
of an ExampleGroup
, not in the context of an instance of Example
.
Wrapper for an instance of a subclass of ExampleGroup. An instance of
RSpec::Core::Example
is returned by example definition methods
such as it and is yielded to the it,
before, after, around,
let and
subject blocks.
This allows us to provide rich metadata about each individual example without adding tons of methods directly to the ExampleGroup that users may inadvertantly redefine.
Useful for configuring logging and/or taking some action based on the state of an example's metadata.
Defined Under Namespace
Classes: ExecutionResult, Procsy
Instance Attribute Summary (collapse)
-
- (void) exception
readonly
Returns the first exception raised in the context of running this example (nil if no exception is raised).
-
- (void) metadata
readonly
Returns the metadata object associated with this example.
Instance Method Summary (collapse)
-
- (void) description
Returns the string submitted to
example
or its aliases (e.g.specify
,it
, etc). -
- (void) example_group
Returns the example group class that provides the context for running this example.
-
- (ExecutionResult) execution_result
Represents the result of running this example.
-
- (String) file_path
The relative path to the file where this example was defined.
-
- (String) full_description
The full description (including the docstrings of all parent example groups).
-
- (Example) initialize(example_group_class, description, user_metadata, example_block = nil)
constructor
private
Creates a new instance of Example.
-
- (void) inspect_output
Returns a description of the example that always includes the location.
-
- (String) location
The exact source location of this example in a form like
./path/to/spec.rb:17
. -
- (Boolean) pending
(also: #pending?)
Flag that indicates that the example is not expected to pass.
-
- (void) rerun_argument
Returns the argument that can be passed to the
rspec
command to rerun this example. -
- (void) run(example_group_instance, reporter)
private
instance_execs the block passed to the constructor in the context of the instance of ExampleGroup.
-
- (Boolean) skip
(also: #skipped?)
Flag that will cause the example to not run.
Constructor Details
- (Example) initialize(example_group_class, description, user_metadata, example_block = nil)
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Creates a new instance of Example.
136 137 138 139 140 141 142 143 144 145 146 |
# File 'lib/rspec/core/example.rb', line 136 def initialize(example_group_class, description, , example_block=nil) @example_group_class = example_group_class @example_block = example_block @metadata = Metadata::ExampleHash.create( @example_group_class., , description, example_block ) @example_group_instance = @exception = nil @clock = RSpec::Core::Time end |
Instance Attribute Details
- (void) exception (readonly)
Returns the first exception raised in the context of running this example (nil if no exception is raised).
108 109 110 |
# File 'lib/rspec/core/example.rb', line 108 def exception @exception end |
- (void) metadata (readonly)
Returns the metadata object associated with this example.
113 114 115 |
# File 'lib/rspec/core/example.rb', line 113 def @metadata end |
Instance Method Details
- (void) description
Returns the string submitted to example
or its aliases (e.g.
specify
, it
, etc). If no string is submitted (e.g.
it { is_expected.to do_something }
) it returns the message generated
by the matcher if there is one, otherwise returns a message including
the location of the example.
76 77 78 79 80 81 82 83 84 |
# File 'lib/rspec/core/example.rb', line 76 def description description = if [:description].to_s.empty? location_description else [:description] end RSpec.configuration.format_docstrings_block.call(description) end |
- (void) example_group
Returns the example group class that provides the context for running this example.
150 151 152 |
# File 'lib/rspec/core/example.rb', line 150 def example_group @example_group_class end |
- (ExecutionResult) execution_result
Returns represents the result of running this example.
53 |
# File 'lib/rspec/core/example.rb', line 53 :execution_result |
- (String) file_path
Returns the relative path to the file where this example was defined.
56 |
# File 'lib/rspec/core/example.rb', line 56 :file_path |
- (String) full_description
Returns the full description (including the docstrings of all parent example groups).
59 |
# File 'lib/rspec/core/example.rb', line 59 :full_description |
- (void) inspect_output
Returns a description of the example that always includes the location.
87 88 89 90 91 92 93 |
# File 'lib/rspec/core/example.rb', line 87 def inspect_output inspect_output = "\"#{description}\"" unless [:description].to_s.empty? inspect_output << " (#{location})" end inspect_output end |
- (String) location
Returns the exact source location of this example in a form
like ./path/to/spec.rb:17
62 |
# File 'lib/rspec/core/example.rb', line 62 :location |
- (Boolean) pending Also known as: pending?
Returns flag that indicates that the example is not expected to pass. It will be run and will either have a pending result (if a failure occurs) or a failed result (if no failure occurs).
66 |
# File 'lib/rspec/core/example.rb', line 66 :pending |
- (void) rerun_argument
Returns the argument that can be passed to the rspec
command to rerun this example.
96 97 98 99 100 101 102 |
# File 'lib/rspec/core/example.rb', line 96 def rerun_argument loaded_spec_files = RSpec.configuration.loaded_spec_files Metadata.ascending() do || return [:location] if loaded_spec_files.include?([:absolute_file_path]) end end |
- (void) run(example_group_instance, reporter)
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
instance_execs the block passed to the constructor in the context of the instance of RSpec::Core::ExampleGroup.
161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 |
# File 'lib/rspec/core/example.rb', line 161 def run(example_group_instance, reporter) @example_group_instance = example_group_instance hooks.register_global_singleton_context_hooks(self, RSpec.configuration.hooks) RSpec.configuration.configure_example(self) RSpec.current_example = self start(reporter) Pending.mark_pending!(self, pending) if pending? begin if skipped? Pending.mark_pending! self, skip elsif !RSpec.configuration.dry_run? with_around_and_singleton_context_hooks do begin run_before_example @example_group_instance.instance_exec(self, &@example_block) if pending? Pending.mark_fixed! self raise Pending::PendingExampleFixedError, 'Expected example to fail since it is pending, but it passed.', [location] end rescue Pending::SkipDeclaredInExample # no-op, required metadata has already been set by the `skip` # method. rescue Exception => e set_exception(e) ensure run_after_example end end end rescue Exception => e set_exception(e) ensure ExampleGroup.each_instance_variable_for_example(@example_group_instance) do |ivar| @example_group_instance.instance_variable_set(ivar, nil) end @example_group_instance = nil end finish(reporter) ensure RSpec.current_example = nil end |
- (Boolean) skip Also known as: skipped?
Returns flag that will cause the example to not run.
The ExecutionResult status will be :pending
.
69 |
# File 'lib/rspec/core/example.rb', line 69 :skip |