1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 Writing Tests 3 Writing Tests
4 ============= 4 =============
5 5
6 Test Cases 6 Test Cases
7 ---------- 7 ----------
8 8
9 The fundamental unit in KUnit is the test case 9 The fundamental unit in KUnit is the test case. A test case is a function with
10 the signature ``void (*)(struct kunit *test)`` 10 the signature ``void (*)(struct kunit *test)``. It calls the function under test
11 and then sets *expectations* for what should h 11 and then sets *expectations* for what should happen. For example:
12 12
13 .. code-block:: c 13 .. code-block:: c
14 14
15 void example_test_success(struct kunit 15 void example_test_success(struct kunit *test)
16 { 16 {
17 } 17 }
18 18
19 void example_test_failure(struct kunit 19 void example_test_failure(struct kunit *test)
20 { 20 {
21 KUNIT_FAIL(test, "This test ne 21 KUNIT_FAIL(test, "This test never passes.");
22 } 22 }
23 23
24 In the above example, ``example_test_success`` 24 In the above example, ``example_test_success`` always passes because it does
25 nothing; no expectations are set, and therefor 25 nothing; no expectations are set, and therefore all expectations pass. On the
26 other hand ``example_test_failure`` always fai 26 other hand ``example_test_failure`` always fails because it calls ``KUNIT_FAIL``,
27 which is a special expectation that logs a mes 27 which is a special expectation that logs a message and causes the test case to
28 fail. 28 fail.
29 29
30 Expectations 30 Expectations
31 ~~~~~~~~~~~~ 31 ~~~~~~~~~~~~
32 An *expectation* specifies that we expect a pi 32 An *expectation* specifies that we expect a piece of code to do something in a
33 test. An expectation is called like a function 33 test. An expectation is called like a function. A test is made by setting
34 expectations about the behavior of a piece of 34 expectations about the behavior of a piece of code under test. When one or more
35 expectations fail, the test case fails and inf 35 expectations fail, the test case fails and information about the failure is
36 logged. For example: 36 logged. For example:
37 37
38 .. code-block:: c 38 .. code-block:: c
39 39
40 void add_test_basic(struct kunit *test 40 void add_test_basic(struct kunit *test)
41 { 41 {
42 KUNIT_EXPECT_EQ(test, 1, add(1 42 KUNIT_EXPECT_EQ(test, 1, add(1, 0));
43 KUNIT_EXPECT_EQ(test, 2, add(1 43 KUNIT_EXPECT_EQ(test, 2, add(1, 1));
44 } 44 }
45 45
46 In the above example, ``add_test_basic`` makes 46 In the above example, ``add_test_basic`` makes a number of assertions about the
47 behavior of a function called ``add``. The fir 47 behavior of a function called ``add``. The first parameter is always of type
48 ``struct kunit *``, which contains information 48 ``struct kunit *``, which contains information about the current test context.
49 The second parameter, in this case, is what th 49 The second parameter, in this case, is what the value is expected to be. The
50 last value is what the value actually is. If ` 50 last value is what the value actually is. If ``add`` passes all of these
51 expectations, the test case, ``add_test_basic` 51 expectations, the test case, ``add_test_basic`` will pass; if any one of these
52 expectations fails, the test case will fail. 52 expectations fails, the test case will fail.
53 53
54 A test case *fails* when any expectation is vi 54 A test case *fails* when any expectation is violated; however, the test will
55 continue to run, and try other expectations un 55 continue to run, and try other expectations until the test case ends or is
56 otherwise terminated. This is as opposed to *a 56 otherwise terminated. This is as opposed to *assertions* which are discussed
57 later. 57 later.
58 58
59 To learn about more KUnit expectations, see Do 59 To learn about more KUnit expectations, see Documentation/dev-tools/kunit/api/test.rst.
60 60
61 .. note:: 61 .. note::
62 A single test case should be short, easy to 62 A single test case should be short, easy to understand, and focused on a
63 single behavior. 63 single behavior.
64 64
65 For example, if we want to rigorously test the 65 For example, if we want to rigorously test the ``add`` function above, create
66 additional tests cases which would test each p 66 additional tests cases which would test each property that an ``add`` function
67 should have as shown below: 67 should have as shown below:
68 68
69 .. code-block:: c 69 .. code-block:: c
70 70
71 void add_test_basic(struct kunit *test 71 void add_test_basic(struct kunit *test)
72 { 72 {
73 KUNIT_EXPECT_EQ(test, 1, add(1 73 KUNIT_EXPECT_EQ(test, 1, add(1, 0));
74 KUNIT_EXPECT_EQ(test, 2, add(1 74 KUNIT_EXPECT_EQ(test, 2, add(1, 1));
75 } 75 }
76 76
77 void add_test_negative(struct kunit *t 77 void add_test_negative(struct kunit *test)
78 { 78 {
79 KUNIT_EXPECT_EQ(test, 0, add(- 79 KUNIT_EXPECT_EQ(test, 0, add(-1, 1));
80 } 80 }
81 81
82 void add_test_max(struct kunit *test) 82 void add_test_max(struct kunit *test)
83 { 83 {
84 KUNIT_EXPECT_EQ(test, INT_MAX, 84 KUNIT_EXPECT_EQ(test, INT_MAX, add(0, INT_MAX));
85 KUNIT_EXPECT_EQ(test, -1, add( 85 KUNIT_EXPECT_EQ(test, -1, add(INT_MAX, INT_MIN));
86 } 86 }
87 87
88 void add_test_overflow(struct kunit *t 88 void add_test_overflow(struct kunit *test)
89 { 89 {
90 KUNIT_EXPECT_EQ(test, INT_MIN, 90 KUNIT_EXPECT_EQ(test, INT_MIN, add(INT_MAX, 1));
91 } 91 }
92 92
93 Assertions 93 Assertions
94 ~~~~~~~~~~ 94 ~~~~~~~~~~
95 95
96 An assertion is like an expectation, except th 96 An assertion is like an expectation, except that the assertion immediately
97 terminates the test case if the condition is n 97 terminates the test case if the condition is not satisfied. For example:
98 98
99 .. code-block:: c 99 .. code-block:: c
100 100
101 static void test_sort(struct kunit *te 101 static void test_sort(struct kunit *test)
102 { 102 {
103 int *a, i, r = 1; 103 int *a, i, r = 1;
104 a = kunit_kmalloc_array(test, 104 a = kunit_kmalloc_array(test, TEST_LEN, sizeof(*a), GFP_KERNEL);
105 KUNIT_ASSERT_NOT_ERR_OR_NULL(t 105 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, a);
106 for (i = 0; i < TEST_LEN; i++) 106 for (i = 0; i < TEST_LEN; i++) {
107 r = (r * 725861) % 659 107 r = (r * 725861) % 6599;
108 a[i] = r; 108 a[i] = r;
109 } 109 }
110 sort(a, TEST_LEN, sizeof(*a), 110 sort(a, TEST_LEN, sizeof(*a), cmpint, NULL);
111 for (i = 0; i < TEST_LEN-1; i+ 111 for (i = 0; i < TEST_LEN-1; i++)
112 KUNIT_EXPECT_LE(test, 112 KUNIT_EXPECT_LE(test, a[i], a[i + 1]);
113 } 113 }
114 114
115 In this example, we need to be able to allocat !! 115 In this example, the method under test should return pointer to a value. If the
116 function. So we use ``KUNIT_ASSERT_NOT_ERR_OR_ !! 116 pointer returns null or an errno, we want to stop the test since the following
117 there's an allocation error. !! 117 expectation could crash the test case. `ASSERT_NOT_ERR_OR_NULL(...)` allows us
118 !! 118 to bail out of the test case if the appropriate conditions are not satisfied to
119 .. note:: !! 119 complete the test.
120 In other test frameworks, ``ASSERT`` macros <<
121 ``return`` so they only work from the test <<
122 current kthread on failure, so you can call <<
123 <<
124 .. note:: <<
125 Warning: There is an exception to the above <<
126 in the suite's exit() function, or in the f <<
127 run when a test is shutting down, and an as <<
128 cleanup code from running, potentially lead <<
129 <<
130 Customizing error messages <<
131 -------------------------- <<
132 <<
133 Each of the ``KUNIT_EXPECT`` and ``KUNIT_ASSER <<
134 variant. These take a format string and argum <<
135 context to the automatically generated error m <<
136 <<
137 .. code-block:: c <<
138 <<
139 char some_str[41]; <<
140 generate_sha1_hex_string(some_str); <<
141 <<
142 /* Before. Not easy to tell why the te <<
143 KUNIT_EXPECT_EQ(test, strlen(some_str) <<
144 <<
145 /* After. Now we see the offending str <<
146 KUNIT_EXPECT_EQ_MSG(test, strlen(some_ <<
147 <<
148 Alternatively, one can take full control over <<
149 ``KUNIT_FAIL()``, e.g. <<
150 <<
151 .. code-block:: c <<
152 <<
153 /* Before */ <<
154 KUNIT_EXPECT_EQ(test, some_setup_funct <<
155 <<
156 /* After: full control over the failur <<
157 if (some_setup_function()) <<
158 KUNIT_FAIL(test, "Failed to se <<
159 <<
160 120
161 Test Suites 121 Test Suites
162 ~~~~~~~~~~~ 122 ~~~~~~~~~~~
163 123
164 We need many test cases covering all the unit' 124 We need many test cases covering all the unit's behaviors. It is common to have
165 many similar tests. In order to reduce duplica 125 many similar tests. In order to reduce duplication in these closely related
166 tests, most unit testing frameworks (including 126 tests, most unit testing frameworks (including KUnit) provide the concept of a
167 *test suite*. A test suite is a collection of 127 *test suite*. A test suite is a collection of test cases for a unit of code
168 with optional setup and teardown functions tha 128 with optional setup and teardown functions that run before/after the whole
169 suite and/or every test case. !! 129 suite and/or every test case. For example:
170 <<
171 .. note:: <<
172 A test case will only run if it is associat <<
173 <<
174 For example: <<
175 130
176 .. code-block:: c 131 .. code-block:: c
177 132
178 static struct kunit_case example_test_ 133 static struct kunit_case example_test_cases[] = {
179 KUNIT_CASE(example_test_foo), 134 KUNIT_CASE(example_test_foo),
180 KUNIT_CASE(example_test_bar), 135 KUNIT_CASE(example_test_bar),
181 KUNIT_CASE(example_test_baz), 136 KUNIT_CASE(example_test_baz),
182 {} 137 {}
183 }; 138 };
184 139
185 static struct kunit_suite example_test 140 static struct kunit_suite example_test_suite = {
186 .name = "example", 141 .name = "example",
187 .init = example_test_init, 142 .init = example_test_init,
188 .exit = example_test_exit, 143 .exit = example_test_exit,
189 .suite_init = example_suite_in 144 .suite_init = example_suite_init,
190 .suite_exit = example_suite_ex 145 .suite_exit = example_suite_exit,
191 .test_cases = example_test_cas 146 .test_cases = example_test_cases,
192 }; 147 };
193 kunit_test_suite(example_test_suite); 148 kunit_test_suite(example_test_suite);
194 149
195 In the above example, the test suite ``example 150 In the above example, the test suite ``example_test_suite`` would first run
196 ``example_suite_init``, then run the test case 151 ``example_suite_init``, then run the test cases ``example_test_foo``,
197 ``example_test_bar``, and ``example_test_baz`` 152 ``example_test_bar``, and ``example_test_baz``. Each would have
198 ``example_test_init`` called immediately befor 153 ``example_test_init`` called immediately before it and ``example_test_exit``
199 called immediately after it. Finally, ``exampl 154 called immediately after it. Finally, ``example_suite_exit`` would be called
200 after everything else. ``kunit_test_suite(exam 155 after everything else. ``kunit_test_suite(example_test_suite)`` registers the
201 test suite with the KUnit test framework. 156 test suite with the KUnit test framework.
202 157
203 .. note:: 158 .. note::
204 The ``exit`` and ``suite_exit`` functions w !! 159 A test case will only run if it is associated with a test suite.
205 ``suite_init`` fail. Make sure that they ca <<
206 state which may result from ``init`` or ``s <<
207 or exiting early. <<
208 160
209 ``kunit_test_suite(...)`` is a macro which tel 161 ``kunit_test_suite(...)`` is a macro which tells the linker to put the
210 specified test suite in a special linker secti 162 specified test suite in a special linker section so that it can be run by KUnit
211 either after ``late_init``, or when the test m 163 either after ``late_init``, or when the test module is loaded (if the test was
212 built as a module). 164 built as a module).
213 165
214 For more information, see Documentation/dev-to 166 For more information, see Documentation/dev-tools/kunit/api/test.rst.
215 167
216 .. _kunit-on-non-uml: <<
217 <<
218 Writing Tests For Other Architectures 168 Writing Tests For Other Architectures
219 ------------------------------------- 169 -------------------------------------
220 170
221 It is better to write tests that run on UML to 171 It is better to write tests that run on UML to tests that only run under a
222 particular architecture. It is better to write 172 particular architecture. It is better to write tests that run under QEMU or
223 another easy to obtain (and monetarily free) s 173 another easy to obtain (and monetarily free) software environment to a specific
224 piece of hardware. 174 piece of hardware.
225 175
226 Nevertheless, there are still valid reasons to 176 Nevertheless, there are still valid reasons to write a test that is architecture
227 or hardware specific. For example, we might wa 177 or hardware specific. For example, we might want to test code that really
228 belongs in ``arch/some-arch/*``. Even so, try 178 belongs in ``arch/some-arch/*``. Even so, try to write the test so that it does
229 not depend on physical hardware. Some of our t 179 not depend on physical hardware. Some of our test cases may not need hardware,
230 only few tests actually require the hardware t 180 only few tests actually require the hardware to test it. When hardware is not
231 available, instead of disabling tests, we can 181 available, instead of disabling tests, we can skip them.
232 182
233 Now that we have narrowed down exactly what bi 183 Now that we have narrowed down exactly what bits are hardware specific, the
234 actual procedure for writing and running the t 184 actual procedure for writing and running the tests is same as writing normal
235 KUnit tests. 185 KUnit tests.
236 186
237 .. important:: 187 .. important::
238 We may have to reset hardware state. If thi 188 We may have to reset hardware state. If this is not possible, we may only
239 be able to run one test case per invocation 189 be able to run one test case per invocation.
240 190
241 .. TODO(brendanhiggins@google.com): Add an act 191 .. TODO(brendanhiggins@google.com): Add an actual example of an architecture-
242 dependent KUnit test. 192 dependent KUnit test.
243 193
244 Common Patterns 194 Common Patterns
245 =============== 195 ===============
246 196
247 Isolating Behavior 197 Isolating Behavior
248 ------------------ 198 ------------------
249 199
250 Unit testing limits the amount of code under t 200 Unit testing limits the amount of code under test to a single unit. It controls
251 what code gets run when the unit under test ca 201 what code gets run when the unit under test calls a function. Where a function
252 is exposed as part of an API such that the def 202 is exposed as part of an API such that the definition of that function can be
253 changed without affecting the rest of the code 203 changed without affecting the rest of the code base. In the kernel, this comes
254 from two constructs: classes, which are struct 204 from two constructs: classes, which are structs that contain function pointers
255 provided by the implementer, and architecture- 205 provided by the implementer, and architecture-specific functions, which have
256 definitions selected at compile time. 206 definitions selected at compile time.
257 207
258 Classes 208 Classes
259 ~~~~~~~ 209 ~~~~~~~
260 210
261 Classes are not a construct that is built into 211 Classes are not a construct that is built into the C programming language;
262 however, it is an easily derived concept. Acco 212 however, it is an easily derived concept. Accordingly, in most cases, every
263 project that does not use a standardized objec 213 project that does not use a standardized object oriented library (like GNOME's
264 GObject) has their own slightly different way 214 GObject) has their own slightly different way of doing object oriented
265 programming; the Linux kernel is no exception. 215 programming; the Linux kernel is no exception.
266 216
267 The central concept in kernel object oriented 217 The central concept in kernel object oriented programming is the class. In the
268 kernel, a *class* is a struct that contains fu 218 kernel, a *class* is a struct that contains function pointers. This creates a
269 contract between *implementers* and *users* si 219 contract between *implementers* and *users* since it forces them to use the
270 same function signature without having to call 220 same function signature without having to call the function directly. To be a
271 class, the function pointers must specify that 221 class, the function pointers must specify that a pointer to the class, known as
272 a *class handle*, be one of the parameters. Th 222 a *class handle*, be one of the parameters. Thus the member functions (also
273 known as *methods*) have access to member vari 223 known as *methods*) have access to member variables (also known as *fields*)
274 allowing the same implementation to have multi 224 allowing the same implementation to have multiple *instances*.
275 225
276 A class can be *overridden* by *child classes* 226 A class can be *overridden* by *child classes* by embedding the *parent class*
277 in the child class. Then when the child class 227 in the child class. Then when the child class *method* is called, the child
278 implementation knows that the pointer passed t 228 implementation knows that the pointer passed to it is of a parent contained
279 within the child. Thus, the child can compute 229 within the child. Thus, the child can compute the pointer to itself because the
280 pointer to the parent is always a fixed offset 230 pointer to the parent is always a fixed offset from the pointer to the child.
281 This offset is the offset of the parent contai 231 This offset is the offset of the parent contained in the child struct. For
282 example: 232 example:
283 233
284 .. code-block:: c 234 .. code-block:: c
285 235
286 struct shape { 236 struct shape {
287 int (*area)(struct shape *this 237 int (*area)(struct shape *this);
288 }; 238 };
289 239
290 struct rectangle { 240 struct rectangle {
291 struct shape parent; 241 struct shape parent;
292 int length; 242 int length;
293 int width; 243 int width;
294 }; 244 };
295 245
296 int rectangle_area(struct shape *this) 246 int rectangle_area(struct shape *this)
297 { 247 {
298 struct rectangle *self = conta 248 struct rectangle *self = container_of(this, struct rectangle, parent);
299 249
300 return self->length * self->wi 250 return self->length * self->width;
301 }; 251 };
302 252
303 void rectangle_new(struct rectangle *s 253 void rectangle_new(struct rectangle *self, int length, int width)
304 { 254 {
305 self->parent.area = rectangle_ 255 self->parent.area = rectangle_area;
306 self->length = length; 256 self->length = length;
307 self->width = width; 257 self->width = width;
308 } 258 }
309 259
310 In this example, computing the pointer to the 260 In this example, computing the pointer to the child from the pointer to the
311 parent is done by ``container_of``. 261 parent is done by ``container_of``.
312 262
313 Faking Classes 263 Faking Classes
314 ~~~~~~~~~~~~~~ 264 ~~~~~~~~~~~~~~
315 265
316 In order to unit test a piece of code that cal 266 In order to unit test a piece of code that calls a method in a class, the
317 behavior of the method must be controllable, o 267 behavior of the method must be controllable, otherwise the test ceases to be a
318 unit test and becomes an integration test. 268 unit test and becomes an integration test.
319 269
320 A fake class implements a piece of code that i 270 A fake class implements a piece of code that is different than what runs in a
321 production instance, but behaves identical fro 271 production instance, but behaves identical from the standpoint of the callers.
322 This is done to replace a dependency that is h 272 This is done to replace a dependency that is hard to deal with, or is slow. For
323 example, implementing a fake EEPROM that store 273 example, implementing a fake EEPROM that stores the "contents" in an
324 internal buffer. Assume we have a class that r 274 internal buffer. Assume we have a class that represents an EEPROM:
325 275
326 .. code-block:: c 276 .. code-block:: c
327 277
328 struct eeprom { 278 struct eeprom {
329 ssize_t (*read)(struct eeprom 279 ssize_t (*read)(struct eeprom *this, size_t offset, char *buffer, size_t count);
330 ssize_t (*write)(struct eeprom 280 ssize_t (*write)(struct eeprom *this, size_t offset, const char *buffer, size_t count);
331 }; 281 };
332 282
333 And we want to test code that buffers writes t 283 And we want to test code that buffers writes to the EEPROM:
334 284
335 .. code-block:: c 285 .. code-block:: c
336 286
337 struct eeprom_buffer { 287 struct eeprom_buffer {
338 ssize_t (*write)(struct eeprom 288 ssize_t (*write)(struct eeprom_buffer *this, const char *buffer, size_t count);
339 int flush(struct eeprom_buffer 289 int flush(struct eeprom_buffer *this);
340 size_t flush_count; /* Flushes 290 size_t flush_count; /* Flushes when buffer exceeds flush_count. */
341 }; 291 };
342 292
343 struct eeprom_buffer *new_eeprom_buffe 293 struct eeprom_buffer *new_eeprom_buffer(struct eeprom *eeprom);
344 void destroy_eeprom_buffer(struct eepr 294 void destroy_eeprom_buffer(struct eeprom *eeprom);
345 295
346 We can test this code by *faking out* the unde 296 We can test this code by *faking out* the underlying EEPROM:
347 297
348 .. code-block:: c 298 .. code-block:: c
349 299
350 struct fake_eeprom { 300 struct fake_eeprom {
351 struct eeprom parent; 301 struct eeprom parent;
352 char contents[FAKE_EEPROM_CONT 302 char contents[FAKE_EEPROM_CONTENTS_SIZE];
353 }; 303 };
354 304
355 ssize_t fake_eeprom_read(struct eeprom 305 ssize_t fake_eeprom_read(struct eeprom *parent, size_t offset, char *buffer, size_t count)
356 { 306 {
357 struct fake_eeprom *this = con 307 struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);
358 308
359 count = min(count, FAKE_EEPROM 309 count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
360 memcpy(buffer, this->contents 310 memcpy(buffer, this->contents + offset, count);
361 311
362 return count; 312 return count;
363 } 313 }
364 314
365 ssize_t fake_eeprom_write(struct eepro 315 ssize_t fake_eeprom_write(struct eeprom *parent, size_t offset, const char *buffer, size_t count)
366 { 316 {
367 struct fake_eeprom *this = con 317 struct fake_eeprom *this = container_of(parent, struct fake_eeprom, parent);
368 318
369 count = min(count, FAKE_EEPROM 319 count = min(count, FAKE_EEPROM_CONTENTS_SIZE - offset);
370 memcpy(this->contents + offset 320 memcpy(this->contents + offset, buffer, count);
371 321
372 return count; 322 return count;
373 } 323 }
374 324
375 void fake_eeprom_init(struct fake_eepr 325 void fake_eeprom_init(struct fake_eeprom *this)
376 { 326 {
377 this->parent.read = fake_eepro 327 this->parent.read = fake_eeprom_read;
378 this->parent.write = fake_eepr 328 this->parent.write = fake_eeprom_write;
379 memset(this->contents, 0, FAKE 329 memset(this->contents, 0, FAKE_EEPROM_CONTENTS_SIZE);
380 } 330 }
381 331
382 We can now use it to test ``struct eeprom_buff 332 We can now use it to test ``struct eeprom_buffer``:
383 333
384 .. code-block:: c 334 .. code-block:: c
385 335
386 struct eeprom_buffer_test { 336 struct eeprom_buffer_test {
387 struct fake_eeprom *fake_eepro 337 struct fake_eeprom *fake_eeprom;
388 struct eeprom_buffer *eeprom_b 338 struct eeprom_buffer *eeprom_buffer;
389 }; 339 };
390 340
391 static void eeprom_buffer_test_does_no 341 static void eeprom_buffer_test_does_not_write_until_flush(struct kunit *test)
392 { 342 {
393 struct eeprom_buffer_test *ctx 343 struct eeprom_buffer_test *ctx = test->priv;
394 struct eeprom_buffer *eeprom_b 344 struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
395 struct fake_eeprom *fake_eepro 345 struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
396 char buffer[] = {0xff}; 346 char buffer[] = {0xff};
397 347
398 eeprom_buffer->flush_count = S 348 eeprom_buffer->flush_count = SIZE_MAX;
399 349
400 eeprom_buffer->write(eeprom_bu 350 eeprom_buffer->write(eeprom_buffer, buffer, 1);
401 KUNIT_EXPECT_EQ(test, fake_eep 351 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
402 352
403 eeprom_buffer->write(eeprom_bu 353 eeprom_buffer->write(eeprom_buffer, buffer, 1);
404 KUNIT_EXPECT_EQ(test, fake_eep 354 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0);
405 355
406 eeprom_buffer->flush(eeprom_bu 356 eeprom_buffer->flush(eeprom_buffer);
407 KUNIT_EXPECT_EQ(test, fake_eep 357 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
408 KUNIT_EXPECT_EQ(test, fake_eep 358 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
409 } 359 }
410 360
411 static void eeprom_buffer_test_flushes 361 static void eeprom_buffer_test_flushes_after_flush_count_met(struct kunit *test)
412 { 362 {
413 struct eeprom_buffer_test *ctx 363 struct eeprom_buffer_test *ctx = test->priv;
414 struct eeprom_buffer *eeprom_b 364 struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
415 struct fake_eeprom *fake_eepro 365 struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
416 char buffer[] = {0xff}; 366 char buffer[] = {0xff};
417 367
418 eeprom_buffer->flush_count = 2 368 eeprom_buffer->flush_count = 2;
419 369
420 eeprom_buffer->write(eeprom_bu 370 eeprom_buffer->write(eeprom_buffer, buffer, 1);
421 KUNIT_EXPECT_EQ(test, fake_eep 371 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
422 372
423 eeprom_buffer->write(eeprom_bu 373 eeprom_buffer->write(eeprom_buffer, buffer, 1);
424 KUNIT_EXPECT_EQ(test, fake_eep 374 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
425 KUNIT_EXPECT_EQ(test, fake_eep 375 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
426 } 376 }
427 377
428 static void eeprom_buffer_test_flushes 378 static void eeprom_buffer_test_flushes_increments_of_flush_count(struct kunit *test)
429 { 379 {
430 struct eeprom_buffer_test *ctx 380 struct eeprom_buffer_test *ctx = test->priv;
431 struct eeprom_buffer *eeprom_b 381 struct eeprom_buffer *eeprom_buffer = ctx->eeprom_buffer;
432 struct fake_eeprom *fake_eepro 382 struct fake_eeprom *fake_eeprom = ctx->fake_eeprom;
433 char buffer[] = {0xff, 0xff}; 383 char buffer[] = {0xff, 0xff};
434 384
435 eeprom_buffer->flush_count = 2 385 eeprom_buffer->flush_count = 2;
436 386
437 eeprom_buffer->write(eeprom_bu 387 eeprom_buffer->write(eeprom_buffer, buffer, 1);
438 KUNIT_EXPECT_EQ(test, fake_eep 388 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0);
439 389
440 eeprom_buffer->write(eeprom_bu 390 eeprom_buffer->write(eeprom_buffer, buffer, 2);
441 KUNIT_EXPECT_EQ(test, fake_eep 391 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[0], 0xff);
442 KUNIT_EXPECT_EQ(test, fake_eep 392 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[1], 0xff);
443 /* Should have only flushed th 393 /* Should have only flushed the first two bytes. */
444 KUNIT_EXPECT_EQ(test, fake_eep 394 KUNIT_EXPECT_EQ(test, fake_eeprom->contents[2], 0);
445 } 395 }
446 396
447 static int eeprom_buffer_test_init(str 397 static int eeprom_buffer_test_init(struct kunit *test)
448 { 398 {
449 struct eeprom_buffer_test *ctx 399 struct eeprom_buffer_test *ctx;
450 400
451 ctx = kunit_kzalloc(test, size 401 ctx = kunit_kzalloc(test, sizeof(*ctx), GFP_KERNEL);
452 KUNIT_ASSERT_NOT_ERR_OR_NULL(t 402 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx);
453 403
454 ctx->fake_eeprom = kunit_kzall 404 ctx->fake_eeprom = kunit_kzalloc(test, sizeof(*ctx->fake_eeprom), GFP_KERNEL);
455 KUNIT_ASSERT_NOT_ERR_OR_NULL(t 405 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->fake_eeprom);
456 fake_eeprom_init(ctx->fake_eep 406 fake_eeprom_init(ctx->fake_eeprom);
457 407
458 ctx->eeprom_buffer = new_eepro 408 ctx->eeprom_buffer = new_eeprom_buffer(&ctx->fake_eeprom->parent);
459 KUNIT_ASSERT_NOT_ERR_OR_NULL(t 409 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->eeprom_buffer);
460 410
461 test->priv = ctx; 411 test->priv = ctx;
462 412
463 return 0; 413 return 0;
464 } 414 }
465 415
466 static void eeprom_buffer_test_exit(st 416 static void eeprom_buffer_test_exit(struct kunit *test)
467 { 417 {
468 struct eeprom_buffer_test *ctx 418 struct eeprom_buffer_test *ctx = test->priv;
469 419
470 destroy_eeprom_buffer(ctx->eep 420 destroy_eeprom_buffer(ctx->eeprom_buffer);
471 } 421 }
472 422
473 Testing Against Multiple Inputs 423 Testing Against Multiple Inputs
474 ------------------------------- 424 -------------------------------
475 425
476 Testing just a few inputs is not enough to ens 426 Testing just a few inputs is not enough to ensure that the code works correctly,
477 for example: testing a hash function. 427 for example: testing a hash function.
478 428
479 We can write a helper macro or function. The f 429 We can write a helper macro or function. The function is called for each input.
480 For example, to test ``sha1sum(1)``, we can wr 430 For example, to test ``sha1sum(1)``, we can write:
481 431
482 .. code-block:: c 432 .. code-block:: c
483 433
484 #define TEST_SHA1(in, want) \ 434 #define TEST_SHA1(in, want) \
485 sha1sum(in, out); \ 435 sha1sum(in, out); \
486 KUNIT_EXPECT_STREQ_MSG(test, o 436 KUNIT_EXPECT_STREQ_MSG(test, out, want, "sha1sum(%s)", in);
487 437
488 char out[40]; 438 char out[40];
489 TEST_SHA1("hello world", "2aae6c35c94 439 TEST_SHA1("hello world", "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed");
490 TEST_SHA1("hello world!", "430ce34d020 440 TEST_SHA1("hello world!", "430ce34d020724ed75a196dfc2ad67c77772d169");
491 441
492 Note the use of the ``_MSG`` version of ``KUNI 442 Note the use of the ``_MSG`` version of ``KUNIT_EXPECT_STREQ`` to print a more
493 detailed error and make the assertions clearer 443 detailed error and make the assertions clearer within the helper macros.
494 444
495 The ``_MSG`` variants are useful when the same 445 The ``_MSG`` variants are useful when the same expectation is called multiple
496 times (in a loop or helper function) and thus 446 times (in a loop or helper function) and thus the line number is not enough to
497 identify what failed, as shown below. 447 identify what failed, as shown below.
498 448
499 In complicated cases, we recommend using a *ta 449 In complicated cases, we recommend using a *table-driven test* compared to the
500 helper macro variation, for example: 450 helper macro variation, for example:
501 451
502 .. code-block:: c 452 .. code-block:: c
503 453
504 int i; 454 int i;
505 char out[40]; 455 char out[40];
506 456
507 struct sha1_test_case { 457 struct sha1_test_case {
508 const char *str; 458 const char *str;
509 const char *sha1; 459 const char *sha1;
510 }; 460 };
511 461
512 struct sha1_test_case cases[] = { 462 struct sha1_test_case cases[] = {
513 { 463 {
514 .str = "hello world", 464 .str = "hello world",
515 .sha1 = "2aae6c35c94fc 465 .sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
516 }, 466 },
517 { 467 {
518 .str = "hello world!", 468 .str = "hello world!",
519 .sha1 = "430ce34d02072 469 .sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",
520 }, 470 },
521 }; 471 };
522 for (i = 0; i < ARRAY_SIZE(cases); ++i 472 for (i = 0; i < ARRAY_SIZE(cases); ++i) {
523 sha1sum(cases[i].str, out); 473 sha1sum(cases[i].str, out);
524 KUNIT_EXPECT_STREQ_MSG(test, o 474 KUNIT_EXPECT_STREQ_MSG(test, out, cases[i].sha1,
525 "sha1sum 475 "sha1sum(%s)", cases[i].str);
526 } 476 }
527 477
528 478
529 There is more boilerplate code involved, but i 479 There is more boilerplate code involved, but it can:
530 480
531 * be more readable when there are multiple inp 481 * be more readable when there are multiple inputs/outputs (due to field names).
532 482
533 * For example, see ``fs/ext4/inode-test.c``. 483 * For example, see ``fs/ext4/inode-test.c``.
534 484
535 * reduce duplication if test cases are shared 485 * reduce duplication if test cases are shared across multiple tests.
536 486
537 * For example: if we want to test ``sha256su 487 * For example: if we want to test ``sha256sum``, we could add a ``sha256``
538 field and reuse ``cases``. 488 field and reuse ``cases``.
539 489
540 * be converted to a "parameterized test". 490 * be converted to a "parameterized test".
541 491
542 Parameterized Testing 492 Parameterized Testing
543 ~~~~~~~~~~~~~~~~~~~~~ 493 ~~~~~~~~~~~~~~~~~~~~~
544 494
545 The table-driven testing pattern is common eno 495 The table-driven testing pattern is common enough that KUnit has special
546 support for it. 496 support for it.
547 497
548 By reusing the same ``cases`` array from above 498 By reusing the same ``cases`` array from above, we can write the test as a
549 "parameterized test" with the following. 499 "parameterized test" with the following.
550 500
551 .. code-block:: c 501 .. code-block:: c
552 502
553 // This is copy-pasted from above. 503 // This is copy-pasted from above.
554 struct sha1_test_case { 504 struct sha1_test_case {
555 const char *str; 505 const char *str;
556 const char *sha1; 506 const char *sha1;
557 }; 507 };
558 const struct sha1_test_case cases[] = !! 508 struct sha1_test_case cases[] = {
559 { 509 {
560 .str = "hello world", 510 .str = "hello world",
561 .sha1 = "2aae6c35c94fc 511 .sha1 = "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
562 }, 512 },
563 { 513 {
564 .str = "hello world!", 514 .str = "hello world!",
565 .sha1 = "430ce34d02072 515 .sha1 = "430ce34d020724ed75a196dfc2ad67c77772d169",
566 }, 516 },
567 }; 517 };
568 518
569 // Creates `sha1_gen_params()` to iter !! 519 // Need a helper function to generate a name for each test case.
570 // the struct member `str` for the cas !! 520 static void case_to_desc(const struct sha1_test_case *t, char *desc)
571 KUNIT_ARRAY_PARAM_DESC(sha1, cases, st !! 521 {
>> 522 strcpy(desc, t->str);
>> 523 }
>> 524 // Creates `sha1_gen_params()` to iterate over `cases`.
>> 525 KUNIT_ARRAY_PARAM(sha1, cases, case_to_desc);
572 526
573 // Looks no different from a normal te 527 // Looks no different from a normal test.
574 static void sha1_test(struct kunit *te 528 static void sha1_test(struct kunit *test)
575 { 529 {
576 // This function can just cont 530 // This function can just contain the body of the for-loop.
577 // The former `cases[i]` is ac 531 // The former `cases[i]` is accessible under test->param_value.
578 char out[40]; 532 char out[40];
579 struct sha1_test_case *test_pa 533 struct sha1_test_case *test_param = (struct sha1_test_case *)(test->param_value);
580 534
581 sha1sum(test_param->str, out); 535 sha1sum(test_param->str, out);
582 KUNIT_EXPECT_STREQ_MSG(test, o 536 KUNIT_EXPECT_STREQ_MSG(test, out, test_param->sha1,
583 "sha1sum 537 "sha1sum(%s)", test_param->str);
584 } 538 }
585 539
586 // Instead of KUNIT_CASE, we use KUNIT 540 // Instead of KUNIT_CASE, we use KUNIT_CASE_PARAM and pass in the
587 // function declared by KUNIT_ARRAY_PA !! 541 // function declared by KUNIT_ARRAY_PARAM.
588 static struct kunit_case sha1_test_cas 542 static struct kunit_case sha1_test_cases[] = {
589 KUNIT_CASE_PARAM(sha1_test, sh 543 KUNIT_CASE_PARAM(sha1_test, sha1_gen_params),
590 {} 544 {}
591 }; 545 };
592 546
>> 547 .. _kunit-on-non-uml:
>> 548
>> 549 Exiting Early on Failed Expectations
>> 550 ------------------------------------
>> 551
>> 552 We can use ``KUNIT_EXPECT_EQ`` to mark the test as failed and continue
>> 553 execution. In some cases, it is unsafe to continue. We can use the
>> 554 ``KUNIT_ASSERT`` variant to exit on failure.
>> 555
>> 556 .. code-block:: c
>> 557
>> 558 void example_test_user_alloc_function(struct kunit *test)
>> 559 {
>> 560 void *object = alloc_some_object_for_me();
>> 561
>> 562 /* Make sure we got a valid pointer back. */
>> 563 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, object);
>> 564 do_something_with_object(object);
>> 565 }
>> 566
593 Allocating Memory 567 Allocating Memory
594 ----------------- 568 -----------------
595 569
596 Where you might use ``kzalloc``, you can inste 570 Where you might use ``kzalloc``, you can instead use ``kunit_kzalloc`` as KUnit
597 will then ensure that the memory is freed once 571 will then ensure that the memory is freed once the test completes.
598 572
599 This is useful because it lets us use the ``KU 573 This is useful because it lets us use the ``KUNIT_ASSERT_EQ`` macros to exit
600 early from a test without having to worry abou 574 early from a test without having to worry about remembering to call ``kfree``.
601 For example: 575 For example:
602 576
603 .. code-block:: c 577 .. code-block:: c
604 578
605 void example_test_allocation(struct ku 579 void example_test_allocation(struct kunit *test)
606 { 580 {
607 char *buffer = kunit_kzalloc(t 581 char *buffer = kunit_kzalloc(test, 16, GFP_KERNEL);
608 /* Ensure allocation succeeded 582 /* Ensure allocation succeeded. */
609 KUNIT_ASSERT_NOT_ERR_OR_NULL(t 583 KUNIT_ASSERT_NOT_ERR_OR_NULL(test, buffer);
610 584
611 KUNIT_ASSERT_STREQ(test, buffe 585 KUNIT_ASSERT_STREQ(test, buffer, "");
612 } 586 }
613 587
614 Registering Cleanup Actions <<
615 --------------------------- <<
616 <<
617 If you need to perform some cleanup beyond sim <<
618 you can register a custom "deferred action", w <<
619 run when the test exits (whether cleanly, or v <<
620 <<
621 Actions are simple functions with no return va <<
622 context argument, and fulfill the same role as <<
623 and Go tests, "defer" statements in languages <<
624 (in some cases) destructors in RAII languages. <<
625 <<
626 These are very useful for unregistering things <<
627 files or other resources, or freeing resources <<
628 <<
629 For example: <<
630 <<
631 .. code-block:: C <<
632 <<
633 static void cleanup_device(void *ctx) <<
634 { <<
635 struct device *dev = (struct d <<
636 <<
637 device_unregister(dev); <<
638 } <<
639 <<
640 void example_device_test(struct kunit <<
641 { <<
642 struct my_device dev; <<
643 <<
644 device_register(&dev); <<
645 <<
646 kunit_add_action(test, &cleanu <<
647 } <<
648 <<
649 Note that, for functions like device_unregiste <<
650 pointer-sized argument, it's possible to autom <<
651 with the ``KUNIT_DEFINE_ACTION_WRAPPER()`` mac <<
652 <<
653 .. code-block:: C <<
654 <<
655 KUNIT_DEFINE_ACTION_WRAPPER(device_unr <<
656 kunit_add_action(test, &device_unregis <<
657 <<
658 You should do this in preference to manually c <<
659 as casting function pointers will break Contro <<
660 <<
661 ``kunit_add_action`` can fail if, for example, <<
662 You can use ``kunit_add_action_or_reset`` inst <<
663 immediately if it cannot be deferred. <<
664 <<
665 If you need more control over when the cleanup <<
666 can trigger it early using ``kunit_release_act <<
667 with ``kunit_remove_action``. <<
668 <<
669 588
670 Testing Static Functions 589 Testing Static Functions
671 ------------------------ 590 ------------------------
672 591
673 If we do not want to expose functions or varia 592 If we do not want to expose functions or variables for testing, one option is to
674 conditionally export the used symbol. For exam !! 593 conditionally ``#include`` the test file at the end of your .c file. For
675 !! 594 example:
676 .. code-block:: c <<
677 <<
678 /* In my_file.c */ <<
679 <<
680 VISIBLE_IF_KUNIT int do_interesting_th <<
681 EXPORT_SYMBOL_IF_KUNIT(do_interesting_ <<
682 <<
683 /* In my_file.h */ <<
684 <<
685 #if IS_ENABLED(CONFIG_KUNIT) <<
686 int do_interesting_thing(void) <<
687 #endif <<
688 <<
689 Alternatively, you could conditionally ``#incl <<
690 your .c file. For example: <<
691 595
692 .. code-block:: c 596 .. code-block:: c
693 597
694 /* In my_file.c */ 598 /* In my_file.c */
695 599
696 static int do_interesting_thing(); 600 static int do_interesting_thing();
697 601
698 #ifdef CONFIG_MY_KUNIT_TEST 602 #ifdef CONFIG_MY_KUNIT_TEST
699 #include "my_kunit_test.c" 603 #include "my_kunit_test.c"
700 #endif 604 #endif
701 605
702 Injecting Test-Only Code 606 Injecting Test-Only Code
703 ------------------------ 607 ------------------------
704 608
705 Similar to as shown above, we can add test-spe 609 Similar to as shown above, we can add test-specific logic. For example:
706 610
707 .. code-block:: c 611 .. code-block:: c
708 612
709 /* In my_file.h */ 613 /* In my_file.h */
710 614
711 #ifdef CONFIG_MY_KUNIT_TEST 615 #ifdef CONFIG_MY_KUNIT_TEST
712 /* Defined in my_kunit_test.c */ 616 /* Defined in my_kunit_test.c */
713 void test_only_hook(void); 617 void test_only_hook(void);
714 #else 618 #else
715 void test_only_hook(void) { } 619 void test_only_hook(void) { }
716 #endif 620 #endif
717 621
718 This test-only code can be made more useful by 622 This test-only code can be made more useful by accessing the current ``kunit_test``
719 as shown in next section: *Accessing The Curre 623 as shown in next section: *Accessing The Current Test*.
720 624
721 Accessing The Current Test 625 Accessing The Current Test
722 -------------------------- 626 --------------------------
723 627
724 In some cases, we need to call test-only code !! 628 In some cases, we need to call test-only code from outside the test file.
725 is helpful, for example, when providing a fake !! 629 For example, see example in section *Injecting Test-Only Code* or if
726 to fail any current test from within an error !! 630 we are providing a fake implementation of an ops struct. Using
727 We can do this via the ``kunit_test`` field in !! 631 ``kunit_test`` field in ``task_struct``, we can access it via
728 access using the ``kunit_get_current_test()`` !! 632 ``current->kunit_test``.
729 <<
730 ``kunit_get_current_test()`` is safe to call e <<
731 KUnit is not enabled, or if no test is running <<
732 return ``NULL``. This compiles down to either <<
733 so will have a negligible performance impact w <<
734 633
735 The example below uses this to implement a "mo !! 634 The example below includes how to implement "mocking":
736 635
737 .. code-block:: c 636 .. code-block:: c
738 637
739 #include <kunit/test-bug.h> /* for kun !! 638 #include <linux/sched.h> /* for current */
740 639
741 struct test_data { 640 struct test_data {
742 int foo_result; 641 int foo_result;
743 int want_foo_called_with; 642 int want_foo_called_with;
744 }; 643 };
745 644
746 static int fake_foo(int arg) 645 static int fake_foo(int arg)
747 { 646 {
748 struct kunit *test = kunit_get !! 647 struct kunit *test = current->kunit_test;
749 struct test_data *test_data = 648 struct test_data *test_data = test->priv;
750 649
751 KUNIT_EXPECT_EQ(test, test_dat 650 KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg);
752 return test_data->foo_result; 651 return test_data->foo_result;
753 } 652 }
754 653
755 static void example_simple_test(struct 654 static void example_simple_test(struct kunit *test)
756 { 655 {
757 /* Assume priv (private, a mem 656 /* Assume priv (private, a member used to pass test data from
758 * the init function) is alloc 657 * the init function) is allocated in the suite's .init */
759 struct test_data *test_data = 658 struct test_data *test_data = test->priv;
760 659
761 test_data->foo_result = 42; 660 test_data->foo_result = 42;
762 test_data->want_foo_called_wit 661 test_data->want_foo_called_with = 1;
763 662
764 /* In a real test, we'd probab 663 /* In a real test, we'd probably pass a pointer to fake_foo somewhere
765 * like an ops struct, etc. in 664 * like an ops struct, etc. instead of calling it directly. */
766 KUNIT_EXPECT_EQ(test, fake_foo 665 KUNIT_EXPECT_EQ(test, fake_foo(1), 42);
767 } 666 }
768 667
769 In this example, we are using the ``priv`` mem 668 In this example, we are using the ``priv`` member of ``struct kunit`` as a way
770 of passing data to the test from the init func 669 of passing data to the test from the init function. In general ``priv`` is
771 pointer that can be used for any user data. Th 670 pointer that can be used for any user data. This is preferred over static
772 variables, as it avoids concurrency issues. 671 variables, as it avoids concurrency issues.
773 672
774 Had we wanted something more flexible, we coul 673 Had we wanted something more flexible, we could have used a named ``kunit_resource``.
775 Each test can have multiple resources which ha 674 Each test can have multiple resources which have string names providing the same
776 flexibility as a ``priv`` member, but also, fo 675 flexibility as a ``priv`` member, but also, for example, allowing helper
777 functions to create resources without conflict 676 functions to create resources without conflicting with each other. It is also
778 possible to define a clean up function for eac 677 possible to define a clean up function for each resource, making it easy to
779 avoid resource leaks. For more information, se !! 678 avoid resource leaks. For more information, see Documentation/dev-tools/kunit/api/test.rst.
780 679
781 Failing The Current Test 680 Failing The Current Test
782 ------------------------ 681 ------------------------
783 682
784 If we want to fail the current test, we can us 683 If we want to fail the current test, we can use ``kunit_fail_current_test(fmt, args...)``
785 which is defined in ``<kunit/test-bug.h>`` and 684 which is defined in ``<kunit/test-bug.h>`` and does not require pulling in ``<kunit/test.h>``.
786 For example, we have an option to enable some 685 For example, we have an option to enable some extra debug checks on some data
787 structures as shown below: 686 structures as shown below:
788 687
789 .. code-block:: c 688 .. code-block:: c
790 689
791 #include <kunit/test-bug.h> 690 #include <kunit/test-bug.h>
792 691
793 #ifdef CONFIG_EXTRA_DEBUG_CHECKS 692 #ifdef CONFIG_EXTRA_DEBUG_CHECKS
794 static void validate_my_data(struct da 693 static void validate_my_data(struct data *data)
795 { 694 {
796 if (is_valid(data)) 695 if (is_valid(data))
797 return; 696 return;
798 697
799 kunit_fail_current_test("data 698 kunit_fail_current_test("data %p is invalid", data);
800 699
801 /* Normal, non-KUnit, error re 700 /* Normal, non-KUnit, error reporting code here. */
802 } 701 }
803 #else 702 #else
804 static void my_debug_function(void) { 703 static void my_debug_function(void) { }
805 #endif 704 #endif
806 705
807 ``kunit_fail_current_test()`` is safe to call <<
808 KUnit is not enabled, or if no test is running <<
809 nothing. This compiles down to either a no-op <<
810 have a negligible performance impact when no t <<
811 <<
812 Managing Fake Devices and Drivers <<
813 --------------------------------- <<
814 <<
815 When testing drivers or code which interacts w <<
816 require a ``struct device`` or ``struct device <<
817 up a real device is not required to test any g <<
818 can be used instead. <<
819 <<
820 KUnit provides helper functions to create and <<
821 are internally of type ``struct kunit_device`` <<
822 ``kunit_bus``. These devices support managed d <<
823 described in Documentation/driver-api/driver-m <<
824 <<
825 To create a KUnit-managed ``struct device_driv <<
826 which will create a driver with the given name <<
827 will automatically be destroyed when the corre <<
828 be manually destroyed with ``driver_unregister <<
829 <<
830 To create a fake device, use the ``kunit_devic <<
831 and register a device, using a new KUnit-manag <<
832 To provide a specific, non-KUnit-managed drive <<
833 instead. Like with managed drivers, KUnit-mana <<
834 cleaned up when the test finishes, but can be <<
835 ``kunit_device_unregister()``. <<
836 <<
837 The KUnit devices should be used in preference <<
838 instead of ``platform_device_register()`` in c <<
839 a platform device. <<
840 <<
841 For example: <<
842 <<
843 .. code-block:: c <<
844 <<
845 #include <kunit/device.h> <<
846 <<
847 static void test_my_device(struct kuni <<
848 { <<
849 struct device *fake_device; <<
850 const char *dev_managed_string <<
851 <<
852 // Create a fake device. <<
853 fake_device = kunit_device_reg <<
854 KUNIT_ASSERT_NOT_ERR_OR_NULL(t <<
855 <<
856 // Pass it to functions which <<
857 dev_managed_string = devm_kstr <<
858 <<
859 // Everything is cleaned up au <<
860 } <<
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.