1 | # Arduino Client for MQTT Test Suite
|
---|
2 |
|
---|
3 | This is a regression test suite for the `PubSubClient` library.
|
---|
4 |
|
---|
5 | There are two parts:
|
---|
6 |
|
---|
7 | - Tests that can be compiled and run on any machine
|
---|
8 | - Tests that build the example sketches using the Arduino IDE
|
---|
9 |
|
---|
10 |
|
---|
11 | It is a work-in-progress and is subject to complete refactoring as the whim takes
|
---|
12 | me.
|
---|
13 |
|
---|
14 |
|
---|
15 | ## Local tests
|
---|
16 |
|
---|
17 | These are a set of executables that can be run to test specific areas of functionality.
|
---|
18 | They do not require a real Arduino to be attached, nor the use of the Arduino IDE.
|
---|
19 |
|
---|
20 | The tests include a set of mock files to stub out the parts of the Arduino environment the library
|
---|
21 | depends on.
|
---|
22 |
|
---|
23 | ### Dependencies
|
---|
24 |
|
---|
25 | - g++
|
---|
26 |
|
---|
27 | ### Running
|
---|
28 |
|
---|
29 | Build the tests using the provided `Makefile`:
|
---|
30 |
|
---|
31 | $ make
|
---|
32 |
|
---|
33 | This will create a set of executables in `./bin/`. Run each of these executables to test the corresponding functionality.
|
---|
34 |
|
---|
35 | *Note:* the `connect_spec` and `keepalive_spec` tests involve testing keepalive timers so naturally take a few minutes to run through.
|
---|
36 |
|
---|
37 | ## Arduino tests
|
---|
38 |
|
---|
39 | *Note:* INO Tool doesn't currently play nicely with Arduino 1.5. This has broken this test suite.
|
---|
40 |
|
---|
41 | Without a suitable arduino plugged in, the test suite will only check the
|
---|
42 | example sketches compile cleanly against the library.
|
---|
43 |
|
---|
44 | With an arduino plugged in, each sketch that has a corresponding python
|
---|
45 | test case is built, uploaded and then the tests run.
|
---|
46 |
|
---|
47 | ### Dependencies
|
---|
48 |
|
---|
49 | - Python 2.7+
|
---|
50 | - [INO Tool](http://inotool.org/) - this provides command-line build/upload of Arduino sketches
|
---|
51 |
|
---|
52 | ### Running
|
---|
53 |
|
---|
54 | The test suite _does not_ run an MQTT server - it is assumed to be running already.
|
---|
55 |
|
---|
56 | $ python testsuite.py
|
---|
57 |
|
---|
58 | A summary of activity is printed to the console. More comprehensive logs are written
|
---|
59 | to the `logs` directory.
|
---|
60 |
|
---|
61 | ### What it does
|
---|
62 |
|
---|
63 | For each sketch in the library's `examples` directory, e.g. `mqtt_basic.ino`, the suite looks for a matching test case
|
---|
64 | `testcases/mqtt_basic.py`.
|
---|
65 |
|
---|
66 | The test case must follow these conventions:
|
---|
67 | - sub-class `unittest.TestCase`
|
---|
68 | - provide the class methods `setUpClass` and `tearDownClass` (TODO: make this optional)
|
---|
69 | - all test method names begin with `test_`
|
---|
70 |
|
---|
71 | The suite will call the `setUpClass` method _before_ uploading the sketch. This
|
---|
72 | allows any test setup to be performed before the sketch runs - such as connecting
|
---|
73 | a client and subscribing to topics.
|
---|
74 |
|
---|
75 |
|
---|
76 | ### Settings
|
---|
77 |
|
---|
78 | The file `testcases/settings.py` is used to config the test environment.
|
---|
79 |
|
---|
80 | - `server_ip` - the IP address of the broker the client should connect to (the broker port is assumed to be 1883).
|
---|
81 | - `arduino_ip` - the IP address the arduino should use (when not testing DHCP).
|
---|
82 |
|
---|
83 | Before each sketch is compiled, these values are automatically substituted in. To
|
---|
84 | do this, the suite looks for lines that _start_ with the following:
|
---|
85 |
|
---|
86 | byte server[] = {
|
---|
87 | byte ip[] = {
|
---|
88 |
|
---|
89 | and replaces them with the appropriate values.
|
---|
90 |
|
---|
91 |
|
---|
92 |
|
---|
93 |
|
---|