assert.h 13 KB

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