add Testing.md

Testing.md

@@ -0,0 +1,63 @@
+# Device Tests & Coverage Report
+
+Only a subset of this library can be tested reasonably with unit tests. Mocking the serial converter chips would hardly represent their real behavior, so I decided to use tests on real devices where the device is connected to:
+
+* Android executing [Android instrumented test](https://developer.android.com/training/testing/unit-testing/instrumented-unit-tests)s 
+* Windows/Linux host running a [RFC-2217](https://tools.ietf.org/html/rfc2217) server
+
+The instrumented test uses the RFC-2217 server to control the other end of the serial line over Wi-Fi.
+
+# Android Setup
+
+By default the USB port is used for ADB debugging, but ADB can also use Wi-Fi. To enable Wi-Fi you have to enable it in *Android Settings -> Developer options*, connect with USB ADB and enable Wi-Fi with ``adb tcpip 5555``, see more details [here](https://developer.android.com/studio/command-line/adb.html).
+
+# Serial host setup
+
+You need python + [pyserial 3.4](https://pythonhosted.org/pyserial/) which includes a  [rfc2217_server.py](https://github.com/pyserial/pyserial/blob/master/examples/rfc2217_server.py). You can install *pyserial* with ``pip install serial``
+
+On Linux the ``rfc2217_server.py`` is typically available in ``usr/share/doc/python-serial/examples``. On Windows you have to take it from github.
+
+Before executing the test, start the *rfc2217* server with: ``python rfc2217_server.py -v`` *com-port*
+
+To see all data apply this [patch](https://github.com/mik3y/usb-serial-for-android/blob/master/test/rfc2217_server.diff) and use ``-v -v`` option.
+
+# Serial device setup
+
+Over the time I collected various [serial breakout boards](images/serial_boards.jpg), but each device comes with a different pin assignment, so I created my own and soldered mini adapters vor every device.
+
+My pin assignment is:
+
+|  1  |  2  |  3  |  4   |  5  |
+| --- | --- | --- | ---- | --- |
+| GND | TxD | Rxd | n.c. | +5V |
+
++5V is connected at all serial devices to provide power to other devices that are not self powered. 
+
+The Raspi needs a level shifter because it is not 5V tolerant. I used a 74HC21 which is not the most commonly used level shifter, but that's what I found over the weekend in my parts collection. +5V is not connected as the Raspi as it is self powered.
+
+The *Arduino Pro Micro* has to be programmed with [arduino_leonardo_bridge.ini](https://github.com/mik3y/usb-serial-for-android/blob/master/test/arduino_leonardo_bridge/arduino_leonardo_bridge.ino)
+
+# Test execution
+
+* Start ``rfc2217_server.py`` on your Windows/Linux host
+* Configure the ip address of your rfc2217 server host in ``usbSerialForAndroid/build.gradle -> testInstrumentationRunnerArguments -> rfc2217_server_host``. Depending on the host type enable/disable the other ``testInstrumentationRunnerArguments``.
+* Connect your device 
+* Start ``DeviceTest`` 
+* When requested, confirm USB permission dialog on your Android device
+
+Tests are sometimes flaky, as they depend on real hardware, which can have varying performance or some data left in receive buffers from previous failing tests. Retrying multiple times, re-attaching the serial device or restarting the ``rfc2217_server.py`` typically helps. Else try increasing the timeouts in ``DeviceTest.java``.
+
+# Coverage report
+
+Enable ``apply from: 'coverage.gradle'`` in ``usbSerialForAndroid/build.gradle``.
+
+Remove previous test results with ``gradle clean`` or *Android Studio : Menu -> Build -> Clean Project*
+
+For each *flavor* defined in ``coverage.gradle`` execute the corresponding *create***Flavor***DebugAndroidTestCoverage* task. You can find these tasks in Android Studios Gradle window in the *usb-serial-for-android -> usbSerialForAndroid -> other* folder. You can show this window with *Android Studio : Menu -> View -> Tool Windows -> Gradle*.
+
+As tests can be  flaky, it's best to first execute *DeviceTest* as this shows the test results and errors much better and on success execute the *create***Flavor***DebugAndroidTestCoverage* task.
+
+Upload coverage reports to [codecov.io](https://codecov.io/gh/mik3y/usb-serial-for-android) using the bash uploader. On Windows execute in ``Git Bash``. I tried to merge the test reports locally, but the recommended *jacocoTestReport* task for whatever reason did nothing.
+
+
+