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