Class: RSpec::Clone::Dsl Private

Inherits:
Object
  • Object
show all
Defined in:
lib/r_spec/clone/dsl.rb

Overview

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

Abstract class for handling the domain-specific language.

Class Method Summary collapse

Class Method Details

.before(&block) ⇒ Object

Executes the given block before each spec in the current context runs.

Examples:

require "r_spec"

RSpec.describe Integer do
  before do
    @value = 123
  end

  it { expect(@value).to be 123 }

  describe "nested" do
    before do
      @value -= 81
    end

    it { expect(@value).to be 42 }
  end

  it { expect(@value).to be 123 }
end

# Output to the console
#   Success: expected to be 123.
#   Success: expected to be 42.
#   Success: expected to be 123.

Parameters:

  • block (Proc) —

    The content to execute at the class initialization.



46
47
48
49
50
51
52
53
 
# File 'lib/r_spec/clone/dsl.rb', line 46

def self.before(&block)
  define_method(BEFORE_METHOD) do
    super()
    instance_eval(&block)
  end

  private BEFORE_METHOD
end

.context(_description, &block) ⇒ Object

Defines an example group that establishes a specific context, like _empty array_ versus _array with elements_.

Unlike a ‘describe` block, all specifications executed within a `context` are isolated in a subprocess. This prevents possible side effects on the Ruby object environment from being propagated outside their context, which could alter the result of the unit test suite.

Examples:

require "r_spec"

RSpec.describe "web resource" do
  context "when resource is not found" do
    pending "responds with 404"
  end

  context "when resource is found" do
    pending "responds with 200"
  end
end

# Output to the console
#   Warning: responds with 404.
#   Warning: responds with 200.

Parameters:

  • _description (String) —

    A description that usually begins with “when”, “with” or “without”.

  • block (Proc) —

    The block to define the specs.



176
177
178
179
 
# File 'lib/r_spec/clone/dsl.rb', line 176

def self.context(_description, &block)
  pid = ::Process.fork { ::Class.new(self).instance_eval(&block) }
  exit false unless ::Process::Status.wait(pid).exitstatus.zero?
end

.describe(const) ⇒ Object

Defines an example group that describes a unit to be tested.

Examples:

require "r_spec"

RSpec.describe String do
  describe "+" do
    it("concats") { expect("foo" + "bar").to eq "foobar" }
  end
end

# Output to the console
#   Success: expected to eq "foobar".

Parameters:

  • const (Module, String) —

    A module to include in block context.

  • block (Proc) —

    The block to define the specs.



138
139
140
141
142
 
# File 'lib/r_spec/clone/dsl.rb', line 138

def self.describe(const, &)
  desc = ::Class.new(self)
  desc.let(:described_class) { const } if const.is_a?(::Module)
  desc.instance_eval(&)
end

.it(_name = nil, &block) ⇒ nil

Defines a concrete test case.

The test is performed by the block supplied to ‘&block`.

It can be used inside a describe or context section.

Examples:

The integer after 41

require "r_spec"

RSpec.describe Integer do
  it { expect(41.next).to be 42 }
end

# Output to the console
#   Success: expected to be 42.

A division by zero

require "r_spec"

RSpec.describe Integer do
  subject { 41 }

  it { is_expected.to be_an_instance_of described_class }

  it "raises an error" do
    expect { subject / 0 }.to raise_exception ZeroDivisionError
  end
end

# Output to the console
#   Success: expected 41 to be an instance of Integer.
#   Success: divided by 0.

Parameters:

  • _name (String, nil) (defaults to: nil) —

    The name of the spec.

  • block (Proc) —

    An expectation to evaluate.

Returns:

  • (nil) —

    Write a message to STDOUT.

Raises:

  • (SystemExit) —

    Terminate execution immediately by calling ‘Kernel.exit(false)` with a failure message written to STDERR.



223
224
225
226
 
# File 'lib/r_spec/clone/dsl.rb', line 223

def self.it(_name = nil, &block)
  Logger.source(*block.source_location)
  example_without_attribute.new.instance_eval(&block)
end

.its(attribute, &block) ⇒ nil

Defines a single concrete test case that specifies the actual value of an attribute of the subject using ExpectationHelper::Its#is_expected.

Examples:

The integer after 41

require "r_spec"

RSpec.describe Integer do
  subject { 41 }

  its(:next) { is_expected.to be 42 }
end

# Output to the console
#   Success: expected to be 42.

A division by zero

require "r_spec"

RSpec.describe Integer do
  subject { 41 }

  its(:/, 0) { is_expected.to raise_exception ZeroDivisionError }
end

# Output to the console
#   Success: divided by 0.

A spec without subject

require "r_spec"

RSpec.describe Integer do
  its(:abs) { is_expected.to raise_exception RSpec::Clone::Error::UndefinedSubject }
end

# Output to the console
#   Success: subject not explicitly defined.

Parameters:

  • attribute (String, Symbol) —

    The property to call to subject.

  • args (Array) —

    An optional list of arguments.

  • kwargs (Hash) —

    An optional list of keyword arguments.

  • block (Proc) —

    An expectation to evaluate.

Returns:

  • (nil) —

    Write a message to STDOUT.

Raises:

  • (SystemExit) —

    Terminate execution immediately by calling ‘Kernel.exit(false)` with a failure message written to STDERR.



276
277
278
279
280
 
# File 'lib/r_spec/clone/dsl.rb', line 276

def self.its(attribute, *, **, &block)
  Logger.source(*block.source_location)
  example_with_attribute(attribute, *, **).new
                                          .instance_eval(&block)
end

.let(name) ⇒ Symbol

Sets a user-defined property.

Examples:

require "r_spec"

RSpec.describe "Name stories" do
  let(:name) { "Bob" }

  it { expect(name).to eq "Bob" }

  context "with last name" do
    let(:name) { "#{super()} Smith" }

    it { expect(name).to eq "Bob Smith" }
  end
end

# Output to the console
#   Success: expected to eq "Bob".
#   Success: expected to eq "Bob Smith".

Parameters:

  • name (String, Symbol) —

    The name of the property.

  • block (Proc) —

    The content of the method to define.

Returns:

  • (Symbol) —

    A private method that define the block content.

Raises:



82
83
84
85
86
 
# File 'lib/r_spec/clone/dsl.rb', line 82

def self.let(name, ...)
  raise Error::ReservedMethod if BEFORE_METHOD.equal?(name.to_sym)

  private define_method(name, ...)
end

.pending(message) ⇒ nil

Defines a pending test case.

‘&block` is never evaluated. It can be used to describe behaviour that is not yet implemented.

Examples:

require "r_spec"

RSpec.describe "an example" do
  pending "is implemented but waiting" do
    expect something to be finished
  end

  pending "is not yet implemented and waiting"
end

# Output to the console
#   Warning: is implemented but waiting.
#   Warning: is not yet implemented and waiting.

Parameters:

  • message (String) —

    The reason why the example is pending.

Returns:

  • (nil) —

    Write a message to STDOUT.



309
310
311
 
# File 'lib/r_spec/clone/dsl.rb', line 309

def self.pending(message)
  Logger.passed_spec Error::PendingExpectation.result(message)
end

.subject ⇒ Symbol

Sets a user-defined property named #subject.

Examples:

require "r_spec"

RSpec.describe Array do
  subject { [1, 2, 3] }

  it "has the prescribed elements" do
    expect(subject).to eq([1, 2, 3])
  end

  it { is_expected.to be_an_instance_of described_class }

  its(:size) { is_expected.to be 3 }
  its(:downcase) { is_expected.to raise_exception NoMethodError }
end

# Output to the console
#   Success: expected to eq [1, 2, 3].
#   Success: expected [1, 2, 3] to be an instance of Array.
#   Success: expected to be 3.
#   Success: undefined method `downcase' for [1, 2, 3]:Array.

Parameters:

  • block (Proc) —

    The subject to set.

Returns:

  • (Symbol) —

    A #subject method that define the block content.



116
117
118
 
# File 'lib/r_spec/clone/dsl.rb', line 116

def self.subject(&)
  let(__method__, &)
end