1 /* SPDX-License-Identifier: GPL-2.0 */
3 * Assertion and expectation serialization API.
5 * Copyright (C) 2019, Google LLC.
6 * Author: Brendan Higgins <brendanhiggins@google.com>
9 #ifndef _KUNIT_ASSERT_H
10 #define _KUNIT_ASSERT_H
12 #include <kunit/string-stream.h>
13 #include <linux/err.h>
18 * enum kunit_assert_type - Type of expectation/assertion.
19 * @KUNIT_ASSERTION: Used to denote that a kunit_assert represents an assertion.
20 * @KUNIT_EXPECTATION: Denotes that a kunit_assert represents an expectation.
22 * Used in conjunction with a &struct kunit_assert to denote whether it
23 * represents an expectation or an assertion.
25 enum kunit_assert_type {
31 * struct kunit_assert - Data for printing a failed assertion or expectation.
32 * @test: the test case this expectation/assertion is associated with.
33 * @type: the type (either an expectation or an assertion) of this kunit_assert.
34 * @line: the source code line number that the expectation/assertion is at.
35 * @file: the file path of the source file that the expectation/assertion is in.
36 * @message: an optional message to provide additional context.
37 * @format: a function which formats the data in this kunit_assert to a string.
39 * Represents a failed expectation/assertion. Contains all the data necessary to
40 * format a string to a user reporting the failure.
44 enum kunit_assert_type type;
47 struct va_format message;
48 void (*format)(const struct kunit_assert *assert,
49 struct string_stream *stream);
53 * KUNIT_INIT_VA_FMT_NULL - Default initializer for struct va_format.
55 * Used inside a struct initialization block to initialize struct va_format to
56 * default values where fmt and va are null.
58 #define KUNIT_INIT_VA_FMT_NULL { .fmt = NULL, .va = NULL }
61 * KUNIT_INIT_ASSERT_STRUCT() - Initializer for a &struct kunit_assert.
62 * @kunit: The test case that this expectation/assertion is associated with.
63 * @assert_type: The type (assertion or expectation) of this kunit_assert.
64 * @fmt: The formatting function which builds a string out of this kunit_assert.
66 * The base initializer for a &struct kunit_assert.
68 #define KUNIT_INIT_ASSERT_STRUCT(kunit, assert_type, fmt) { \
70 .type = assert_type, \
73 .message = KUNIT_INIT_VA_FMT_NULL, \
77 void kunit_base_assert_format(const struct kunit_assert *assert,
78 struct string_stream *stream);
80 void kunit_assert_print_msg(const struct kunit_assert *assert,
81 struct string_stream *stream);
84 * struct kunit_fail_assert - Represents a plain fail expectation/assertion.
85 * @assert: The parent of this type.
87 * Represents a simple KUNIT_FAIL/KUNIT_ASSERT_FAILURE that always fails.
89 struct kunit_fail_assert {
90 struct kunit_assert assert;
93 void kunit_fail_assert_format(const struct kunit_assert *assert,
94 struct string_stream *stream);
97 * KUNIT_INIT_FAIL_ASSERT_STRUCT() - Initializer for &struct kunit_fail_assert.
98 * @test: The test case that this expectation/assertion is associated with.
99 * @type: The type (assertion or expectation) of this kunit_assert.
101 * Initializes a &struct kunit_fail_assert. Intended to be used in
102 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros.
104 #define KUNIT_INIT_FAIL_ASSERT_STRUCT(test, type) { \
105 .assert = KUNIT_INIT_ASSERT_STRUCT(test, \
107 kunit_fail_assert_format) \
111 * struct kunit_unary_assert - Represents a KUNIT_{EXPECT|ASSERT}_{TRUE|FALSE}
112 * @assert: The parent of this type.
113 * @condition: A string representation of a conditional expression.
114 * @expected_true: True if of type KUNIT_{EXPECT|ASSERT}_TRUE, false otherwise.
116 * Represents a simple expectation or assertion that simply asserts something is
117 * true or false. In other words, represents the expectations:
118 * KUNIT_{EXPECT|ASSERT}_{TRUE|FALSE}
120 struct kunit_unary_assert {
121 struct kunit_assert assert;
122 const char *condition;
126 void kunit_unary_assert_format(const struct kunit_assert *assert,
127 struct string_stream *stream);
130 * KUNIT_INIT_UNARY_ASSERT_STRUCT() - Initializes &struct kunit_unary_assert.
131 * @test: The test case that this expectation/assertion is associated with.
132 * @type: The type (assertion or expectation) of this kunit_assert.
133 * @cond: A string representation of the expression asserted true or false.
134 * @expect_true: True if of type KUNIT_{EXPECT|ASSERT}_TRUE, false otherwise.
136 * Initializes a &struct kunit_unary_assert. Intended to be used in
137 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros.
139 #define KUNIT_INIT_UNARY_ASSERT_STRUCT(test, type, cond, expect_true) { \
140 .assert = KUNIT_INIT_ASSERT_STRUCT(test, \
142 kunit_unary_assert_format), \
144 .expected_true = expect_true \
148 * struct kunit_ptr_not_err_assert - An expectation/assertion that a pointer is
149 * not NULL and not a -errno.
150 * @assert: The parent of this type.
151 * @text: A string representation of the expression passed to the expectation.
152 * @value: The actual evaluated pointer value of the expression.
154 * Represents an expectation/assertion that a pointer is not null and is does
155 * not contain a -errno. (See IS_ERR_OR_NULL().)
157 struct kunit_ptr_not_err_assert {
158 struct kunit_assert assert;
163 void kunit_ptr_not_err_assert_format(const struct kunit_assert *assert,
164 struct string_stream *stream);
167 * KUNIT_INIT_PTR_NOT_ERR_ASSERT_STRUCT() - Initializes a
168 * &struct kunit_ptr_not_err_assert.
169 * @test: The test case that this expectation/assertion is associated with.
170 * @type: The type (assertion or expectation) of this kunit_assert.
171 * @txt: A string representation of the expression passed to the expectation.
172 * @val: The actual evaluated pointer value of the expression.
174 * Initializes a &struct kunit_ptr_not_err_assert. Intended to be used in
175 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros.
177 #define KUNIT_INIT_PTR_NOT_ERR_STRUCT(test, type, txt, val) { \
178 .assert = KUNIT_INIT_ASSERT_STRUCT(test, \
180 kunit_ptr_not_err_assert_format), \
186 * struct kunit_binary_assert - An expectation/assertion that compares two
187 * non-pointer values (for example, KUNIT_EXPECT_EQ(test, 1 + 1, 2)).
188 * @assert: The parent of this type.
189 * @operation: A string representation of the comparison operator (e.g. "==").
190 * @left_text: A string representation of the expression in the left slot.
191 * @left_value: The actual evaluated value of the expression in the left slot.
192 * @right_text: A string representation of the expression in the right slot.
193 * @right_value: The actual evaluated value of the expression in the right slot.
195 * Represents an expectation/assertion that compares two non-pointer values. For
196 * example, to expect that 1 + 1 == 2, you can use the expectation
197 * KUNIT_EXPECT_EQ(test, 1 + 1, 2);
199 struct kunit_binary_assert {
200 struct kunit_assert assert;
201 const char *operation;
202 const char *left_text;
203 long long left_value;
204 const char *right_text;
205 long long right_value;
208 void kunit_binary_assert_format(const struct kunit_assert *assert,
209 struct string_stream *stream);
212 * KUNIT_INIT_BINARY_ASSERT_STRUCT() - Initializes a
213 * &struct kunit_binary_assert.
214 * @test: The test case that this expectation/assertion is associated with.
215 * @type: The type (assertion or expectation) of this kunit_assert.
216 * @op_str: A string representation of the comparison operator (e.g. "==").
217 * @left_str: A string representation of the expression in the left slot.
218 * @left_val: The actual evaluated value of the expression in the left slot.
219 * @right_str: A string representation of the expression in the right slot.
220 * @right_val: The actual evaluated value of the expression in the right slot.
222 * Initializes a &struct kunit_binary_assert. Intended to be used in
223 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros.
225 #define KUNIT_INIT_BINARY_ASSERT_STRUCT(test, \
232 .assert = KUNIT_INIT_ASSERT_STRUCT(test, \
234 kunit_binary_assert_format), \
235 .operation = op_str, \
236 .left_text = left_str, \
237 .left_value = left_val, \
238 .right_text = right_str, \
239 .right_value = right_val \
243 * struct kunit_binary_ptr_assert - An expectation/assertion that compares two
244 * pointer values (for example, KUNIT_EXPECT_PTR_EQ(test, foo, bar)).
245 * @assert: The parent of this type.
246 * @operation: A string representation of the comparison operator (e.g. "==").
247 * @left_text: A string representation of the expression in the left slot.
248 * @left_value: The actual evaluated value of the expression in the left slot.
249 * @right_text: A string representation of the expression in the right slot.
250 * @right_value: The actual evaluated value of the expression in the right slot.
252 * Represents an expectation/assertion that compares two pointer values. For
253 * example, to expect that foo and bar point to the same thing, you can use the
254 * expectation KUNIT_EXPECT_PTR_EQ(test, foo, bar);
256 struct kunit_binary_ptr_assert {
257 struct kunit_assert assert;
258 const char *operation;
259 const char *left_text;
260 const void *left_value;
261 const char *right_text;
262 const void *right_value;
265 void kunit_binary_ptr_assert_format(const struct kunit_assert *assert,
266 struct string_stream *stream);
269 * KUNIT_INIT_BINARY_PTR_ASSERT_STRUCT() - Initializes a
270 * &struct kunit_binary_ptr_assert.
271 * @test: The test case that this expectation/assertion is associated with.
272 * @type: The type (assertion or expectation) of this kunit_assert.
273 * @op_str: A string representation of the comparison operator (e.g. "==").
274 * @left_str: A string representation of the expression in the left slot.
275 * @left_val: The actual evaluated value of the expression in the left slot.
276 * @right_str: A string representation of the expression in the right slot.
277 * @right_val: The actual evaluated value of the expression in the right slot.
279 * Initializes a &struct kunit_binary_ptr_assert. Intended to be used in
280 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros.
282 #define KUNIT_INIT_BINARY_PTR_ASSERT_STRUCT(test, \
289 .assert = KUNIT_INIT_ASSERT_STRUCT(test, \
291 kunit_binary_ptr_assert_format), \
292 .operation = op_str, \
293 .left_text = left_str, \
294 .left_value = left_val, \
295 .right_text = right_str, \
296 .right_value = right_val \
300 * struct kunit_binary_str_assert - An expectation/assertion that compares two
301 * string values (for example, KUNIT_EXPECT_STREQ(test, foo, "bar")).
302 * @assert: The parent of this type.
303 * @operation: A string representation of the comparison operator (e.g. "==").
304 * @left_text: A string representation of the expression in the left slot.
305 * @left_value: The actual evaluated value of the expression in the left slot.
306 * @right_text: A string representation of the expression in the right slot.
307 * @right_value: The actual evaluated value of the expression in the right slot.
309 * Represents an expectation/assertion that compares two string values. For
310 * example, to expect that the string in foo is equal to "bar", you can use the
311 * expectation KUNIT_EXPECT_STREQ(test, foo, "bar");
313 struct kunit_binary_str_assert {
314 struct kunit_assert assert;
315 const char *operation;
316 const char *left_text;
317 const char *left_value;
318 const char *right_text;
319 const char *right_value;
322 void kunit_binary_str_assert_format(const struct kunit_assert *assert,
323 struct string_stream *stream);
326 * KUNIT_INIT_BINARY_STR_ASSERT_STRUCT() - Initializes a
327 * &struct kunit_binary_str_assert.
328 * @test: The test case that this expectation/assertion is associated with.
329 * @type: The type (assertion or expectation) of this kunit_assert.
330 * @op_str: A string representation of the comparison operator (e.g. "==").
331 * @left_str: A string representation of the expression in the left slot.
332 * @left_val: The actual evaluated value of the expression in the left slot.
333 * @right_str: A string representation of the expression in the right slot.
334 * @right_val: The actual evaluated value of the expression in the right slot.
336 * Initializes a &struct kunit_binary_str_assert. Intended to be used in
337 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros.
339 #define KUNIT_INIT_BINARY_STR_ASSERT_STRUCT(test, \
346 .assert = KUNIT_INIT_ASSERT_STRUCT(test, \
348 kunit_binary_str_assert_format), \
349 .operation = op_str, \
350 .left_text = left_str, \
351 .left_value = left_val, \
352 .right_text = right_str, \
353 .right_value = right_val \
356 #endif /* _KUNIT_ASSERT_H */