1 /* SPDX-License-Identifier: GPL-2.0 */ 2 /* 3 * Assertion and expectation serialization API. 4 * 5 * Copyright (C) 2019, Google LLC. 6 * Author: Brendan Higgins <brendanhiggins@google.com> 7 */ 8 9 #ifndef _KUNIT_ASSERT_H 10 #define _KUNIT_ASSERT_H 11 12 #include <linux/err.h> 13 #include <linux/printk.h> 14 15 struct kunit; 16 struct string_stream; 17 18 /** 19 * enum kunit_assert_type - Type of expectation/assertion. 20 * @KUNIT_ASSERTION: Used to denote that a kunit_assert represents an assertion. 21 * @KUNIT_EXPECTATION: Denotes that a kunit_assert represents an expectation. 22 * 23 * Used in conjunction with a &struct kunit_assert to denote whether it 24 * represents an expectation or an assertion. 25 */ 26 enum kunit_assert_type { 27 KUNIT_ASSERTION, 28 KUNIT_EXPECTATION, 29 }; 30 31 /** 32 * struct kunit_assert - Data for printing a failed assertion or expectation. 33 * @test: the test case this expectation/assertion is associated with. 34 * @type: the type (either an expectation or an assertion) of this kunit_assert. 35 * @line: the source code line number that the expectation/assertion is at. 36 * @file: the file path of the source file that the expectation/assertion is in. 37 * @message: an optional message to provide additional context. 38 * @format: a function which formats the data in this kunit_assert to a string. 39 * 40 * Represents a failed expectation/assertion. Contains all the data necessary to 41 * format a string to a user reporting the failure. 42 */ 43 struct kunit_assert { 44 struct kunit *test; 45 enum kunit_assert_type type; 46 int line; 47 const char *file; 48 struct va_format message; 49 void (*format)(const struct kunit_assert *assert, 50 struct string_stream *stream); 51 }; 52 53 /** 54 * KUNIT_INIT_VA_FMT_NULL - Default initializer for struct va_format. 55 * 56 * Used inside a struct initialization block to initialize struct va_format to 57 * default values where fmt and va are null. 58 */ 59 #define KUNIT_INIT_VA_FMT_NULL { .fmt = NULL, .va = NULL } 60 61 /** 62 * KUNIT_INIT_ASSERT_STRUCT() - Initializer for a &struct kunit_assert. 63 * @kunit: The test case that this expectation/assertion is associated with. 64 * @assert_type: The type (assertion or expectation) of this kunit_assert. 65 * @fmt: The formatting function which builds a string out of this kunit_assert. 66 * 67 * The base initializer for a &struct kunit_assert. 68 */ 69 #define KUNIT_INIT_ASSERT_STRUCT(kunit, assert_type, fmt) { \ 70 .test = kunit, \ 71 .type = assert_type, \ 72 .file = __FILE__, \ 73 .line = __LINE__, \ 74 .message = KUNIT_INIT_VA_FMT_NULL, \ 75 .format = fmt \ 76 } 77 78 void kunit_base_assert_format(const struct kunit_assert *assert, 79 struct string_stream *stream); 80 81 void kunit_assert_print_msg(const struct kunit_assert *assert, 82 struct string_stream *stream); 83 84 /** 85 * struct kunit_fail_assert - Represents a plain fail expectation/assertion. 86 * @assert: The parent of this type. 87 * 88 * Represents a simple KUNIT_FAIL/KUNIT_ASSERT_FAILURE that always fails. 89 */ 90 struct kunit_fail_assert { 91 struct kunit_assert assert; 92 }; 93 94 void kunit_fail_assert_format(const struct kunit_assert *assert, 95 struct string_stream *stream); 96 97 /** 98 * KUNIT_INIT_FAIL_ASSERT_STRUCT() - Initializer for &struct kunit_fail_assert. 99 * @test: The test case that this expectation/assertion is associated with. 100 * @type: The type (assertion or expectation) of this kunit_assert. 101 * 102 * Initializes a &struct kunit_fail_assert. Intended to be used in 103 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 104 */ 105 #define KUNIT_INIT_FAIL_ASSERT_STRUCT(test, type) { \ 106 .assert = KUNIT_INIT_ASSERT_STRUCT(test, \ 107 type, \ 108 kunit_fail_assert_format) \ 109 } 110 111 /** 112 * struct kunit_unary_assert - Represents a KUNIT_{EXPECT|ASSERT}_{TRUE|FALSE} 113 * @assert: The parent of this type. 114 * @condition: A string representation of a conditional expression. 115 * @expected_true: True if of type KUNIT_{EXPECT|ASSERT}_TRUE, false otherwise. 116 * 117 * Represents a simple expectation or assertion that simply asserts something is 118 * true or false. In other words, represents the expectations: 119 * KUNIT_{EXPECT|ASSERT}_{TRUE|FALSE} 120 */ 121 struct kunit_unary_assert { 122 struct kunit_assert assert; 123 const char *condition; 124 bool expected_true; 125 }; 126 127 void kunit_unary_assert_format(const struct kunit_assert *assert, 128 struct string_stream *stream); 129 130 /** 131 * KUNIT_INIT_UNARY_ASSERT_STRUCT() - Initializes &struct kunit_unary_assert. 132 * @test: The test case that this expectation/assertion is associated with. 133 * @type: The type (assertion or expectation) of this kunit_assert. 134 * @cond: A string representation of the expression asserted true or false. 135 * @expect_true: True if of type KUNIT_{EXPECT|ASSERT}_TRUE, false otherwise. 136 * 137 * Initializes a &struct kunit_unary_assert. Intended to be used in 138 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 139 */ 140 #define KUNIT_INIT_UNARY_ASSERT_STRUCT(test, type, cond, expect_true) { \ 141 .assert = KUNIT_INIT_ASSERT_STRUCT(test, \ 142 type, \ 143 kunit_unary_assert_format), \ 144 .condition = cond, \ 145 .expected_true = expect_true \ 146 } 147 148 /** 149 * struct kunit_ptr_not_err_assert - An expectation/assertion that a pointer is 150 * not NULL and not a -errno. 151 * @assert: The parent of this type. 152 * @text: A string representation of the expression passed to the expectation. 153 * @value: The actual evaluated pointer value of the expression. 154 * 155 * Represents an expectation/assertion that a pointer is not null and is does 156 * not contain a -errno. (See IS_ERR_OR_NULL().) 157 */ 158 struct kunit_ptr_not_err_assert { 159 struct kunit_assert assert; 160 const char *text; 161 const void *value; 162 }; 163 164 void kunit_ptr_not_err_assert_format(const struct kunit_assert *assert, 165 struct string_stream *stream); 166 167 /** 168 * KUNIT_INIT_PTR_NOT_ERR_ASSERT_STRUCT() - Initializes a 169 * &struct kunit_ptr_not_err_assert. 170 * @test: The test case that this expectation/assertion is associated with. 171 * @type: The type (assertion or expectation) of this kunit_assert. 172 * @txt: A string representation of the expression passed to the expectation. 173 * @val: The actual evaluated pointer value of the expression. 174 * 175 * Initializes a &struct kunit_ptr_not_err_assert. Intended to be used in 176 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 177 */ 178 #define KUNIT_INIT_PTR_NOT_ERR_STRUCT(test, type, txt, val) { \ 179 .assert = KUNIT_INIT_ASSERT_STRUCT(test, \ 180 type, \ 181 kunit_ptr_not_err_assert_format), \ 182 .text = txt, \ 183 .value = val \ 184 } 185 186 /** 187 * struct kunit_binary_assert - An expectation/assertion that compares two 188 * non-pointer values (for example, KUNIT_EXPECT_EQ(test, 1 + 1, 2)). 189 * @assert: The parent of this type. 190 * @operation: A string representation of the comparison operator (e.g. "=="). 191 * @left_text: A string representation of the expression in the left slot. 192 * @left_value: The actual evaluated value of the expression in the left slot. 193 * @right_text: A string representation of the expression in the right slot. 194 * @right_value: The actual evaluated value of the expression in the right slot. 195 * 196 * Represents an expectation/assertion that compares two non-pointer values. For 197 * example, to expect that 1 + 1 == 2, you can use the expectation 198 * KUNIT_EXPECT_EQ(test, 1 + 1, 2); 199 */ 200 struct kunit_binary_assert { 201 struct kunit_assert assert; 202 const char *operation; 203 const char *left_text; 204 long long left_value; 205 const char *right_text; 206 long long right_value; 207 }; 208 209 void kunit_binary_assert_format(const struct kunit_assert *assert, 210 struct string_stream *stream); 211 212 /** 213 * KUNIT_INIT_BINARY_ASSERT_STRUCT() - Initializes a 214 * &struct kunit_binary_assert. 215 * @test: The test case that this expectation/assertion is associated with. 216 * @type: The type (assertion or expectation) of this kunit_assert. 217 * @op_str: A string representation of the comparison operator (e.g. "=="). 218 * @left_str: A string representation of the expression in the left slot. 219 * @left_val: The actual evaluated value of the expression in the left slot. 220 * @right_str: A string representation of the expression in the right slot. 221 * @right_val: The actual evaluated value of the expression in the right slot. 222 * 223 * Initializes a &struct kunit_binary_assert. Intended to be used in 224 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 225 */ 226 #define KUNIT_INIT_BINARY_ASSERT_STRUCT(test, \ 227 type, \ 228 op_str, \ 229 left_str, \ 230 left_val, \ 231 right_str, \ 232 right_val) { \ 233 .assert = KUNIT_INIT_ASSERT_STRUCT(test, \ 234 type, \ 235 kunit_binary_assert_format), \ 236 .operation = op_str, \ 237 .left_text = left_str, \ 238 .left_value = left_val, \ 239 .right_text = right_str, \ 240 .right_value = right_val \ 241 } 242 243 /** 244 * struct kunit_binary_ptr_assert - An expectation/assertion that compares two 245 * pointer values (for example, KUNIT_EXPECT_PTR_EQ(test, foo, bar)). 246 * @assert: The parent of this type. 247 * @operation: A string representation of the comparison operator (e.g. "=="). 248 * @left_text: A string representation of the expression in the left slot. 249 * @left_value: The actual evaluated value of the expression in the left slot. 250 * @right_text: A string representation of the expression in the right slot. 251 * @right_value: The actual evaluated value of the expression in the right slot. 252 * 253 * Represents an expectation/assertion that compares two pointer values. For 254 * example, to expect that foo and bar point to the same thing, you can use the 255 * expectation KUNIT_EXPECT_PTR_EQ(test, foo, bar); 256 */ 257 struct kunit_binary_ptr_assert { 258 struct kunit_assert assert; 259 const char *operation; 260 const char *left_text; 261 const void *left_value; 262 const char *right_text; 263 const void *right_value; 264 }; 265 266 void kunit_binary_ptr_assert_format(const struct kunit_assert *assert, 267 struct string_stream *stream); 268 269 /** 270 * KUNIT_INIT_BINARY_PTR_ASSERT_STRUCT() - Initializes a 271 * &struct kunit_binary_ptr_assert. 272 * @test: The test case that this expectation/assertion is associated with. 273 * @type: The type (assertion or expectation) of this kunit_assert. 274 * @op_str: A string representation of the comparison operator (e.g. "=="). 275 * @left_str: A string representation of the expression in the left slot. 276 * @left_val: The actual evaluated value of the expression in the left slot. 277 * @right_str: A string representation of the expression in the right slot. 278 * @right_val: The actual evaluated value of the expression in the right slot. 279 * 280 * Initializes a &struct kunit_binary_ptr_assert. Intended to be used in 281 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 282 */ 283 #define KUNIT_INIT_BINARY_PTR_ASSERT_STRUCT(test, \ 284 type, \ 285 op_str, \ 286 left_str, \ 287 left_val, \ 288 right_str, \ 289 right_val) { \ 290 .assert = KUNIT_INIT_ASSERT_STRUCT(test, \ 291 type, \ 292 kunit_binary_ptr_assert_format), \ 293 .operation = op_str, \ 294 .left_text = left_str, \ 295 .left_value = left_val, \ 296 .right_text = right_str, \ 297 .right_value = right_val \ 298 } 299 300 /** 301 * struct kunit_binary_str_assert - An expectation/assertion that compares two 302 * string values (for example, KUNIT_EXPECT_STREQ(test, foo, "bar")). 303 * @assert: The parent of this type. 304 * @operation: A string representation of the comparison operator (e.g. "=="). 305 * @left_text: A string representation of the expression in the left slot. 306 * @left_value: The actual evaluated value of the expression in the left slot. 307 * @right_text: A string representation of the expression in the right slot. 308 * @right_value: The actual evaluated value of the expression in the right slot. 309 * 310 * Represents an expectation/assertion that compares two string values. For 311 * example, to expect that the string in foo is equal to "bar", you can use the 312 * expectation KUNIT_EXPECT_STREQ(test, foo, "bar"); 313 */ 314 struct kunit_binary_str_assert { 315 struct kunit_assert assert; 316 const char *operation; 317 const char *left_text; 318 const char *left_value; 319 const char *right_text; 320 const char *right_value; 321 }; 322 323 void kunit_binary_str_assert_format(const struct kunit_assert *assert, 324 struct string_stream *stream); 325 326 /** 327 * KUNIT_INIT_BINARY_STR_ASSERT_STRUCT() - Initializes a 328 * &struct kunit_binary_str_assert. 329 * @test: The test case that this expectation/assertion is associated with. 330 * @type: The type (assertion or expectation) of this kunit_assert. 331 * @op_str: A string representation of the comparison operator (e.g. "=="). 332 * @left_str: A string representation of the expression in the left slot. 333 * @left_val: The actual evaluated value of the expression in the left slot. 334 * @right_str: A string representation of the expression in the right slot. 335 * @right_val: The actual evaluated value of the expression in the right slot. 336 * 337 * Initializes a &struct kunit_binary_str_assert. Intended to be used in 338 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 339 */ 340 #define KUNIT_INIT_BINARY_STR_ASSERT_STRUCT(test, \ 341 type, \ 342 op_str, \ 343 left_str, \ 344 left_val, \ 345 right_str, \ 346 right_val) { \ 347 .assert = KUNIT_INIT_ASSERT_STRUCT(test, \ 348 type, \ 349 kunit_binary_str_assert_format), \ 350 .operation = op_str, \ 351 .left_text = left_str, \ 352 .left_value = left_val, \ 353 .right_text = right_str, \ 354 .right_value = right_val \ 355 } 356 357 #endif /* _KUNIT_ASSERT_H */ 358