Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Exemplor doesn't care about your unit tests. He demands usage examples.

Fetching latest commit…

Cannot retrieve the latest commit at this time

README
Exemplor (the exemplar)
=======================

An example-based test framework inspired by [testy](http://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
Something went wrong with that request. Please try again.