Unit testing and Continuous Integration (CI) for Arduino libraries, from a Ruby gem
Clone or download
ianfixes Merge pull request #92 from ianfixes/2019-01-16_library_location
Enable redirection of installation output
Latest commit f0b54cf Jan 17, 2019

README.md

ArduinoCI Ruby gem (arduino_ci) Gem Version Documentation

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 provides that ability.

You want to run tests on your Arduino library without hardware present, but the IDE doesn't support that. Arduino CI provides that ability.

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.

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 Travis or Appveyor. Any OS that can run the Arduino IDE can run arduino_ci.

Platform CI Status
OSX OSX Build Status
Linux Linux Build Status
Windows Windows Build status

Installation In Your GitHub Project And Using Travis CI

The following prerequisites must be fulfilled:

  • A compiler; g++ is preferred. On OSX, this is provided by the built-in clang.
  • A GitHub (or other repository-hosting) project for your library
  • A CI system like Travis or Appveor that is linked to your project

Changes to Your Repo

Add a file called Gemfile (no extension) to your Arduino project:

source 'https://rubygems.org'
gem 'arduino_ci'

Testing Locally

First, pull in the arduino_ci library as a dependency.

$ bundle install

With that installed, just the following shell command each time you want the tests to execute:

$ bundle exec arduino_ci_remote.rb

Testing with remote CI

Note: arduino_ci_remote.rb expects to be run from the root directory of your Arduino project library.

Travis CI

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. The script will test all example projects of the library and all unit tests.

Next, you need this in .travis.yml in your repo

sudo: false
language: ruby
script:
   - bundle install
   - bundle exec arduino_ci_remote.rb

Appveyor CI

You'll need to go to https://ci.appveyor.com/projects and add your project.

Next, you'll need this in appveyor.yml in your repo.

build: off
test_script:
  - bundle install
  - bundle exec arduino_ci_remote.rb

Quick Start

This software is in beta. But SampleProjects/DoSomething has a decent writeup and is a good bare-bones example of all the features.

Reference

For more information on the usage of arduino_ci, see REFERENCE.md. It contains information such as:

  • Where to put unit test files
  • How to structure unit test files
  • How to control the global (physical) state of the Arduino board
  • How to modify the Arduino platforms, compilers, test plans, etc

Known Problems

Comparison to Other Arduino Testing Tools

Project CI Builds Examples Unittest Arduino Mocks Windows OSX Linux License
ArduinoCI Free (Apache-2.0)
ArduinoUnit Hardware-based Free (MIT)
Adafruit travis-ci-arduino Free (MIT)
PlatformIO Paid only Proprietary (EULA)

Author

This gem was written by Ian Katz (ianfixes@gmail.com) in 2018. It's released under the Apache 2.0 license.

See Also