include/kunit/assert.h

   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/kernel.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 */