Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 37 ยท Shards and Web

Testing in Crystal with Spec

Learn testing in Crystal with the built-in Spec framework: describe, it, should and expect, hooks, pending tests, running crystal spec, and testing macros and fibers, with a Ruby mini-spec stand-in.

Crystal ships with a small, RSpec-inspired testing library called Spec. There is nothing to install: put files ending in _spec.cr in the spec/ folder, require spec, and run crystal spec. Tests are compiled like any other program, so type errors in a test fail at compile time and the whole suite runs quickly.

The compiler is not available on this site, so the Crystal listings are read-only. The Ruby stand-ins include a complete mini Spec with the same describe / it / expect shape, so you can see how such a framework works inside.

A first spec

Suppose src/calculator.cr holds:

CRYSTAL
class Calculator
  def add(a : Int32, b : Int32) : Int32
    a + b
  end

  def divide(a : Int32, b : Int32) : Float64
    raise ArgumentError.new("division by zero") if b == 0
    a / b
  end
end

Then spec/calculator_spec.cr:

CRYSTAL
require "./spec_helper"

describe Calculator do
  describe "#add" do
    it "adds two numbers" do
      Calculator.new.add(2, 3).should eq(5)
    end

    it "handles negatives" do
      Calculator.new.add(-2, 1).should eq(-1)
    end
  end

  describe "#divide" do
    it "returns a float" do
      Calculator.new.divide(7, 2).should eq(3.5)
    end

    it "refuses to divide by zero" do
      expect_raises(ArgumentError, "division by zero") do
        Calculator.new.divide(1, 0)
      end
    end
  end
end

with spec/spec_helper.cr:

CRYSTAL
require "spec"
require "../src/*"

Run it with crystal spec (or crystal spec spec/calculator_spec.cr:12 to run only the example at line 12). Each describe groups examples, each it is one test, and a test passes when it finishes without an exception.

Expectations

Spec offers two spellings. The should style reads left to right, and the expect style reads like a sentence. Use whichever your team prefers, but stay consistent:

CRYSTAL
value.should eq(5)              # equality
value.should_not eq(6)
value.should be_nil
value.should be_true
value.should be > 3             # comparison: be >, be <, be >=, be <=
value.should be_a(Int32)
value.should be_close(3.14, 0.01)
list.should contain(3)
list.should be_empty
text.should start_with("He")
text.should end_with("lo")
text.should match(/\d+/)

expect(value).to eq(5)          # same checks, expect style
expect_raises(KeyError) { ({} of String => Int32)["x"] }

eq uses ==. be uses identity (same?) for objects, which is why be_a and be > exist for the other cases. When an expectation fails, Spec prints the file, the line and both values:

TEXT
Failures:

  1) Calculator#add adds two numbers

       Expected: 6
            got: 5

     spec/calculator_spec.cr:6
Ruby Ruby stand-in: a tiny Spec framework

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Hooks and shared setup

Run code around each example with before_each and after_each, or around the whole group with before_all and after_all:

CRYSTAL
describe Stack do
  stack = Stack(Int32).new

  before_each do
    stack = Stack(Int32).new     # a fresh object for every example
    stack.push(1)
  end

  it "pops the last pushed value" do
    stack.push(2)
    stack.pop.should eq(2)
  end

  it "starts with one item" do
    stack.size.should eq(1)
  end
end

Plain variables inside describe are shared by the examples, so reset them in before_each to keep examples independent. Independence matters: Spec can run examples in random order with crystal spec --order random, which finds hidden dependencies between tests (the seed is printed so you can replay a failure).

Pending, focus and tags

CRYSTAL
pending "supports Unicode" do      # reported as pending, not run
end

it "is the one I am debugging", focus: true do
end                                 # with focus, crystal spec runs only these

it "is slow", tags: "slow" do
end                                 # crystal spec --tag slow / --tag ~slow

Testing different things

  • Pure functions are the easiest: pass values, compare results.
  • Exceptions: expect_raises(Type, "message part") { ... }.
  • Time: inject a clock or pass a Time value instead of calling Time.utc inside the method, so the test is deterministic.
  • Fibers and channels: use channels or WaitGroup to wait for results. Never use sleep to wait, because that slows the suite and fails on a slow machine. Time out with select + timeout (see select, Mutex and Parallelism).
  • HTTP: HTTP::Server::Context can be built with an IO::Memory for the response, so handlers run in a test without opening a socket.
  • Macros: test the behavior of the generated code, not the macro text.
CRYSTAL
it "writes a JSON body" do
  io = IO::Memory.new
  request = HTTP::Request.new("GET", "/health")
  response = HTTP::Server::Response.new(io)
  context = HTTP::Server::Context.new(request, response)

  Health.new.call(context)
  response.close

  io.to_s.should contain(%({"status":"ok"}))
end
Ruby Ruby stand-in: injecting a clock for a deterministic test

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Beyond Spec: tools

crystal tool format keeps style consistent, Ameba is the static analyzer (a shard, installed as a development dependency, see Shards and Dependencies), and crystal spec --warnings all shows deprecation warnings. Run all three in your continuous integration job.

flowchart LR
  A["crystal tool format --check"] --> B["ameba"]
  B --> C["crystal spec"]
  C --> D["shards build --release"]

A typical CI pipeline for a Crystal project.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file name does crystal spec pick up?

    Files ending in _spec.cr under spec/ are compiled together and run.
  2. 2. How do you check that a block raises an error?

    expect_raises fails if the block finishes without raising that exception type.
  3. 3. Why shouldn't tests wait on fibers with sleep?

    Synchronize with a channel or WaitGroup, with a timeout as a safety net.
  4. 4. What does crystal spec --order random help find?

    Random order exposes hidden dependencies; the printed seed replays a failing order.

Summary

  • Put *_spec.cr files in spec/, require spec, run crystal spec.
  • describe groups, it defines a test, should eq(...) or expect(...).to checks.
  • expect_raises, before_each, pending, focus and tags cover most needs.
  • Make code testable by injecting clocks, IO and channels.
  • Combine format, Ameba and spec in CI.

Next: Project: A To-Do Command-Line App