mirror of
https://gitea.invidious.io/iv-org/shard-spectator.git
synced 2024-08-15 00:53:35 +00:00
135 lines
4.2 KiB
Markdown
135 lines
4.2 KiB
Markdown
Spectator
|
|
=========
|
|
|
|
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
|
|
------------
|
|
|
|
Add this to your application's `shard.yml`:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```crystal
|
|
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`.
|
|
|
|
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
|
|
-----------
|
|
|
|
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
|
|
- [X] `describe` and `context` blocks
|
|
- [X] 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
|
|
- [ ] Should syntax
|
|
- [ ] Matchers
|
|
- [ ] 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`
|
|
- [ ] Runner
|
|
- [ ] Fail fast
|
|
- [ ] Test filtering
|
|
- [ ] Fail on no tests
|
|
- [ ] Randomize test order
|
|
- [ ] Expectation combining with `&` and `|`
|
|
- [ ] Pending tests - `pending`
|
|
- [ ] Shared examples - `behaves_like`, `include_examples`
|
|
|
|
### 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](https://gitlab.com/arctic-fox) Michael Miller - creator, maintainer
|