- Notifications
You must be signed in to change notification settings - Fork34
Unit testing and Continuous Integration (CI) for Arduino libraries, from a Ruby gem
License
Arduino-CI/arduino_ci
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
Arduino CI testsArduino 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 librarywithout 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 toGitHub events, anArduino 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 themingw-gcc-c++
package) python
(if using a board architecture that requires it, e.g. ESP32, ESP8266; seethis issue). Considerpyserial
as well.
In that environment, you can install by runninggem install arduino_ci
. To update to a latest version, usegem update arduino_ci
.
You can now test your library by simply running the commandarduino_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 specificArduino/libraries
directory on your system. If your library is elsewhere,arduino_ci
willautomatically create a symbolic link in thelibraries
directory that points to the directory of the project being tested. This simplifieds working with project dependencies, butit can have unintended consequences on Windows systems.
If you use a Windows systemit is recommended that you only run
arduino_ci
from project directories that are already inside thelibraries
directory becausein some cases deleting a folder that contains a symbolic link to another folder can cause theentire linked folder to be removed instead of just the link itself.
Unit testing binaries created byarduino_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, seetheArduino-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 installarduino_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 togem install bundler
to a minimum of version 2.0 if it's not already there. You may find it easiest to do this by usingrbenv
.
You will need to add a file calledGemfile
(no extension) to your Arduino project.
If you are simply trying to avoid the need to installarduino_ci
system-wide (which may require administrator permissions), yourGemfile
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-constraintgem'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
andbundle install
by just installing as per the "Quick Start" instructions above.
If you want to use the latest code on GitHub, yourGemfile
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 neededgem'arduino_ci',git:'https://github.com/ArduinoCI/arduino_ci.git',ref:'<your desired ref, branch, or tag>'
First, Thanks! SeeCONTRIBUTING.md. YourGemfile
would look like this:
source'https://rubygems.org'gem'arduino_ci',path:'/path/to/development/dir/for/arduino_ci'
Fulfilling thearduino_ci
library dependency is as easy as running one or both of these commands:
$bundle configset --local path'vendor/bundle'# if you lack administrative privileges to install globally$bundle install
This will create aGemfile.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:
$bundleexec arduino_ci.rb
For more information on the usage ofarduino_ci.rb
, seeREFERENCE.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-lateststeps: -uses:actions/checkout@v3 -uses:ruby/setup-ruby@v1with:ruby-version:2.6 -run:| gem install arduino_ci arduino_ci.rb
You'll need to go tohttps://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:falselanguage:rubyscript: -gem install arduino_ci -arduino_ci.rb
You'll need to go tohttps://ci.appveyor.com/projects and add your project.
Next, you'll need this inappveyor.yml
in your repo.
build:offtest_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
About
Unit testing and Continuous Integration (CI) for Arduino libraries, from a Ruby gem
Topics
Resources
License
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.
Contributors13
Uh oh!
There was an error while loading.Please reload this page.