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 <kunit/string-stream.h> 13 #include <linux/err.h> 14 15 struct kunit; 16 17 /** 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. 21 * 22 * Used in conjunction with a &struct kunit_assert to denote whether it 23 * represents an expectation or an assertion. 24 */ 25 enum kunit_assert_type { 26 KUNIT_ASSERTION, 27 KUNIT_EXPECTATION, 28 }; 29 30 /** 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. 38 * 39 * Represents a failed expectation/assertion. Contains all the data necessary to 40 * format a string to a user reporting the failure. 41 */ 42 struct kunit_assert { 43 struct kunit *test; 44 enum kunit_assert_type type; 45 int line; 46 const char *file; 47 struct va_format message; 48 void (*format)(const struct kunit_assert *assert, 49 struct string_stream *stream); 50 }; 51 52 /** 53 * KUNIT_INIT_VA_FMT_NULL - Default initializer for struct va_format. 54 * 55 * Used inside a struct initialization block to initialize struct va_format to 56 * default values where fmt and va are null. 57 */ 58 #define KUNIT_INIT_VA_FMT_NULL { .fmt = NULL, .va = NULL } 59 60 /** 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. 65 * 66 * The base initializer for a &struct kunit_assert. 67 */ 68 #define KUNIT_INIT_ASSERT_STRUCT(kunit, assert_type, fmt) { \ 69 .test = kunit, \ 70 .type = assert_type, \ 71 .file = __FILE__, \ 72 .line = __LINE__, \ 73 .message = KUNIT_INIT_VA_FMT_NULL, \ 74 .format = fmt \ 75 } 76 77 void kunit_base_assert_format(const struct kunit_assert *assert, 78 struct string_stream *stream); 79 80 void kunit_assert_print_msg(const struct kunit_assert *assert, 81 struct string_stream *stream); 82 83 /** 84 * struct kunit_fail_assert - Represents a plain fail expectation/assertion. 85 * @assert: The parent of this type. 86 * 87 * Represents a simple KUNIT_FAIL/KUNIT_ASSERT_FAILURE that always fails. 88 */ 89 struct kunit_fail_assert { 90 struct kunit_assert assert; 91 }; 92 93 void kunit_fail_assert_format(const struct kunit_assert *assert, 94 struct string_stream *stream); 95 96 /** 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. 100 * 101 * Initializes a &struct kunit_fail_assert. Intended to be used in 102 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 103 */ 104 #define KUNIT_INIT_FAIL_ASSERT_STRUCT(test, type) { \ 105 .assert = KUNIT_INIT_ASSERT_STRUCT(test, \ 106 type, \ 107 kunit_fail_assert_format) \ 108 } 109 110 /** 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. 115 * 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} 119 */ 120 struct kunit_unary_assert { 121 struct kunit_assert assert; 122 const char *condition; 123 bool expected_true; 124 }; 125 126 void kunit_unary_assert_format(const struct kunit_assert *assert, 127 struct string_stream *stream); 128 129 /** 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. 135 * 136 * Initializes a &struct kunit_unary_assert. Intended to be used in 137 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 138 */ 139 #define KUNIT_INIT_UNARY_ASSERT_STRUCT(test, type, cond, expect_true) { \ 140 .assert = KUNIT_INIT_ASSERT_STRUCT(test, \ 141 type, \ 142 kunit_unary_assert_format), \ 143 .condition = cond, \ 144 .expected_true = expect_true \ 145 } 146 147 /** 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. 153 * 154 * Represents an expectation/assertion that a pointer is not null and is does 155 * not contain a -errno. (See IS_ERR_OR_NULL().) 156 */ 157 struct kunit_ptr_not_err_assert { 158 struct kunit_assert assert; 159 const char *text; 160 const void *value; 161 }; 162 163 void kunit_ptr_not_err_assert_format(const struct kunit_assert *assert, 164 struct string_stream *stream); 165 166 /** 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. 173 * 174 * Initializes a &struct kunit_ptr_not_err_assert. Intended to be used in 175 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 176 */ 177 #define KUNIT_INIT_PTR_NOT_ERR_STRUCT(test, type, txt, val) { \ 178 .assert = KUNIT_INIT_ASSERT_STRUCT(test, \ 179 type, \ 180 kunit_ptr_not_err_assert_format), \ 181 .text = txt, \ 182 .value = val \ 183 } 184 185 /** 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. 194 * 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); 198 */ 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; 206 }; 207 208 void kunit_binary_assert_format(const struct kunit_assert *assert, 209 struct string_stream *stream); 210 211 /** 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. 221 * 222 * Initializes a &struct kunit_binary_assert. Intended to be used in 223 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 224 */ 225 #define KUNIT_INIT_BINARY_ASSERT_STRUCT(test, \ 226 type, \ 227 op_str, \ 228 left_str, \ 229 left_val, \ 230 right_str, \ 231 right_val) { \ 232 .assert = KUNIT_INIT_ASSERT_STRUCT(test, \ 233 type, \ 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 \ 240 } 241 242 /** 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. 251 * 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); 255 */ 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; 263 }; 264 265 void kunit_binary_ptr_assert_format(const struct kunit_assert *assert, 266 struct string_stream *stream); 267 268 /** 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. 278 * 279 * Initializes a &struct kunit_binary_ptr_assert. Intended to be used in 280 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 281 */ 282 #define KUNIT_INIT_BINARY_PTR_ASSERT_STRUCT(test, \ 283 type, \ 284 op_str, \ 285 left_str, \ 286 left_val, \ 287 right_str, \ 288 right_val) { \ 289 .assert = KUNIT_INIT_ASSERT_STRUCT(test, \ 290 type, \ 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 \ 297 } 298 299 /** 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. 308 * 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"); 312 */ 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; 320 }; 321 322 void kunit_binary_str_assert_format(const struct kunit_assert *assert, 323 struct string_stream *stream); 324 325 /** 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. 335 * 336 * Initializes a &struct kunit_binary_str_assert. Intended to be used in 337 * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros. 338 */ 339 #define KUNIT_INIT_BINARY_STR_ASSERT_STRUCT(test, \ 340 type, \ 341 op_str, \ 342 left_str, \ 343 left_val, \ 344 right_str, \ 345 right_val) { \ 346 .assert = KUNIT_INIT_ASSERT_STRUCT(test, \ 347 type, \ 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 \ 354 } 355 356 #endif /* _KUNIT_ASSERT_H */ 357