You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+17-4
Original file line number
Diff line number
Diff line change
@@ -9,8 +9,8 @@ ArduinoCI uses a very standard GitHub workflow.
9
9
10
10
Pull requests will trigger a Travis CI job. The following two commands will be expected to pass (so you may want to run them locally before opening the pull request):
11
11
12
-
*`rubocop -D` - code style tests
13
-
*`rspec` - functional tests
12
+
*`bundle exec rubocop -D .` - code style tests
13
+
*`bundle exec rspec` - functional tests
14
14
15
15
If you do not already have a working ruby development environment set up, run the following commands:
Be prepared to write tests to accompany any code you would like to see merged.
27
25
See `SampleProjects/TestSomething/test/*.cpp` for the existing tests (run by rspec).
28
26
29
27
28
+
## Convenience Features
29
+
30
+
To speed up testing by targeting only the files you're working on, you can set several environment variables that `bundle exec rspec` will respond to:
31
+
32
+
*`ARDUINO_CI_SKIP_SPLASH_SCREEN_RSPEC_TESTS`: if set, this will avoid any rspec test that calls the arduino executable (and as such, causes the splash screen to pop up).
33
+
*`ARDUINO_CI_SKIP_RUBY_RSPEC_TESTS`: if set, this will skip all tests against ruby code (useful if you are not changing Ruby code).
34
+
*`ARDUINO_CI_SKIP_CPP_RSPEC_TESTS`: if set, this will skip all tests against the `TestSomething` sample project (useful if you are not changing C++ code).
35
+
36
+
You can set them to any value, they just have to be set. Example usage:
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](https://github.com/ianfixes/arduino_ci) provides that ability.
5
-
6
-
You want to run tests on your Arduino library without hardware present, but the IDE doesn't support that. Arduino CI provides that ability.
4
+
You want to run tests on your Arduino library (bonus: without hardware present), but the IDE doesn't support that. Arduino CI provides that ability.
7
5
8
6
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.
9
7
8
+
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](https://github.com/ianfixes/arduino_ci) provides that ability.
9
+
10
10
`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`.
11
11
12
12
Platform | CI Status
@@ -16,13 +16,36 @@ Linux | [](https://ci.appveyor.com/project/ianfixes/arduino-ci)
17
17
18
18
19
-
## Installation In Your GitHub Project And Using Travis CI
19
+
## Comparison to Other Arduino Testing Tools
20
20
21
-
The following prerequisites must be fulfilled:
21
+
| Project | CI | Builds Examples | Unittest | Arduino Mocks | Windows | OSX | Linux | License |
* A compiler; [g++](https://gcc.gnu.org/) is preferred. On OSX, this is provided by the built-in `clang`.
24
-
* A GitHub (or other repository-hosting) project for your library
25
-
* A CI system like Travis or Appveor that is linked to your project
29
+
30
+
## Quick Start
31
+
32
+
For a bare-bones example that you can copy from, see [SampleProjects/DoSomething](SampleProjects/DoSomething).
33
+
34
+
The complete set of C++ unit tests for the `arduino_ci` library itself are in the [SampleProjects/TestSomething](SampleProjects/TestSomething) project. The [test files](SampleProjects/TestSomething/test/) are named after the type of feature being tested.
35
+
36
+
37
+
### You Need Ruby and Bundler
38
+
39
+
You'll need Ruby version 2.2 or higher, and to `gem install bundler` if it's not already there.
40
+
41
+
42
+
### You Need A Compiler (`g++`)
43
+
44
+
For unit testing, you will need a compiler; [g++](https://gcc.gnu.org/) is preferred.
45
+
46
+
***Linux**: `gcc`/`g++` is likely pre-installed.
47
+
***OSX**: `g++` is an alias for `clang`, which is provided by Xcode and the developer tools. You are free to `brew install gcc` as well; this is also tested and working.
48
+
***Windows**: you will need Cygwin, and the `mingw-gcc-g++` package. A full set of (working) install instructions can be found in `appveyor.yml`, as this is how CI runs for this project.
26
49
27
50
28
51
### Changes to Your Repo
@@ -34,21 +57,66 @@ source 'https://rubygems.org'
34
57
gem 'arduino_ci'
35
58
```
36
59
37
-
### Testing Locally
60
+
It would also make sense to add the following to your `.gitignore`, or copy [the `.gitignore` used by this project](.gitignore):
61
+
62
+
```
63
+
/.bundle/
64
+
/.yardoc
65
+
Gemfile.lock
66
+
/_yardoc/
67
+
/coverage/
68
+
/doc/
69
+
/pkg/
70
+
/spec/reports/
71
+
vendor
72
+
*.gem
73
+
74
+
# rspec failure tracking
75
+
.rspec_status
76
+
77
+
# C++ stuff
78
+
*.bin
79
+
*.bin.dSYM
80
+
```
81
+
82
+
83
+
### Installing the Dependnencies
38
84
39
-
First, pull in the `arduino_ci` library as a dependency.
85
+
Fulfilling the `arduino_ci` library dependency is as easy as running this command:
40
86
41
87
```
42
88
$ bundle install
43
89
```
44
90
45
91
92
+
### Running tests
93
+
46
94
With that installed, just the following shell command each time you want the tests to execute:
47
95
48
96
```
49
97
$ bundle exec arduino_ci_remote.rb
50
98
```
51
99
100
+
`arduino_ci_remote.rb` is the main entry point for this library. This command will iterate over all the library's `examples/` and attempt to compile them. If you set up unit tests, it will run those as well.
101
+
102
+
103
+
### Reference
104
+
105
+
For more information on the usage of `arduino_ci_remote.rb`, see [REFERENCE.md](REFERENCE.md). It contains information such as:
106
+
107
+
* How to configure build options (platforms to test, Arduino library dependencies to install) with an `.arduino-ci.yml` file
108
+
* Where to put unit test files
109
+
* How to structure unit test files
110
+
* How to control the global (physical) state of the Arduino board
111
+
* How to modify the Arduino platforms, compilers, test plans, etc
112
+
113
+
114
+
## Setting up Pull Request Testing and/or External CI
115
+
116
+
The following prerequisites must be fulfilled:
117
+
118
+
* A GitHub (or other repository-hosting) project for your library
119
+
* A CI system like [Travis CI](https://travis-ci.org/) or [Appveyor](https://www.appveyor.com/) that is linked to your project
52
120
53
121
54
122
### Testing with remote CI
@@ -66,10 +134,11 @@ Next, you need this in `.travis.yml` in your repo
66
134
sudo: false
67
135
language: ruby
68
136
script:
69
-
- bundle install
70
-
- bundle exec arduino_ci_remote.rb
137
+
- bundle install
138
+
- bundle exec arduino_ci_remote.rb
71
139
```
72
140
141
+
73
142
#### Appveyor CI
74
143
75
144
You'll need to go to https://ci.appveyor.com/projects and add your project.
@@ -83,37 +152,13 @@ test_script:
83
152
- bundle exec arduino_ci_remote.rb
84
153
```
85
154
86
-
## Quick Start
87
-
88
-
This software is in beta. But [SampleProjects/DoSomething](SampleProjects/DoSomething) has a decent writeup and is a good bare-bones example of all the features.
89
-
90
-
## Reference
91
-
92
-
For more information on the usage of `arduino_ci`, see [REFERENCE.md](REFERENCE.md). It contains information such as:
93
-
94
-
* Where to put unit test files
95
-
* How to structure unit test files
96
-
* How to control the global (physical) state of the Arduino board
97
-
* How to modify the Arduino platforms, compilers, test plans, etc
98
-
99
-
100
155
## Known Problems
101
156
102
157
* The Arduino library is not fully mocked.
103
158
* I don't have preprocessor defines for all the Arduino board flavors
104
159
* https://github.com/ianfixes/arduino_ci/issues
105
160
106
161
107
-
## Comparison to Other Arduino Testing Tools
108
-
109
-
110
-
| Project | CI | Builds Examples | Unittest | Arduino Mocks | Windows | OSX | Linux | License |
0 commit comments