sravan/system76-coreboot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Tidy up the English in the testing tutorial

Browse Source 
Tweak a few sentences noticed when reading this.

BUG=none
BRANCH=none
TEST=none

Change-Id: I0a072c83402bc551a6bbdb7cd7c55fc3505784b2
Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/77096
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Stefan Reinauer <stefan.reinauer@coreboot.org>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/77464
Reviewed-by: Martin L Roth <gaumless@gmail.com>
Reviewed-by: Patrick Georgi <patrick@coreboot.org>
Tested-by: Patrick Georgi <patrick@coreboot.org>
This commit is contained in:
Simon Glass
2023-08-08 13:30:31 -06:00
committed by Martin L Roth
parent d7c88c2308
commit aacf35cca3
1 changed files with 15 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
Documentation/tutorial/part3.md
View File

@@ -1,20 +1,20 @@
# Writing unit tests for coreboot # Writing unit tests for coreboot
## Introduction ## Introduction
General thoughts about unit testing coreboot can be found in [Unit General thoughts about unit testing coreboot can be found in
testing coreboot](../technotes/2020-03-unit-testing-coreboot.md). [Unit-testing coreboot](../technotes/2020-03-unit-testing-coreboot.md).
Additionally, [code coverage](../technotes/2021-05-code-coverage.md) Additionally, [code coverage](../technotes/2021-05-code-coverage.md)
support is available for unit tests. support is available for unit tests.
This document aims to guide developers through the process of adding and This document aims to guide developers through the process of adding and
writing unit tests for coreboot modules. writing unit tests for coreboot modules.
As an example of unit under test, `src/device/i2c.c` (referred hereafter As an example of unit-under-test, `src/device/i2c.c` (referred hereafter
as UUT "Unit Under Test") will be used. This is simple module, thus it as UUT "Unit Under Test") will be used. This is simple module, thus it
should be easy for the reader to focus solely on the testing logic, should be easy for the reader to focus solely on the testing logic,
without the need to spend too much time on digging deeply into the without the need to spend too much time on digging deeply into the
source code details and flow of operations. That being said, a good source code details and flow of operations. That being said, a good
understanding of what the unit under test is doing is crucial for understanding of what the unit-under-test is doing is crucial for
writing unit tests. writing unit tests.
This tutorial should also be helpful for developers who want to follow This tutorial should also be helpful for developers who want to follow
@@ -23,7 +23,7 @@ though TDD has a different work flow of building tests first, followed
by the code that satisfies them, the process of writing tests and adding by the code that satisfies them, the process of writing tests and adding
them to the tree is the same. them to the tree is the same.
## Analysis of unit under test ## Analysis of unit-under-test
First of all, it is necessary to precisely establish what we want to First of all, it is necessary to precisely establish what we want to
test in a particular module. Usually this will be an externally exposed test in a particular module. Usually this will be an externally exposed
API, which can be used by other modules. API, which can be used by other modules.
@@ -69,7 +69,7 @@ UUT and not on the other modules. While some software dependencies may
be hard to be mock (for example due to complicated dependencies) and be hard to be mock (for example due to complicated dependencies) and
thus should be simply linked into the test binaries, all hardware thus should be simply linked into the test binaries, all hardware
dependencies need to be mocked out, since in the user-space host dependencies need to be mocked out, since in the user-space host
environment, targets hardware is not available. environment, target hardware is not available.
```eval_rst ```eval_rst
.. admonition:: i2c-test example .. admonition:: i2c-test example
@@ -142,12 +142,12 @@ for coreboot `make unit-tests`.
make unit-tests make unit-tests
``` ```
When trying to build test binary, one can often see linker complains When trying to build test binary, one can often see the linker complaining
about `undefined reference` to couple of symbols. This is one of about `undefined reference` for a couple of symbols. This is one of the
solutions to determine all external dependencies of UUT - iteratively solutions to determine all external dependencies of UUT - iteratively
build test and resolve errors one by one. At this step, developer should build test and resolve errors one by one. At this step, developer should
decide either it's better to add an extra module to provide necessary decide either it's better to add an extra module to provide necessary
definitions or rather mock such dependency. Quick guide through adding definitions or rather mock such dependency. A quick guide about adding
mocks is provided later in this doc. mocks is provided later in this doc.
## Writing new tests ## Writing new tests
@@ -324,8 +324,8 @@ a described range.
.. admonition:: i2c-test example .. admonition:: i2c-test example
In our example, we may want to check that `platform_i2c_transfer` is In our example, we may want to check that `platform_i2c_transfer` is
fed with number of segments bigger than 0, each segment has flags fed with a number of segments bigger than 0, each segment has flags
which are in supported range and each segment has buf which is which are in the supported range and each segment has a buf which is
non-NULL. We are expecting such values for _every_ call, thus the non-NULL. We are expecting such values for _every_ call, thus the
last parameter in `expect*` macros is -1. last parameter in `expect*` macros is -1.
@@ -375,16 +375,16 @@ API documentation.
### Test runner ### Test runner
Finally, the developer needs to implement the test `main()` function. Finally, the developer needs to implement the test `main()` function.
All tests should be registered there and cmocka test runner invoked. All All tests should be registered there and the cmocka test runner invoked.
methods for invoking Cmocka test are described All methods for invoking Cmocka test are described
[here](https://api.cmocka.org/group__cmocka__exec.html). [here](https://api.cmocka.org/group__cmocka__exec.html).
```eval_rst ```eval_rst
.. admonition:: i2c-test example .. admonition:: i2c-test example
We don't need any extra setup and teardown functions for i2c-test, so We don't need any extra setup and teardown functions for i2c-test, so
let's simply register test for `i2c_read_field` and return from main let's simply register the test for `i2c_read_field` and return from
value which is output of Cmocka's runner (it returns number of tests main the output of Cmocka's runner (it returns number of tests
that failed). that failed).
.. code-block:: c .. code-block:: c