search

Arduino-CI / arduino_ci

Unit testing and Continuous Integration (CI) for Arduino libraries, from a Ruby gem
Apache License 2.0
110 stars 34 forks source link
arduino ci unit-testing-framework

readme

ArduinoCI Ruby gem (arduino_ci)

Gem Version Documentation Gitter GitHub Marketplace

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.

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 OSX Build Status
Linux Linux Build Status
Windows Windows Build status

Quick Start

This project has the following dependencies:

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:

Assumptions About Your Repository

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.

Changes to Your Repository

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

A Quick Example

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

Advanced Start

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.

You Need Ruby and Bundler

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.

Non-root installation

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.

Using the latest-available code

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>'

Using a version of arduino_ci source code on your local machine

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'

Installing the Dependencies

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.

Running arduino_ci.rb To Test Your Library

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

$ bundle exec arduino_ci.rb

Reference

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

Setting up Pull Request Testing and/or External CI

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

Arduino CI's Own GitHub action

GitHub Marketplace

Your Own Scripted GitHub Action

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

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

Known Problems

Author

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

See Also