Teal

Stratus3D

Description

An Erlang assertion library. Writing unit tests for Erlang applications is usually pretty straightforward. After all, most of the time you are just testing functions. Testing functions is easy because you just invoke a function with some parameters and then check if the expected value was returned. With pattern matching this is trivial. However, not everything is so simple. Say for example, you want to test that a module implements a certain behavior. You could do something like this:

% Check if a module exports all the callbacks defined in a behavior
Exports = module_under_test:module_info(exports),
lists:foreach(fun(Callback) ->
        % Assert the callback is in the list of exported functions
        true = lists:member(Callback, Exports)
        end, [ % Callbacks defined in behaviour
            {callback_1, 1},
            {another_callback, 2},
            {a_third, 0}
        ]).

Or with Teal, it would be as simple as:

teal_behaviours:assert_implements_behaviour(module_under_test, expected_behavior).

Teal does all the hard work behind the scenes verifying that the module does in fact implement the behavior. And unlike the custom code in the first example, Teal's implements_behaviour function will work with any behavior.

I created Teal because I kept writing similar test helper functions in my unit tests. I tried to extract all the common patterns I saw in my test helpers into generic functions in Teal. This library by no means complete. I am sure there are common assertions that I missed. If you have anything that you think should be part of Teal feel free to create a pull request or issue on GitHub.

For Elixir, checkout Lilac, an Elixir wrapper for Teal.

Installation

To build Teal cd into the root and run make.

To make the Teal modules available during your tests. Added it to your ERL_LIBS environment variable(most likely defined in ~/.bashrc if you are using Bash):

export ERL_LIBS=/full/path/to/teal/

Or add it to your Erlang resource file (~/.erlang) like so:

code:load_abs("/full/path/to/teal/").

All the Teal modules should now be able in your tests.

Usage

Once you have the Teal installed you should be able to use any of the functions below in your Common Test or EUnit test suites. You could also use Teal directly in your application if you wanted. But most of the functions are only useful in unit tests. For example, using functions like teal:raises_exception in your application code would violate Erlang's "fail fast" principle in most cases.

API

The API is documented below. Most of the functions listed return a boolean. Of the functions that return booleans, there are two additional variations of each function that are not documented below. By prefixing one of these functions with assert_ (e.g. teal_lists:includes_members becomes teal_lists:assert_includes_members) an exception is raised if the assertion fails instead of returning false. This allows you to ignore the return value since failure causes an error to be raised. Functions prefixed with assert_ can also take an additional argument. The extra argument is the message in the error that is raised when the assertion fails. This allows you to generate more readable failure messages.

teal

not_equal/2 - Args: Term1 :: term(), Term2 :: term()
Verifies that first term does not match the second.
```
  teal:not_equal(a, b). %=> true
  teal:not_equal(a, a). %=> false
```
teal:raises_exception/1 Args: Fun :: fun()
Checks if an exception was raised when invoking Fun. You are probably better of being more specific. Check the other functions below.
```
  teal:raises_exception(fun() -> error(err) end). %=> true
  teal:raises_exception(fun() -> true end). %=> false
```

teal:raises_exception_with_message/2 Args: Fun :: fun(), ErrMsg :: term()

Checks if an exception with a message matching ErrMsg was raised when invoking Fun.

  ErrMsg = some_err_msg,
  teal:raises_exception_with_message(fun() -> error(ErrMsg) end, ErrMsg). %=> true
  teal:raises_exception_with_message(fun() -> error(another_err) end, ErrMsg). %=> false
  teal:raises_exception_with_message(fun() -> true end, ErrMsg). %=> false

teal:raises_throw/1 Args: Fun :: fun()

Checks if a throw exception was raised when invoking Fun.

  teal:raises_throw(fun() -> throw(err) end). %=> true
  teal:raises_throw(fun() -> true end). %=> false

teal:raises_throw_with_message/2 Args: Fun :: fun(), ErrMsg :: term()

Checks if a throw exception with a message matching ErrMsg was raised when invoking Fun.

  ErrMsg = some_err_msg,
  teal:raises_throw_with_message(fun() -> throw(ErrMsg) end, ErrMsg). %=> true
  teal:raises_throw_with_message(fun() -> throw(another_err) end, ErrMsg). %=> false
  teal:raises_throw_with_message(fun() -> true end, ErrMsg). %=> false

teal:raises_error/1 Args: Fun :: fun()

Checks if an error exception was raised when invoking Fun.

  teal:raises_error(fun() -> error(err) end). %=> true
  teal:raises_error(fun() -> true end). %=> false

teal:raises_error_with_message/2 Args: Fun :: fun(), ErrMsg :: term()

Checks if an error exception with a message matching ErrMsg was raised when invoking Fun.

  ErrMsg = some_err_msg,
  teal:raises_error_with_message(fun() -> error(ErrMsg) end, ErrMsg). %=> true
  teal:raises_error_with_message(fun() -> error(another_err) end, ErrMsg). %=> false
  teal:raises_error_with_message(fun() -> true end, ErrMsg). %=> false

teal:raises_exit/1 Args: Fun :: fun()

Checks if an exit was raised when invoking Fun.

  teal:raises_exit(fun() -> exit(err) end). %=> true
  teal:raises_exit(fun() -> true end). %=> false

teal:raises_exit_with_message/2 Args: Fun :: fun(), ErrMsg :: term()

Checks if an exit with a message matching ErrMsg was raised when invoking Fun.

  ErrMsg = some_err_msg,
  teal:raises_exit_with_message(fun() -> exit(ErrMsg) end, ErrMsg). %=> true
  teal:raises_exit_with_message(fun() -> exit(another_err) end, ErrMsg). %=> false
  teal:raises_exit_with_message(fun() -> true end, ErrMsg). %=> false

teal_lists

includes_members/2 - Args: List :: list(), Members :: list()
Checks if all members of the Members list are present in the List list. Examples:
```
  teal_lists:includes_members([1,2,3,4], [2,4]). %=> true
  teal_lists:includes_members([1,2,3,4], [5]). %=> false
```
teal_lists:same_members/2 - Args: List1 :: list(), List2 :: list()
Similar to includes_members/2. Checks if all members in List1 are present in List2 and no extra members are present in List2. The only thing this does different than the = comparison is ignore the ordering of the items in the lists.
```
  teal_lists:same_members([1,2,3,4], [4,2,3,1]). %=> true
  teal_lists:same_members([1,2,3,4], [2,4]). %=> false
```
order/2 - Args: List :: list(), OrderFun :: list()
Checks if all the members in List are already in the order specified by the OrderFun. List is sorted by OrderFun and then matched against List. If the two lists match the order is correct and the function returns true. Otherwise it returns false.
```
  Fun = fun(A,B) ->
          A =< B
  end,
  teal_lists:order([1,2,3,4], Fun). %=> true
  teal_lists:order([1,4,3,2], Fun). %=> false
```

teal_types

not_of_type/2 - Args: Term :: any(), Type :: atom()

Checks if Term is not of type Type

  teal_types:not_of_type(a, atom). %=> false
  teal_types:not_of_type(<<"test">>, binary). %=> false
  teal_types:not_of_type(a, binary). %=> true

not_record/1 - Args: Term :: any()
Checks if Term could be a record. If the term is a tuple with an atom as the first value Term is assumed to be a record and the function returns false. Otherwise it returns true.
```
  teal_types:not_record({foo, bar}). %=> false
  teal_types:not_record({[], a}). %=> true
  teal_types:not_record(not_a_record). %=> true
```
could_be_record/1 - Args: Term :: any()
Checks if Term could be a record. If the term is a tuple with an atom as the first value in Term tuple then the term could be a record and the function returns true. Otherwise it returns false. Opposite of teal_types:not_record/1.
```
  teal_types:could_be_record({foo, bar}). %=> true
  teal_types:could_be_record({[], a}). %=> false
  teal_types:could_be_record(not_a_record). %=> false
```

teal_modules

is_module/1 - Args: ModuleName :: atom()
Checks if ModuleName is the name of an Erlang module.
```
  teal_modules:is_module(erlang). %=> true
  teal_modules:is_module(abc). %=> false
```
exports/2 - Args: Module :: atom(), Function :: atom()
Check if Module exports a function with a name that matches Function.
```
  teal_modules:exports(erlang, port_call). %=> true
  teal_modules:exports(erlang, missing_fun). %=> false
```
exports_with_arity/3 - Args: Module :: atom(), Function :: atom(), Arity :: integer()
Check if Module exports a function with a name that matches Function and an arity of Arity.
```
  teal_modules:exports(erlang, port_call, 2). %=> true
  teal_modules:exports(erlang, port_call, 1). %=> false
```

teal_processes

is_registered/1 - Args: Process :: pid() | atom()

Checks Process is registered.

  teal_processes:is_registered(RegisteredPidOrAtom). %=> true
  teal_processes:is_registered(UnregisteredPidOrAtom). %=> false

is_registered_with_name/2 - Args: Process :: pid(), Name :: atom()

Checks if Process is registered with Name. Similar to teal_processes:is_registered/1.

  RegisteredPidOrAtom = <0.43.0>,
  UnregisteredName = <0.112.0>,
  register(RegisteredName, RegisteredPidOrAtom),
  teal_processes:is_registered_with_name(RegisteredPidOrAtom, RegisteredName). %=> true
  teal_processes:is_registered_with_name(UnregisteredPidOrAtom, UnregisteredName). %=> false

get_state/1 - Args: Process :: pid() | atom()
Returns the state of the Process. Process must be either a gen_server, gen_event, or gen_fsm process.
```
  teal_processes:get_state(RegisteredPidOrAtom). %=> returns RegisteredPidOrAtom processes' state.
```
receive_message/2 - Args: Message :: term(), Timeout :: integer()
Returns a pid, if the pid does not receive the given message before the timeout the pid raises an error.
```
  Msg = test,
  function_that_sends_msg_to_self(Msg),
  teal_processes:receive_message(Msg, 500), %=> true
  teal_processes:receive_message(Msg, 500), %=> false
```

teal_behaviours

has_callback/3 - Args: Module :: atom(), Name :: atom(), Arity :: integer()

Checks if Module has a function with Name and Arity.

  teal_behaviours:has_callback(gen_server, handle_call, 3). %=> true
  teal_behaviours:has_callback(erlang, callback, 1). %=> false

is_behaviour/1 - Args: Module :: atom()
Checks if a Module is also a behaviour. This is done by checking the module for callback attributes. If any are found Module is considered a behaviour.
```
  teal_behaviours:is_behaviour(gen_server). %=> true
  teal_behaviours:is_behaviour(erlang). %=> false
```
implements_behaviour/2 - Args: Module :: atom(), Behaviour :: atom()
Check if Module implements all the callbacks defined in Behaviour. If functions with the same name and arity exist for each callback in BehaviourModule is assumed to have implemented Behaviour correctly.
```
  teal_behaviours:implements_behaviour(supervisor, gen_server). %=> true
  teal_behaviours:implements_behaviour(erlang, gen_server). %=> false
```

teal_numbers

close_to/3 - Args: Received :: float(), Value :: float(), Delta :: float()
Checks if Received is within Delta of Value. If it is the function returns true. Otherwise it returns false.
```
  teal_numbers:close_to(7, 10, 5). %=> true
  teal_numbers:close_to(4, 10, 5). %=> false
```

TODO

Re-evaluate the 24 functions related to check for exceptions in teal.erl. Can the code be simplified? The code is not DRY at all right now.
Create a teal_time module to handle time and date and datetime assertions.
Use Teal to test Teal? Not sure if this is a good idea or not.
Create the following assertions:
- teal_os:command/1
- teal_os:command_status/2
- teal_os:command_output/2
- teal_otp:get_gen_server_state/1 Args: Process :: pid() | atom() Returns the custom state of the Process.

Similar Tools

https://github.com/hyperthunk/hamcrest-erlang

Known Issues

No known issues. If you see something that could be improved feel free to open an issue on GitHub (https://github.com/Stratus3D/teal/issues)

Contributing

Feel free to create an issue or pull request if you find a bug or if you have additional assertions that you would like to be included in this library.