ArduinoCI Ruby gem (arduino_ci)

Arduino CI tests Arduino libraries; it 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.

• enables running unit tests against the library without hardware present
• provides a system of mocks that allow fine-grained control over the hardware 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
• 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

Note: for running tests in response to GitHub events, an Arduino CI GitHub Action 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
OSX
Linux
Windows

This project has the following dependencies:

• ruby 2.5 or higher
• A compiler like g++ (on OSX, clang works; on Cygwin, use the mingw-gcc-c++ package)
• python (if using a board architecture that requires it, e.g. ESP32, ESP8266; see this issue). Consider pyserial as well.

In that environment, you can install by running gem install arduino_ci. To update to a latest version, use gem update arduino_ci.

You can now test your library by simply running the command arduino_ci.rb from your library directory. This will perform the following:

• validation of some fields in library.properties, if it exists
• running unit tests from files found in test/, if they exist
• testing compilation of example sketches found in examples/, if they exist

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.

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.

Unit testing binaries created by arduino_ci should not be committed to the codebase. To avoid that, add the following to your .gitignore:

# arduino_ci unit test binaries and artifacts
*.bin
*.bin.dSYM

For a fairly minimal practical example of a unit-testable library repo that you can copy from, see the Arduino-CI/Blink repository.

New features and bugfixes reach GitHub before they reach a released ruby gem. Alternately, it may be that (for your own reasons) you do not wish to install arduino_ci globally on your system. A few additional setup steps are required if you wish to do this.

In addition to version 2.5 or higher, you'll also need to gem install bundler to a minimum of version 2.0 if it's not already there. You may find it easiest to do this by using rbenv.

You will need to add a file called Gemfile (no extension) to your Arduino project.

If you are simply trying to avoid the need to install arduino_ci system-wide (which may require administrator permissions), your Gemfile would look like this:

source 'https://rubygems.org'

# Replace 1.2 with the desired version of arduino_ci.  See https://guides.rubygems.org/patterns/#pessimistic-version-constraint
gem 'arduino_ci', '~> 1.2'

It would also make sense to add the following to your .gitignore:

/.bundle/
vendor

Note: this used to be the recommended installation method, but with the library's maturation it's better to avoid the use of Gemfile and bundle install by just installing as per the "Quick Start" instructions above.

If you want to use the latest code on GitHub, your Gemfile would look like this:

source 'https://rubygems.org'

# to use the latest github code in a given repo and branch, replace the below values for git: and ref: as needed
gem 'arduino_ci', git: 'https://github.com/ArduinoCI/arduino_ci.git', ref: '<your desired ref, branch, or tag>'

First, Thanks! See CONTRIBUTING.md. Your Gemfile would look like this:

source 'https://rubygems.org'

gem 'arduino_ci', path: '/path/to/development/dir/for/arduino_ci'

Fulfilling the arduino_ci library dependency is as easy as running one or both of these commands:

$ bundle config set --local path 'vendor/bundle'   # if you lack administrative privileges to install globally
$ bundle install

This will create a Gemfile.lock in your project directory, which you may optionally check into source control. A broader introduction to ruby dependencies is outside the scope of this document.

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

$ bundle exec arduino_ci.rb

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

• How to configure build options (platforms to test, Arduino library dependencies to install) with an .arduino-ci.yml file
• 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

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

GitHub Actions allows you to automate your workflows directly in GitHub. No additional steps are needed. Just create a YAML file with the information below in your repo under the .github/workflows/ directory.

on: [push, pull_request]
jobs:
  runTest:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: 2.6
      - run: |
          gem install arduino_ci
          arduino_ci.rb

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:
  - gem install arduino_ci
  - arduino_ci.rb

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:
  - gem install arduino_ci
  - arduino_ci.rb

• 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

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

• Contributing
• Adafruit/ci-arduino which inspired this project
• mmurdoch/arduinounit from which the unit test macros were adopted