Callsmethod expecting an iterator and compares iterated values withexpected.

See.it_iterates for details.

Callsmethod with a block and compares yielded values withexpected.

See.it_iterates for details.

Asserts that the givencall and itsIO-accepting variant both match the givenexpectation, used to test string printing.

Given a call of the formfoo.bar(*args, **opts), this tests the following cases:

• The call itself. Additionally this call must return aString.
• String.build { |io| foo.bar(io, *args, **opts) }, which constructs a String via anIO overload.
• io = ...; foo.bar(io, *args, **opts); io.to_s, whereio is anIO configured to use the UTF-16 encoding, and contents written to it are decoded back into a UTF-8String. This case ensures that theIO overload does not produce malformed UTF-8 byte sequences via a non-default encoding. This case is skipped if thewithout_iconv flag is set.

The overload that accepts astr argument is usually easier to work with.

Asserts that the givencall and itsIO-accepting variant both produce the given stringstr.

Equivalent toassert_prints call, should: eq(str).str must be validly encoded in UTF-8.

require "spec"
require "spec/helpers/string"

it "prints integers with `Int#to_s`" do
  assert_prints 123.to_s, "123"
  assert_prints 123.to_s(16), "7b"
end

Methods that do not follow the convention ofIO-accepting and String-returning overloads can also be tested as long as suitable wrapper methods are defined:

require "spec"
require "spec/helpers/string"

private def fprintf(format, *args)
  sprintf(format, *args)
end

private def fprintf(io : IO, format, *args)
  io.printf(format, *args)
end

it "prints with `sprintf` and `IO#printf`" do
  assert_prints fprintf("%d", 123), "123"
  assert_prints fprintf("%x %b", 123, 6), "7b 110"
end

Spec helper for generic iteration methods which tests both yielding and iterator overloads.

This helper creates two spec examples nameddescription with suffixes " yielding" and" iterator". The yielding example callsmethod with a block and expects the iteration elements to be yielded to the block. The iterator example callsmethod without a block and expects it to return anIterator which it then consumes.

The iterated elements are collected in an array and compared toexpected, ensuring type-equality of the elements.

By default, both examples make sure that the iteration is finished after iterating all elements fromexpected. If the iteration is infinite, passinginfinite: true skips that check and allows to test a finite sample of an infinite iteration.

require "spec/helpers/iterate"

it_iterates "Array#each", [1, 2, 3], (1..3).each
it_iterates "infinite #cycle", [1, 2, 3, 1, 2, 3, 1], (1..3).cycle, infinite: true

If the iteration elements are tuples (i.e. multiple values), the yielding variant by default only catches the first value because of the block argument mechanics. Passingtuple: true ensures all yielded arguments are collected using a splat.

require "spec/helpers/iterate"

it_iterates "Array#each_with_index", [{1, 0}, {2, 1}, {3, 2}], (1..3).each_with_index, tuple: true

Executes the given block after the last spec in the current context runs.

A context is defined by#describe or#context blocks, or outside of them it's the root context. This is independent of the source location the specs and this hook are defined.

If multiple blocks are registered on the same context, they are executed in order of definition.

require "spec"

it "sample_a" { }

describe "nested_context" do
  after_all do
    puts "runs at end of nested_context"
  end

  it "sample_b" { }
end

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

A context is defined by#describe or#context blocks, or outside of them it's the root context. Nested contexts inherit the*_each blocks of their ancestors.

If multiple blocks are registered for the same spec, the blocks defined in the outermost context go first. Blocks on the same context are executed in order of definition.

require "spec"

it "sample_a" { }

describe "nested_context" do
  after_each do
    puts "runs after sample_b"
  end

  it "sample_b" { }
end

Executes the given block when the current context runs.

The block must callrun on the givenContext::Procsy object.

This is essentially a#before_all and#after_all hook combined into one. It is useful for example when setup and teardown steps need shared state.

A context is defined by#describe or#context blocks. This hook does not work outside such a block (i.e. in the root context).

If multiple blocks are registered for the same spec, the blocks defined in the outermost context go first. Blocks on the same context are executed in order of definition.

require "spec"

describe "main_context" do
  around_each do |example|
    puts "runs at beginning of main_context"
    example.run
    puts "runs at end of main_context"
  end

  it "sample_a" { }

  describe "nested_context" do
    around_each do |example|
      puts "runs at beginning of nested_context"
      example.run
      puts "runs at end of nested_context"
    end

    it "sample_b" { }
  end
end

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

The block must callrun on the givenExample::Procsy object.

This is essentially a#before_each and#after_each hook combined into one. It is useful for example when setup and teardown steps need shared state.

A context is defined by#describe or#context blocks, or outside of them it's the root context. Nested contexts inherit the*_each blocks of their ancestors.

If multiple blocks are registered for the same spec, the blocks defined in the outermost context go first. Blocks on the same context are executed in order of definition.

require "spec"

it "sample_a" { }

describe "nested_context" do
  around_each do |example|
    puts "runs before sample_b"
    example.run
    puts "runs after sample_b"
  end

  it "sample_b" { }
end

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

A context is defined by#describe or#context blocks, or outside of them it's the root context. This is independent of the source location the specs and this hook are defined.

If multiple blocks are registered on the same context, they are executed in order of definition.

require "spec"

it "sample_a" { }

describe "nested_context" do
  before_all do
    puts "runs at start of nested_context"
  end

  it "sample_b" { }
end

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

A context is defined by#describe or#context blocks, or outside of them it's the root context. Nested contexts inherit the*_each blocks of their ancestors.

If multiple blocks are registered for the same spec, the blocks defined in the outermost context go first. Blocks on the same context are executed in order of definition.

require "spec"

it "sample_a" { }

describe "nested_context" do
  before_each do
    puts "runs before sample_b"
  end

  it "sample_b" { }
end

Defines an example group that establishes a specific context, likeempty array versusarray with elements. Inside&block examples are defined by#it or#pending.

It is functionally equivalent to#describe.

Iffocus istrue, only this#context, and others marked withfocus: true, will run.

Defines an example group that describes a unit to be tested. Inside&block examples are defined by#it or#pending.

Several#describe blocks can be nested.

Example:

require "spec"

describe "Int32" do
  describe "+" do
    it "adds" { (1 + 1).should eq 2 }
  end
end

Iffocus istrue, only this#describe, and others marked withfocus: true, will run.

Fails an example.

This method can be used to manually fail an example defined in an#it block.

Defines a concrete test case.

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

Example:

require "spec"

it "adds" { (1 + 1).should eq 2 }

It is usually used inside a#describe or#context section.

Iffocus istrue, only this test, and others marked withfocus: true, will run.

Defines a pending test case.

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

Example:

require "spec"

pending "check cat" { cat.alive? }

It is usually used inside a#describe or#context section.

Iffocus istrue, only this test, and others marked withfocus: true, will run.

Defines a yet-to-be-implemented pending test case

Iffocus istrue, only this test, and others marked withfocus: true, will run.

Marks the current example pending

In case an example needs to be pending on some condition that requires executing it, this allows to mark it as such rather than letting it fail or never run.

require "spec"

it "test git" do
  cmd = Process.find_executable("git")
  pending!("git is not available") unless cmd
  cmd.should end_with("git")
end