diff --git a/doc/overview.edoc b/doc/overview.edoc new file mode 100644 index 0000000..7590ed9 --- /dev/null +++ b/doc/overview.edoc @@ -0,0 +1,153 @@ +@author Sven Heyll +@copyright 2011, 2012 Sven Heyll +@version 4 +@title ErlyMock - An EasyMock inspired mocking library. +@doc + +

ErlyMock was built to be helpful for Test Driven Development. I know this +goal is by no means yet reached, so I ask you kindly to support this +project. All suggestions, complaints and improvements are welcome.

+ +

+ErlyMock is the latest incarnation of an Erlang mocking library inspired by +Easymock for Java. It is used in unit tests to verify that a set of functions is +called by the code under test in correct order and with correct parameters. +

+

+With ErlyMock it is possible to declare the behavior of arbitrary +modules/functions with or without expecting acutal invocations. The user simply +declares what each function call to some function should return or do at the +beginning of a unit test. +

+

Some features:

+ + +

Usage example:

+ +

Assume there are two modules, used by the code to be tested, that shall be mocked (at least to prevent damaging side effects):

+ +A rocket launcher server: + +-module(rocket_launcher). + +launch(Longitude, Latitude, Type) -> + .... + +And A UI module: + +-module(rocket_launcher_ui). + +ask_for_instructions() -> + ... + +Then this is how a happy case unit test might look like: + +launche_missle_test() -> + % create a new mock process + M = em:new(), + + % define the expectations + em:strict(M, rocket_launcher_ui, ask_for_instructions, [], + {return, [{longitude, 123}, + {latitude, 999}, + {type, some_rocket_type}]}), + em:strict(M, missle_lauchner, launch, [123, 999, some_rocket_type]), + + % tell the mock that all expectations are defined + em:replay(M), + + % run code under test + rocket_app:interactive(), + + % verify expectations immediately + em:verify(M). + + +Another example shall show the usefulness of {@link em:await_expectations/1} +instead of {@link em:verify/1} to wait for asynchronouse invokations and {@link +em:zelf/1} as argument matcher matching the process id of the process calling +the mocked functions in the replay phase. + + + +%% Let's look at the impl first: +-module(xxx_impl). + + + +download_image(Url) -> + gen_server:cast(?MODULE, {download, URL}). + +%% ... + +handle_cast({download, URL}, State) -> + net_io:schedule_download(Url, self()), + {noreply, State}. + +%%%%%%%%%% Now this 'cast' happens asynchronously using 'em:verify/1' would not +%%%%%%%%%% help a lot, it would be pure luck if the erlang scheduler executed +%%%%%%%%%% that handle_cast before. This is the case where +%%%%%%%%%% em:await_expectations/1 comes in handy... + +%% Let's look at the test first: + +downld_img_test() -> + % create a new mock process + M = em:new(), + + Url = test_url, + + em:strict(M, net_io, schedule_download, + [Url, + %% em:zelf() will match 'self()' of the process under test! + em:zelf()]), + + em:replay(M), + + %% call code under test + xxx_impl:download_image(Url), + + %% await the cast to happen: + em:await_expectations(M). + + + +For more details please read the {@link em} module documentation. + + +

History

+ +

ErlyMock has undergone many stages and years of development and usage before +reaching this stage.

+ +

It was first published here: +http://sheyll.blogspot.com/2009/02/erlang-mock-erlymock.html Then Samual Rivas +cleaned it up and added support for restoring cover compiled modules for his +project, see http://www.lambdastream.com/.

+ +

The code was then added with all modifications to the great new +erlang-maven-plugin forge which can be found here: +http://sourceforge.net/projects/erlang-plugin/.

+ +

Then I decided to partially rewrite ErlyMock in order to provide a simpler +API and in order to improve the code quality. Also, I wanted to use the gen_fsm +OTP standard behavior.

+ +

Later loxybjorn on github added rebar support, now erlymock could automatically be added to rebar projects.

+ +

Several improvements were added by Olle Törnström, who helped fixing module purging issues.

+ +

Finally I decided to remove maven support, and to rely totally on rebar.

+ +Thanks to all who helped with erlymock. diff --git a/src/changes/changes.xml b/src/changes/changes.xml deleted file mode 100644 index ca76a1b..0000000 --- a/src/changes/changes.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - Release Notes - - - - - - diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm deleted file mode 100644 index b158aaf..0000000 --- a/src/site/apt/index.apt.vm +++ /dev/null @@ -1,150 +0,0 @@ - -${project.name} - - ${project.description} - - ErlyMock is the latest incarnation of an Erlang mocking library inspired by Easymock for Java. It is used in unit tests to verify that a set of functions is called by the code under test in correct order and with correct parameters. - - With ErlyMock it is possible to declare the behavior of arbitrary modules/functions with or without expecting acutal invocations. The user simply declares what each function call to some function should return or do at the beginning of a unit test. - -* Features - - * API documentation: {{http://erlymock-site.sourceforge.net/edoc/index.html}} - - * battle proven in at least three large projects at {{http://www.lindenbaum.eu}} - - * comprehensive runtime messages - - * two-letter module name(we went from 'mock' to 'em', which was quite an improvement for us) - - * small, flexible and easy to use API - - * allows strict expectations - - * allows stub behavior definitions to be intuitively mixed with strict expectations - - * correctly restores cover compiled module - - * automatic cleanup when mock or test process dies - - * implemented with OTP standard behaviour - - * because it is a maven project can be automatically installed as maven test dependency - Please refer to the excellent maven-erlang-plugin (excellent since Version 2.0.0-SNAPSHOT) - found here: {{http://erlang-plugin.sourceforge.net}}. - - [] - - - -* Usage Example - - Assume there are two modules, used by the code to be tested, that shall be mocked (at least to prevent damaging side effects): - - A rocket launcher server: - ------------------------------------------------------------- --module(rocket_launcher). - -launch(Longitude, Latitude, Type) -> - .... ------------------------------------------------------------- - - - And A UI module: - ------------------------------------------------------------- --module(rocket_launcher_ui). - -ask_for_instructions() -> - ... ------------------------------------------------------------- - - - Then this is how a happy case unit test might look like: - ------------------------------------------------------------- -launche_missle_test() -> - % create a new mock process - M = em:new(), - - % define the expectations - em:strict(M, rocket_launcher_ui, ask_for_instructions, [], - {return, [{longitude, 123}, - {latitude, 999}, - {type, some_rocket_type}]}), - em:strict(M, missle_lauchner, launch, [123, 999, some_rocket_type]), - - % tell the mock that all expectations are defined - em:replay(M), - - % run code under test - rocket_app:interactive(), - - % verify expectations - em:verify(M). ------------------------------------------------------------- - -* Installation und usage with Maven - - Assume there is a new Project, that needs some unit testing with mocks. This is simple when using maven. - - Assume there is already one source file called "borg.erl". - - 1. decide upon a short project name that would be a valid erlang atom without ' i.e. myproject - - 2. Create a directory by that name: mkdir myproject - - 3. Create a new maven project by writing a simple pom.xml which contains erlymock as dependency: - ------------------------------------------------------------- - - 4.0.0 - your.group.id - myproject - 1.0.0-SNAPSHOT - erlang-std - MyProject - Look ma' my project! - - - - eu.lindenbaum - maven-erlang-plugin - 2.0.0 - true - - - - - - com.github.sheyll - em - 3.0.0 - erlang-std - test - - - ------------------------------------------------------------- - - 4. all necessary directories by running: "mvn erlang:setup" - - 5. copy sources to myproject/src/ - - 6. copy unit tests into myproject/test_src/ - - - Now you can run 'mvn test' to run eunit. Erlymock will automatically be downloaded by maven. - - -* History of ErlyMock - - ErlyMock has undergone many stages and years of development and usage before reaching this stage. - It was first published here: {{http://sheyll.blogspot.com/2009/02/erlang-mock-erlymock.html}} - Then Samual Rivas cleaned it up and added support for restoring cover compiled modules for his project, - see {{http://www.lambdastream.com/}}. - The code was then added with all modifications to the great new erlang-maven-plugin forge which can be found here: {{http://sourceforge.net/projects/erlang-plugin/}}. - - Then I decided to partially rewrite ErlyMock in order to provide a simpler API and in order to improve the code quality. - Also, I wanted to use the gen_fsm OTP standard behavior. diff --git a/src/site/site.xml b/src/site/site.xml deleted file mode 100644 index 24576f8..0000000 --- a/src/site/site.xml +++ /dev/null @@ -1,16 +0,0 @@ - - - - - - - - - - - - - - - \ No newline at end of file