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/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_loc - Identifies the source location of a line of code.
  33  * @line: the line number in the file.
  34  * @file: the file name.
  35  */
  36 struct kunit_loc {
  37         int line;
  38         const char *file;
  39 };
  40
  41 #define KUNIT_CURRENT_LOC { .file = __FILE__, .line = __LINE__ }
  42
  43 /**
  44  * struct kunit_assert - Data for printing a failed assertion or expectation.
  45  * @format: a function which formats the data in this kunit_assert to a string.
  46  *
  47  * Represents a failed expectation/assertion. Contains all the data necessary to
  48  * format a string to a user reporting the failure.
  49  */
  50 struct kunit_assert {
  51         void (*format)(const struct kunit_assert *assert,
  52                        const struct va_format *message,
  53                        struct string_stream *stream);
  54 };
  55
  56 void kunit_assert_prologue(const struct kunit_loc *loc,
  57                            enum kunit_assert_type type,
  58                            struct string_stream *stream);
  59
  60 /**
  61  * struct kunit_fail_assert - Represents a plain fail expectation/assertion.
  62  * @assert: The parent of this type.
  63  *
  64  * Represents a simple KUNIT_FAIL/KUNIT_ASSERT_FAILURE that always fails.
  65  */
  66 struct kunit_fail_assert {
  67         struct kunit_assert assert;
  68 };
  69
  70 void kunit_fail_assert_format(const struct kunit_assert *assert,
  71                               const struct va_format *message,
  72                               struct string_stream *stream);
  73
  74 /**
  75  * KUNIT_INIT_FAIL_ASSERT_STRUCT - Initializer for &struct kunit_fail_assert.
  76  *
  77  * Initializes a &struct kunit_fail_assert. Intended to be used in
  78  * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros.
  79  */
  80 #define KUNIT_INIT_FAIL_ASSERT_STRUCT {                                 \
  81         .assert = { .format = kunit_fail_assert_format },               \
  82 }
  83
  84 /**
  85  * struct kunit_unary_assert - Represents a KUNIT_{EXPECT|ASSERT}_{TRUE|FALSE}
  86  * @assert: The parent of this type.
  87  * @condition: A string representation of a conditional expression.
  88  * @expected_true: True if of type KUNIT_{EXPECT|ASSERT}_TRUE, false otherwise.
  89  *
  90  * Represents a simple expectation or assertion that simply asserts something is
  91  * true or false. In other words, represents the expectations:
  92  * KUNIT_{EXPECT|ASSERT}_{TRUE|FALSE}
  93  */
  94 struct kunit_unary_assert {
  95         struct kunit_assert assert;
  96         const char *condition;
  97         bool expected_true;
  98 };
  99
 100 void kunit_unary_assert_format(const struct kunit_assert *assert,
 101                                const struct va_format *message,
 102                                struct string_stream *stream);
 103
 104 /**
 105  * KUNIT_INIT_UNARY_ASSERT_STRUCT() - Initializes &struct kunit_unary_assert.
 106  * @cond: A string representation of the expression asserted true or false.
 107  * @expect_true: True if of type KUNIT_{EXPECT|ASSERT}_TRUE, false otherwise.
 108  *
 109  * Initializes a &struct kunit_unary_assert. Intended to be used in
 110  * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros.
 111  */
 112 #define KUNIT_INIT_UNARY_ASSERT_STRUCT(cond, expect_true) {                    \
 113         .assert = { .format = kunit_unary_assert_format },                     \
 114         .condition = cond,                                                     \
 115         .expected_true = expect_true                                           \
 116 }
 117
 118 /**
 119  * struct kunit_ptr_not_err_assert - An expectation/assertion that a pointer is
 120  *      not NULL and not a -errno.
 121  * @assert: The parent of this type.
 122  * @text: A string representation of the expression passed to the expectation.
 123  * @value: The actual evaluated pointer value of the expression.
 124  *
 125  * Represents an expectation/assertion that a pointer is not null and is does
 126  * not contain a -errno. (See IS_ERR_OR_NULL().)
 127  */
 128 struct kunit_ptr_not_err_assert {
 129         struct kunit_assert assert;
 130         const char *text;
 131         const void *value;
 132 };
 133
 134 void kunit_ptr_not_err_assert_format(const struct kunit_assert *assert,
 135                                      const struct va_format *message,
 136                                      struct string_stream *stream);
 137
 138 /**
 139  * KUNIT_INIT_PTR_NOT_ERR_ASSERT_STRUCT() - Initializes a
 140  *      &struct kunit_ptr_not_err_assert.
 141  * @txt: A string representation of the expression passed to the expectation.
 142  * @val: The actual evaluated pointer value of the expression.
 143  *
 144  * Initializes a &struct kunit_ptr_not_err_assert. Intended to be used in
 145  * KUNIT_EXPECT_* and KUNIT_ASSERT_* macros.
 146  */
 147 #define KUNIT_INIT_PTR_NOT_ERR_STRUCT(txt, val) {                              \
 148         .assert = { .format = kunit_ptr_not_err_assert_format },               \
 149         .text = txt,                                                           \
 150         .value = val                                                           \
 151 }
 152
 153 /**
 154  * struct kunit_binary_assert_text - holds strings for &struct
 155  *      kunit_binary_assert and friends to try and make the structs smaller.
 156  * @operation: A string representation of the comparison operator (e.g. "==").
 157  * @left_text: A string representation of the left expression (e.g. "2+2").
 158  * @right_text: A string representation of the right expression (e.g. "2+2").
 159  */
 160 struct kunit_binary_assert_text {
 161         const char *operation;
 162         const char *left_text;
 163         const char *right_text;
 164 };
 165
 166 /**
 167  * struct kunit_binary_assert - An expectation/assertion that compares two
 168  *      non-pointer values (for example, KUNIT_EXPECT_EQ(test, 1 + 1, 2)).
 169  * @assert: The parent of this type.
 170  * @text: Holds the textual representations of the operands and op (e.g.  "==").
 171  * @left_value: The actual evaluated value of the expression in the left slot.
 172  * @right_value: The actual evaluated value of the expression in the right slot.
 173  *
 174  * Represents an expectation/assertion that compares two non-pointer values. For
 175  * example, to expect that 1 + 1 == 2, you can use the expectation
 176  * KUNIT_EXPECT_EQ(test, 1 + 1, 2);
 177  */
 178 struct kunit_binary_assert {
 179         struct kunit_assert assert;
 180         const struct kunit_binary_assert_text *text;
 181         long long left_value;
 182         long long right_value;
 183 };
 184
 185 void kunit_binary_assert_format(const struct kunit_assert *assert,
 186                                 const struct va_format *message,
 187                                 struct string_stream *stream);
 188
 189 /**
 190  * KUNIT_INIT_BINARY_ASSERT_STRUCT() - Initializes a binary assert like
 191  *      kunit_binary_assert, kunit_binary_ptr_assert, etc.
 192  *
 193  * @format_func: a function which formats the assert to a string.
 194  * @text_: Pointer to a kunit_binary_assert_text.
 195  * @left_val: The actual evaluated value of the expression in the left slot.
 196  * @right_val: The actual evaluated value of the expression in the right slot.
 197  *
 198  * Initializes a binary assert like kunit_binary_assert,
 199  * kunit_binary_ptr_assert, etc. This relies on these structs having the same
 200  * fields but with different types for left_val/right_val.
 201  * This is ultimately used by binary assertion macros like KUNIT_EXPECT_EQ, etc.
 202  */
 203 #define KUNIT_INIT_BINARY_ASSERT_STRUCT(format_func,                           \
 204                                         text_,                                 \
 205                                         left_val,                              \
 206                                         right_val) {                           \
 207         .assert = { .format = format_func },                                   \
 208         .text = text_,                                                         \
 209         .left_value = left_val,                                                \
 210         .right_value = right_val                                               \
 211 }
 212
 213 /**
 214  * struct kunit_binary_ptr_assert - An expectation/assertion that compares two
 215  *      pointer values (for example, KUNIT_EXPECT_PTR_EQ(test, foo, bar)).
 216  * @assert: The parent of this type.
 217  * @text: Holds the textual representations of the operands and op (e.g.  "==").
 218  * @left_value: The actual evaluated value of the expression in the left slot.
 219  * @right_value: The actual evaluated value of the expression in the right slot.
 220  *
 221  * Represents an expectation/assertion that compares two pointer values. For
 222  * example, to expect that foo and bar point to the same thing, you can use the
 223  * expectation KUNIT_EXPECT_PTR_EQ(test, foo, bar);
 224  */
 225 struct kunit_binary_ptr_assert {
 226         struct kunit_assert assert;
 227         const struct kunit_binary_assert_text *text;
 228         const void *left_value;
 229         const void *right_value;
 230 };
 231
 232 void kunit_binary_ptr_assert_format(const struct kunit_assert *assert,
 233                                     const struct va_format *message,
 234                                     struct string_stream *stream);
 235
 236 /**
 237  * struct kunit_binary_str_assert - An expectation/assertion that compares two
 238  *      string values (for example, KUNIT_EXPECT_STREQ(test, foo, "bar")).
 239  * @assert: The parent of this type.
 240  * @text: Holds the textual representations of the operands and comparator.
 241  * @left_value: The actual evaluated value of the expression in the left slot.
 242  * @right_value: The actual evaluated value of the expression in the right slot.
 243  *
 244  * Represents an expectation/assertion that compares two string values. For
 245  * example, to expect that the string in foo is equal to "bar", you can use the
 246  * expectation KUNIT_EXPECT_STREQ(test, foo, "bar");
 247  */
 248 struct kunit_binary_str_assert {
 249         struct kunit_assert assert;
 250         const struct kunit_binary_assert_text *text;
 251         const char *left_value;
 252         const char *right_value;
 253 };
 254
 255 void kunit_binary_str_assert_format(const struct kunit_assert *assert,
 256                                     const struct va_format *message,
 257                                     struct string_stream *stream);
 258
 259 #endif /*  _KUNIT_ASSERT_H */