Update README with feature list and sample usage

This commit is contained in:
Michael Miller 2018-08-30 15:09:29 -06:00
parent a65aedbfb7
commit 755921fa6f

View file

@ -1,7 +1,10 @@
Spectator
=========
TODO: Write a description here
Fully-featured spec-based test framework for Crystal.
Provides more functionality from [RSpec](http://rspec.info/)
than the built-in Crystal [Spec](https://crystal-lang.org/api/latest/Spec.html) utility.
Spectator also provides additional features to make testing easier and more fluent.
Installation
------------
@ -17,16 +20,100 @@ dependencies:
Usage
-----
If it doesn't exist already, create a `spec/spec_helper.cr` file.
In it, place the following:
```crystal
require "spectator"
require "../src/*"
```
TODO: Write usage instructions here
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`.
Here's a minimal spec to demonstrate:
```crystal
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 it elegant.
We may come up with a better 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 creates syntax errors.
If you run into this, please create an issue so that we may help you find a solution.
Features
--------
TODO: Document the features and give brief usage examples.
Development
-----------
TODO: Write development instructions here
This shard is under heavy development and is not ready to be used for production.
### Feature Progress
[X] `describe` and `context` blocks
[ ] Contextual values with `let`, `let!`, `subject`, `described_class`
[ ] Test multiple and generated values - `given`
[ ] Before and after hooks - `before_each`, `before_all`, `after_each`, `after_all`, `around_each`
[ ] One-liner syntax
[ ] Equality matchers - `eq`, `be`, `be_a`, `match`
[ ] Truthy matchers - `be_true`, `be_false`, `be_truthy`, `be_falsey`
[ ] Comparison matchers - `<`, `<=`, `>`, `>=`, `be_within`
[ ] Question matchers - `be_nil`, `be_xxx`
[ ] Exception matchers - `raise_error`
[ ] Collection matchers - `start_with`, `end_with`, `contain`, `contain_exactly`
[ ] Change matchers - `change`, `from`, `to`, `by`, `by_at_least`, `by_at_most`
[ ] Satisfy matcher - `satisfy`
[ ] Yield matchers - `yield_control`, `times`, `yield_values`
[ ] Expectation combining with `&` and `|`
[ ] Pending tests - `pending`
[ ] Shared examples - `behaves_like`, `include_examples`
[ ] Fail fast
[ ] Test filtering
[ ] Fail on no tests
[ ] Randomize test order
[ ] Should syntax
### 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
------------