Harden and document Wire mocks

ianfixes · ianfixes · commit 6a16d2759e78 · 2020-12-28T10:36:43.000-05:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - `assertInfinity()` and `assertNotInfinity()` for comparing floats to infinity
 - `assertNAN()` and `assertNotNAN()` for comparing floats to `NaN`
 - `assertion()`, `ReporterTAP.onAssert()`, and `testBehaviorExp` macro to handle simple expression evaluation (is true, is false, etc)
+- `Wire.resetMocks()` and documentation
 
 ### Changed
 - Rubocop expected syntax downgraded from ruby 2.6 to 2.5
diff --git a/REFERENCE.md b/REFERENCE.md
@@ -656,3 +656,47 @@ unittest(eeprom)
   assertEqual(10, a);
 }
 ```
+
+
+### Wire
+
+This library allows communication with I2C / TWI devices.
+
+The interface the library has been fully mocked, with the addition of several functions for debugging
+
+* `Wire.resetMocks()`: Initializes all mocks, and for test repeatability should be called at the top of any unit tests that use Wire.
+* `Wire.didBegin()`: returns whether `Wire.begin()` was called at any point
+* `Wire.getMosi(address)`: returns a pointer to a `deque` that represents the history of data sent to `address`
+* `Wire.getMiso(address)`: returns a pointer to a `deque` that defines what the master will read from `address` (i.e. for you to supply)
+
+```c++
+unittest(wire_basics) {
+  // ensure known starting state
+  Wire.resetMocks();
+
+  // in case you need to check that your library is properly calling .begin()
+  assertFalse(Wire.didBegin());
+  Wire.begin();
+  assertTrue(Wire.didBegin());
+
+  // pick a random device. master write buffer should be empty
+  const uint8_t randomSlaveAddr = 14;
+  deque<uint8_t>* mosi = Wire.getMosi(randomSlaveAddr);
+  assertEqual(0, mosi->size());
+
+  // write some random data to random device
+  const uint8_t randomData[] = { 0x07, 0x0E };
+  Wire.beginTransmission(randomSlaveAddr);
+  Wire.write(randomData[0]);
+  Wire.write(randomData[1]);
+  Wire.endTransmission();
+
+  // check master write buffer values
+  assertEqual(2, mosi->size());
+  assertEqual(randomData[0], mosi->front());
+  mosi->pop_front();
+  assertEqual(randomData[1], mosi->front());
+  mosi->pop_front();
+  assertEqual(0, mosi->size());
+}
+```
diff --git a/SampleProjects/TestSomething/test/wire.cpp b/SampleProjects/TestSomething/test/wire.cpp
@@ -3,14 +3,27 @@
 #include <Wire.h>
 using std::deque;
 
+unittest(wire_init) {
+    Wire.resetMocks();
+    assertFalse(Wire.didBegin());
+    Wire.begin();
+    assertTrue(Wire.didBegin());
+    Wire.resetMocks();
+    assertFalse(Wire.didBegin());
+}
+
 unittest(begin_write_end) {
+    Wire.resetMocks();
+
+    const uint8_t randomSlaveAddr = 14;
+    const uint8_t randomData[] = { 0x07, 0x0E };
+
     // master write buffer should be empty
-    deque<uint8_t>* mosi = Wire.getMosi(14);
+    deque<uint8_t>* mosi = Wire.getMosi(randomSlaveAddr);
     assertEqual(0, mosi->size());
-    
+
     // write some random data to random slave
-    const uint8_t randomSlaveAddr = 14;
-    const uint8_t randomData[] = { 0x07, 0x0E };
+
     Wire.begin();
     Wire.beginTransmission(randomSlaveAddr);
     Wire.write(randomData[0]);
@@ -27,6 +40,8 @@ unittest(begin_write_end) {
 }
 
 unittest(readTwo_writeOne) {
+    Wire.resetMocks();
+
     Wire.begin();
     deque<uint8_t>* miso;
     // place some values on random slaves' read buffers
diff --git a/cpp/arduino/Wire.h b/cpp/arduino/Wire.h
@@ -54,19 +54,52 @@ struct wireData_t {
 class TwoWire : public ObservableDataStream {
 private:
   bool _didBegin = false;
-  wireData_t *in = nullptr;  // pointer to current slave for writing
-  wireData_t *out = nullptr; // pointer to current slave for reading
+  wireData_t* in = nullptr;  // pointer to current slave for writing
+  wireData_t* out = nullptr; // pointer to current slave for reading
   wireData_t slaves[SLAVE_COUNT];
 
 public:
-  // constructor initializes internal data
-  TwoWire() {
+
+  //////////////////////////////////////////////////////////////////////////////////////////////
+  // testing methods
+  //////////////////////////////////////////////////////////////////////////////////////////////
+
+  // initialize all the mocks
+  void resetMocks() {
+    _didBegin = false;
+    in = nullptr;  // pointer to current slave for writing
+    out = nullptr; // pointer to current slave for reading
     for (int i = 0; i < SLAVE_COUNT; ++i) {
       slaves[i].misoSize = 0;
       slaves[i].mosiSize = 0;
+      slaves[i].misoBuffer.clear();
+      slaves[i].mosiBuffer.clear();
     }
   }
 
+  // to verify that Wire.begin() was called at some point
+  bool didBegin() { return _didBegin; }
+
+  // to access the MISO buffer, which allows you to mock what the master will read in a request
+  deque<uint8_t>* getMiso(uint8_t address) {
+    return &slaves[address].misoBuffer;
+  }
+
+  // to access the MOSI buffer, which records what the master sends during a write
+  deque<uint8_t>* getMosi(uint8_t address) {
+    return &slaves[address].mosiBuffer;
+  }
+
+
+  //////////////////////////////////////////////////////////////////////////////////////////////
+  // mock implementation
+  //////////////////////////////////////////////////////////////////////////////////////////////
+
+  // constructor initializes internal data
+  TwoWire() {
+    resetMocks();
+  }
+
   // https://www.arduino.cc/en/Reference/WireBegin
   // Initiate the Wire library and join the I2C bus as a master or slave. This
   // should normally be called only once.
@@ -220,15 +253,6 @@ class TwoWire : public ObservableDataStream {
   // We don't (yet) support the slave role in the mock
   void onRequest(void (*callback)(void)) { assert(false); }
 
-  // testing methods
-  bool didBegin() { return _didBegin; }
-
-  deque<uint8_t> *getMiso(uint8_t address) {
-    return &slaves[address].misoBuffer;
-  }
-  deque<uint8_t> *getMosi(uint8_t address) {
-    return &slaves[address].mosiBuffer;
-  }
 };
 
 extern TwoWire Wire;
