summaryrefslogtreecommitdiff
path: root/common/mock/README.md
diff options
context:
space:
mode:
authorJack Rosenthal <jrosenth@chromium.org>2021-11-04 12:11:58 -0600
committerCommit Bot <commit-bot@chromium.org>2021-11-05 04:22:34 +0000
commit252457d4b21f46889eebad61d4c0a65331919cec (patch)
tree01856c4d31d710b20e85a74c8d7b5836e35c3b98 /common/mock/README.md
parent08f5a1e6fc2c9467230444ac9b582dcf4d9f0068 (diff)
downloadchrome-ec-stabilize-14496.B-ish.tar.gz
In the interest of making long-term branch maintenance incur as little technical debt on us as possible, we should not maintain any files on the branch we are not actually using. This has the added effect of making it extremely clear when merging CLs from the main branch when changes have the possibility to affect us. The follow-on CL adds a convenience script to actually pull updates from the main branch and generate a CL for the update. BUG=b:204206272 BRANCH=ish TEST=make BOARD=arcada_ish && make BOARD=drallion_ish Signed-off-by: Jack Rosenthal <jrosenth@chromium.org> Change-Id: I17e4694c38219b5a0823e0a3e55a28d1348f4b18 Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3262038 Reviewed-by: Jett Rink <jettrink@chromium.org> Reviewed-by: Tom Hughes <tomhughes@chromium.org>
Diffstat (limited to 'common/mock/README.md')
-rw-r--r--common/mock/README.md88
1 files changed, 0 insertions, 88 deletions
diff --git a/common/mock/README.md b/common/mock/README.md
deleted file mode 100644
index c7695531b6..0000000000
--- a/common/mock/README.md
+++ /dev/null
@@ -1,88 +0,0 @@
-# Common Mocks
-
-This directory holds mock implementations for use in fuzzers and tests.
-
-Each mock is given some friendly build name, like ROLLBACK or FP_SENSOR. This
-name is defined in [common/mock/build.mk](build.mk) and referenced from unit
-tests and fuzzers' `.mocklist` file.
-
-## Creating a new mock
-
-* Add the mock source to [common/mock](/common/mock) and the optional header
- file to [include/mock](/include/mock). Header files are only necessary if
- you want to expose additional [mock control](#mock-controls)
- functions/variables. See the [Design Patterns](#design-patterns) section for
- more detail on design patterns.
-* Add a new entry in [common/mock/build.mk](build.mk) that is conditioned on
- your mock's name.
-
-If a unit test or fuzzer requests this mock, the build system will set the
-variable `HAS_MOCK_<BUILD_NAME>` to `y` at build time. This variable is used to
-conditionally include the mock source in [common/mock/build.mk](build.mk).
-
-Example line from [common/mock/build.mk](build.mk):
-
-```make
-# Mocks
-mock-$(HAS_MOCK_ROLLBACK) += mock/rollback_mock.o
-```
-
-## Using a mock
-
-Unit tests and fuzzers can request a particular mock by adding an entry to their
-`.mocklist` file. The mocklist file is similar to a `.tasklist` file, where it
-is named according to the test/fuzz's name followed by `.mocklist`, like
-`fpsensor.mocklist`. The mocklist file is optional, so you may need to create
-one.
-
-Example `.mocklist`:
-
-```c
-/* Copyright 2019 The Chromium OS Authors. All rights reserved.
- * Use of this source code is governed by a BSD-style license that can be
- * found in the LICENSE file.
- */
-
- #define CONFIG_TEST_MOCK_LIST \
- MOCK(ROLLBACK) \
- MOCK(FP_SENSOR)
-```
-
-If you need additional [mock control](#mock-controls) functionality, you may
-need to include the mock's header file, which is prepended with `mock/` in the
-include line.
-
-For example, to control the return values of the rollback mock:
-
-```c
-#include "mock/rollback_mock.h"
-
-void yourfunction() {
- mock_ctrl_rollback.get_secret_fail = true;
-}
-```
-
-## Mock Controls
-
-Mocks can change their behavior by exposing "mock controls".
-
-We do this, most commonly, by exposing an additional global struct per mock that
-acts as the settings for the mock implementation. The mock user can then modify
-fields of the struct to change the mock's behavior. For example, the
-`fp_sensor_init_return` field may control what value the mocked `fp_sensor_init`
-function returns.
-
-The declaration for these controls are specified in the mock's header file,
-which resides in [include/mock](/include/mock).
-
-## Design Patterns
-
-* When creating mock controls, consider placing all your mock parameters in
- one externally facing struct, like in
- [fp_sensor_mock.h](/include/mock/fp_sensor_mock.h). The primary reason for
- this is to allow the mock to be easily used by a fuzzer (write random bytes
- into the struct with memcpy).
-* When following the above pattern, please provide a macro for resetting
- default values for this struct, like in
- [fp_sensor_mock.h](/include/mock/fp_sensor_mock.h). This allows unit tests
- to quickly reset the mock state/parameters before each unrelated unit test.