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