feat: Isolate/test debug interface (#50)

* fix: Refactor mock Stream
* feat: Isolate/test NoteLog interface

Author: zfields

library.properties

@@ -1,5 +1,5 @@
 name=Blues Wireless Notecard
-version=1.3.5
+version=1.3.6
 author=Blues Wireless
 maintainer=Blues Wireless <[email protected]>
 sentence=An easy to use Notecard Library for Arduino.

src/NoteI2c.hpp

@@ -4,8 +4,6 @@
 #include <stddef.h>
 #include <stdint.h>
 
-#include "Notecard.h"
-
 class NoteI2c {
   public:
     /**************************************************************************/

src/NoteI2c_Arduino.hpp

@@ -3,6 +3,8 @@
 
 #include "NoteI2c.hpp"
 
+#include "Notecard.h"
+
 #ifndef MOCK
   #include <Wire.h>
 #else

src/NoteLog.hpp

@@ -0,0 +1,41 @@
+#ifndef NOTE_LOG_HPP
+#define NOTE_LOG_HPP
+
+#include <stddef.h>
+
+class NoteLog {
+public:
+    /**************************************************************************/
+    /*!
+        @brief  Type used to abstract specific hardware implementation types.
+    */
+    /**************************************************************************/
+    typedef void * channel_t;
+
+    virtual ~NoteLog(void) {}
+
+    /**************************************************************************/
+    /*!
+        @brief  Writes a message to the Notecard debug port.
+        @param    message
+                A null-terminated, message string.
+        @return The number of bytes transmitted.
+    */
+    /**************************************************************************/
+    virtual size_t print(const char * message) = 0;
+};
+
+/******************************************************************************/
+/*!
+    @brief  Helper function to abstract, create and maintain a single instance
+    of the NoteLog interface implementation, as required by the underlying
+    `note-c` library.
+    @param[in] log_channel  Pointer to the hardware specific serial stream
+    implementation.
+*/
+/******************************************************************************/
+NoteLog * make_note_log (
+    NoteLog::channel_t log_channel
+);
+
+#endif // NOTE_LOG_HPP

src/NoteLog_Arduino.cpp

@@ -0,0 +1,33 @@
+#include "NoteLog_Arduino.hpp"
+
+NoteLog *
+make_note_log (
+    NoteLog::channel_t log_channel_
+)
+{
+    static NoteLog * note_log = nullptr;
+    if (note_log) {
+        delete note_log;
+    }
+    note_log = new NoteLog_Arduino(reinterpret_cast<Stream *>(log_channel_));
+    return note_log;
+}
+
+NoteLog_Arduino::NoteLog_Arduino
+(
+    Stream * log_stream_
+) :
+    _notecardLog(log_stream_)
+{ }
+
+size_t
+NoteLog_Arduino::print (
+    const char * str_
+)
+{
+    size_t result;
+
+    result = _notecardLog->print(str_);
+
+    return result;
+}

src/NoteLog_Arduino.hpp

@@ -0,0 +1,22 @@
+#ifndef NOTE_LOG_ARDUINO_HPP
+#define NOTE_LOG_ARDUINO_HPP
+
+#include "NoteLog.hpp"
+
+#ifndef MOCK
+#include <Arduino.h>
+#else
+#include "mock/mock-arduino.hpp"
+#endif
+
+class NoteLog_Arduino final : public NoteLog
+{
+public:
+    NoteLog_Arduino(Stream * log_stream_);
+    size_t print(const char * message) override;
+
+private:
+    Stream * const _notecardLog;
+};
+
+#endif // NOTE_LOG_ARDUINO_HPP

src/Notecard.cpp

@@ -42,14 +42,28 @@
 #include <stdio.h>
 #include <stdlib.h>
 
+#include "NoteLog.hpp"
 #include "NoteI2c.hpp"
 #include "NoteSerial.hpp"
 
-Stream *Notecard::_debugSerial;
-bool Notecard::_debugSerialInitialized;
-
 namespace
 {
+    NoteLog *noteLog(nullptr);
+
+    size_t noteLogPrint(const char * str_)
+    {
+        size_t result;
+        if (noteLog)
+        {
+            result = noteLog->print(str_);
+        }
+        else
+        {
+            result = 0;
+        }
+        return result;
+    }
+
     NoteI2c *noteI2c(nullptr);
 
     const char *noteI2cReceive(uint16_t device_address_, uint8_t *buffer_, uint16_t size_, uint32_t *available_)
@@ -208,9 +222,8 @@ void Notecard::begin(HardwareSerial &selectedSerialPort, int selectedSpeed)
 /**************************************************************************/
 void Notecard::setDebugOutputStream(Stream &dbgserial)
 {
-    _debugSerial = &dbgserial;
-    _debugSerialInitialized = true;
-    NoteSetFnDebugOutput(Notecard::debugSerialOutput);
+    noteLog = make_note_log(&dbgserial);
+    NoteSetFnDebugOutput(noteLogPrint);
 }
 
 /**************************************************************************/
@@ -220,7 +233,6 @@ void Notecard::setDebugOutputStream(Stream &dbgserial)
 /**************************************************************************/
 void Notecard::clearDebugOutputStream()
 {
-    _debugSerialInitialized = false;
     NoteSetFnDebugOutput(nullptr);
 }
 
@@ -356,24 +368,3 @@ bool Notecard::responseError(J *rsp)
 {
     return NoteResponseError(rsp);
 }
-
-/***************************************************************************
- PRIVATE FUNCTIONS
- ***************************************************************************/
-
-/**************************************************************************/
-/*!
-    @brief  Writes a message to the debug Serial stream.
-    @param    message
-              The message to log.
-    @return The number of bytes written.
-*/
-/**************************************************************************/
-size_t Notecard::debugSerialOutput(const char *message)
-{
-    if (!_debugSerialInitialized)
-    {
-        return 0;
-    }
-    return (_debugSerial->print(message));
-}

src/Notecard.h

@@ -29,7 +29,6 @@
 
 #ifndef MOCK
 #include <Arduino.h>
-#include <HardwareSerial.h>
 #include <Wire.h>
 #include <note-c/note.h>
 #else
@@ -135,12 +134,6 @@ class Notecard
     void logDebugf(const char *format, ...);
     bool debugSyncStatus(int pollFrequencyMs, int maxLevel);
     bool responseError(J *rsp);
-
-private:
-    static Stream *_debugSerial;
-    static bool _debugSerialInitialized;
-
-    static size_t debugSerialOutput(const char *message);
 };
 
 #endif

test/NoteLog_Arduino.test.cpp

@@ -0,0 +1,77 @@
+#include "NoteLog_Arduino.hpp"
+#include "TestFunction.hpp"
+#include "mock/mock-arduino.hpp"
+#include "mock/mock-parameters.hpp"
+
+#include <string.h>
+
+// Compile command: g++ -Wall -Wextra -Wpedantic mock/mock-arduino.cpp ../src/NoteLog_Arduino.cpp NoteLog_Arduino.test.cpp -std=c++11 -I. -I../src -DMOCK && ./a.out || echo "Tests Result: $?"
+
+int test_notelog_arduino_print_does_not_modify_str_parameter_value_before_passing_to_stream_print()
+{
+    int result;
+
+    // Arrange
+    NoteLog_Arduino notelog(&Serial);
+    const char EXPECTED_RESULT[] = "Hello, Test!";
+
+    streamPrint_Parameters.reset();
+
+    // Action
+    notelog.print(EXPECTED_RESULT);
+
+    // Assert
+    if (!strcmp(EXPECTED_RESULT, streamPrint_Parameters.str_cache.c_str()))
+    {
+        result = 0;
+    }
+    else
+    {
+        result = static_cast<int>('d' + 'e' + 'b' + 'u' + 'g');
+        std::cout << "FAILED] " << __FILE__ << ":" << __LINE__ << std::endl;
+        std::cout << "\tstreamPrint_Parameters.str_cache.c_str() == \"" << streamPrint_Parameters.str_cache.c_str() << "\", EXPECTED: \"" << EXPECTED_RESULT << "\"" << std::endl;
+        std::cout << "[";
+    }
+
+    return result;
+}
+
+int test_notelog_arduino_print_does_not_modify_stream_print_result_value_before_returning_to_caller()
+{
+    int result;
+
+    // Arrange
+    NoteLog_Arduino notelog(&Serial);
+    const size_t EXPECTED_RESULT = 13;
+
+    streamPrint_Parameters.reset();
+    streamPrint_Parameters.result = EXPECTED_RESULT;
+
+    // Action
+    const size_t ACTUAL_RESULT = notelog.print("Hello, Test!");
+
+    // Assert
+    if (ACTUAL_RESULT == EXPECTED_RESULT)
+    {
+        result = 0;
+    }
+    else
+    {
+        result = static_cast<int>('d' + 'e' + 'b' + 'u' + 'g');
+        std::cout << "FAILED] " << __FILE__ << ":" << __LINE__ << std::endl;
+        std::cout << "\tnotelog.print(\"Hello, Test!\") == " << ACTUAL_RESULT << ", EXPECTED: " << EXPECTED_RESULT << std::endl;
+        std::cout << "[";
+    }
+
+    return result;
+}
+
+int main(void)
+{
+    TestFunction tests[] = {
+        {test_notelog_arduino_print_does_not_modify_str_parameter_value_before_passing_to_stream_print, "test_notelog_arduino_print_does_not_modify_buffer_parameter_value_before_passing_to_stream_print"},
+        {test_notelog_arduino_print_does_not_modify_stream_print_result_value_before_returning_to_caller, "test_notelog_arduino_print_does_not_modify_stream_print_result_value_before_returning_to_caller"},
+    };
+
+    return TestFunction::runTests(tests, (sizeof(tests) / sizeof(TestFunction)));
+}

test/Notecard.test.cpp

@@ -586,7 +586,7 @@ int test_notecard_setDebugOutputStream_shares_a_debug_log_functon_pointer()
   noteSetFnDebugOutput_Parameters.reset();
 
   // Action
-  notecard.setDebugOutputStream(dbgserial);
+  notecard.setDebugOutputStream(Serial);
 
   // Assert
   if (noteSetFnDebugOutput_Parameters.fn)

test/mock/mock-arduino.cpp

@@ -5,6 +5,7 @@ HardwareSerialBegin_Parameters hardwareSerialBegin_Parameters;
 HardwareSerialFlush_Parameters hardwareSerialFlush_Parameters;
 HardwareSerialRead_Parameters hardwareSerialRead_Parameters;
 HardwareSerialWrite_Parameters hardwareSerialWrite_Parameters;
+StreamPrint_Parameters streamPrint_Parameters;
 TwoWireBegin_Parameters twoWireBegin_Parameters;
 TwoWireBeginTransmission_Parameters twoWireBeginTransmission_Parameters;
 TwoWireEnd_Parameters twoWireEnd_Parameters;
@@ -17,7 +18,6 @@ TwoWireWriteBuffer_Parameters twoWireWriteBuffer_Parameters;
 // Global Arduino Objects (Singletons)
 HardwareSerial Serial;
 TwoWire Wire;
-Stream dbgserial;
 
 void
 delay (
@@ -91,11 +91,19 @@ HardwareSerial::write (
     return hardwareSerialWrite_Parameters.result;
 }
 
-long unsigned int
+size_t
 Stream::print (
-    const char *
+    const char * str
 ) {
-    return 0;
+    // Record invocation(s)
+    ++streamPrint_Parameters.invoked;
+
+    // Stash parameter(s)
+    streamPrint_Parameters.str = str;
+    streamPrint_Parameters.str_cache = str;
+
+    // Return user-supplied result
+    return streamPrint_Parameters.result;
 }
 
 void