Class: RSpec::Core::Example
- Defined in:
- lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/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 inadvertently redefine.
Useful for configuring logging and/or taking some action based on the state of an example’s metadata.
Direct Known Subclasses
Defined Under Namespace
Classes: ExecutionResult, Procsy
Constant Summary collapse
- AllExceptionsExcludingDangerousOnesOnRubiesThatAllowIt =
Support::AllExceptionsExceptOnesWeMustNotRescue
Instance Attribute Summary collapse
- #clock ⇒ Object
-
#example_group_instance ⇒ Object
readonly
Returns the example_group_instance that provides the context for running this example.
-
#exception ⇒ Object
readonly
Returns the first exception raised in the context of running this example (nil if no exception is raised).
-
#metadata ⇒ Object
readonly
Returns the metadata object associated with this example.
-
#reporter ⇒ RSpec::Core::Reporter
readonly
The current reporter for the example.
Class Method Summary collapse
-
.delegate_to_metadata(key) ⇒ Object
Used to define methods that delegate to this example’s metadata.
- .parse_id(id) ⇒ Object
Instance Method Summary collapse
-
#description ⇒ Object
Returns the string submitted to ‘example` or its aliases (e.g. `specify`, `it`, etc).
-
#display_exception ⇒ Object
The exception that will be displayed to the user – either the failure of the example or the ‘pending_exception` if the example is pending.
-
#display_exception=(ex) ⇒ Object
Assigns the exception that will be displayed to the user – either the failure of the example or the ‘pending_exception` if the example is pending.
-
#duplicate_with(metadata_overrides = {}) ⇒ Example
Duplicates the example and overrides metadata with the provided hash.
-
#example_group ⇒ Object
Returns the example group class that provides the context for running this example.
-
#execution_result ⇒ ExecutionResult
Represents the result of running this example.
-
#fail_with_exception(reporter, exception) ⇒ Object
Used internally to set an exception and fail without actually executing the example when an exception is raised in before(:context).
-
#file_path ⇒ String
The relative path to the file where this example was defined.
-
#full_description ⇒ String
The full description (including the docstrings of all parent example groups).
-
#id ⇒ String
The unique id of this example.
-
#initialize(example_group_class, description, user_metadata, example_block = nil) ⇒ Example
constructor
private
Creates a new instance of Example.
-
#inspect ⇒ Object
(also: #to_s)
Provide a human-readable representation of this class.
-
#inspect_output ⇒ Object
Returns a description of the example that always includes the location.
- #instance_exec(*args, &block) ⇒ Object
-
#location ⇒ String
The exact source location of this example in a form like ‘./path/to/spec.rb:17`.
-
#location_rerun_argument ⇒ Object
Returns the location-based argument that can be passed to the ‘rspec` command to rerun this example.
-
#pending ⇒ Boolean
Flag that indicates that the example is not expected to pass.
- #pending? ⇒ Boolean
-
#rerun_argument ⇒ Object
deprecated
Deprecated.
Use #location_rerun_argument instead.
-
#run(example_group_instance, reporter) ⇒ Object
private
instance_execs the block passed to the constructor in the context of the instance of ExampleGroup.
-
#set_aggregate_failures_exception(exception) ⇒ Object
Used to set the exception when ‘aggregate_failures` fails.
-
#set_exception(exception) ⇒ Object
Used internally to set an exception in an after hook, which captures the exception but doesn’t raise it.
-
#skip ⇒ Boolean
Flag that will cause the example to not run.
-
#skip_with_exception(reporter, exception) ⇒ Object
Used internally to skip without actually executing the example when skip is used in before(:context).
- #skipped? ⇒ Boolean
- #update_inherited_metadata(updates) ⇒ Object
Constructor Details
#initialize(example_group_class, description, user_metadata, example_block = nil) ⇒ Example
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.
186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 186 def initialize(example_group_class, description, , example_block=nil) @example_group_class = example_group_class @example_block = example_block # Register the example with the group before creating the metadata hash. # This is necessary since creating the metadata hash triggers # `when_first_matching_example_defined` callbacks, in which users can # load RSpec support code which defines hooks. For that to work, the # examples and example groups must be registered at the time the # support code is called or be defined afterwards. # Begin defined beforehand but registered afterwards causes hooks to # not be applied where they should. example_group_class.examples << self @metadata = Metadata::ExampleHash.create( @example_group_class., , example_group_class.method(:next_runnable_index_for), description, example_block ) config = RSpec.configuration config.(@metadata) # This should perhaps be done in `Metadata::ExampleHash.create`, # but the logic there has no knowledge of `RSpec.world` and we # want to keep it that way. It's easier to just assign it here. @metadata[:last_run_status] = config.last_run_statuses[id] @example_group_instance = @exception = nil @clock = RSpec::Core::Time @reporter = RSpec::Core::NullReporter end |
Instance Attribute Details
#clock ⇒ Object
174 175 176 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 174 def clock @clock end |
#example_group_instance ⇒ Object (readonly)
Returns the example_group_instance that provides the context for running this example.
170 171 172 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 170 def example_group_instance @example_group_instance end |
#exception ⇒ Object (readonly)
Returns the first exception raised in the context of running this example (nil if no exception is raised).
158 159 160 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 158 def exception @exception end |
#metadata ⇒ Object (readonly)
Returns the metadata object associated with this example.
163 164 165 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 163 def @metadata end |
#reporter ⇒ RSpec::Core::Reporter (readonly)
Returns the current reporter for the example.
226 227 228 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 226 def reporter @reporter end |
Class Method Details
.delegate_to_metadata(key) ⇒ Object
Used to define methods that delegate to this example’s metadata.
48 49 50 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 48 def self.(key) define_method(key) { @metadata[key] } end |
.parse_id(id) ⇒ Object
122 123 124 125 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 122 def self.parse_id(id) # http://rubular.com/r/OMZSAPcAfn id.match(/\A(.*?)(?:\[([\d\s:,]+)\])?\z/).captures end |
Instance Method Details
#description ⇒ Object
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/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/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 |
#display_exception ⇒ Object
The exception that will be displayed to the user – either the failure of the example or the ‘pending_exception` if the example is pending.
388 389 390 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 388 def display_exception @exception || execution_result.pending_exception end |
#display_exception=(ex) ⇒ Object
Assigns the exception that will be displayed to the user – either the failure of the example or the ‘pending_exception` if the example is pending.
396 397 398 399 400 401 402 403 404 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 396 def display_exception=(ex) if pending? && !(Pending::PendingExampleFixedError === ex) @exception = nil execution_result.pending_fixed = false execution_result.pending_exception = ex else @exception = ex end end |
#duplicate_with(metadata_overrides = {}) ⇒ Example
Duplicates the example and overrides metadata with the provided hash.
132 133 134 135 136 137 138 139 140 141 142 143 144 145 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 132 def duplicate_with(={}) = .clone.merge() RSpec::Core::Metadata::RESERVED_KEYS.each do |reserved_key| .delete reserved_key end # don't clone the example group because the new example # must belong to the same example group (not a clone). # # block is nil in new_metadata so we have to get it from metadata. Example.new(example_group, description.clone, , [:block]) end |
#example_group ⇒ Object
Returns the example group class that provides the context for running this example.
230 231 232 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 230 def example_group @example_group_class end |
#execution_result ⇒ ExecutionResult
Returns represents the result of running this example.
53 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 53 :execution_result |
#fail_with_exception(reporter, exception) ⇒ Object
Used internally to set an exception and fail without actually executing the example when an exception is raised in before(:context).
439 440 441 442 443 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 439 def fail_with_exception(reporter, exception) start(reporter) set_exception(exception) finish(reporter) end |
#file_path ⇒ String
Returns the relative path to the file where this example was defined.
56 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 56 :file_path |
#full_description ⇒ String
Returns the full description (including the docstrings of all parent example groups).
59 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 59 :full_description |
#id ⇒ String
Returns the unique id of this example. Pass this at the command line to re-run this exact example.
117 118 119 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 117 def id @id ||= Metadata.id_from() end |
#inspect ⇒ Object Also known as: to_s
Provide a human-readable representation of this class
220 221 222 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 220 def inspect "#<#{self.class.name} #{description.inspect}>" end |
#inspect_output ⇒ Object
Returns a description of the example that always includes the location.
87 88 89 90 91 92 93 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/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 |
#instance_exec(*args, &block) ⇒ Object
456 457 458 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 456 def instance_exec(*args, &block) @example_group_instance.instance_exec(*args, &block) end |
#location ⇒ String
Returns the exact source location of this example in a form like ‘./path/to/spec.rb:17`.
62 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 62 :location |
#location_rerun_argument ⇒ Object
Returns the location-based argument that can be passed to the ‘rspec` command to rerun this example.
96 97 98 99 100 101 102 103 104 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 96 def location_rerun_argument @location_rerun_argument ||= begin loaded_spec_files = RSpec.configuration.loaded_spec_files Metadata.ascending() do || return [:location] if loaded_spec_files.include?([:absolute_file_path]) end end end |
#pending ⇒ Boolean
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/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 66 :pending |
#pending? ⇒ Boolean
234 235 236 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 234 def pending? !!pending end |
#rerun_argument ⇒ Object
Use #location_rerun_argument instead.
If there are multiple examples identified by this location, they will use #id to rerun instead, but this method will still return the location (that’s why it is deprecated!).
Returns the location-based argument that can be passed to the ‘rspec` command to rerun this example.
111 112 113 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 111 def rerun_argument location_rerun_argument end |
#run(example_group_instance, reporter) ⇒ Object
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.
246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 246 def run(example_group_instance, reporter) @example_group_instance = example_group_instance @reporter = reporter RSpec.configuration.configure_example(self, hooks) 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 RSpec.current_scope = :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 => _ # The "=> _" is normally useless but on JRuby it is a workaround # for a bug that prevents us from getting backtraces: # https://github.com/jruby/jruby/issues/4467 # # no-op, required metadata has already been set by the `skip` # method. rescue AllExceptionsExcludingDangerousOnesOnRubiesThatAllowIt => e set_exception(e) ensure RSpec.current_scope = :after_example_hook run_after_example end end end rescue Support::AllExceptionsExceptOnesWeMustNotRescue => e set_exception(e) ensure @example_group_instance = nil # if you love something... let it go end finish(reporter) ensure execution_result.ensure_timing_set(clock) RSpec.current_example = nil end |
#set_aggregate_failures_exception(exception) ⇒ Object
Used to set the exception when ‘aggregate_failures` fails.
425 426 427 428 429 430 431 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 425 def set_aggregate_failures_exception(exception) return set_exception(exception) unless display_exception exception = RSpec::Core::MultipleExceptionError::InterfaceTag.for(exception) exception.add display_exception self.display_exception = exception end |
#set_exception(exception) ⇒ Object
Used internally to set an exception in an after hook, which captures the exception but doesn’t raise it.
412 413 414 415 416 417 418 419 420 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 412 def set_exception(exception) return self.display_exception = exception unless display_exception unless RSpec::Core::MultipleExceptionError === display_exception self.display_exception = RSpec::Core::MultipleExceptionError.new(display_exception) end display_exception.add exception end |
#skip ⇒ Boolean
Returns flag that will cause the example to not run. The ExecutionResult status will be ‘:pending`.
69 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 69 :skip |
#skip_with_exception(reporter, exception) ⇒ Object
Used internally to skip without actually executing the example when skip is used in before(:context).
449 450 451 452 453 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 449 def skip_with_exception(reporter, exception) start(reporter) Pending.mark_skipped! self, exception.argument finish(reporter) end |
#skipped? ⇒ Boolean
238 239 240 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 238 def skipped? !!skip end |
#update_inherited_metadata(updates) ⇒ Object
148 149 150 151 152 |
# File 'lib/rubypitaya/app-template/vendor/bundle/ruby/3.1.0/gems/rspec-core-3.12.0/lib/rspec/core/example.rb', line 148 def (updates) .update(updates) do |_key, existing_example_value, _new_inherited_value| existing_example_value end end |