https://github.com/devstopfix/given-exunit
Feature testing micro-library for Elixir's ExUnit
https://github.com/devstopfix/given-exunit
Last synced: 11 months ago
JSON representation
Feature testing micro-library for Elixir's ExUnit
- Host: GitHub
- URL: https://github.com/devstopfix/given-exunit
- Owner: devstopfix
- License: mit
- Created: 2023-07-09T10:49:47.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2023-07-19T13:56:29.000Z (over 2 years ago)
- Last Synced: 2025-03-27T06:49:13.219Z (11 months ago)
- Language: Elixir
- Size: 86.9 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Given ExUnit
Given-When-Then is a style of representing tests of specifying a system's
behaviour using specification by example - [Martin Fowler][gwt].
This is a micro library that is a lite extension to ExUnit and prefers
pattern matching over regular expressions. There are other BDD libraries
but they do not seem to be maintained. The advantages of Given are:
1. no regular expressions
2. pattern match errors are clear and obvious
3. line numbers in errors are accurate as there are no separate text files
We use a parser to split clauses into words, strings, integers and dates then
call functions and rely on pattern matching to build up a test state. The input
is the standard context created with the `setup` and `setup_all` callbacks
and this context is passed from clause to clause with new data appended.
Here is a working example using the [peek at elixir-lang.org][ex]:
```elixir
defmodule Given.ReadmeTest do
use ExUnit.Case
use Given.Case
describe "elixir-lang.org" do
scenario "peek", ~s"""
Given the string "Elixir"
When graphemes
And frequencies
Then "i" occurs 2 times
And "E" occurs 1 time
"""
end
# Pre-conditions
def given_({:the_string, s}, _), do: [str: s]
# Actions
def when_({:graphemes}, %{str: s}), do: [gs: String.graphemes(s)]
def when_({:frequencies}, %{gs: gs}), do: [freq: Enum.frequencies(gs)]
# Post-conditions
def then_({l, :occurs, n, _}, %{freq: freq}), do: assert n == freq[l]
end
```
See the [Case module][case] for the syntax of the scenarios and
the [Parser module][parser] contains the terms that can be used.
[](https://github.com/devstopfix/given-exunit/actions/workflows/ci.yml)
## Installation
```elixir
def deps do
[
{:given, "~> 1.22", only: [:test, :dev]}
]
end
```
### Testing
When changing the grammar or the parser, run tests with:
PROPCHECK_NUMTESTS=20000 mix test
Run deliberately failing tests with:
mix test --only failing_test
[case]: https://hexdocs.pm/given_exunit/Given.Case.html
[parser]: https://hexdocs.pm/given_exunit/Given.Parser.html
[docs]: https://hexdocs.pm/given_exunit
[ex]: https://elixir-lang.org
[gwt]: https://martinfowler.com/bliki/GivenWhenThen.html