From patchwork Sun Dec 7 20:16:04 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 819 Return-Path: X-Original-To: u-boot-concept@u-boot.org Delivered-To: u-boot-concept@u-boot.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1765138646; bh=YIXWQwJuggv6x52z5/t8avDKe6z7F/BL8Vqs7vh86iY=; h=From:To:Date:In-Reply-To:References:CC:Subject:List-Id: List-Archive:List-Help:List-Owner:List-Post:List-Subscribe: List-Unsubscribe:From; b=r2yQZN/3AJUtvKyG6njig0RaBbwUy4ZpPFPWvSIQmYv4m1MRI6uf2d0xz6muE65xI bXgb834Dfga+D44y1Ja1gb4Zp1CQCfM9+vrP/susUg4P7jzdDNgXiU2fXIvSaetNkY C0/eJS4g+U1o+XpI2OiY15TCfpdutU0ykB8MvthSB0tDgKma97g34kGs5w8plAIfEQ HpIcAqGE8cF6yBPCVhNpdMd8rDkrWey4ruyJme96Yc02lYnK65R2a2YGb0e2VQgMz8 aQrdilDW8J9RyDV4Vb/AO4/+HXZlHXA8AO8iK+Yk1dXPUNPvDVAYEQLHHjC4RYCO6k x1GA0tytjmO4w== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id CEB7B689A7 for ; Sun, 7 Dec 2025 13:17:26 -0700 (MST) X-Virus-Scanned: Debian amavis at Received: from mail.u-boot.org ([127.0.0.1]) by localhost (mail.u-boot.org [127.0.0.1]) (amavis, port 10024) with ESMTP id mtgB0Rw5IsTg for ; Sun, 7 Dec 2025 13:17:26 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1765138645; bh=YIXWQwJuggv6x52z5/t8avDKe6z7F/BL8Vqs7vh86iY=; h=From:To:Date:In-Reply-To:References:CC:Subject:List-Id: List-Archive:List-Help:List-Owner:List-Post:List-Subscribe: List-Unsubscribe:From; b=uhdlvWqBfVOhmvjgZ9XnGJ+MlmiKxKauh2LkHjrCBK+/OLKvzYNtjTw29PpTGMsny 6Md864amplbU2Hu/+j7zdSOs85JAOdaAiZfFk9A+XaghMGcRYUp6eEBYqN9JPDbJ9S kLEfsYuEo2HrfbfpwkRv5vGX7FZcEfvtSeF4CdGgm07iCNH2kdh8IdHmV2CEtkZQyN /4p1NqTQh2FnuqP0CHzT/NaqOYaJXAuNbKT2qvxtaLw5QOUdA1zXrWKmr8EMvJNFUx B1EdX+n1JJT94ooU/xZ/jawOmEfBCJ+T5oH94QPmJMPcePmyrHsBY0gLwM5rnkfrL/ jv6RHYDZuFdSA== Received: from mail.u-boot.org (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id D201968994 for ; Sun, 7 Dec 2025 13:17:25 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1765138643; bh=BXxgmDetLgO8mZ5Ax1IOLo81/UTK3npTAkwxguV2npo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=LAAfTVY3HIfcKUl4X+idhpptKr+1BR4RI+r6dlYrWEK3+t6Al5Zw7a54l91r3stZ6 wLquzbqjFrpQRJgI6pYGd5hCCw3KNMR7PNaAvndQ5c6hCWnycAmads4fX6bi6qdzSj 64kL9tsMHcWzKIvtohPtqLkp7Y3ys9uMCoQ2HtjWg0cdOnftQf0kvWhpmVhCCJqk9W UVDOg+9iOfPjHYiP55293YySO06F2BYpNIl9W4URh/9SDt157lY51zacI9vn8j7bO/ kW3WTRSkH+J2Kujyorhrjv19woVL/cxbnkfZRvsh6dS35LQHbS+irGwCcOjOEcj/wa oBARUefdX4iRA== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 98A9D68994; Sun, 7 Dec 2025 13:17:23 -0700 (MST) X-Virus-Scanned: Debian amavis at Received: from mail.u-boot.org ([127.0.0.1]) by localhost (mail.u-boot.org [127.0.0.1]) (amavis, port 10026) with ESMTP id 3gEh7FRVGqK9; Sun, 7 Dec 2025 13:17:23 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1765138643; bh=nSyb/wfMTUxaRHrzP8d/MG3KTuQ1Zdx1pUwXpQFV3sQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=jhih79D6Tq8o0M1XWL/hTEQyryfbielWJwKVpfvDNpTjENQoq/L06uIZ+cbWISEBt HRqNLCxaRpclos2GaYFjPOLUf5+0r+keP+dwCPPuBcYbyfIgLK2vWKlq+Et3MxF5w7 dhgxMNePLcKiF1rHnza3tub9qmmYT8H8w9l1FoyGsN+fBv8XkIfJLc23QeIWP/MhxI 7WRtiIl6ICrh4ZV39karX8zcZQZ935I7ynAg7fJmF4WBHGJu0clLh1GT2fB4T2CTQs 4TAXAoRS7iSijBgK/JsBdWyS0ZZr39Hz0K/GRQS9ydDKrDk2ZjQgWxfEq1wt/KLHML /pKwrvIzOOPbQ== Received: from u-boot.org (unknown [73.34.74.121]) by mail.u-boot.org (Postfix) with ESMTPSA id DE3CA5F6BF; Sun, 7 Dec 2025 13:17:22 -0700 (MST) From: Simon Glass To: U-Boot Concept Date: Sun, 7 Dec 2025 13:16:04 -0700 Message-ID: <20251207201628.2882382-8-sjg@u-boot.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20251207201628.2882382-1-sjg@u-boot.org> References: <20251207201628.2882382-1-sjg@u-boot.org> MIME-Version: 1.0 Message-ID-Hash: BMSZDMGZJE74VOBTKQJAQ3GFN4IDRLYQ X-Message-ID-Hash: BMSZDMGZJE74VOBTKQJAQ3GFN4IDRLYQ X-MailFrom: sjg@u-boot.org X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header CC: Heinrich Schuchardt , Simon Glass , "Claude Opus 4 . 5" X-Mailman-Version: 3.3.10 Precedence: list Subject: [Concept] [PATCH 07/22] doc: test: Document assertion macros List-Id: Discussion and patches related to U-Boot Concept Archived-At: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: From: Simon Glass Add documentation for all the ut_assert*() macros and memory helpers available in include/test/ut.h. Co-developed-by: Claude Opus 4.5 Signed-off-by: Simon Glass --- doc/develop/tests_writing.rst | 104 ++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) diff --git a/doc/develop/tests_writing.rst b/doc/develop/tests_writing.rst index f6f852c297d..4b0616376d0 100644 --- a/doc/develop/tests_writing.rst +++ b/doc/develop/tests_writing.rst @@ -373,6 +373,110 @@ existing suite or creating a new one. An example SPL test is spl_test_load(). +Assertions +---------- + +The test framework provides various assertion macros, defined in +``include/test/ut.h``. All of these return from the test function on failure, +unless ``uts->soft_fail`` is set. + +Basic assertions +~~~~~~~~~~~~~~~~ + +ut_assert(cond) + Assert that a condition is non-zero (true) + +ut_assertf(cond, fmt, args...) + Assert that a condition is non-zero, with a printf() message on failure + +ut_assertok(cond) + Assert that an operation succeeds (returns 0) + +ut_reportf(fmt, args...) + Report a failure with a printf() message (always fails) + +Value comparisons +~~~~~~~~~~~~~~~~~ + +ut_asserteq(expr1, expr2) + Assert that two int expressions are equal + +ut_asserteq_64(expr1, expr2) + Assert that two 64-bit expressions are equal + +ut_asserteq_str(expr1, expr2) + Assert that two strings are equal + +ut_asserteq_strn(expr1, expr2) + Assert that two strings are equal, up to the length of the first + +ut_asserteq_mem(expr1, expr2, len) + Assert that two memory areas are equal + +ut_asserteq_ptr(expr1, expr2) + Assert that two pointers are equal + +ut_asserteq_addr(expr1, expr2) + Assert that two addresses (converted from pointers via map_to_sysmem()) + are equal + +Pointer assertions +~~~~~~~~~~~~~~~~~~ + +ut_assertnull(expr) + Assert that a pointer is NULL + +ut_assertnonnull(expr) + Assert that a pointer is not NULL + +ut_assertok_ptr(expr) + Assert that a pointer is not an error pointer (checked with IS_ERR()) + +Console output assertions +~~~~~~~~~~~~~~~~~~~~~~~~~ + +These are used to check console output when ``UTF_CONSOLE`` flag is set. + +ut_assert_nextline(fmt, args...) + Assert that the next console output line matches the format string + +ut_assert_nextlinen(fmt, args...) + Assert that the next console output line matches up to the format + string length + +ut_assert_nextline_empty() + Assert that the next console output line is empty + +ut_assert_skipline() + Assert that there is a next console output line, and skip it + +ut_assert_skip_to_line(fmt, args...) + Skip console output until a matching line is found + +ut_assert_skip_to_linen(fmt, args...) + Skip console output until a partial match is found (compares up to the + format-string length) + +ut_assert_console_end() + Assert that there is no more console output + +ut_assert_nextlines_are_dump(total_bytes) + Assert that the next lines are a print_buffer() hex dump of the specified + size + +Memory helpers +~~~~~~~~~~~~~~ + +These help check for memory leaks: + +ut_check_free() + Return the number of bytes free in the malloc() pool + +ut_check_delta(last) + Return the change in free memory since ``last`` was obtained from + ``ut_check_free()``. A positive value means more memory has been allocated. + + Writing Python tests --------------------