arduino_ci 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6dab88af65d6e71fd9cd3e2f389340b184fb1fbb063ccb7a6743f893c47f690d
-  data.tar.gz: 267b58186eea10a1f52ff4c16838270437a7d52d8fd0a3681f84e770845efa0d
+  metadata.gz: 95cc7dc7ab0591e45ffe7c1a9cdf31f64b21a8cf794a12ea83a4190af20e7488
+  data.tar.gz: 6e20b49ad3b015445c79511e9795fddbf205f01e20eb8c413e7ff342f4b240f9
 SHA512:
-  metadata.gz: 8765d7d3c01fb5a4f9737604ee9ee33a020629e3e5d404403069ac346caad36f69a94893ca2db49cdc14bb50a1d5557d29cccd9b58022fb3d1a00cd9de348323
-  data.tar.gz: e537d36bd505b31630aae9e7359a71f82dbb07977bac93dbc4194d6da4112ca005e22b2e9051970d0d67afd4e5dcdabcd9a6dddda1ee399c0a7cfc01aecb631c
+  metadata.gz: f40e840a35f788a4e02e0e332b5e7669198214419d9361abf10cc03558028bc691bb16379143b95c258dd2527fb8b03924d3cfb240c3af6b2fac526966b30274
+  data.tar.gz: bf8dc24b59f479ad858b75450a546ebd5e7bee694e33c8b443d2fa89576fe40fb09dede3c17353b7ca6c9c7dcda921aa7bb3f156c3beb98fd62cc99123c03119

data/README.md

@@ -1,17 +1,24 @@
 
 # ArduinoCI Ruby gem (`arduino_ci`)
 [![Gem Version](https://badge.fury.io/rb/arduino_ci.svg)](https://rubygems.org/gems/arduino_ci)
-[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://www.rubydoc.info/gems/arduino_ci/1.1.0)
+[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://www.rubydoc.info/gems/arduino_ci/1.2.0)
 [![Gitter](https://badges.gitter.im/Arduino-CI/arduino_ci.svg)](https://gitter.im/Arduino-CI/arduino_ci?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
+[![GitHub Marketplace](https://img.shields.io/badge/Get_it-on_Marketplace-informational.svg)](https://github.com/marketplace/actions/arduino_ci)
 
-You want to run tests on your Arduino library (bonus: without hardware present), but the IDE doesn't support that.  Arduino CI provides that ability.
+Arduino CI was created to enable better collaboration among Arduino library maintainers and contributors, by enabling automated code checks to be performed as part of a pull request process.
 
-You want to precisely replicate certain software states in your library, but you don't have sub-millisecond reflexes for physically faking the inputs, outputs, and serial port.   Arduino CI fakes 100% of the physical input and output of an Arduino board, including the clock.
+* enables running unit tests against the library **without hardware present**
+* provides a system of mocks that allow fine-grained control over the hardare inputs, including the system's clock
+* verifies compilation of any example sketches included in the library
+* can test a wide range of arduino boards with different hardware options available
+* compares entries in `library.properties` to the contents of the library and reports mismatches
+* can be run both locally and as part of CI (GitHub Actions, TravisCI, Appveyor, etc.)
+* runs on multiple platforms -- any platform that supports the Arduino IDE
+* provides detailed analysis of segfaults in compilers that support such debugging features
 
-You want your Arduino library to be automatically built and tested every time someone contributes code to your project on GitHub, but the Arduino IDE lacks the ability to run unit tests. [Arduino CI](https://github.com/Arduino-CI/arduino_ci) provides that ability.
-
-`arduino_ci` is a cross-platform build/test system, consisting of a Ruby gem and a series of C++ mocks.  It enables tests to be run both locally and as part of a CI service like GitHub Actions, TravisCI, Appveyor, etc.  Any OS that can run the Arduino IDE can run `arduino_ci`.
+> Note: for running tests in response to [GitHub events](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/github-event-types), an [Arduino CI GitHub Action](https://github.com/marketplace/actions/arduino_ci) is available for your convenience.  This method of running `arduino_ci` is driven by Docker, which may also serve your local testing needs (as it does not require a ruby environment to be installed).
 
+Arduino CI works on multiple platforms, which should enable your CI system of choice to leverage it for testing.
 
 Platform | CI Status
 ---------|:---------
@@ -20,30 +27,22 @@ Linux    | [![Linux Build Status](https://github.com/Arduino-CI/arduino_ci/workf
 Windows  | [![Windows Build status](https://github.com/Arduino-CI/arduino_ci/workflows/windows/badge.svg)](https://github.com/Arduino-CI/arduino_ci/actions?workflow=windows)
 
 
-## Comparison to Other Arduino Testing Tools
+## Quick Start
 
-| Project                                                                     | CI | Builds Examples | Unittest | Arduino Mocks | Windows | OSX | Linux | License |
-|-----------------------------------------------------------------------------|:--:|:---------------:|:--------:|:-------------:|:-------:|:---:|:-----:|:--------|
-|[ArduinoCI](https://github.com/Arduino-CI/arduino_ci)                          | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |Free (Apache-2.0)|
-|[ArduinoUnit](https://github.com/mmurdoch/arduinounit)                       | ❌ | ❌ | ⚠️ Hardware-based|❌ | ✅ | ✅ | ✅ |Free (MIT)|
-|[Adafruit `ci-arduino`](https://github.com/adafruit/ci-arduino)| ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |Free (MIT)|
-|[PlatformIO](https://platformio.org)                                         | ✅ | ✅ | ⚠️ Paid only | ❌ | ✅ | ✅ | ✅ |⚠️ EULA|
-|Official [Arduino IDE](https://www.arduino.cc/en/main/software)              | ❌ | ⚠️ Manually | ❌ |N/A 😉| ✅ | ✅ | ✅ |Free (GPLv2)|
+### You Need Your Arduino Library
 
+For a fairly minimal practical example of a unit-testable library repo that you can copy from, see [the `Arduino-CI/Blink` repository](https://github.com/Arduino-CI/Blink).
 
-## Quick Start
+> Note: The `SampleProjects` directory you see within _this_ repo contains tests for validing the `arduino_ci` framework itself, and due to that coupling will not be helpful to duplicate.  That said, the [SampleProjects/TestSomething](SampleProjects/TestSomething) project contains [test files](SampleProjects/TestSomething/test/) (each named after the type of feature being tested) that may be illustrative of testing strategy and capabilities _on an individual basis_.
 
-For a bare-bones example that you can copy from, see [SampleProjects/DoSomething](SampleProjects/DoSomething).
+Arduino expects all libraries to be in a specific `Arduino/libraries` directory on your system.  If your library is elsewhere, `arduino_ci` will _automatically_ create a symbolic link in the `libraries` directory that points to the directory of the project being tested.  This simplifieds working with project dependencies, but **it can have unintended consequences on Windows systems**.
 
-The complete set of C++ unit tests for the `arduino_ci` library itself are in the [SampleProjects/TestSomething](SampleProjects/TestSomething) project.  The [test files](SampleProjects/TestSomething/test/) are named after the type of feature being tested.
+> If you use a Windows system **it is recommended that you only run `arduino_ci` from project directories that are already inside the `libraries` directory** because [in some cases deleting a folder that contains a symbolic link to another folder can cause the _entire linked folder_ to be removed instead of just the link itself](https://superuser.com/a/306618).
 
-> Arduino expects all libraries to be in a specific `Arduino/libraries` directory on your system.  If your library is elsewhere, `arduino_ci` will _automatically_ create a symbolic link in the `libraries` directory that points to the directory of the project being tested.  This simplifieds working with project dependencies, but **it can have unintended consequences on Windows systems** because [in some cases deleting a folder that contains a symbolic link to another folder can cause the _entire linked folder_ to be removed instead of just the link itself](https://superuser.com/a/306618).
->
-> If you use a Windows system **it is recommended that you only run `arduino_ci` from project directories that are already inside the `libraries` directory**
 
 ### You Need Ruby and Bundler
 
-You'll need Ruby version 2.2 or higher, and to `gem install bundler` if it's not already there.
+You'll need Ruby version 2.5 or higher, and to `gem install bundler` if it's not already there.
 
 
 ### You Need A Compiler (`g++`)
@@ -52,7 +51,14 @@ For unit testing, you will need a compiler; [g++](https://gcc.gnu.org/) is prefe
 
 * **Linux**: `gcc`/`g++` is likely pre-installed.
 * **OSX**: `g++` is an alias for `clang`, which is provided by Xcode and the developer tools.  You are free to `brew install gcc` as well; this is also tested and working.
-* **Windows**: you will need Cygwin, and the `mingw-gcc-g++` package.  A full set of (working) install instructions can be found in `appveyor.yml`, as this is how CI runs for this project.
+* **Windows**: you will need Cygwin, and the `mingw-gcc-g++` package.
+
+
+### You _May_ Need `python`
+
+ESP32 and ESP8266 boards have [a dependency on `python` that they don't install themselves](https://github.com/Arduino-CI/arduino_ci/issues/235#issuecomment-739629243).  If you intend to test on these platforms (which are included in the default list of platforms to test against), you will need to make `python` (and possibly `pyserial`) available in the test environment.
+
+Alternately, you might configure `arduino_ci` to simply not test against these.  Consult the reference for those details.
 
 
 ### Changes to Your Repo
@@ -61,9 +67,11 @@ Add a file called `Gemfile` (no extension) to your Arduino project:
 
 ```ruby
 source 'https://rubygems.org'
-gem 'arduino_ci'
+gem 'arduino_ci' '~> 1.1'
 ```
 
+At the time of this writing, `1.1` is the latest version available, and the `~>` syntax will allow your system to update it to the latest `1.x.x` version.  The list of all available versions can be found on [rubygems.org](https://rubygems.org/gems/arduino_ci) if you prefer to explicitly pin a higher version.
+
 It would also make sense to add the following to your `.gitignore`, or copy [the `.gitignore` used by this project](.gitignore):
 
 ```
@@ -184,7 +192,7 @@ test_script:
 
 ## Known Problems
 
-* The Arduino library is not fully mocked.
+* The Arduino library is not fully mocked, nor is `avr-libc`.
 * I don't have preprocessor defines for all the Arduino board flavors
 * https://github.com/Arduino-CI/arduino_ci/issues
 

data/REFERENCE.md

@@ -29,6 +29,11 @@ This completely skips the compilation tests (of library examples) portion of the
 This completely skips the compilation tests (of library examples) portion of the CI script.  It does not skip the compilation of unit tests.
 
 
+### `--skip-library-properties` option
+
+This completely skips validation of entries in `library.properties`.
+
+
 ### `--testfile-select` option
 
 This allows a file (or glob) pattern to be executed in your tests directory, creating a whitelist of files to test.  E.g. `--testfile-select=test_animal_*.cpp` would match `test_animal_cat.cpp` and `test_animal_dog.cpp` (testing only those) and not `test_plant_rose.cpp`.
@@ -39,6 +44,16 @@ This allows a file (or glob) pattern to be executed in your tests directory, cre
 This allows a file (or glob) pattern to be executed in your tests directory, creating a blacklist of files to skip.  E.g. `--testfile-reject=test_animal_*.cpp` would match `test_animal_cat.cpp` and `test_animal_dog.cpp` (skipping those) and test only `test_plant_rose.cpp`, `test_plant_daisy.cpp`, etc.
 
 
+### `CUSTOM_INIT_SCRIPT` environment variable
+
+If set, testing will execute (using `/bin/sh`) the script referred to by this variable -- relative to the current working directory.  This enables use cases like the GitHub action to install custom library versions (i.e. a version of a library that is different than what the library manager would automatically install by name) prior to CI test runs.
+
+
+### `USE_SUBDIR` environment variable
+
+If set, testing will be conducted in this subdirectory (relative to the working directory).  This is for monorepos or other layouts where the library directory and project root directory are different.
+
+
 ### `EXPECT_UNITTESTS` environment variable
 
 If set, testing will fail if no unit test files are detected (or if the directory does not exist).  This is to avoid communicating a passing status in cases where a commit may have accidentally moved or deleted the test files.
@@ -49,6 +64,11 @@ If set, testing will fail if no unit test files are detected (or if the director
 If set, testing will fail if no example sketches are detected.  This is to avoid communicating a passing status in cases where a commit may have accidentally moved or deleted the examples.
 
 
+### `SKIP_LIBRARY_PROPERTIES` environment variable
+
+If set, testing will skip validating `library.properties` entries.  This is to work around any possible bugs in `arduino_ci`'s interpretation of what is "correct".
+
+
 ## Indirectly Overriding Build Behavior (medium term use), and Advanced Options
 
 For build behavior that you'd like to persist across commits (e.g. defining the set of platforms to test against, disabling a test that you expect to re-enable at some future point), a special configuration file called `.arduino-ci.yml` can be used.  There are 3 places you can put them:
@@ -74,6 +94,8 @@ packages:
 
 To define a platform called `bogo` that uses a board called `potato:salad:bogo` (based on the `potato:salad` family), set it up in the `plaforms:` section.  Note that this will override any default configuration of `bogo` if it had existed in `arduino_ci`'s `misc/default.yml` file.  If this board defines particular features in the compiler, you can set those here.
 
+> Note that the platform names are arbitrary -- just keys in this yaml file and in the [`default.yml`](https://github.com/Arduino-CI/arduino_ci/blob/master/misc/default.yml) file included in this gem.  That said, they are also case sensitive; defining the `bogo` platform will not let you refer to it as `Bogo` nor `BOGO`.
+
 ```yaml
 platforms:
   # our custom definition of the "bogo" platform
@@ -107,7 +129,9 @@ platforms:
 ### Control How Examples Are Compiled
 
 Put a file `.arduino-ci.yml` in each example directory where you require a different configuration than default.
-The `compile:` section controls the platforms on which the compilation will be attempted, as well as any external libraries that must be installed and included.
+The `compile:` section controls the platforms on which the compilation will be attempted, as well as any external libraries that must be installed and included.  This works by _overriding_ portions of the default configuration.
+
+> Note that the platform names _must_ match (case-sensitive) the platform names in the underlying [`default.yml`](https://github.com/Arduino-CI/arduino_ci/blob/master/misc/default.yml), or else match platforms that you have defined yourself in your `.arduino-ci.yml` override.
 
 ```yaml
 compile:
@@ -198,15 +222,27 @@ This test defines one `unittest` (a macro provided by `ArduinoUnitTests.h`), cal
 
 The following assertion functions are available in unit tests.
 
-* `assertEqual(expected, actual)`
-* `assertNotEqual(expected, actual)`
-* `assertLess(expected, actual)`
-* `assertMore(expected, actual)`
-* `assertLessOrEqual(expected, actual)`
-* `assertMoreOrEqual(expected, actual)`
-* `assertTrue(actual)`
-* `assertFalse(actual)`
-* `assertNull(actual)`
+```c++
+assertEqual(expected, actual);               // a == b
+assertNotEqual(unwanted, actual);            // a != b
+assertComparativeEquivalent(expected, actual);    // abs(a - b) == 0 or (!(a > b) && !(a < b))
+assertComparativeNotEquivalent(unwanted, actual); // abs(a - b) > 0  or ((a > b) || (a < b))
+assertLess(upperBound, actual);              // a < b
+assertMore(lowerBound, actual);              // a > b
+assertLessOrEqual(upperBound, actual);       // a <= b
+assertMoreOrEqual(lowerBound, actual);       // a >= b
+assertTrue(actual);
+assertFalse(actual);
+assertNull(actual);
+
+// special cases for floats
+assertEqualFloat(expected, actual, epsilon);    // fabs(a - b) <= epsilon
+assertNotEqualFloat(unwanted, actual, epsilon); // fabs(a - b) >= epsilon
+assertInfinity(actual);                         // isinf(a)
+assertNotInfinity(actual);                      // !isinf(a)
+assertNAN(arg);                                 // isnan(a)
+assertNotNAN(arg);                              // !isnan(a)
+```
 
 These functions will report the result of the test to the console, and the testing will continue if they fail.
 
@@ -327,7 +363,7 @@ unittest(pin_history)
   // we expect 6 values in that queue (5 that we set plus one
   // initial value), which we'll hard-code here for convenience.
   // (we'll actually assert those 6 values in the next block)
-  assertEqual(6, state->digitalPin[1].queueSize));
+  assertEqual(6, state->digitalPin[1].queueSize());
   bool expected[6] = {LOW, HIGH, LOW, LOW, HIGH, HIGH};
   bool actual[6];
 
@@ -634,3 +670,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());
+}
+```

data/cpp/arduino/Arduino.h

@@ -36,9 +36,6 @@ typedef uint8_t byte;
 #define highByte(w) ((uint8_t) ((w) >> 8))
 #define lowByte(w) ((uint8_t) ((w) & 0xff))
 
-// Arduino defines this
-#define _NOP() do { 0; } while (0)
-
 // might as well use that NO-op macro for these, while unit testing
 // you need interrupts? interrupt yourself
 #define yield() _NOP()
@@ -70,5 +67,3 @@ inline unsigned int makeWord(unsigned int w) { return w; }
 inline unsigned int makeWord(unsigned char h, unsigned char l) { return (h << 8) | l; }
 
 #define word(...) makeWord(__VA_ARGS__)
-
-

data/cpp/arduino/ArduinoDefines.h

@@ -92,3 +92,6 @@
 #if defined(__AVR_ATmega328P__) || defined(__AVR_ATmega32U4__) || defined(__AVR_ATmega328__) || defined(__AVR_ATmega168__) || defined(__AVR_ATmega1280__) || defined(__AVR_ATmega2560__)
   #define LED_BUILTIN 13
 #endif
+
+// Arduino defines this
+#define _NOP() do { 0; } while (0)

data/cpp/arduino/Godmode.h

@@ -160,21 +160,78 @@ class GodmodeState {
 };
 
 // io pins
-#define pinMode(...) _NOP()
-#define analogReference(...) _NOP()
+inline void pinMode(uint8_t pin, uint8_t mode) { _NOP(); }
+inline void analogReference(uint8_t mode) { _NOP(); }
 
 void digitalWrite(uint8_t, uint8_t);
 int digitalRead(uint8_t);
 int analogRead(uint8_t);
 void analogWrite(uint8_t, int);
-#define analogReadResolution(...) _NOP()
-#define analogWriteResolution(...) _NOP()
+inline void analogReadResolution(uint8_t bits) { _NOP(); }
+inline void analogWriteResolution(uint8_t bits) { _NOP(); }
 void attachInterrupt(uint8_t interrupt, void ISR(void), uint8_t mode);
 void detachInterrupt(uint8_t interrupt);
 
 // TODO: issue #26 to track the commanded state here
-inline void tone(uint8_t _pin, unsigned int frequency, unsigned long duration = 0) {}
-inline void noTone(uint8_t _pin) {}
+inline void tone(uint8_t _pin, unsigned int frequency, unsigned long duration = 0) { throw "Not Yet Implemented"; }
+inline void noTone(uint8_t _pin) { throw "Not Yet Implemented"; }
+inline uint8_t pulseIn(uint8_t _pin, uint8_t _value, uint32_t _timeout) { throw "Not Yet Implemented"; }
+inline uint8_t pulseIn(uint8_t pin, uint8_t value) { return pulseIn(pin, value, (uint32_t) 1000000); }
+inline uint32_t pulseInLong(uint8_t _pin, uint8_t _value, uint32_t _timeout) { throw "Not Yet Implemented"; }
+inline uint32_t pulseInLong(uint8_t pin, uint8_t value) { return pulseInLong(pin, value, (uint32_t) 1000000); }
+
+/**
+ * Shifts in a byte of data one bit at a time.
+ *
+ * Starts from either the most (i.e. the leftmost) or least (rightmost)
+ * significant bit. For each bit, the clock pin is pulled high, the next bit is
+ * read from the data line, and then the clock pin is taken low.
+ *
+ * @param dataPin the pin on which to input each bit
+ * @param clockPin the pin to toggle to signal a read from dataPin
+ * @param bitOrder which order to shift in the bits; either MSBFIRST or LSBFIRST. B=Bit, not byte
+ *
+ * @return The value read
+ */
+inline uint8_t shiftIn(uint8_t dataPin, uint8_t clockPin, bool bitOrder) {
+  bool mFirst = bitOrder == MSBFIRST;
+  uint8_t ret = 0x00;
+  for (uint8_t i = 0, mask = (bitOrder == MSBFIRST ? 0x80 : 0x01); i < 8; ++i) {
+    digitalWrite(clockPin, HIGH);
+    uint8_t setBit = mFirst ? 0x80 : 0x01;
+    uint8_t val = (mFirst ? (setBit >> i) : (setBit << i));
+    ret = ret | (digitalRead(dataPin) ? val : 0x00);
+    digitalWrite(clockPin, LOW);
+  }
+  return ret;
+}
+
+/**
+ * Shifts out a byte of data one bit at a time.
+ *
+ * Starts from either the most (i.e. the leftmost) or least (rightmost)
+ * significant bit. Each bit is written in turn to a data pin, after which a
+ * clock pin is pulsed (taken high, then low) to indicate that the bit is
+ * available.
+ *
+ * @param dataPin the pin on which to input each bit
+ * @param clockPin the pin to toggle to signal a write from dataPin
+ * @param bitOrder which order to shift in the bits; either MSBFIRST or LSBFIRST. B=Bit, not byte
+ * @param value the data to shift out
+ *
+ * @return The value read
+ */
+inline void shiftOut(uint8_t dataPin, uint8_t clockPin, bool bitOrder, uint8_t value) {
+  bool mFirst = bitOrder == MSBFIRST;
+  uint8_t ret = 0x00;
+  for (uint8_t i = 0, mask = (bitOrder == MSBFIRST ? 0x80 : 0x01); i < 8; ++i) {
+    uint8_t setBit = mFirst ? 0x80 : 0x01;
+    uint8_t val = (mFirst ? (setBit >> i) : (setBit << i));
+    digitalWrite(dataPin, (value & val) ? HIGH : LOW);
+    digitalWrite(clockPin, HIGH);
+    digitalWrite(clockPin, LOW);
+  }
+}
 
 // These definitions allow the following to compile (see issue #193):
 // https://github.com/arduino-libraries/Ethernet/blob/master/src/utility/w5100.h:341

data/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 @@ public:
   // 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;