1Testing in U-Boot
2=================
3
4U-Boot has a large amount of code. This file describes how this code is
5tested and what tests you should write when adding a new feature.
6
7
8Running tests
9-------------
10
11To run most tests on sandbox, type this:
12
13    make check
14
15in the U-Boot directory. Note that only the pytest suite is run using this
16command.
17
18Some tests take ages to run. To run just the quick ones, type this:
19
20    make qcheck
21
22
23Sandbox
24-------
25U-Boot can be built as a user-space application (e.g. for Linux). This
26allows test to be executed without needing target hardware. The 'sandbox'
27target provides this feature and it is widely used in tests.
28
29
30Pytest Suite
31------------
32
33Many tests are available using the pytest suite, in test/py. This can run
34either on sandbox or on real hardware. It relies on the U-Boot console to
35inject test commands and check the result. It is slower to run than C code,
36but provides the ability to unify lots of tests and summarise their results.
37
38You can run the tests on sandbox with:
39
40	./test/py/test.py --bd sandbox --build
41
42This will produce HTML output in build-sandbox/test-log.html
43
44See test/py/README.md for more information about the pytest suite.
45
46
47tbot
48----
49
50Tbot provides a way to execute tests on target hardware. It is intended for
51trying out both U-Boot and Linux (and potentially other software) on a
52number of boards automatically. It can be used to create a continuous test
53environment. See http://www.tbot.tools for more information.
54
55
56Ad-hoc tests
57------------
58
59There are several ad-hoc tests which run outside the pytest environment:
60
61   test/fs	- File system test (shell script)
62   test/image	- FIT and legacy image tests (shell script and Python)
63   test/stdint	- A test that stdint.h can be used in U-Boot (shell script)
64   trace	- Test for the tracing feature (shell script)
65
66TODO: Move these into pytest.
67
68
69When to write tests
70-------------------
71
72If you add code to U-Boot without a test you are taking a risk. Even if you
73perform thorough manual testing at the time of submission, it may break when
74future changes are made to U-Boot. It may even break when applied to mainline,
75if other changes interact with it. A good mindset is that untested code
76probably doesn't work and should be deleted.
77
78You can assume that the Pytest suite will be run before patches are accepted
79to mainline, so this provides protection against future breakage.
80
81On the other hand there is quite a bit of code that is not covered with tests,
82or is covered sparingly. So here are some suggestions:
83
84- If you are adding a new uclass, add a sandbox driver and a test that uses it
85- If you are modifying code covered by an existing test, add a new test case
86  to cover your changes
87- If the code you are modifying has not tests, consider writing one. Even a
88  very basic test is useful, and may be picked up and enhanced by others. It
89  is much easier to add onto a test - writing a new large test can seem
90  daunting to most contributors.
91
92
93Future work
94-----------
95
96Converting existing shell scripts into pytest tests.
97