Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/andrenth/ospec

BDD for OCaml
https://github.com/andrenth/ospec

Last synced: about 1 month ago
JSON representation

BDD for OCaml

Awesome Lists containing this project

README 

        
                               ospec

                               ~~~~~



1. INTRODUCTION

---------------



OSpec is a Behavior-Driven Development tool for OCaml, inspired by RSpec, a

Ruby BDD library. It is implemented as a Camlp4 syntax extension.



This is a work in progress and should be considered beta quality.



Note: OSpec requires OCaml >= 3.10.0 to run. On versions below 3.11.0, though,

there are two limitations due to OCaml toplevel bugs:



* If you want to use helpers in your specifications (see below), you must

  explicitely "open Helpers" at the top of every specification file.



* Running the "ospec" command with multiple files as arguments doesn't work.



2. USAGE

--------



To build and install OSpec, simply type



  $ ocaml setup.ml -configure

  $ ocaml setup.ml -build

  # ocaml setup.ml -install



These commands (and OSpec itself) rely on findlib, so you need to have it

installed for them to work. An executable called "ospec" which takes

specification files as command line arguments will be build. For example, the

command below will run the specifications in the file specs.ml:



  $ ospec specs.ml



The default report format is "nested". You can choose the format from the

command line using the "-format" option. Currently the available formats are

"nested" and "progress".



3. SYNTAX

---------



Specifications are defined with the "describe" keyword. Inside a specification,

examples are defined, with the "it" keyword, including one or more expectations.

Expectations are tests comparing some result to an expected value using the

"should" keyword.



Here's useless specification which shows how OSpec's syntax works:



  describe "The number one" do

    it "should equal 2 when added to itself" do

      (1 + 1) should = 2  (* anything 'a -> 'a -> bool should work *)

    done;



    it "should be positive" do

      let positive x = x > 0 in

      1 should be positive  (* 'a -> bool should work too *)

    done;



    it "should be negative when multiplied by -1" do

      let x = 1 * (-1) in

      x should be < 0;      (* "be" is optional *)

      x should not be >= 0

    done;



    it "should fail when divided by 0" do

      (* For exception tests, wrap it in a fun *)

      let f = fun () -> 1 / 0 in

      f should raise_an_exception;

      f should raise_exception Division_by_zero;

      f should not raise Exit

    done;



    it "should match ^[0-9]+$ when converted to a string" do

      (string_of_int 1) should match_regexp "^[0-9]+$"

    done;



    (* Specify behaviors still not implemented like this *)

    it "should be cool"

  done



It is also possible to group related examples in nested specifications. See

examples/nested.ml for a sample.



4. BEFORE AND AFTER BLOCKS

--------------------------



OSpec supports "before" and "after" blocks, which can be used to run code

before or after running the examples. This is only useful for operations

which cause side-effects on some global variable (see examples/hooks.ml).

Defining a variable in a "before" block doesn't make it available for the

examples, since the scope of such a variable would be the "before" block

itself.



  describe "An example" do

    before all do

      (* Code here runs once, before all examples. *)

    done;



    before each do

      (* Code here runs before each example. *)

    done;



    after each do

      (* Code here runs after each example. *)

    done;



    after all do

      (* Code here runs once, after all examples. *)

    done;



    it "should behave in a certain way" do

      (* ... *)

    done

  done



5. MATCH SYNTAX EXTENSION

-------------------------



OSpec also extends the "match" syntax so that you can write expectations like



  [1] should match h::t

  [1] should not match []



6. PROPERTY TESTING

-------------------



OSpec provides support for property testing with the "forall" function.

Combining forall with a sample generator (either one of the provided generators

or a custom one), it is possible to write specifications such as



  describe "A list" do

    it "should equal itself when reversed twice" do

      forall (list_of int) l . (List.rev (List.rev l)) should = l

    done

  done



In the example above, two generators are used: "list_of" and "int". The former

is a higher-order generator, since it takes another sample generator as a

parameter. This generator is used to sample values which the random list will

contain (in this case, int values). Each sample list will be bound to "l",

which can then be used in the property specified after the dot.



It is also possible to specify constraints to the generated samples, such as

in the (contrived) example below.



  describe "A bool" do

    it "should be true if all samples are true" do

      forall bool b . b = true -> b should = true

    done

  done



If the value of the boolean expression before the arrow is false for a given

sample, it is discarded and a new one is generated.



By default, 100 samples are generated for each property test. A different

number of samples may be specified explicitly as in the example below.



  forall 42 bool b . b = true -> b should = true



This will generate 42 bool instances instead of the default 100.



7. PREDEFINED GENERATORS

------------------------



Below is a list of sample generators defined by OSpec. They can be used as

building blocks for custom generators for more complex data types. A generator

is simply a function of type (unit -> 'a). By convention, higher-order

generators are named with an "_of" suffix.



val bool : unit -> bool

  Generates true or false with 50% probabilty each.



val float : unit -> float

  Generates a random float in the interval [0, 1).



val int : unit -> int

  Generates a random int between 0 (inclusive) and max_int (exclusive).



val int_in_range : int -> int -> unit -> int

  Generates a random int in the inclusive range given by the two int arguments.



val int32 : unit -> Int32.t

  Generates a random int32 between 0 (inclusive) and Int32.max_int (exclusive).



val int32_in_range : int32 -> int32 -> unit -> int32

  Generates a random int32 in the inclusive range given by the two int32

  arguments.



val int64 : unit -> Int64.t

  Generates a random int64 between 0 (inclusive) and Int64.max_int (exclusive).



val int64_in_range : int64 -> int64 -> unit -> int64

  Generates a random int64 in the inclusive range given by the two int64

  arguments.



val nativeint : unit -> Nativeint.t

  Generates a random nativeint between 0 (inclusive) and Nativeint.max_int

  (exclusive).



val nativeint_in_range : nativeint -> nativeint -> unit -> nativeint

  Generates a random nativeint in the inclusive range given by the two nativeint

  arguments.



val char : unit -> char

  Generates a random character.



val char_in_range : char -> char -> unit -> char

  Generates a random character in the inclusive range given by the two char

  arguments.



val ascii : unit -> char

  Generates a random ASCII character.



val digit : unit -> char

  Generates a random digit character.



val lowercase : unit -> char

  Generates a random lowercase character [a-z].



val uppercase : unit -> char

  Generates a random uppercase character [A-Z].



val alphanumeric : unit -> char

  Generates a random alphanumeric character.



val string_of : ?length:(unit -> int) -> (unit -> char) -> unit -> string

  Given one of the character generators, returns a random string of length

  given by the "length" int generator.



val string : ?length:(unit -> int) -> unit -> string

  Generates a random string of ASCII characters. It is equivalent to

  "string_of ascii".



val list_of : ?length:(unit -> int) -> (unit -> 'a) -> unit -> 'a list

  Given a generator for the list elements, returns a random list of length

  given by the "length" int generator.



val list : ?length:(unit -> int) -> unit -> unit list

  Generates a random-sized list of unit elements.



val array_of : ?length:(unit -> int) -> (unit -> 'a) -> unit -> 'a array

  Given a generator for the array elements, returns a random array of length

  given by the "length" int generator.



val array : ?length:(unit -> int) -> unit -> unit array

  Generates a random-sized array of unit elements.



val queue_of : ?length:(unit -> int) -> (unit -> 'a) -> unit -> 'a Queue.t

  Given a generator for the queue elements, returns a random queue of length

  given by the "length" int generator.



val queue : ?length:(unit -> int) -> unit -> unit queue

  Generates a random-sized queue of unit elements.



val stack_of : ?length:(unit -> int) -> (unit -> 'a) -> unit -> 'a Stack.t

  Given a generator for the stack elements, returns a random stack of length

  given by the "length" int generator.



val stack : ?length:(unit -> int) -> unit -> unit stack

  Generates a random-sized stack of unit elements.



val hashtbl_of : ?length:(unit -> int) -> (unit -> 'a) * (unit -> 'b) -> unit ->

                 ('a, 'b) Hashtbl.t

  Given a tuple of generators for the hash table keys and values, returns a

  random hash table of length given by the "length" int generator.



8. HELPERS

----------



Some helper functions are provided, as shown above. They are described below.



val raise_an_exception : (unit -> 'a) -> bool

  Returns true if any exception is raised



val raise_exception : (unit -> 'a) -> exn -> bool

  Returns true if the given exception is raised



val match_regexp : string -> string -> bool

  Returns true if the given string (first argument) matches the given regex

  (second argument).



9. TODO

-------



* Provide more report formats.

* Provide more helpers.

* Cleanup the code, which is horrible and hacky.

* ...