Unit testing support

.gitignore

@@ -13,4 +13,4 @@ vendor
 .rspec_status
 
 # C++ stuff
-arduino_ci_built.bin
+*.bin

.rubocop.yml

@@ -78,3 +78,6 @@ Style/StringLiterals:
 
 Style/TrailingCommaInLiteral:
   Enabled: false
+
+Style/SymbolArray:
+  Enabled: false

.travis.yml

@@ -8,9 +8,12 @@ language: ruby
 #  - rbx
 #  - "2.5.0"
 
-before_install: gem install bundler -v 1.15.4
+#before_install: gem install bundler -v 1.15.4
 script:
+   - bundle install
    - bundle exec rubocop --version
    - bundle exec rubocop -D .
    - bundle exec rspec
-   - bundle exec ci_system_check.rb
+   - cd SampleProjects/DoSomething
+   - bundle install
+   - bundle exec arduino_ci_remote.rb

CHANGELOG.md

@@ -6,6 +6,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 ### Added
+- Unit testing support
+- Documentation for all Ruby methods
 - `ArduinoInstallation` class for managing lib / executable paths
 - `DisplayManager` class for managing Xvfb instance if needed
 - `ArduinoCmd` captures and caches preferences
@@ -15,6 +17,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - `ArduinoCmd` installs libraries
 - `ArduinoCmd` selects boards (compiler preference)
 - `ArduinoCmd` verifies sketches
+- `CppLibrary` manages GCC for unittests
+- `CIConfig` manages overridable config for all testing
 
 ### Changed
 - `DisplayManger.with_display` doesn't `disable` if the display was enabled prior to starting the block

README.md

@@ -7,26 +7,38 @@
 [Arduino CI](https://github.com/ifreecarve/arduino_ci) is a Ruby gem for executing Continuous Integration (CI) tests on an Arduino library -- both locally and as part of a service like Travis CI.
 
 
-## Installation
+## Installation In Your GitHub Project And Using Travis CI
 
-Add this line to your application's Gemfile:
+Add a file called `Gemfile` (no extension) to your Arduino project:
 
 ```ruby
+source 'https://rubygems.org'
 gem 'arduino_ci'
 ```
 
-And then execute:
+Next, you need this in `.travis.yml`
 
-    $ bundle
+```yaml
+sudo: false
+language: ruby
+script:
+   - bundle install
+   - bundle exec arduino_ci_remote.rb
+```
+
+That's literally all there is to it on the repository side.  You'll need to go to https://travis-ci.org/profile/ and enable testing for your Arduino project.  Once that happens, you should be all set.
 
-Or install it yourself as:
 
-    $ gem install arduino_ci
+## More Documentation
 
+This software is in alpha.  But [SampleProjects/DoSomething](SampleProjects/DoSomething) has a decent writeup and is a good bare-bones example of all the features.
 
-## Usage
+## Known Problems
 
-TODO: Write usage instructions here, based on other TODO of writing the actual gem.
+* The Arduino library is not fully mocked.
+* I don't have preprocessor defines for all the Arduino board flavors
+* Arduino Zero boards don't work in CI.  I'm confused.
+* https://github.com/ifreecarve/arduino_ci/issues
 
 
 ## Author
@@ -37,3 +49,5 @@ This gem was written by Ian Katz ([email protected]) in 2018.  It's released
 ## See Also
 
 * [Contributing](CONTRIBUTING.md)
+* [Adafruit/travis-ci-arduino](https://github.com/adafruit/travis-ci-arduino) which inspired this project
+* [mmurdoch/arduinounit](https://github.com/mmurdoch/arduinounit) from which the unit test macros were adopted

SampleProjects/DoSomething/Gemfile.lock

@@ -2,10 +2,12 @@ PATH
   remote: /Users/ikatz/Development/non-wayfair/arduino_ci
   specs:
     arduino_ci (0.0.1)
+      os (~> 1.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    os (1.0.0)
 
 PLATFORMS
   ruby

SampleProjects/DoSomething/README.md

@@ -1,4 +1,4 @@
-# Arduino CI and Unit Tests HOWTO [![Build Status](https://travis-ci.org/ifreecarve/arduino-ci-unit-tests.svg?branch=master)](https://travis-ci.org/ifreecarve/arduino-ci-unit-tests)
+# Arduino CI and Unit Tests HOWTO
 
 This project is a template for a CI-enabled (and unit testable) Arduino project of your own.
 
@@ -7,17 +7,105 @@ This project is a template for a CI-enabled (and unit testable) Arduino project
 
 * Travis CI
 * Unit tests
-* Development workflow matches CI workflow - the `platformio ci` line at the bottom of `.travis.yml` can be run on your local terminal (just append the name of the file you want to compile).
+* Development workflow matches CI workflow
 
 # Where The Magic Happens
 
 Here is the minimal set of files that you will need to adapt to your own project:
 
-* `.travis.yml` - You'll need to fill in the `env` section with files relevant to your project, and list out all the `--board`s under the `script` section.
-* `platformio.ini` - You'll need to add information for any architectures you plan to support.
-* `library.properties` - You'll need to update the `architectures` and `includes` lines as appropriate
+
+### `Gemfile` Ruby gem configuration
+
+```ruby
+source 'https://rubygems.org'
+gem 'arduino_ci'
+```
+
+You'll need this to get access to the functionality.
+
+> This is different from the `Gemfile` that's included in this directory!  That's for purposes of testing the ruby gem that also lives in this repository.  So "do as I say, not as I do", in this case.
+
+
+### `.travis.yml` Travis CI configuration
+
+At a minimum, you will need the following lines in your file:
+
+```yaml
+language: ruby
+script:
+   - bundle install
+   - bundle exec arduino_ci_remote.rb
+```
+
+This will install the necessary ruby gem, and run it.  There are no command line arguments as of this writing, because all configuration is provided by...
+
+### `.arduino-ci.yaml` ArduinoCI configuration
+
+This file controls all aspects of building and unit testing.  The (relatively-complete) defaults can be found [in the base project](../../misc/default.yaml).
+
+The most relevant sections for most projects will be as follows:
+
+```yaml
+compile:
+  libraries: ~
+  platforms:
+    - uno
+    - due
+    - leonardo
+
+unittest:
+  libraries: ~
+  platforms:
+    - uno
+    - due
+    - leonardo
+```
+
+This does nothing but specify a list of what platforms should run each set of tests.  The platforms themselves can also be defined and/or extended in the yaml file.  For example, `esp8266` as shown here:
+
+```yaml
+platforms:
+  esp8266:
+    board: esp8266:esp8266:huzzah
+    package: esp8266:esp8266
+    gcc:
+      features:
+      defines:
+      warnings:
+      flags:
+```
+
+Of course, this wouldn't work by itself -- the Arduino IDE would have to know how to install the package via the board manager.  So there's a section for packages too:
+
+```yaml
+packages:
+  esp8266:esp8266:
+    url: http://arduino.esp8266.com/stable/package_esp8266com_index.json
+```
+
+### Unit tests in `test/`
+
+All `.cpp` files in the `test/` directory are assumed to contain unit tests.  Each and every one will be compiled and executed on its own.
+
+The most basic unit test file is as follows:
+
+```C++
+#include <ArduinoUnitTests.h>
+#include "../do-something.h"
+
+unittest(your_test_name)
+{
+  assertEqual(4, doSomething());
+}
+
+int main(int argc, char *argv[]) {
+  return Test::run_and_report(argc, argv);
+}
+```
+
+This test defines one `unittest` (a macro provided by `ArduionUnitTests.h`), called `your_test_name`, which makes some assertions on the target library.  The `int main` section is boilerplate.
 
 
 # Credits
 
-This Arduino example was created in January 2018 by Ian Katz <ianfixes@gmail.com>.
+This Arduino example was created in January 2018 by Ian Katz <ifreecarve@gmail.com>.

SampleProjects/DoSomething/do-something.cpp

@@ -1,5 +1,5 @@
 #include <Arduino.h>
-#include <do-something.h>
+#include "do-something.h"
 int doSomething(void) {
   millis();  // this line is only here to test that we're able to refer to the builtins
   return 4;

SampleProjects/DoSomething/do-something.h

@@ -1,2 +1,3 @@
+#pragma once
 #include <Arduino.h>
 int doSomething(void);

SampleProjects/DoSomething/library.properties

@@ -1,10 +1,10 @@
-name=arduino-ci-unit-tests
+name=DoSomething
 version=0.1.0
 author=Ian Katz <[email protected]>
 maintainer=Ian Katz <[email protected]>
 sentence=Arduino CI unit test example
 paragraph=A skeleton library demonstrating CI and unit tests
 category=Other
-url=https://github.com/ifreecarve/arduino-ci-unit-tests
+url=https://github.com/ifreecarve/arduino_ci/SampleProjects/DoSomething
 architectures=avr
 includes=do-something.h

SampleProjects/DoSomething/test/good-library.cpp

@@ -0,0 +1,11 @@
+#include <ArduinoUnitTests.h>
+#include "../do-something.h"
+
+unittest(library_does_something)
+{
+  assertEqual(4, doSomething());
+}
+
+int main(int argc, char *argv[]) {
+  return Test::run_and_report(argc, argv);
+}

SampleProjects/DoSomething/test/good-null.cpp

@@ -0,0 +1,24 @@
+#include <ArduinoUnitTests.h>
+
+unittest(equality_as_vars)
+{
+  int x = 3;
+  int y = 3;
+  int z = 3;
+  assertEqual(x, y);
+  assertEqual(x, z);
+}
+
+unittest(equality_as_values)
+{
+  assertEqual(1, 1);
+  assertEqual(4, 4);
+}
+
+unittest(nothing)
+{
+}
+
+int main(int argc, char *argv[]) {
+  return Test::run_and_report(argc, argv);
+}

SampleProjects/README.md

@@ -1,4 +1,4 @@
 Arduino Sample Projects
 =======================
 
-This directory contains example projects that are meant to be built with this gem.
+This directory contains example projects that are meant to be built with this gem.  Except "TestSomething". That one's just a beater for CI testing and includes some tests that are designed to fail (to test negative inputs).

SampleProjects/TestSomething/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gem 'arduino_ci', path: '../../'

SampleProjects/TestSomething/Gemfile.lock

@@ -0,0 +1,19 @@
+PATH
+  remote: /Users/ikatz/Development/non-wayfair/arduino_ci
+  specs:
+    arduino_ci (0.0.1)
+      os (~> 1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    os (1.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  arduino_ci!
+
+BUNDLED WITH
+   1.16.0

SampleProjects/TestSomething/README.md

@@ -0,0 +1,3 @@
+# TestSomething
+
+This is a "beater" example that is referenced by tests of the Arduino CI module itself.

SampleProjects/TestSomething/examples/TestSomethingExample/TestSomethingExample.ino

@@ -0,0 +1,9 @@
+#include <test-something.h>
+// if it seems bare, that's because it's only meant to
+// demonstrate compilation -- that references work
+void setup() {
+}
+
+void loop() {
+  testSomething();
+}

SampleProjects/TestSomething/library.properties

@@ -0,0 +1,10 @@
+name=TestSomething
+version=0.1.0
+author=Ian Katz <[email protected]>
+maintainer=Ian Katz <[email protected]>
+sentence=Arduino CI unit test example
+paragraph=A skeleton library demonstrating CI and unit tests
+category=Other
+url=https://github.com/ifreecarve/arduino_ci/SampleProjects/TestSomething
+architectures=avr,esp8266
+includes=do-something.h

SampleProjects/TestSomething/test-something.cpp

@@ -0,0 +1,5 @@
+#include "test-something.h"
+int testSomething(void) {
+  millis();  // this line is only here to test that we're able to refer to the builtins
+  return 4;
+};

SampleProjects/TestSomething/test-something.h

@@ -0,0 +1,3 @@
+#pragma once
+#include <Arduino.h>
+int testSomething(void);

SampleProjects/TestSomething/test/bad-null.cpp

@@ -0,0 +1,12 @@
+#include <ArduinoUnitTests.h>
+
+unittest(pretend_equal_things_arent)
+{
+  int x = 3;
+  int y = 3;
+  assertNotEqual(x, y);
+}
+
+int main(int argc, char *argv[]) {
+  return Test::run_and_report(argc, argv);
+}

SampleProjects/TestSomething/test/good-library.cpp

@@ -0,0 +1,11 @@
+#include <ArduinoUnitTests.h>
+#include "../test-something.h"
+
+unittest(library_tests_something)
+{
+  assertEqual(4, testSomething());
+}
+
+int main(int argc, char *argv[]) {
+  return Test::run_and_report(argc, argv);
+}