126 lines
4.2 KiB
ReStructuredText
126 lines
4.2 KiB
ReStructuredText
Testing
|
|
-------
|
|
|
|
.. include:: defs.rst
|
|
|
|
Overview
|
|
~~~~~~~~
|
|
|
|
Testing PyFTDI is challenging because it relies on several pieces of hardware:
|
|
|
|
* one or more FTDI device
|
|
* |I2C|, SPI, JTAG bus slaves or communication equipment for UART
|
|
|
|
The ``tests`` directory contain several tests files, which are primarily aimed
|
|
at demonstrating usage of PyFTDI in common use cases.
|
|
|
|
Most unit tests are disabled, as they require specific slaves, with a dedicated
|
|
HW wiring. Reproducing such test environments can be challenging, as it
|
|
requires dedicated test benchs.
|
|
|
|
This is a growing concern as PyFTDI keeps evolving, and up to now, regression
|
|
tests were hard to run.
|
|
|
|
Hardware tests
|
|
~~~~~~~~~~~~~~
|
|
|
|
Please refer to the ``pyftdi/tests`` directory. There is one file dedicated to
|
|
each feature to test. Note that you need to read and edit these tests files to
|
|
fit your actual test environment, and enable the proper unit test cases, as
|
|
most are actually disabled by default.
|
|
|
|
You need specific bus slaves to perform most of these tests.
|
|
|
|
.. _virtual_framework:
|
|
|
|
Virtual test framework
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
With PyFTDI v0.45, a new test module enables PyFTDI API partial testing using a
|
|
pure software environment with no hardware. This also eases automatic testing
|
|
within a continuous integration environment.
|
|
|
|
This new module implements a virtual USB backend for PyUSB, which creates some
|
|
kind of virtual, limited USB stack. The PyUSB can be told to substitute the
|
|
native platform's libusb with this module.
|
|
|
|
This module, ``usbvirt`` can be dynamically confifured with the help of YaML
|
|
definition files to create one or more virtual FTDI devices on a virtual USB
|
|
bus topology. This enables to test ``usbtools`` module to enumerate, detect,
|
|
report and access FTDI devices using the regular :doc:`urlscheme` syntax.
|
|
|
|
``usbvirt`` also routes all vendor-specific USB API calls to a secondary
|
|
``ftdivirt`` module, which is in charge of handling all FTDI USB requests.
|
|
|
|
This module enables testing PyFtdi_ APIs. It also re-uses the MPSSE tracker
|
|
engine to decode and verify MPSSE requests used to support |I2C|, SPI and UART
|
|
features.
|
|
|
|
For now, it is able to emulate most of GPIO requests (async, sync and MPSSE)
|
|
and UART input/output. It also manages the frequency and baudrate settings.
|
|
|
|
It is not able to emulate the MPSSE commands (with the exception of set and get
|
|
GPIO values), as it represents a massive workload...
|
|
|
|
Beware: WIP
|
|
```````````
|
|
|
|
This is an experimental work in progress, which is its early inception stage.
|
|
|
|
It has nevertheless already revealed a couple of bugs that had been hiding
|
|
within PyFtdi_ for years.
|
|
|
|
There is a large work effort ahead to be able to support more use cases and
|
|
tests more APIs, and many unit tests to write.
|
|
|
|
It cannot replace hardware tests with actual boards and slaves, but should
|
|
simplify test setup and help avoiding regression issues.
|
|
|
|
|
|
Usage
|
|
`````
|
|
|
|
No hardware is required to run these tests, to even a single FTDI device.
|
|
|
|
The test configuration files are described in YaML file format, therefore the
|
|
ruamel.yaml_ package is required.
|
|
|
|
.. code-block:: python
|
|
|
|
pip3 install ruamel.yaml
|
|
PYTHONPATH=. FTDI_LOGLEVEL=info pyftdi/tests/mockusb.py
|
|
|
|
Configuration
|
|
`````````````
|
|
|
|
The ``pyftdi/tests/resources`` directory contains definition files which are
|
|
loaded by the mock unit tests.
|
|
|
|
Although it is possible to create fine grained USB device definitions, the
|
|
configuration loader tries to automatically define missing parts to match the
|
|
USB device topology of FTDI devices.
|
|
|
|
This enables to create simple definition files without having to mess with low
|
|
level USB definitions whenever possible.
|
|
|
|
EEPROM content
|
|
..............
|
|
|
|
The :ref:`ftconf` tool can be used to load, modify and generate the content of
|
|
a virtual EEPROM, see :doc:`eeprom`.
|
|
|
|
Examples
|
|
........
|
|
|
|
* An example of a nearly comprehensive syntax can be found in ``ft232h.yaml``.
|
|
* Another, much more simple example with only mandatory settings can be found
|
|
in ``ft230x.yaml``.
|
|
* An example of multiple FTDI device definitions can be found in
|
|
``ftmany.yaml``
|
|
|
|
|
|
Availability
|
|
~~~~~~~~~~~~
|
|
|
|
Note that unit tests and the virtual infrastructure are not included in the
|
|
distributed Python packages, they are only available from the git repository.
|