esp-idf/tools/unit-test-app/README.md

# Unit Test App

ESP-IDF unit tests are run using Unit Test App. The app can be built with the unit tests for a specific component. Unit tests are in `test` subdirectories of respective components.

# Building Unit Test App

## CMake

* Follow the setup instructions in the top-level esp-idf README.
* Set IDF_PATH environment variable to point to the path to the esp-idf top-level directory.
* Change into `tools/unit-test-app` directory
* `idf.py menuconfig` to configure the Unit Test App.
* `idf.py -T <component> -T <component> ... build` with `component` set to names of the components to be included in the test app. Or `idf.py -T all build` to build the test app with all the tests for components having `test` subdirectory.
* Follow the printed instructions to flash, or run `idf.py -p PORT flash`.
* Unit test have a few preset sdkconfigs. It provides command `idf.py ut-clean-config_name` and `idf.py ut-build-config_name` (where `config_name` is the file name under `unit-test-app/configs` folder) to build with preset configs. For example, you can use `idf.py -T all ut-build-default` to build with config file `unit-test-app/configs/default`. Built binary for this config will be copied to `unit-test-app/output/config_name` folder.
* You may extract the test cases presented in the built elf file by calling `ElfUnitTestParser.py <your_elf>`.

# Flash Size

The unit test partition table assumes a 4MB flash size. When testing `-T all`, this additional factory app partition size is required.

If building unit tests to run on a smaller flash size, edit `partition_table_unit_tests_app.csv` and use `-T <component> <component> ...` or instead of `-T all` tests don't fit in a smaller factory app partition (exact size will depend on configured options).

# Running Unit Tests

The unit test loader will prompt by showing a menu of available tests to run:

* Type a number to run a single test.
* `*` to run all tests.
* `[tagname]` to run tests with "tag"
* `![tagname]` to run tests without "tag" (`![ignore]` is very useful as it runs all CI-enabled tests.)
* `"test name here"` to run test with given name

# Testing Unit Tests with CI

For now we prefer to use component-based unit test to test in CI. Running unit-test-app in CI is being deprecated.
add unit tests to esp-idf rename nvs host test folder, modify .gitlab-ci.yml remove unit-test-app build re-format unit test files remove extra newlines in project.mk some refactoring for unit test part in project.mk add build files of unit-test-app in gitignore add README.md for unit test app correct headings in README.md remove files and make minor tweaks in unit test app update .gitlab-ci.yml to use unit test app delete unused lines in component_wrapper.mk delete periph_i2s.h and lcd test add text floating point in components/esp32/test/Kconfig correct idf test build paths in .gitlab-ci.yml 2016-11-17 03:36:10 -05:00			`# Unit Test App`

			ESP-IDF unit tests are run using Unit Test App. The app can be built with the unit tests for a specific component. Unit tests are in `test` subdirectories of respective components.

			`# Building Unit Test App`

cmake: Add support for test build 2018-08-26 22:48:16 -04:00			`## CMake`

			`* Follow the setup instructions in the top-level esp-idf README.`
			`* Set IDF_PATH environment variable to point to the path to the esp-idf top-level directory.`
			* Change into `tools/unit-test-app` directory
			* `idf.py menuconfig` to configure the Unit Test App.
idf.py: Add support for action specific options Changes argument parsing mechanism from argparse to a new one, that provides better support for extensions and options that are only applicable to specific subcommands, Breaking changes: 1. All global options should go before subcommands, i.e. `idf.py build -C ~/some/project` will not work anymore, only `idf.py -C ~/some/project build` is acceptable 2. To provide multiple values to an option like `--define-cache-entry` it's necessary to repeat option many times, i.e. `idf.py -D entry1 entry2 entry3` will not work, right way is: `idf.py -D entry1 -D entry2 -D entry3` At the moment there are 3 options like this: `--define-cache-entry` in base list and `--test-components` and `--test-exclude-components` in the unit test extensions 3. Drops `defconfig` and `bootloader-clean` subcommands Closes https://github.com/espressif/esp-idf/issues/3570 Closes https://github.com/espressif/esp-idf/issues/3571 2019-04-10 12:06:52 -04:00			* `idf.py -T <component> -T <component> ... build` with `component` set to names of the components to be included in the test app. Or `idf.py -T all build` to build the test app with all the tests for components having `test` subdirectory.
			* Follow the printed instructions to flash, or run `idf.py -p PORT flash`.
			* Unit test have a few preset sdkconfigs. It provides command `idf.py ut-clean-config_name` and `idf.py ut-build-config_name` (where `config_name` is the file name under `unit-test-app/configs` folder) to build with preset configs. For example, you can use `idf.py -T all ut-build-default` to build with config file `unit-test-app/configs/default`. Built binary for this config will be copied to `unit-test-app/output/config_name` folder.
ci: extract ElfUnitTestParser allowing resolve elf offline 2022-05-23 03:06:46 -04:00			* You may extract the test cases presented in the built elf file by calling `ElfUnitTestParser.py <your_elf>`.
cmake: Add support for test build 2018-08-26 22:48:16 -04:00
unit test app: Require 4MB flash PSRAM config unit tests had outgrown the 0x14000 byte allocated factory size. 2018-05-24 22:16:26 -04:00			`# Flash Size`

Build & config: Remove the "make" build system The "make" build system was deprecated in v4.0 in favor of idf.py (cmake). The remaining support is removed in v5.0. 2021-11-04 10:28:07 -04:00			The unit test partition table assumes a 4MB flash size. When testing `-T all`, this additional factory app partition size is required.
unit test app: Require 4MB flash PSRAM config unit tests had outgrown the 0x14000 byte allocated factory size. 2018-05-24 22:16:26 -04:00
Build & config: Remove the "make" build system The "make" build system was deprecated in v4.0 in favor of idf.py (cmake). The remaining support is removed in v5.0. 2021-11-04 10:28:07 -04:00			If building unit tests to run on a smaller flash size, edit `partition_table_unit_tests_app.csv` and use `-T <component> <component> ...` or instead of `-T all` tests don't fit in a smaller factory app partition (exact size will depend on configured options).
unit test app: Require 4MB flash PSRAM config unit tests had outgrown the 0x14000 byte allocated factory size. 2018-05-24 22:16:26 -04:00
unit test runer: Add capability to use ![tag] to run all-tests-except-tag Mostly useful for running ![ignore] to skip ignored tests. 2017-05-10 03:22:30 -04:00			`# Running Unit Tests`

			`The unit test loader will prompt by showing a menu of available tests to run:`

			`* Type a number to run a single test.`
			* `*` to run all tests.
			* `[tagname]` to run tests with "tag"
			* `![tagname]` to run tests without "tag" (`![ignore]` is very useful as it runs all CI-enabled tests.)
			* `"test name here"` to run test with given name
unit-test-app: udpate CI related part to README 2018-05-22 02:33:35 -04:00
			`# Testing Unit Tests with CI`

ci: remove ttfw related files 2023-10-04 10:41:03 -04:00			`For now we prefer to use component-based unit test to test in CI. Running unit-test-app in CI is being deprecated.`