nuntius (nuntius v1.0.0)

The main interface for the system.

Summary

Functions

Removes a mocking process.

Removes an expect function.

Adds a new expect function to a mocked process.

Adds a new named expect function to a mocked process.

Returns the list of expect functions for a process.

Returns the history of messages received by a mocked process.

Returns the list of mocked processes.

Returns the PID of the currently mocked process.

Returns the PID of a mocked process (the original one with that name).

Injects a new mock process in front of the process with the provided name.

Passes the current message down to the mocked process.

Passes a message down to the mocked process.

Returns whether a particular message was received already.

Erases the history for a mocked process.

Stops the application.

Types

-type event() ::
          #{timestamp := integer(),
            message := message(),
            mocked := boolean(),
            with := term(),
            stack := term(),
            passed_through := boolean()}.
Link to this type

expect_fun/0

-type expect_fun() :: fun((_) -> _).
-type expect_id() :: reference() | expect_name().
Link to this type

expect_name/0

-type expect_name() :: atom().
-type message() :: term().
-type opts() :: #{passthrough => boolean(), history => boolean(), exit_on_nomatch => boolean()}.
Link to this type

process_name/0

-type process_name() :: atom().

Functions

Link to this function

delete(ProcessName)

-spec delete(process_name()) -> ok | {error, not_mocked}.

Removes a mocking process.

Link to this function

delete(ProcessName, ExpectId)

-spec delete(process_name(), expect_id()) -> ok | {error, not_mocked}.

Removes an expect function.


If the expect function was not already there, this function still returns 'ok'.


If the process is not mocked, an error is returned.

Link to this function

expect(ProcessName, Function)

-spec expect(process_name(), expect_fun()) -> reference() | {error, not_mocked}.

Adds a new expect function to a mocked process.


When a message is received by the process, this function will be run on it.


If the message doesn't match any clause, the process might exit, depending on option exit_on_nomatch.


If the process is not mocked, an error is returned.


When the function is successfully added, a reference is returned as an identifier.

Link to this function

expect(ProcessName, ExpectName, Function)

-spec expect(process_name(), expect_name(), expect_fun()) -> expect_name() | {error, not_mocked}.

Adds a new named expect function to a mocked process.


When a message is received by the process, this function will be run on it.


If the message doesn't match any clause, the process might exit, depending on option exit_on_nomatch.


If the process is not mocked, an error is returned.


If there was already an expect function with that name, it's replaced.


When the expect function is successfully added or replaced, it'll keep the name as its identifier.

Link to this function

expects(ProcessName)

-spec expects(process_name()) -> Expectations | {error, not_mocked}
                 when Expectations :: #{expect_id() => expect_fun()}.

Returns the list of expect functions for a process.

Link to this function

history(ProcessName)

-spec history(process_name()) -> [event()] | {error, not_mocked}.

Returns the history of messages received by a mocked process.

-spec mocked() -> [process_name()].

Returns the list of mocked processes.

Link to this function

mocked_process()

-spec mocked_process() -> pid().

Returns the PID of the currently mocked process.


Note: this code should only be used inside an expect fun.

Link to this function

mocked_process(ProcessName)

-spec mocked_process(process_name()) -> pid() | {error, not_mocked}.

Returns the PID of a mocked process (the original one with that name).

Link to this function

new(ProcessName)

-spec new(process_name()) -> ok | {error, not_found | already_mocked}.

Equivalent to new(ProcessName, #{}).

Injects a new mock process in front of the process with the provided name.


Returns an error if there is no process registered under that name.

Link to this function

new(ProcessName, Opts)

-spec new(process_name(), opts()) -> ok | {error, not_found | already_mocked}.

Injects a new mock process in front of the process with the provided name.



Options:


  • passthrough: if true, all messages are passed through to the process by default. If false, messages that are not handled by any expectation are just dropped.
    • default: true
  • history: if true, the mocking process will keep the history of messages received.
    • default: true
  • exit_on_nomatch: if true, the mocking process will exit with an exception if none of the expectations match the message. Otherwise it'll silently ignore it.
    • default: true
-spec passthrough() -> ok.

Passes the current message down to the mocked process.


Note: this code should only be used inside an expect fun.

Link to this function

passthrough(Message)

-spec passthrough(message()) -> ok.

Passes a message down to the mocked process.


Note: this code should only be used inside an expect fun.

Link to this function

received(ProcessName, Message)

-spec received(process_name(), message()) -> boolean() | {error, not_mocked}.

Returns whether a particular message was received already.


Note: it only works with history => true.

Link to this function

reset_history(ProcessName)

-spec reset_history(process_name()) -> ok | {error, not_mocked}.

Erases the history for a mocked process.

-spec start() -> {ok, [module()]}.

Equivalent to application:ensure_all_started(nuntius).

Starts the application.

-spec stop() -> ok.

Stops the application.