Exemplor (the exemplar)

An example-based test framework inspired by [testy](github.com/ahoward/testy).

Simpler that BDD/TDD, fancier than a file with a bunch of print statements.

Very tiny api. Here it is

eg.helpers do
  ... your helpers ...
end

eg.setup { ... setup codez ... }

eg "an example" do
  ... example code ...
end

eg "another example" do
  ... etc ...
end

The output is both human readable and machine parsable, which means you can test your tests.

Writing Examples

---

See ‘examples.rb` and `/examples` for more examples.

The simplest possible example:

eg 'An example block without any checks prints the value of the block' do
  "foo"
end

#=>

(i) An example block without any checks prints the value of the block: foo

The ‘i’ stands for ‘info’ which means the example ran without error.

Inspecting a few values, by default ‘Check` prints its argument and the value of the argument:

eg 'Accessing different parts of an array' do
  list = [1, 2, 3]
  Check(list.first)
  Check(list[1])
  Check(list.last)
end

#=>

(I) Accessing different parts of an array:
  (i) list.first: 1
  (i) list[1]: 2
  (i) list.last: 3

The capital ‘I’ means all checks were ‘info’ checks.

Calls to ‘Check` with the same argument can be disambiguated with `[]`:

eg 'Array appending' do
  list = [1, 42]
  Check(list.last)["before append"]
  list << 2
  Check(list.last)["after append"]
end

#=>

(I) Array appending:
  (i) list.last before append: 42
  (i) list.last after append: 2

Errors are caught and reported nicely:

eg 'Raising an error' do
  raise "boom!"
end

#=>

(e) Raising an error:
  class: RuntimeError
  message: boom!
  backtrace:
  - examples/an_error.rb:4
  # ... more backtrace lines

Once you’re happy with how your code is running you can make some assertions about its behaviour by adding ‘is()` calls after your `Check()` statements:

eg 'Asserting first is first' do
  list = [1, 2, 3]
  Check(list.first).is(1)
end

#=>

(s) Asserting first is first:
  (s) list.first: 1

‘s’ stands for ‘success’ and ‘f’ for failure:

eg 'Assertion failure' do
  list = [1, 2, 3]
  Check(list.first).is(2)
end

#=>

(f) Assertion failure:
  (f) list.first:
    expected: 2
    actual: 1

Running Examples

---

Running with ‘–list` or `-l` lists all examples:

$> ruby examples.rb -l
- errors are caught and nicely displayed
- check_output_matches_expected_for :no_checks
- check_output_matches_expected_for :oneliner
- check_output_matches_expected_for :no_checks_non_string
- check_output_matches_expected_for :with_checks
- check_output_matches_expected_for :check_with_disambiguation
- check_output_matches_expected_for :assertion_success
- check_output_matches_expected_for :assertion_failure
- check_output_matches_expected_for :assertion_success_and_failure
- check_output_matches_expected_for :helpers
- check_output_matches_expected_for :with_setup
- called with --list arg
- called with --l arg
- called with some other arg (always interpreted as a regex)

Otherwise the first argument is taken as a regex and only examples whose titles match are run:

$> ruby examples.rb called
(s) called with --list arg:
  (s) list:
  - Modified env
  - Unmodified env
(s) called with --l arg:
  (s) list:
  - Modified env
  - Unmodified env
(s) called with some other arg (always interpreted as a regex):
  (s) tests_run: 1