README.md
1# Tests for LVGL
2
3The tests in the folder can be run locally and automatically by GitHub CI.
4
5## Running locally
6
7### Requirements (Linux)
8
9Install requirements by:
10
11```sh
12scripts/install-prerequisites.sh
13```
14
15### Run test
161. Run all executable tests with `./tests/main.py test`.
172. Build all build-only tests with `./tests/main.py build`.
183. Clean prior test build, build all build-only tests,
19 run executable tests, and generate code coverage
20 report `./tests/main.py --clean --report build test`.
21
22For full information on running tests run: `./tests/main.py --help`.
23
24## Running automatically
25
26GitHub's CI automatically runs these tests on pushes and pull requests to `master` and `releasev8.*` branches.
27
28## Directory structure
29- `src` Source files of the tests
30 - `test_cases` The written tests,
31 - `test_runners` Generated automatically from the files in `test_cases`.
32 - other miscellaneous files and folders
33- `ref_imgs` - Reference images for screenshot compare
34- `report` - Coverage report. Generated if the `report` flag was passed to `./main.py`
35- `unity` Source files of the test engine
36
37## Add new tests
38
39### Create new test file
40New test needs to be added into the `src/test_cases` folder. The name of the files should look like `test_<name>.c`. The basic skeleton of a test file copy `_test_template.c`.
41
42### Asserts
43See the list of asserts [here](https://github.com/ThrowTheSwitch/Unity/blob/master/docs/UnityAssertionsReference.md).
44
45There are some custom, LVGL specific asserts:
46- `TEST_ASSERT_EQUAL_SCREENSHOT("image1.png")` Render the active screen and compare its content with an image in the `ref_imgs` folder.
47If the compare fails `lvgl/test_screenshot_error.h` is created with the content of the frame buffer as an image.
48To see the that image `#include "test_screenshot_error.h"` and call `test_screenshot_error_show();`.
49- `TEST_ASSERT_EQUAL_COLOR(color1, color2)` Compare two colors.
50
51### Adding new reference images
52The reference images can be taken by copy-pasting the test code in to LVGL simulator and saving the screen.
53LVGL needs to
54- 800x480 resolution
55- 32 bit color depth
56- `LV_USE_PERF_MONITOR` and `LV_USE_MEM_MONITOR` disabled
57- use the default theme, with the default color (don't set a theme manually)
58
