Merge branch 'master' of gitlab.com:konsulko/internal/pyagl into master

 Conflicts:

	pyagl/tests/test_audiomixer.py

	pyagl/tests/test_bluetooth.py

1 files changed, 30 insertions, 18 deletions

diff --git a/README.md b/README.md
index 95f4f1f..d81cf82 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-#pyagl
+#pyagl
 
 ## Basic info
 Python library with bindings and tests for Automotive Grade Linux services
@@ -67,24 +67,36 @@ Creating a new modules and tests can be done with a few steps:
 3. cookiecutter -f ../templates/ 
 
 ## Running the tests
-The tests can be run either directly from the cloned repository or the default Python site-packages directory per system default or virtualenv:  
-* for example on Debian systems the default site packages dir should be in /usr/local/lib/python3.8/dist-packages/pyagl/tests
-* otherwise for virtualenv - <virtualenv_dir>/lib/python3.8/site-packages/pyagl/tests
+The tests can be run on target if installed, directly from the cloned repository, or if installed locally on a development host, from the default Python site-packages directory or a configured virtualenv.  On target the tests will be in /usr/lib/python3.8/site-packages/pyagl/tests.  If installed locally on a development machine:
+* on Debian systems the default site packages directory should be in /usr/local/lib/python3.8/dist-packages/pyagl/tests
+* for virtualenv, the directory will be <virtualenv_dir>/lib/python3.8/site-packages/pyagl/tests
 
-pytest
- 
-Running the tests rests on the assumptions that the following environment variables will be exported:  
-All tests require AGL_TGT_IP and will look for AGL_TGT_PORT
-* AGL_TGT_IP - required - pointing at an IP Address with AGL instance
+### Invoking pytest
+The tests may be run with `pytest` by passing it the tests directory:
+```
+pytest <tests directory>
+```
+On target, the command would be:
+```
+pytest /usr/lib/python3.8/site-packages/pyagl/tests
+```
+Note that the tests have been labelled with `pytest` markers to allow selecting or deselecting tests with the `pytest` '-k' option.  Each binding's test are marked with the name of the binding, with additional markers that include:
+* regular - all regular verb tests with expected values
+* hwrequired - verb tests requiring available physical hardware
+
+### Test Configuration
+ Running the tests remotely involves the export of the following environment variables:
+* AGL_TGT_IP - required - point at an IP Address with AGL instance
 * AGL_TGT_PORT - optional - if not exported, the library wil connect to the IP address via ssh to find out the service's listening TCP port
-* AGL_BTMAP_RECIPIENT - optional - When running Bluetooth MAP tests, this would be used as phone number to write text messages to
-* AGL_BTMAP_TEXT - optional - When running Bluetooth MAP tests, messages will be composed with this text
-* AGL_PBAP_PHONENUM - optional - When running Bluetooth PBAP tests, this phone number will be used to .search()
-* AGL_PBAP_VCF - optional - Bluetooh PBAP tests - query a contact entry out of the phonebook 
-* AGL_BT_TEST_ADDR - optional - Bluetooth tests - pair/connect/disconnect with an actual Bluetooth device(phone)'s address  
-it should have the DBus address style as "dev_00_01_02_03_04_05" instead regular colon-separated MAC address
 
-Should some of the optional variables be omitted, the fixtures and their dependent tests should fail gracefully
- with "XFAIL"(expected fail) or "SKIP" result.  
+When running tests on target, AGL_TGT_IP is not required, as the tests will assume the local host is the target.
+
+Some specific tests are dependent on additional configuration via the following environment variables:
+* AGL_AVAILABLE_INTERFACES - optional, specify which of ethernet, wifi, and bluetooth interfaces are available.  The value is a comma separated list, with a default value of "ethernet,wifi,bluetooth".
+* AGL_BTMAP_RECIPIENT - optional, when running Bluetooth MAP tests, this would be used as phone number to write text messages to.
+* AGL_BTMAP_TEXT - optional, when running Bluetooth MAP tests, messages will be composed with this text.
+* AGL_PBAP_PHONENUM - optional , when running Bluetooth PBAP tests, this phone number will be used to .search().
+* AGL_PBAP_VCF - optional, for the Bluetooh PBAP tests query a contact entry out of the phonebook.
+* AGL_BT_TEST_ADDR - optional, for the Bluetooth tests pair/connect/disconnect with an actual Bluetooth device(phone)'s address .  The address should have the DBus address style as "dev_00_01_02_03_04_05" instead of a regular colon-separated MAC address.
 
-There are tests that are dependent on other tests, therefore if the dependent tests fail, the whole test chain will be skipped.
\ No newline at end of file
+Should some of the optional variables be omitted, the fixtures and their dependent tests should fail gracefully with a "XFAIL" (expected fail) or "SKIP" result.  There are tests that are dependent on other tests, therefore if the dependent tests fail, the whole test chain will be skipped.