README.md.ecr

# 🔬 microtest [![Crystal CI](https://github.com/Ragmaanir/microtest/actions/workflows/crystal.yml/badge.svg)](https://github.com/Ragmaanir/microtest/actions/workflows/crystal.yml)

### Version <%= Microtest::VERSION %>

A small testing framework inspired by minitest/minitest.cr.

## Features

- This framework is opinionated
- It uses power asserts by default. There are no `assert_equals`, `assert_xyz`, just power asserts (except for `assert_raises`)
- It uses the spec syntax for test case structure (`describe`, `test`, `before`, `after`). Reasons: No test-case name-clashes when using describe. Not forgetting to call super in setup/teardown methods.
- No nesting of describe blocks. IMO nesting of those blocks is an anti-pattern.
- No let-definitions. Only before / after hooks. Use local variables mostly.
- Tests have to be started explicitly by `Microtest.run!`, no at-exit hook.
- Colorized and abbreviated exception stacktraces
- Randomized test order (SEED can be specified as environment variable)
- Focus individual tests (`test! "my test" do ...`)
- Different reportes (progress, descriptions, slow tests)

## Installation


Add this to your application's `shard.yml`:

```yaml
development_dependencies:
  microtest:
    github: ragmaanir/microtest
    version: ~> <%= Microtest::VERSION %>
```

And add this to your `spec_helper.rb`:

```crystal
require "microtest"

include Microtest::DSL

Microtest.run!
```


## Usage

```crystal
<%= File.read("spec/examples/waterpump.cr") %>
```

Run the test with:

`crystal spec`

You can provide the seed to run the tests in the same order:

`SEED=123 crystal spec`

## Power Assert Output

```crystal
<%= File.read("spec/examples/assertion_failure.cr") %>
```

Generates:

<%= image("assertion_failure") %>

### Microtest Test Output (microtest tests using progress reporter)

<%= image("spec") %>

## Reporters

Use common reporter combinations:

```crystal
# both versions include error-list-, slow-tests- and summary-reporters:
Microtest.run!(:progress)
Microtest.run!(:descriptions)
```

Or select the used reporters explicitly:

```crystal
Microtest.run!([
  Microtest::DescriptionReporter.new,
  Microtest::ErrorListReporter.new,
  Microtest::SlowTestsReporter.new,
  Microtest::SummaryReporter.new,
] of Microtest::Reporter)
```

```crystal
<%= File.read("spec/examples/multiple_tests.cr") %>
```

### Progress Reporter
<%= image("progress_reporter") %>

### Description Reporter
<%= image("description_reporter") %>

### When focus active

```crystal
<%= File.read("spec/examples/focus.cr") %>
```

<%= image("focus") %>

## Development

Run `./cli readme` to run tests and generate `README.md` from `README.md.ecr` and generate the images of the test outputs (using an alpine docker image).