espressif/esptool
1
0
Fork 0
mirror of https://github.com/espressif/esptool.git synced 2025-10-17 07:32:30 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(tests): Add test suite description and instructions

Browse Source
This commit is contained in:
radim.karnis
2022-10-19 14:10:42 +02:00
parent 2b42855e32
commit 943b997668
2 changed files with 34 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
CONTRIBUTING.rst
View File

@@ -104,26 +104,51 @@ When you submit a Pull Request, the GitHub Actions automated build system will r
Automated Integration Tests
^^^^^^^^^^^^^^^^^^^^^^^^^^^
The test directory contains an integration suite with some integration tests for ``esptool.py``:
The test directory contains a `pytest <https://docs.pytest.org/>`_ integration suite with some integration tests for ``esptool.py``, ``espefuse.py``, and ``espsecure.py``.
* ``test_imagegen.py`` tests the elf2image command and is run automatically by GitHub Actions for each Pull Request. You can run this command locally to check for regressions in the elf2image functionality.
The following tests run automatically by GitHub Actions for each Pull Request. You can run them locally to check for regressions in the respective functionality:
* ``test_esptool.py`` is a `Python unittest <https://docs.python.org/3/library/unittest.html>`_ file that contains integration tests to be run against real Espressif hardware. These tests need real hardware so are not run automatically by GitHub Actions, they need to be run locally in a command line with the following format:
* ``test_imagegen.py`` tests the ``elf2image`` command
* ``test_image_info.py`` tests the ``image_info`` command
* ``test_mergebin.py`` tests the ``merge_bin`` command
* ``test_modules.py`` tests the modules used by ``esptool.py`` for regressions
* ``test_espsecure.py`` tests ``espsecure.py`` functionality
``./test_esptool.py <serial port> <name of chip> <baud rate> [optional test name(s)]``
The following tests are not run automatically by GitHub Actions, because they need real connected hardware. Therefore, they need to be run locally in a command line:
* ``test_esptool.py`` contains integration tests for ``esptool.py`` and needs to be run against real Espressif hardware with the following format:
``pytest test_esptool.py --port <serial port> --chip <name of chip> --baud <baud rate>``
For example, to run all tests on an ESP32 board connected to /dev/ttyUSB0, at 230400bps:
``./test_esptool.py /dev/ttyUSB0 esp32 230400``
``pytest test_esptool.py --port /dev/ttyUSB0 --chip esp32 --baud 230400``
Or to run the TestFlashing suite only on an ESP8266 board connected to /dev/ttyUSB2, at 460800bps:
Or to run the TestFlashing suite only (using the pytest ``-k`` option to select tests based on their name) on an ESP8266 board connected to /dev/ttyUSB2, at 460800bps:
``./test_esptool.py /dev/ttyUSB2 esp8266 460800 TestFlashing``
``pytest test_esptool.py --port /dev/ttyUSB2 --chip esp8266 --baud 460800 -k TestFlashing``
.. note::
Some tests might fail at higher baud rates on some hardware.
The following tests are not run automatically by GitHub Actions, but can be run locally in a command line:
* ``test_espefuse.py`` tests ``espefuse.py`` functionality. To run it:
``pytest test_espefuse.py --chip <name of chip>``
These test use the ``--virt`` virtual mode of ``espefuse.py`` to safely test the functionality without a connection to a chip and without the possibility of affecting the actual eFuses in a real hardware.
.. warning::
Do not attempt to run these tests on real hardware! You risk damaging or destroying the ESP chip!
The whole test suite (without the tests needing an actual hardware) can be easily run with the following command in the esptool root folder:
``pytest --ignore=test/test_esptool.py``
Pull Request Process
--------------------

25
test/README.md
View File

@@ -1,24 +1,3 @@
# esptool.py test cases README
# test_elf2image.py
Exists to catch unexpected changes in elf2image or image_info output. Does not require an ESP8266 to verify.
## About Tests
Test method is fairly lo-fi:
Directory test/elf2image/ contains subdirectories esp8266-v1, esp8266-v2 and esp32. These contain test cases.
Each test case is a .elf file, which is stored alongside one or more .bin files representing the output of elf2image, and one .txt file representing the output of image_info when reading back the binary.
Default run of test_elf2image.py will re-run elf2image & image_info on all these images. Suitable --chip and --version args are supplied, determined by the directory name.
The test runner verifies that nothing in the output of either command has changed.
## Dealing With Output Changes
If changes are detected, we can check if valid images are still being produced. If the changes turn out to be OK, running "test_elf2image.py --regen" will regenerate all of the .bin and .txt files for the test cases.
(--regen can also be used to evaluate test failures, by looking at git diff output.)
# esptool.py test suite
See the [Automated Integration Tests section in `esptool.py` documentation](https://docs.espressif.com/projects/esptool/en/latest/esp32/contributing.html#automated-integration-tests) to learn about the test suite and how to run it.