Spectator

Spectator is a fully-featured spec-based test framework for Crystal. It provides more functionality from RSpec than the built-in Crystal Spec utility. Additionally, Spectator provides extra features to make testing easier and more fluent.

Goal:

Spectator is designed to:

• Reduce complexity of test code.
• Remove boilerplate from tests.
• Lower the difficulty of writing non-trivial tests.
• Provide an elegant syntax that is easy to read and understand.
• Provide common utilities that the end-user would otherwise need to write.

Installation

Add this to your application's shard.yml:

development_dependencies:
  spectator:
    gitlab: arctic-fox/spectator

Usage

If it doesn't exist already, create a spec/spec_helper.cr file. In it, place the following:

require "spectator"
require "../src/*"

This will include Spectator and the source code for your shard. Now you can start writing your specs. The syntax is the same as what you would expect from modern RSpec. The "expect" syntax is recommended and the default, however the "should" syntax is also available. Your specs must be wrapped in a Spectator.describe block. All other blocks inside the top-level block may use describe and context without the Spectator. prefix.

Here's a minimal spec to demonstrate:

require "./spec_helper"

Spectator.describe String do
  subject { "foo" }

  describe "#==" do
    context "with the same value" do
      let(value) { subject.dup }

      it "is true" do
        is_expected.to eq(value)
      end
    end

    context "with a different value" do
      let(value) { "bar" }

      it "is false" do
        is_expected.to_not eq(value)
      end
    end
  end
end

If you find yourself trying to shoehorn in functionality or unsure how to write a test, please create an issue for it. We want to make it as easy as possible to write specs and keep your code clean. We may come up with a solution or even introduce a feature to support your needs.

NOTE: Due to the way this shard uses macros, you may find that some code you would expect to work, or works in other spec libraries, creates syntax errors. If you run into this, please create an issue so that we may help you resolve it.

Features

TODO: Document the features and give brief usage examples.

Development

This shard is under heavy development and is not ready to be used for production.

Feature Progress

In no particular order, features that have been implemented and are planned:

• DSL
  • describe and context blocks
  • Contextual values with let, let!, subject, described_class
  • Test multiple and generated values - sample, random_sample
  • Concise syntax - given
  • Before and after hooks - before_each, before_all, after_each, after_all, around_each
  • Pre- and post-conditions - pre_condition, post_condition
  • Other hooks - on_success, on_failure, on_error
  • One-liner syntax
  • Should syntax - should, should_not
  • Helper methods and modules
  • Aliasing - custom example group types with preset attributes
  • Pending tests - pending
  • Shared examples - behaves_like, include_examples
• Matchers
  • Equality matchers - eq, ne, be ==, be !=
  • Comparison matchers - be <, be <=, be >, be >=, be_within[.of], be_close
  • Type matchers - be_a
  • Collection matchers - contain, have, contain_exactly[.in_order|.in_any_order], match_array[.in_order|.in_any_order], start_with, end_with, be_empty, have_key, have_value, all, all_satisfy
  • Truthy matchers - be, be_true, be_truthy, be_false, be_falsey, be_nil
  • Error matchers - raise_error
  • Yield matchers - yield_control[.times], yield_with_args[.times], yield_with_no_args[.times], yield_successive_args
  • Output matchers - output[.to_stdout|.to_stderr]
  • Misc. matchers - exist, match, satisfy, change[.by|.from[.to]|.to|.by_at_least|.by_at_most], have_attributes
  • Expectation combining - and, or
• Runner
  • Fail fast
  • Test filtering - by name, context, and tags
  • Fail on no tests
  • Randomize test order
  • Dry run - for validation and checking formatted output
  • Config block in spec_helper.cr
  • Config file - .rspec
• Reporter and formatting
  • RSpec/Crystal Spec default
  • JSON
  • JUnit

How it Works

This shard makes extensive use of the Crystal macro system to build classes and modules. Each describe and context block creates a new module nested in its parent. The it block creates a class derived from an Example class. An instance of the example class is created to run the test. Each example class includes a context module, which contains all test values and hooks.

Contributing

1. Fork it (https://gitlab.com/arctic-fox/spectator/fork/new)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Merge Request

Contributors

• arctic-fox Michael Miller - creator, maintainer