ceedling 0.28.3 → 0.29.0

data/plugins/colour_report/lib/colour_report.rb

@@ -0,0 +1,16 @@
+require 'ceedling/plugin'
+require 'ceedling/streaminator'
+require 'ceedling/constants'
+
+class ColourReport < Plugin
+
+  def setup
+    @ceedling[:stream_wrapper].stdout_override(&ColourReport.method(:colour_stdout))
+  end
+
+  def self.colour_stdout(string)
+    require 'colour_reporter.rb'
+    report string
+  end
+
+end

data/plugins/command_hooks/README.md

@@ -1,52 +1,53 @@
-ceedling-command-hooks
-======================
-
-Plugin for easily calling command line tools at various points in the build process
-
-Define any of these sections in :tools: to provide additional hooks to be called on demand:
-
-```
-    :pre_mock_generate
-    :post_mock_generate
-    :pre_runner_generate
-    :post_runner_generate
-    :pre_compile_execute
-    :post_compile_execute
-    :pre_link_execute
-    :post_link_execute
-    :pre_test_fixture_execute
-    :pre_test_fixture_execute
-    :pre_test
-    :post_test
-    :pre_release
-    :post_release
-    :pre_build
-    :post_build
-```
-
-Each of these tools can support an :executable string and an :args list, like so:
-
-```
-:tools:
-  :post_link_execute:
-    :executable: objcopy.exe
-    :args:
-      - ${1} #This is replaced with the executable name
-      - output.srec
-      - --strip-all
-```
-
-You may also specify an array of executables to be called in a particular place, like so:
-
-```
-:tools:
-  :post_test:
-    -  :executable: echo
-       :args: "${1} was glorious!"
-    -  :executable: echo
-       :args:
-         - it kinda made me cry a little.
-         - you?
-```
-
-Happy Tweaking!
+ceedling-command-hooks
+======================
+
+Plugin for easily calling command line tools at various points in the build process
+
+Define any of these sections in :tools: to provide additional hooks to be called on demand:
+
+```
+    :pre_mock_generate
+    :post_mock_generate
+    :pre_runner_generate
+    :post_runner_generate
+    :pre_compile_execute
+    :post_compile_execute
+    :pre_link_execute
+    :post_link_execute
+    :pre_test_fixture_execute
+    :pre_test
+    :post_test
+    :pre_release
+    :post_release
+    :pre_build
+    :post_build
+```
+
+Each of these tools can support an :executable string and an :arguments list, like so:
+
+```
+:tools:
+  :post_link_execute:
+    :executable: objcopy.exe
+    :arguments:
+      - ${1} #This is replaced with the executable name
+      - output.srec
+      - --strip-all
+```
+
+You may also specify an array of executables to be called in a particular place, like so:
+
+```
+:tools:
+  :post_test:
+    -  :executable: echo
+       :arguments: "${1} was glorious!"
+    -  :executable: echo
+       :arguments:
+         - it kinda made me cry a little.
+         - you?
+```
+
+Please note that it varies which arguments are being parsed down to the
+hooks. For now see `command_hooks.rb` to figure out which suits you best.
+Happy Tweaking!

data/plugins/command_hooks/lib/command_hooks.rb

@@ -1,75 +1,92 @@
-require 'ceedling/plugin'
-require 'ceedling/constants'
-
-class CommandHooks < Plugin
-
-  attr_reader :config
-
-  def setup
-    @config = {
-      :pre_mock_generate         => ((defined? TOOLS_PRE_MOCK_GENERATE)         ? TOOLS_PRE_MOCK_GENERATE         : nil ),
-      :post_mock_generate        => ((defined? TOOLS_POST_MOCK_GENERATE)        ? TOOLS_POST_MOCK_GENERATE        : nil ),
-      :pre_runner_generate       => ((defined? TOOLS_PRE_RUNNER_GENERATE)       ? TOOLS_PRE_RUNNER_GENERATE       : nil ),
-      :post_runner_generate      => ((defined? TOOLS_POST_RUNNER_GENERATE)      ? TOOLS_POST_RUNNER_GENERATE      : nil ),
-      :pre_compile_execute       => ((defined? TOOLS_PRE_COMPILE_EXECUTE)       ? TOOLS_PRE_COMPILE_EXECUTE       : nil ),
-      :post_compile_execute      => ((defined? TOOLS_POST_COMPILE_EXECUTE)      ? TOOLS_POST_COMPILE_EXECUTE      : nil ),
-      :pre_link_execute          => ((defined? TOOLS_PRE_LINK_EXECUTE)          ? TOOLS_PRE_LINK_EXECUTE          : nil ),
-      :post_link_execute         => ((defined? TOOLS_POST_LINK_EXECUTE)         ? TOOLS_POST_LINK_EXECUTE         : nil ),
-      :pre_test_fixture_execute  => ((defined? TOOLS_PRE_TEST_FIXTURE_EXECUTE)  ? TOOLS_PRE_TEST_FIXTURE_EXECUTE  : nil ),
-      :post_test_fixture_execute => ((defined? TOOLS_POST_TEST_FIXTURE_EXECUTE) ? TOOLS_POST_TEST_FIXTURE_EXECUTE : nil ),
-      :pre_test                  => ((defined? TOOLS_PRE_TEST)                  ? TOOLS_PRE_TEST                  : nil ),
-      :post_test                 => ((defined? TOOLS_POST_TEST)                 ? TOOLS_POST_TEST                 : nil ),
-      :pre_release               => ((defined? TOOLS_PRE_RELEASE)               ? TOOLS_PRE_RELEASE               : nil ),
-      :post_release              => ((defined? TOOLS_POST_RELEASE)              ? TOOLS_POST_RELEASE              : nil ),
-      :pre_build                 => ((defined? TOOLS_PRE_BUILD)                 ? TOOLS_PRE_BUILD                 : nil ),
-      :post_build                => ((defined? TOOLS_POST_BUILD)                ? TOOLS_POST_BUILD                : nil ),
-      :post_build                => ((defined? TOOLS_POST_BUILD)                ? TOOLS_POST_BUILD                : nil ),
-      :post_error                => ((defined? TOOLS_POST_ERROR)                ? TOOLS_POST_ERROR                : nil ),
-    }
-    @plugin_root = File.expand_path(File.join(File.dirname(__FILE__), '..'))
-  end
-
-  def pre_mock_generate(arg_hash);         run_hook(:pre_mock_generate,         arg_hash[:header_file] ); end
-  def post_mock_generate(arg_hash);        run_hook(:post_mock_generate,        arg_hash[:header_file] ); end
-  def pre_runner_generate(arg_hash);       run_hook(:pre_runner_generate,       arg_hash[:source     ] ); end
-  def post_runner_generate(arg_hash);      run_hook(:post_runner_generate,      arg_hash[:runner_file] ); end
-  def pre_compile_execute(arg_hash);       run_hook(:pre_compile_execute,       arg_hash[:source_file] ); end
-  def post_compile_execute(arg_hash);      run_hook(:post_compile_execute,      arg_hash[:object_file] ); end
-  def pre_link_execute(arg_hash);          run_hook(:pre_link_execute,          arg_hash[:executable]  ); end
-  def post_link_execute(arg_hash);         run_hook(:post_link_execute,         arg_hash[:executable]  ); end
-  def pre_test_fixture_execute(arg_hash);  run_hook(:pre_test_fixture_execute,  arg_hash[:executable]  ); end
-  def post_test_fixture_execute(arg_hash); run_hook(:post_test_fixture_execute, arg_hash[:executable]  ); end
-  def pre_test(test);                      run_hook(:pre_test,                  test                   ); end
-  def post_test(test);                     run_hook(:post_test,                 test                   ); end
-  def pre_release;                         run_hook(:pre_release                                       ); end
-  def post_release;                        run_hook(:post_release                                      ); end
-  def pre_build;                           run_hook(:pre_build                                         ); end
-  def post_build;                          run_hook(:post_build                                        ); end
-  def post_error;                          run_hook(:post_error                                        ); end
-
-  private
-
-  def run_hook_step(hook, name="")
-    if (hook[:executable])
-      args = ( (hook[:args].is_a? Array) ? hook[:args] : [] )
-      cmd = @ceedling[:tool_executor].build_command_line( hook, args, name )
-      shell_result = @ceedling[:tool_executor].exec( cmd[:line], cmd[:options] )
-    end
-  end
-
-  def run_hook(which_hook, name="")
-    if (@config[which_hook])
-      @ceedling[:streaminator].stdout_puts("Running Hook #{which_hook}...", Verbosity::NORMAL)
-      if (@config[which_hook].is_a? Array)
-        @config[which_hook].each do |hook|
-          run_hook_step(hook, name)
-        end
-      elsif (@config[which_hook].is_a? Hash)
-        run_hook_step( @config[which_hook], name )
-      else
-        @ceedling[:streaminator].stdout_puts("Hook #{which_hook} was poorly formed", Verbosity::COMPLAINT)
-      end
-    end
-  end
-end
-
+require 'ceedling/plugin'
+require 'ceedling/constants'
+class CommandHooks < Plugin
+
+  attr_reader :config
+
+  def setup
+    @config = {
+      :pre_mock_generate         => ((defined? TOOLS_PRE_MOCK_GENERATE)         ? TOOLS_PRE_MOCK_GENERATE         : nil ),
+      :post_mock_generate        => ((defined? TOOLS_POST_MOCK_GENERATE)        ? TOOLS_POST_MOCK_GENERATE        : nil ),
+      :pre_runner_generate       => ((defined? TOOLS_PRE_RUNNER_GENERATE)       ? TOOLS_PRE_RUNNER_GENERATE       : nil ),
+      :post_runner_generate      => ((defined? TOOLS_POST_RUNNER_GENERATE)      ? TOOLS_POST_RUNNER_GENERATE      : nil ),
+      :pre_compile_execute       => ((defined? TOOLS_PRE_COMPILE_EXECUTE)       ? TOOLS_PRE_COMPILE_EXECUTE       : nil ),
+      :post_compile_execute      => ((defined? TOOLS_POST_COMPILE_EXECUTE)      ? TOOLS_POST_COMPILE_EXECUTE      : nil ),
+      :pre_link_execute          => ((defined? TOOLS_PRE_LINK_EXECUTE)          ? TOOLS_PRE_LINK_EXECUTE          : nil ),
+      :post_link_execute         => ((defined? TOOLS_POST_LINK_EXECUTE)         ? TOOLS_POST_LINK_EXECUTE         : nil ),
+      :pre_test_fixture_execute  => ((defined? TOOLS_PRE_TEST_FIXTURE_EXECUTE)  ? TOOLS_PRE_TEST_FIXTURE_EXECUTE  : nil ),
+      :post_test_fixture_execute => ((defined? TOOLS_POST_TEST_FIXTURE_EXECUTE) ? TOOLS_POST_TEST_FIXTURE_EXECUTE : nil ),
+      :pre_test                  => ((defined? TOOLS_PRE_TEST)                  ? TOOLS_PRE_TEST                  : nil ),
+      :post_test                 => ((defined? TOOLS_POST_TEST)                 ? TOOLS_POST_TEST                 : nil ),
+      :pre_release               => ((defined? TOOLS_PRE_RELEASE)               ? TOOLS_PRE_RELEASE               : nil ),
+      :post_release              => ((defined? TOOLS_POST_RELEASE)              ? TOOLS_POST_RELEASE              : nil ),
+      :pre_build                 => ((defined? TOOLS_PRE_BUILD)                 ? TOOLS_PRE_BUILD                 : nil ),
+      :post_build                => ((defined? TOOLS_POST_BUILD)                ? TOOLS_POST_BUILD                : nil ),
+      :post_error                => ((defined? TOOLS_POST_ERROR)                ? TOOLS_POST_ERROR                : nil ),
+    }
+    @plugin_root = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+  end
+
+  def pre_mock_generate(arg_hash);         run_hook(:pre_mock_generate,         arg_hash[:header_file] ); end
+  def post_mock_generate(arg_hash);        run_hook(:post_mock_generate,        arg_hash[:header_file] ); end
+  def pre_runner_generate(arg_hash);       run_hook(:pre_runner_generate,       arg_hash[:source     ] ); end
+  def post_runner_generate(arg_hash);      run_hook(:post_runner_generate,      arg_hash[:runner_file] ); end
+  def pre_compile_execute(arg_hash);       run_hook(:pre_compile_execute,       arg_hash[:source_file] ); end
+  def post_compile_execute(arg_hash);      run_hook(:post_compile_execute,      arg_hash[:object_file] ); end
+  def pre_link_execute(arg_hash);          run_hook(:pre_link_execute,          arg_hash[:executable]  ); end
+  def post_link_execute(arg_hash);         run_hook(:post_link_execute,         arg_hash[:executable]  ); end
+  def pre_test_fixture_execute(arg_hash);  run_hook(:pre_test_fixture_execute,  arg_hash[:executable]  ); end
+  def post_test_fixture_execute(arg_hash); run_hook(:post_test_fixture_execute, arg_hash[:executable]  ); end
+  def pre_test(test);                      run_hook(:pre_test,                  test                   ); end
+  def post_test(test);                     run_hook(:post_test,                 test                   ); end
+  def pre_release;                         run_hook(:pre_release                                       ); end
+  def post_release;                        run_hook(:post_release                                      ); end
+  def pre_build;                           run_hook(:pre_build                                         ); end
+  def post_build;                          run_hook(:post_build                                        ); end
+  def post_error;                          run_hook(:post_error                                        ); end
+
+  private
+
+  ##
+  # Run a hook if its available.
+  #
+  # :args:
+  #   - hook: Name of the hook to run
+  #   - name: Name of file (default: "")
+  #
+  # :return:
+  #    shell_result.
+  #
+  def run_hook_step(hook, name="")
+    if (hook[:executable])
+      # Handle argument replacemant ({$1}), and get commandline
+      cmd = @ceedling[:tool_executor].build_command_line( hook, [], name )
+      shell_result = @ceedling[:tool_executor].exec(cmd[:line], cmd[:options])
+    end
+  end
+
+  ##
+  # Run a hook if its available.
+  #
+  # If __which_hook__ is an array, run each of them sequentially.
+  #
+  # :args:
+  #   - which_hook: Name of the hook to run
+  #   - name: Name of file
+  #
+  def run_hook(which_hook, name="")
+    if (@config[which_hook])
+      @ceedling[:streaminator].stdout_puts("Running Hook #{which_hook}...", Verbosity::NORMAL)
+      if (@config[which_hook].is_a? Array)
+        @config[which_hook].each do |hook|
+          run_hook_step(hook, name)
+        end
+      elsif (@config[which_hook].is_a? Hash)
+        run_hook_step( @config[which_hook], name )
+      else
+        @ceedling[:streaminator].stdout_puts("Hook #{which_hook} was poorly formed", Verbosity::COMPLAINT)
+      end
+    end
+  end
+end
+

data/plugins/fake_function_framework/README.md

@@ -1,250 +1,250 @@
-# A Fake Function Framework Plug-in for Ceedling
-
-This is a plug-in for [Ceedling](https://github.com/ThrowTheSwitch/Ceedling) to use the [Fake Function Framework](https://github.com/meekrosoft/fff) for mocking instead of CMock.
-
-Using fff provides less strict mocking than CMock, and allows for more loosely-coupled tests.
-And, when tests fail -- since you get the actual line number of the failure -- it's a lot easier to figure out what went wrong.
-
-## Installing the plug-in
-
-To use the plugin you need to 1) get the contents of this repo and 2) configure your project to use it.
-
-### Get the source
-
-The easiest way to get the source is to just clone this repo into the Ceedling plugin folder for your existing Ceedling project.
-(Don't have a Ceedling project already? [Here are instructions to create one.](http://www.electronvector.com/blog/try-embedded-test-driven-development-right-now-with-ceedling))
-From within `<your-project>/vendor/ceedling/plugins`, run:
-
-`git clone https://github.com/ElectronVector/fake_function_framework.git`
-
-This will create a new folder named `fake_function_framework` in the plugins folder.
-
-### Enable the plug-in.
-
-The plug-in is enabled from within your project.yml file.
-
-In the `:plugins` configuration, add `fake_function_framework` to the list of enabled plugins:
-
-```yaml
-:plugins:
-  :load_paths:
-    - vendor/ceedling/plugins
-  :enabled:
-    - stdout_pretty_tests_report
-    - module_generator
-    - fake_function_framework
-```
-*Note that you could put the plugin source in some other loaction.
-In that case you'd need to add a new path the `:load_paths`.*
-
-## How to use it
-
-You use fff with Ceedling the same way you used to use CMock.
-Modules can still be generated with the default module generator: `rake module:create[my_module]`.
-If you want to "mock" `some_module.h` in your tests, just `#include "mock_some_module.h"`.
-This creates a fake function for each of the functions defined in `some_module.h`.
-
-The name of each fake is the original function name with an appended `_fake`.
-For example, if we're generating fakes for a stack module with `push` and `pop` functions, we would have the fakes `push_fake` and `pop_fake`.
-These fakes are linked into our test executable so that any time our unit under test calls `push` or `pop` our fakes are called instead.
-
-Each of these fakes is actually a structure containing information about how the function was called, and what it might return.
-We can use Unity to inspect these fakes in our tests, and verify the interactions of our units.
-There is also a global structure named `fff` which we can use to check the sequence of calls.
-
-The fakes can also be configured to return particular values, so you can exercise the unit under test however you want.
-
-The examples below explain how to use fff to test a variety of module interactions.
-Each example uses fakes for a "display" module, created from a display.h file with `#include "mock_display.h"`. The `display.h` file must exist and must contain the prototypes for the functions to be faked.
-
-### Test that a function was called once
-
-```c
-void
-test_whenTheDeviceIsReset_thenTheStatusLedIsTurnedOff()
-{
-    // When
-    event_deviceReset();
-
-    // Then
-    TEST_ASSERT_EQUAL(1, display_turnOffStatusLed_fake.call_count);
-}
-```
-
-### Test that a function was NOT called
-
-```c
-void
-test_whenThePowerReadingIsLessThan5_thenTheStatusLedIsNotTurnedOn(void)
-{
-    // When
-    event_powerReadingUpdate(4);
-
-    // Then
-    TEST_ASSERT_EQUAL(0, display_turnOnStatusLed_fake.call_count);
-}
-```
-
-## Test that a single function was called with the correct argument
-
-```c
-void
-test_whenTheVolumeKnobIsMaxed_thenVolumeDisplayIsSetTo11(void)
-{
-    // When
-    event_volumeKnobMaxed();
-
-    // Then
-    TEST_ASSERT_EQUAL(1, display_setVolume_fake.call_count);
-    TEST_ASSERT_EQUAL(11, display_setVolume_fake.arg0_val);
-}
-```
-
-## Test that calls are made in a particular sequence
-
-```c
-void
-test_whenTheModeSelectButtonIsPressed_thenTheDisplayModeIsCycled(void)
-{
-    // When
-    event_modeSelectButtonPressed();
-    event_modeSelectButtonPressed();
-    event_modeSelectButtonPressed();
-
-    // Then
-    TEST_ASSERT_EQUAL_PTR((void*)display_setModeToMinimum, fff.call_history[0]);
-    TEST_ASSERT_EQUAL_PTR((void*)display_setModeToMaximum, fff.call_history[1]);
-    TEST_ASSERT_EQUAL_PTR((void*)display_setModeToAverage, fff.call_history[2]);
-}
-```
-
-## Fake a return value from a function
-
-```c
-void
-test_givenTheDisplayHasAnError_whenTheDeviceIsPoweredOn_thenTheDisplayIsPoweredDown(void)
-{
-    // Given
-    display_isError_fake.return_val = true;
-
-    // When
-    event_devicePoweredOn();
-
-    // Then
-    TEST_ASSERT_EQUAL(1, display_powerDown_fake.call_count);
-}
-```
-
-## Fake a function with a value returned by reference
-
-```c
-void
-test_givenTheUserHasTypedSleep_whenItIsTimeToCheckTheKeyboard_theDisplayIsPoweredDown(void)
-{
-    // Given
-    char mockedEntry[] = "sleep";
-    void return_mock_value(char * entry, int length)
-    {
-        if (length > strlen(mockedEntry))
-        {
-            strncpy(entry, mockedEntry, length);
-        }
-    }
-    display_getKeyboardEntry_fake.custom_fake = return_mock_value;
-
-    // When
-    event_keyboardCheckTimerExpired();
-
-    // Then
-    TEST_ASSERT_EQUAL(1, display_powerDown_fake.call_count);
-}
-```
-
-## Fake a function with a function pointer parameter
-
-```
-void
-test_givenNewDataIsAvailable_whenTheDisplayHasUpdated_thenTheEventIsComplete(void)
-{
-    // A mock function for capturing the callback handler function pointer.
-    void(*registeredCallback)(void) = 0;
-    void mock_display_updateData(int data, void(*callback)(void))
-    {
-        //Save the callback function.
-        registeredCallback = callback;
-    }
-    display_updateData_fake.custom_fake = mock_display_updateData;
-
-    // Given
-    event_newDataAvailable(10);
-
-    // When
-    if (registeredCallback != 0)
-    {
-        registeredCallback();
-    }
-
-    // Then
-    TEST_ASSERT_EQUAL(true, eventProcessor_isLastEventComplete());
-}
-```
-
-## Helper macros
-
-For convenience, there are also some helper macros that create new Unity-style asserts:
-
-- `TEST_ASSERT_CALLED(function)`: Asserts that a function was called once.
-- `TEST_ASSERT_NOT_CALLED(function)`: Asserts that a function was never called.
-- `TEST_ASSERT_CALLED_TIMES(times, function)`: Asserts that a function was called a particular number of times.
-- `TEST_ASSERT_CALLED_IN_ORDER(order, function)`: Asserts that a function was called in a particular order.
-
-Here's how you might use one of these instead of simply checking the call_count value:
-
-```c
-void
-test_whenTheDeviceIsReset_thenTheStatusLedIsTurnedOff()
-{
-    // When
-    event_deviceReset();
-
-    // Then
-    // This how to directly use fff...
-    TEST_ASSERT_EQUAL(1, display_turnOffStatusLed_fake.call_count);
-    // ...and this is how to use the helper macro.
-    TEST_ASSERT_CALLED(display_turnOffStatusLed);
-}
-```
-
-## Test setup
-
-All of the fake functions, and any fff global state are all reset automatically between each test.
-
-## CMock configuration
-
-Use still use some of the CMock configuration options for setting things like the mock prefix, and for including additional header files in the mock files.
-
-```yaml
-:cmock:
-    :mock_prefix: mock_
-        :includes:
-            -
-        :includes_h_pre_orig_header:
-            -
-        :includes_h_post_orig_header:
-            -
-        :includes_c_pre_header:
-            -
-        :includes_c_post_header:
-```
-
-## Running the tests
-
-There are unit and integration tests for the plug-in itself.
-These are run with the default `rake` task.
-The integration test runs the tests for the example project in examples/fff_example.
-For the integration tests to succeed, this repository must be placed in a Ceedling tree in the plugins folder.
-
-## More examples
-
-There is an example project in examples/fff_example.
-It shows how to use the plug-in with some full-size examples.
+# A Fake Function Framework Plug-in for Ceedling
+
+This is a plug-in for [Ceedling](https://github.com/ThrowTheSwitch/Ceedling) to use the [Fake Function Framework](https://github.com/meekrosoft/fff) for mocking instead of CMock.
+
+Using fff provides less strict mocking than CMock, and allows for more loosely-coupled tests.
+And, when tests fail -- since you get the actual line number of the failure -- it's a lot easier to figure out what went wrong.
+
+## Installing the plug-in
+
+To use the plugin you need to 1) get the contents of this repo and 2) configure your project to use it.
+
+### Get the source
+
+The easiest way to get the source is to just clone this repo into the Ceedling plugin folder for your existing Ceedling project.
+(Don't have a Ceedling project already? [Here are instructions to create one.](http://www.electronvector.com/blog/try-embedded-test-driven-development-right-now-with-ceedling))
+From within `<your-project>/vendor/ceedling/plugins`, run:
+
+`git clone https://github.com/ElectronVector/fake_function_framework.git`
+
+This will create a new folder named `fake_function_framework` in the plugins folder.
+
+### Enable the plug-in.
+
+The plug-in is enabled from within your project.yml file.
+
+In the `:plugins` configuration, add `fake_function_framework` to the list of enabled plugins:
+
+```yaml
+:plugins:
+  :load_paths:
+    - vendor/ceedling/plugins
+  :enabled:
+    - stdout_pretty_tests_report
+    - module_generator
+    - fake_function_framework
+```
+*Note that you could put the plugin source in some other loaction.
+In that case you'd need to add a new path the `:load_paths`.*
+
+## How to use it
+
+You use fff with Ceedling the same way you used to use CMock.
+Modules can still be generated with the default module generator: `rake module:create[my_module]`.
+If you want to "mock" `some_module.h` in your tests, just `#include "mock_some_module.h"`.
+This creates a fake function for each of the functions defined in `some_module.h`.
+
+The name of each fake is the original function name with an appended `_fake`.
+For example, if we're generating fakes for a stack module with `push` and `pop` functions, we would have the fakes `push_fake` and `pop_fake`.
+These fakes are linked into our test executable so that any time our unit under test calls `push` or `pop` our fakes are called instead.
+
+Each of these fakes is actually a structure containing information about how the function was called, and what it might return.
+We can use Unity to inspect these fakes in our tests, and verify the interactions of our units.
+There is also a global structure named `fff` which we can use to check the sequence of calls.
+
+The fakes can also be configured to return particular values, so you can exercise the unit under test however you want.
+
+The examples below explain how to use fff to test a variety of module interactions.
+Each example uses fakes for a "display" module, created from a display.h file with `#include "mock_display.h"`. The `display.h` file must exist and must contain the prototypes for the functions to be faked.
+
+### Test that a function was called once
+
+```c
+void
+test_whenTheDeviceIsReset_thenTheStatusLedIsTurnedOff()
+{
+    // When
+    event_deviceReset();
+
+    // Then
+    TEST_ASSERT_EQUAL(1, display_turnOffStatusLed_fake.call_count);
+}
+```
+
+### Test that a function was NOT called
+
+```c
+void
+test_whenThePowerReadingIsLessThan5_thenTheStatusLedIsNotTurnedOn(void)
+{
+    // When
+    event_powerReadingUpdate(4);
+
+    // Then
+    TEST_ASSERT_EQUAL(0, display_turnOnStatusLed_fake.call_count);
+}
+```
+
+## Test that a single function was called with the correct argument
+
+```c
+void
+test_whenTheVolumeKnobIsMaxed_thenVolumeDisplayIsSetTo11(void)
+{
+    // When
+    event_volumeKnobMaxed();
+
+    // Then
+    TEST_ASSERT_EQUAL(1, display_setVolume_fake.call_count);
+    TEST_ASSERT_EQUAL(11, display_setVolume_fake.arg0_val);
+}
+```
+
+## Test that calls are made in a particular sequence
+
+```c
+void
+test_whenTheModeSelectButtonIsPressed_thenTheDisplayModeIsCycled(void)
+{
+    // When
+    event_modeSelectButtonPressed();
+    event_modeSelectButtonPressed();
+    event_modeSelectButtonPressed();
+
+    // Then
+    TEST_ASSERT_EQUAL_PTR((void*)display_setModeToMinimum, fff.call_history[0]);
+    TEST_ASSERT_EQUAL_PTR((void*)display_setModeToMaximum, fff.call_history[1]);
+    TEST_ASSERT_EQUAL_PTR((void*)display_setModeToAverage, fff.call_history[2]);
+}
+```
+
+## Fake a return value from a function
+
+```c
+void
+test_givenTheDisplayHasAnError_whenTheDeviceIsPoweredOn_thenTheDisplayIsPoweredDown(void)
+{
+    // Given
+    display_isError_fake.return_val = true;
+
+    // When
+    event_devicePoweredOn();
+
+    // Then
+    TEST_ASSERT_EQUAL(1, display_powerDown_fake.call_count);
+}
+```
+
+## Fake a function with a value returned by reference
+
+```c
+void
+test_givenTheUserHasTypedSleep_whenItIsTimeToCheckTheKeyboard_theDisplayIsPoweredDown(void)
+{
+    // Given
+    char mockedEntry[] = "sleep";
+    void return_mock_value(char * entry, int length)
+    {
+        if (length > strlen(mockedEntry))
+        {
+            strncpy(entry, mockedEntry, length);
+        }
+    }
+    display_getKeyboardEntry_fake.custom_fake = return_mock_value;
+
+    // When
+    event_keyboardCheckTimerExpired();
+
+    // Then
+    TEST_ASSERT_EQUAL(1, display_powerDown_fake.call_count);
+}
+```
+
+## Fake a function with a function pointer parameter
+
+```
+void
+test_givenNewDataIsAvailable_whenTheDisplayHasUpdated_thenTheEventIsComplete(void)
+{
+    // A mock function for capturing the callback handler function pointer.
+    void(*registeredCallback)(void) = 0;
+    void mock_display_updateData(int data, void(*callback)(void))
+    {
+        //Save the callback function.
+        registeredCallback = callback;
+    }
+    display_updateData_fake.custom_fake = mock_display_updateData;
+
+    // Given
+    event_newDataAvailable(10);
+
+    // When
+    if (registeredCallback != 0)
+    {
+        registeredCallback();
+    }
+
+    // Then
+    TEST_ASSERT_EQUAL(true, eventProcessor_isLastEventComplete());
+}
+```
+
+## Helper macros
+
+For convenience, there are also some helper macros that create new Unity-style asserts:
+
+- `TEST_ASSERT_CALLED(function)`: Asserts that a function was called once.
+- `TEST_ASSERT_NOT_CALLED(function)`: Asserts that a function was never called.
+- `TEST_ASSERT_CALLED_TIMES(times, function)`: Asserts that a function was called a particular number of times.
+- `TEST_ASSERT_CALLED_IN_ORDER(order, function)`: Asserts that a function was called in a particular order.
+
+Here's how you might use one of these instead of simply checking the call_count value:
+
+```c
+void
+test_whenTheDeviceIsReset_thenTheStatusLedIsTurnedOff()
+{
+    // When
+    event_deviceReset();
+
+    // Then
+    // This how to directly use fff...
+    TEST_ASSERT_EQUAL(1, display_turnOffStatusLed_fake.call_count);
+    // ...and this is how to use the helper macro.
+    TEST_ASSERT_CALLED(display_turnOffStatusLed);
+}
+```
+
+## Test setup
+
+All of the fake functions, and any fff global state are all reset automatically between each test.
+
+## CMock configuration
+
+Use still use some of the CMock configuration options for setting things like the mock prefix, and for including additional header files in the mock files.
+
+```yaml
+:cmock:
+    :mock_prefix: mock_
+        :includes:
+            -
+        :includes_h_pre_orig_header:
+            -
+        :includes_h_post_orig_header:
+            -
+        :includes_c_pre_header:
+            -
+        :includes_c_post_header:
+```
+
+## Running the tests
+
+There are unit and integration tests for the plug-in itself.
+These are run with the default `rake` task.
+The integration test runs the tests for the example project in examples/fff_example.
+For the integration tests to succeed, this repository must be placed in a Ceedling tree in the plugins folder.
+
+## More examples
+
+There is an example project in examples/fff_example.
+It shows how to use the plug-in with some full-size examples.