ceedling 0.9.0 → 1.0.1

data/plugins/fff/README.md

@@ -0,0 +1,242 @@
+# 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 can allow for more loosely-coupled tests.
+
+This Ceedling 1.x plugin wraps a snapshot of _FFF_, version 0.1.1.
+
+### Thanks
+
+A special thanks to [Matt Chernosky](http://www.electronvector.com) for developing this plugin originally. It's a well-loved piece of the Ceedling 
+ecosystem and we really appreciate his support through the years.
+
+### Enable the plug-in.
+
+The plug-in is enabled from within your project.yml file.
+
+In the `:plugins` configuration, add `fff` to the list of enabled plugins:
+
+```yaml
+:plugins:
+  :load_paths:
+    - vendor/ceedling/plugins
+  :enabled:
+    - report_tests_pretty_stdout
+    - module_generator
+    - fff
+```
+*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.
+
+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.

data/plugins/fff/Rakefile

@@ -0,0 +1,26 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-24 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'rake'
+require 'rspec/core/rake_task'
+
+desc "Run all rspecs"
+RSpec::Core::RakeTask.new(:spec) do |t|
+    t.pattern = Dir.glob('spec/**/*_spec.rb')
+    t.rspec_opts = '--format documentation'
+    # t.rspec_opts << ' more options'
+end
+
+desc "Run integration test on example"
+task :integration_test do
+    chdir("./examples/fff_example") do
+        sh "ceedling clobber"
+        sh "ceedling test:all"
+    end
+end
+
+task :default => [:spec, :integration_test]

data/plugins/fff/config/fff.yml

@@ -0,0 +1,13 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+---
+:paths:
+  :support:
+    - $PLUGIN_PATH/src 
+    - $PLUGIN_PATH/vendor/fff
+...

data/plugins/fff/examples/fff_example/project.yml

@@ -0,0 +1,145 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+---
+:project:
+  # how to use ceedling. If you're not sure, leave this as `gem` and `?`
+  :which_ceedling: ../../../..
+  :ceedling_version: '?'
+
+  # optional features. If you don't need them, keep them turned off for performance
+  :use_mocks: TRUE
+  :use_test_preprocessor: :all
+  :use_backtrace: :none
+
+  # tweak the way ceedling handles automatic tasks
+  :build_root: build
+  :test_file_prefix: test_
+  :default_tasks:
+    - test:all
+
+  # performance options. If your tools start giving mysterious errors, consider 
+  # dropping this to 1 to force single-tasking
+  :test_threads: 8
+  :compile_threads: 8
+
+  # enable release build (more details in release_build section below)
+  :release_build: FALSE
+
+# further details to configure the way Ceedling handles test code
+:test_build:
+  :use_assembly: FALSE
+
+# further details to configure the way Ceedling handles release code
+:release_build:
+  :output: MyApp.out
+  :use_assembly: FALSE
+  :artifacts: []
+
+# Plugins are optional Ceedling features which can be enabled. Ceedling supports
+# a variety of plugins which may effect the way things are compiled, reported, 
+# or may provide new command options. Refer to the readme in each plugin for 
+# details on how to use it.
+:plugins:
+  :load_paths: []
+  :enabled:
+    - module_generator
+    - fff
+    - report_tests_pretty_stdout
+
+# override the default extensions for your system and toolchain
+:extension:
+  #:header: .h
+  #:source: .c
+  #:assembly: .s
+  #:dependencies: .d
+  #:object: .o
+  :executable: .out
+  #:testpass: .pass
+  #:testfail: .fail
+  #:subprojects: .a
+
+# This is where Ceedling should look for your source and test files.
+# see documentation for the many options for specifying this.
+:paths:
+  :test:
+    - +:test/**
+  :source:
+    - src/**
+  :include:
+    - src/**
+  :libraries: []
+
+# You can even specify specific files to add or remove from your test
+# and release collections. Usually it's better to use paths and let
+# Ceedling do the work for you!
+:files:
+  :test: []
+  :source: []
+
+# Compilation symbols to be injected into builds
+# See documentation for advanced options:
+#  - Test name matchers for different symbols per test executable build
+#  - Referencing symbols in multiple lists using advanced YAML
+#  - Specifiying symbols used during test preprocessing
+:defines:
+  :test:
+    - TEST # Simple list option to add symbol 'TEST' to compilation of all files in all test executables
+  :release: []
+
+  # Enable to inject name of a test as a unique compilation symbol into its respective executable build. 
+  :use_test_definition: FALSE 
+
+# Configure additional command line flags provided to tools used in each build step
+# :flags:
+#   :release:
+#     :compile:         # Add '-Wall' and '--02' to compilation of all files in release target
+#       - -Wall
+#       - --O2
+#   :test:
+#     :compile:
+#       '(_|-)special': # Add '-pedantic' to compilation of all files in all test executables with '_special' or '-special' in their names
+#         - -pedantic
+#       '*':            # Add '-foo' to compilation of all files in all test executables
+#         - -foo
+
+# Configuration Options specific to CMock. See CMock docs for details
+:cmock:
+  :mock_prefix: mock_
+  :when_no_prototypes: :warn
+  :enforce_strict_ordering: TRUE
+  :plugins:
+    - :ignore
+    - :callback
+  :treat_as:
+    uint8:    HEX8
+    uint16:   HEX16
+    uint32:   UINT32
+    int8:     INT8
+    bool:     UINT8
+
+# Configuration options specific to Unity. 
+:unity:
+  :defines:
+    - UNITY_EXCLUDE_FLOAT
+
+# You can optionally have ceedling create environment variables for you before
+# performing the rest of its tasks.
+:environment: []
+
+# LIBRARIES
+# These libraries are automatically injected into the build process. Those specified as
+# common will be used in all types of builds. Otherwise, libraries can be injected in just
+# tests or releases. These options are MERGED with the options in supplemental yaml files.
+:libraries:
+  :placement: :end
+  :flag: "-l${1}"
+  :path_flag: "-L ${1}"
+  :system: []    # for example, you might list 'm' to grab the math library
+  :test: []
+  :release: []
+

data/plugins/fff/examples/fff_example/src/bar.c

@@ -0,0 +1,8 @@
+/* =========================================================================
+    Ceedling - Test-Centered Build System for C
+    ThrowTheSwitch.org
+    Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+    SPDX-License-Identifier: MIT
+========================================================================= */
+
+#include "bar.h"

data/plugins/fff/examples/fff_example/src/bar.h

@@ -0,0 +1,21 @@
+/* =========================================================================
+    Ceedling - Test-Centered Build System for C
+    ThrowTheSwitch.org
+    Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+    SPDX-License-Identifier: MIT
+========================================================================= */
+
+#ifndef bar_H
+#define bar_H
+
+#include "custom_types.h"
+
+void bar_turn_on(void);
+void bar_print_message(const char * message);
+void bar_print_message_formatted(const char * format, ...);
+void bar_numbers(int one, int two, char three);
+void bar_const_test(const char * a, char * const b, const int c);
+custom_t bar_needs_custom_type(void);
+const char * bar_return_const_ptr(int one);
+
+#endif // bar_H

data/plugins/fff/examples/fff_example/src/custom_types.h

@@ -0,0 +1,13 @@
+/* =========================================================================
+    Ceedling - Test-Centered Build System for C
+    ThrowTheSwitch.org
+    Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+    SPDX-License-Identifier: MIT
+========================================================================= */
+
+#ifndef custom_types_H
+#define custom_types_H
+
+typedef int custom_t;
+
+#endif

data/plugins/fff/examples/fff_example/src/display.c

@@ -0,0 +1,14 @@
+/* =========================================================================
+    Ceedling - Test-Centered Build System for C
+    ThrowTheSwitch.org
+    Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+    SPDX-License-Identifier: MIT
+========================================================================= */
+
+#include <stdio.h>
+#include "display.h"
+
+void display_turnOffStatusLed(void)
+{
+    printf("Display: Status LED off");
+}

data/plugins/fff/examples/fff_example/src/display.h

@@ -0,0 +1,23 @@
+/* =========================================================================
+    Ceedling - Test-Centered Build System for C
+    ThrowTheSwitch.org
+    Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+    SPDX-License-Identifier: MIT
+========================================================================= */
+
+#include <stdbool.h>
+
+void display_turnOffStatusLed(void);
+void display_turnOnStatusLed(void);
+void display_setVolume(int level);
+void display_setModeToMinimum(void);
+void display_setModeToMaximum(void);
+void display_setModeToAverage(void);
+bool display_isError(void);
+void display_powerDown(void);
+void display_updateData(int data, void(*updateCompleteCallback)(void));
+
+/*
+    The entry is returned (up to `length` bytes) in the provided `entry` buffer.
+*/
+void display_getKeyboardEntry(char * entry, int length);

data/plugins/fff/examples/fff_example/src/event_processor.c

@@ -0,0 +1,100 @@
+/* =========================================================================
+    Ceedling - Test-Centered Build System for C
+    ThrowTheSwitch.org
+    Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+    SPDX-License-Identifier: MIT
+========================================================================= */
+
+/*
+    This module implements some business logic to test.
+
+    Signal events by calling the functions on the module.
+*/
+
+#include <stdio.h>
+#include <string.h>
+#include "event_processor.h"
+#include "display.h"
+
+void event_deviceReset(void)
+{
+    //printf ("Device reset\n");
+    display_turnOffStatusLed();
+}
+
+void event_volumeKnobMaxed(void)
+{
+    display_setVolume(11);
+}
+
+void event_powerReadingUpdate(int powerReading)
+{
+    if (powerReading >= 5)
+    {
+        display_turnOnStatusLed();
+    }
+}
+
+void event_modeSelectButtonPressed(void)
+{
+    static int mode = 0;
+
+    if (mode == 0)
+    {
+        display_setModeToMinimum();
+        mode++;
+    }
+    else if (mode == 1)
+    {
+        display_setModeToMaximum();
+        mode++;
+    }
+    else if (mode == 2)
+    {
+        display_setModeToAverage();
+        mode++;
+    }
+    else
+    {
+        mode = 0;
+    }
+}
+
+void event_devicePoweredOn(void)
+{
+    if (display_isError())
+    {
+        display_powerDown();
+    }
+}
+
+void event_keyboardCheckTimerExpired(void)
+{
+    char userEntry[100];
+
+    display_getKeyboardEntry(userEntry, 100);
+
+    if (strcmp(userEntry, "sleep") == 0)
+    {
+        display_powerDown();
+    }
+}
+
+static bool event_lastComplete = false;
+
+/* Function called when the display update is complete. */
+static void displayUpdateComplete(void)
+{
+    event_lastComplete = true;
+}
+
+void event_newDataAvailable(int data)
+{
+    event_lastComplete = false;
+    display_updateData(data, displayUpdateComplete);
+}
+
+bool eventProcessor_isLastEventComplete(void)
+{
+    return event_lastComplete;
+}

data/plugins/fff/examples/fff_example/src/event_processor.h

@@ -0,0 +1,18 @@
+/* =========================================================================
+    Ceedling - Test-Centered Build System for C
+    ThrowTheSwitch.org
+    Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+    SPDX-License-Identifier: MIT
+========================================================================= */
+
+#include <stdbool.h>
+
+void event_deviceReset(void);
+void event_volumeKnobMaxed(void);
+void event_powerReadingUpdate(int powerReading);
+void event_modeSelectButtonPressed(void);
+void event_devicePoweredOn(void);
+void event_keyboardCheckTimerExpired(void);
+void event_newDataAvailable(int data);
+
+bool eventProcessor_isLastEventComplete(void);

data/plugins/fff/examples/fff_example/src/foo.c

@@ -0,0 +1,23 @@
+/* =========================================================================
+    Ceedling - Test-Centered Build System for C
+    ThrowTheSwitch.org
+    Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+    SPDX-License-Identifier: MIT
+========================================================================= */
+
+#include "foo.h"
+#include "bar.h"
+#include "subfolder/zzz.h"
+
+void foo_turn_on(void) {
+  bar_turn_on();
+  zzz_sleep(1, "sleepy");
+}
+
+void foo_print_message(const char * message) {
+  bar_print_message(message);
+}
+
+void foo_print_special_message(void) {
+  bar_print_message_formatted("The numbers are %d, %d and %d", 1, 2, 3);
+}

data/plugins/fff/examples/fff_example/src/foo.h

@@ -0,0 +1,15 @@
+/* =========================================================================
+    Ceedling - Test-Centered Build System for C
+    ThrowTheSwitch.org
+    Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+    SPDX-License-Identifier: MIT
+========================================================================= */
+
+#ifndef foo_H
+#define foo_H
+
+void foo_turn_on(void);
+void foo_print_message(const char * message);
+void foo_print_special_message(void);
+
+#endif // foo_H

data/plugins/fff/examples/fff_example/src/subfolder/zzz.c

@@ -0,0 +1,8 @@
+/* =========================================================================
+    Ceedling - Test-Centered Build System for C
+    ThrowTheSwitch.org
+    Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+    SPDX-License-Identifier: MIT
+========================================================================= */
+
+#include "zzz.h"

data/plugins/fff/examples/fff_example/src/subfolder/zzz.h

@@ -0,0 +1,13 @@
+/* =========================================================================
+    Ceedling - Test-Centered Build System for C
+    ThrowTheSwitch.org
+    Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+    SPDX-License-Identifier: MIT
+========================================================================= */
+
+#ifndef zzz_H
+#define zzz_H
+
+int zzz_sleep(int time, char * name);
+
+#endif // zzz_H