From patchwork Wed Nov 9 00:36:16 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Latypov X-Patchwork-Id: 17295 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:6687:0:0:0:0:0 with SMTP id l7csp60557wru; Tue, 8 Nov 2022 16:42:34 -0800 (PST) X-Google-Smtp-Source: AMsMyM7eqos4d+tR3bVU/s/oikK0pNR3DkVE99+rDfS+PcKeVr1QbGHGoqkzIZeenbPm4AngT33u X-Received: by 2002:a05:6402:e01:b0:442:dd7e:f49d with SMTP id h1-20020a0564020e0100b00442dd7ef49dmr57669223edh.355.1667954554578; Tue, 08 Nov 2022 16:42:34 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1667954554; cv=none; d=google.com; s=arc-20160816; b=yezbUpb6oW1aV4vy1kcrCVqb+vRFuLrkzH243o2EZZfipsYBPAAUz5dpiz4wSDdNxq Y+Z4wb3IZ/VcoTnl/iMoIWEQUe2GCC7xjPwxTAJ/dhbB6launRKjW+HXpuuKxEP1O3iD UWm9URnfQYiaeJAFW9LjkSMXyRPdkeel2H/JajrcWB8iS+WkSa0ekZDf/GVt2hs5//l8 oWKMXIalGWhD4lYw6iS/hqNp1seOz/TH7JNUmPQmsbglQAvsH/iHwzrC6mUQ/CT1oIAr cBviTCOl9n27PAqCxMoENJ1hPzN4ULLUl1efvGY/tDWBDxfXV6aJ6uVCZiVJEWGBAuZz e9jA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:cc:to:from:subject:message-id:mime-version:date :dkim-signature; bh=CZKNxZ4ut/Q7ACsrFTYtA5PMiQEhI2gWEXdAM+wb9gg=; b=ohGpgVpSlBIxhlztTpPtCUhEzCQGE7eD3Dz5uQ0VAXV21Bwdt/RiPntFavzNZ3/4o0 984/nLsbrJRV54YWBCq2wtNJVJs+1iaOChMSUty3bbBdQD6oDXaJcoDrVt7m3TrpweBC cuGxcbC4l5q481CZO8PHsYbStcxkpG2DMR9IVaKtjqsuYdHQdWfA6eyM3eL1OrJlLAnN Dt43fu8ubaaAiboT8WfHpgLbsCyY2AMkphv+NkSlxPAl0usxkZKEsH3tscCXswgc78Ma chASKh5LPYjRu63UbVEW6QR6weBJkncq/D/s50+kbtYo5EOdZYOCdeFyP5XPkOjIWNTM XL1Q== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@google.com header.s=20210112 header.b=cYSLYVLk; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=google.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id p19-20020a170906499300b00780837381d8si10888306eju.591.2022.11.08.16.42.03; Tue, 08 Nov 2022 16:42:34 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@google.com header.s=20210112 header.b=cYSLYVLk; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=google.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229870AbiKIAga (ORCPT + 99 others); Tue, 8 Nov 2022 19:36:30 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37812 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229447AbiKIAg1 (ORCPT ); Tue, 8 Nov 2022 19:36:27 -0500 Received: from mail-pl1-x649.google.com (mail-pl1-x649.google.com [IPv6:2607:f8b0:4864:20::649]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 6C70A63156 for ; Tue, 8 Nov 2022 16:36:26 -0800 (PST) Received: by mail-pl1-x649.google.com with SMTP id c7-20020a170903234700b0018729febd96so12244182plh.19 for ; Tue, 08 Nov 2022 16:36:26 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20210112; h=cc:to:from:subject:message-id:mime-version:date:from:to:cc:subject :date:message-id:reply-to; bh=CZKNxZ4ut/Q7ACsrFTYtA5PMiQEhI2gWEXdAM+wb9gg=; b=cYSLYVLkoMHuam5SuetiF8cgGiYoAYiOA1FDE0de+JVwbInSf58Fn7Nuqba7t29Tlm kAEkRJI243IEl56URLz4GqhHzc5kNIoyBU5dolJ68qRmCHxVduAFhPFH9sXXHt7fsP2m wmOYn67OQtdmCCrHj+8T+iKeAM2KzgvXbTWuWou/qcNVuehaO2UQIl6x966q4q7Z8zpd Ngq+YURUPwM23Bk/LkbCwHiBmOToe4IyoOidBtQN8lPzxQ470F5rRAwMWnq3T1F7EKp0 isviHND/AkHcHu1qZfF96e0YUSkLT9d59G44rU/vjx0VWjDPLr9E1T9TmfaZIhC402Jc UqQg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:from:subject:message-id:mime-version:date:x-gm-message-state :from:to:cc:subject:date:message-id:reply-to; bh=CZKNxZ4ut/Q7ACsrFTYtA5PMiQEhI2gWEXdAM+wb9gg=; b=uGNn3nyujfayjeFMLCifu/pETX0detScG10rm+ZbsoftSoZibEh/4VrZUEgMVWrzdP LPTDnlVYI8tnLCcIRmn6c7z1V7FXOJplk+Y3OWKqwSmO8UxIewaFQBJwMvYUHgikRAXE tT/fdAeLWpBKxTyjihbJzWuvfLVMc83CXBM2RNTEP7sLm3p0OPbDSSxpaVuXptKf2lqn 6WEiJZ1gGn2ablnwVBhQ5EGbqvP+EQlYE75ohpttkMwZLJk0t++/w0gAYre3sbHrSklx p83EgbaW0P0qZH6CP9pOfLCdjwG/rkEdRvFA40f0yzF4Ga2OGy407/114OF/ji45t9Ec VesA== X-Gm-Message-State: ACrzQf2ss912KG76PD+6iA3e/oKcEl2+TLlFdLeyc4OLairnG3UklzOB 7N9mhwMEhfsBA0jBas4zF9I0Lo434BsSlQ== X-Received: from dlatypov-spec.c.googlers.com ([fda3:e722:ac3:cc00:24:72f4:c0a8:3f35]) (user=dlatypov job=sendgmr) by 2002:a17:90a:f3d4:b0:213:959f:5a90 with SMTP id ha20-20020a17090af3d400b00213959f5a90mr63952761pjb.54.1667954185985; Tue, 08 Nov 2022 16:36:25 -0800 (PST) Date: Tue, 8 Nov 2022 16:36:16 -0800 Mime-Version: 1.0 X-Mailer: git-send-email 2.38.1.431.g37b22c650d-goog Message-ID: <20221109003618.3784591-1-dlatypov@google.com> Subject: [PATCH v2 1/3] Documentation: KUnit: make usage.rst a superset of tips.rst, remove duplication From: Daniel Latypov To: brendanhiggins@google.com, davidgow@google.com Cc: rmoar@google.com, linux-kernel@vger.kernel.org, kunit-dev@googlegroups.com, linux-kselftest@vger.kernel.org, linux-doc@vger.kernel.org, skhan@linuxfoundation.org, Daniel Latypov X-Spam-Status: No, score=-9.6 required=5.0 tests=BAYES_00,DKIMWL_WL_MED, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE, SPF_HELO_NONE,SPF_PASS,USER_IN_DEF_DKIM_WL autolearn=unavailable autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1748977115037753579?= X-GMAIL-MSGID: =?utf-8?q?1748977115037753579?= usage.rst had most of the content of the tips.rst page copied over. But it's missing https://www.kernel.org/doc/html/v6.0/dev-tools/kunit/tips.html#customizing-error-messages Copy it over so we can retire tips.rst w/o losing content. And in that process, it also gained a duplicate section about how KUNIT_ASSERT_*() exit the test case early. Remove that. Signed-off-by: Daniel Latypov Reviewed-by: Sadiya Kazi --- Documentation/dev-tools/kunit/usage.rst | 49 ++++++++++++++++--------- 1 file changed, 31 insertions(+), 18 deletions(-) base-commit: 6fe1ad4a156095859721fef85073df3ed43081d4 diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index 2737863ef365..b0a6c3bc0eeb 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -118,6 +118,37 @@ expectation could crash the test case. `ASSERT_NOT_ERR_OR_NULL(...)` allows us to bail out of the test case if the appropriate conditions are not satisfied to complete the test. +Customizing error messages +-------------------------- + +Each of the ``KUNIT_EXPECT`` and ``KUNIT_ASSERT`` macros have a ``_MSG`` +variant. These take a format string and arguments to provide additional +context to the automatically generated error messages. + +.. code-block:: c + + char some_str[41]; + generate_sha1_hex_string(some_str); + + /* Before. Not easy to tell why the test failed. */ + KUNIT_EXPECT_EQ(test, strlen(some_str), 40); + + /* After. Now we see the offending string. */ + KUNIT_EXPECT_EQ_MSG(test, strlen(some_str), 40, "some_str='%s'", some_str); + +Alternatively, one can take full control over the error message by using +``KUNIT_FAIL()``, e.g. + +.. code-block:: c + + /* Before */ + KUNIT_EXPECT_EQ(test, some_setup_function(), 0); + + /* After: full control over the failure message. */ + if (some_setup_function()) + KUNIT_FAIL(test, "Failed to setup thing for testing"); + + Test Suites ~~~~~~~~~~~ @@ -546,24 +577,6 @@ By reusing the same ``cases`` array from above, we can write the test as a {} }; -Exiting Early on Failed Expectations ------------------------------------- - -We can use ``KUNIT_EXPECT_EQ`` to mark the test as failed and continue -execution. In some cases, it is unsafe to continue. We can use the -``KUNIT_ASSERT`` variant to exit on failure. - -.. code-block:: c - - void example_test_user_alloc_function(struct kunit *test) - { - void *object = alloc_some_object_for_me(); - - /* Make sure we got a valid pointer back. */ - KUNIT_ASSERT_NOT_ERR_OR_NULL(test, object); - do_something_with_object(object); - } - Allocating Memory ----------------- From patchwork Wed Nov 9 00:36:17 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Latypov X-Patchwork-Id: 17293 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:6687:0:0:0:0:0 with SMTP id l7csp60285wru; Tue, 8 Nov 2022 16:41:44 -0800 (PST) X-Google-Smtp-Source: AMsMyM78hXNC3bIUBuaaayNA6J31SsAZ1c1SiAgeaURl49OzmDt+WpP18o87+MgT/VekbgC3bF/5 X-Received: by 2002:a17:907:9603:b0:742:9ed3:3af2 with SMTP id gb3-20020a170907960300b007429ed33af2mr54490430ejc.510.1667954504132; Tue, 08 Nov 2022 16:41:44 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1667954504; cv=none; d=google.com; s=arc-20160816; b=BQs472Z2g+jXI7J97V9ym52uXHydlRZpUFGQSrkRFyE9LXJ7I3IXVcYVn60Hxp33Ou 4XHUDnYJVOmQ/rOy3gDJky48+VolOg8mOH76Ds345NAp36CVCc2QPSzHNnT52jUQdLWT c9gUI8b4Ug8+09MA9hbKsUY0v6yvx/nSKWyXj1vS/5p3narbIH9c0x8Z65k1t+tVWnUt azW82umB/Cqo7PfsPuh13nh39WR8+bcXjm6OxQGBBninxcJ8yHOFQiwD251yVpqFl4tC 0x8CgEtdejqEVMwT2nUEGlyoauWaP8tVTLcH4KIcW7lUv+m9Yo4xLBt0rB82KTJBLcIn NxVQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:cc:to:from:subject:message-id:references :mime-version:in-reply-to:date:dkim-signature; bh=i16E6SEJ1XE3RexrHSv+UKrQKUgWn1ksElBhVAhWC74=; b=gRYQDeGfZVLw+e+7v7NYRBUfrIgs2Ze/hlfZUHfw3MBbqPTW/kHbZz1UIO3oArDGv4 BW1h9qg1Smy950ShFeTeJPJy+SF4eLvvRloR9fYq5qOzB9qMLMPNG3ntW4Xv70QOZBuo 3v5RPh+8DZUKgGSH+WGjJ2lljYOPfUP+w3ClKX40fCOvrXfVS6ryUBoL/0zrnpERI1X3 50nVY2ZVHVh5OWZmISnvPnzYfRzaFJ8oMo1dF22Iu7/2yl+Gboj4VUVW805gIv+pBed9 FGwOhbLO/fysshhyzzLTonMzjgBlI+pT2H1YOx1Dg9hFn0BW0iEcyHYLKqbH6CTS1h+Z icoQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@google.com header.s=20210112 header.b=ozndvYKn; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=google.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id x36-20020a50baa7000000b004627f27a119si13341708ede.318.2022.11.08.16.41.14; Tue, 08 Nov 2022 16:41:44 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@google.com header.s=20210112 header.b=ozndvYKn; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=google.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229759AbiKIAgd (ORCPT + 99 others); Tue, 8 Nov 2022 19:36:33 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37830 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229828AbiKIAg3 (ORCPT ); Tue, 8 Nov 2022 19:36:29 -0500 Received: from mail-pj1-x1049.google.com (mail-pj1-x1049.google.com [IPv6:2607:f8b0:4864:20::1049]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 42BD863155 for ; Tue, 8 Nov 2022 16:36:28 -0800 (PST) Received: by mail-pj1-x1049.google.com with SMTP id pq17-20020a17090b3d9100b0020a4c65c3a9so6908329pjb.0 for ; Tue, 08 Nov 2022 16:36:28 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20210112; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:from:to:cc:subject:date:message-id:reply-to; bh=i16E6SEJ1XE3RexrHSv+UKrQKUgWn1ksElBhVAhWC74=; b=ozndvYKnYfbi79PbuCYdzeMtofBcdWRIc10S48fA0ZiNj/LbcnyA78EeEyHbGlu9n6 7J9OUUeOSTjZdMHJ2Jj8jMxpE5/dNiSdsErzggvwEEW2nUjxnCa6+TDqTkoDJz9gOj99 WXadIIjgvnxIVJ/DBFiBgHJkkWlKthceyqDaVjg9MiPmZqLDPR9LHxZsOGuMW6BjHu/c 3eJf90rCsgm0AwbOvUrB59Y/Jmt+M8z3+xf8wujZCxWlDqOqjDioHBcPrSHS2jcF5xIG mcVvtHsOwHn5TgP74M+8eZTB81t5B4R9Xo69adh1fUPMDntg2alkPx9VTHycCQY1TfJc Zpeg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=i16E6SEJ1XE3RexrHSv+UKrQKUgWn1ksElBhVAhWC74=; b=fKCHd+Bh95eSTID1URhvU7ZcNoo0N5RXScFOCWIdCOEFV8UeTWOl8AvLNIV+Z6zvJq CPu/6hqZeGUacOV7y0922BQjPC9SSINE6V5K0ee+m8rYqqKYW3lTWO9uOPKFzpp9AnFS dLdiIxaZAsHEmm2Q1UrqXPideJUzG8hREjRd+9B+4dztXEOKvR8ywc/7Xbc0WoVxsttZ cB5oCvC8HxfYNbqRVv4fdSq5mvKW5KsH7aXs4/uAJYTMOc/Q+ejxFrKTpawzNcDSmH8o Jtsih8ReaT3ZWA4JRhSwCrFUuO8k+Q0ewzaXeR7bmcBh9O5534BPBJd4VHXD6cqiaDXN Kb/A== X-Gm-Message-State: ANoB5plqGTJPQfcn/xFZMsaC+ZXKYuQmkNNiLl5Jtr36CVvXyJn3DK+I IXve0HmFLTMstN0FLYdyr8aMtFcWDeaL9Q== X-Received: from dlatypov-spec.c.googlers.com ([fda3:e722:ac3:cc00:24:72f4:c0a8:3f35]) (user=dlatypov job=sendgmr) by 2002:aa7:9ad7:0:b0:56e:d7f4:3c4a with SMTP id x23-20020aa79ad7000000b0056ed7f43c4amr657937pfp.76.1667954187657; Tue, 08 Nov 2022 16:36:27 -0800 (PST) Date: Tue, 8 Nov 2022 16:36:17 -0800 In-Reply-To: <20221109003618.3784591-1-dlatypov@google.com> Mime-Version: 1.0 References: <20221109003618.3784591-1-dlatypov@google.com> X-Mailer: git-send-email 2.38.1.431.g37b22c650d-goog Message-ID: <20221109003618.3784591-2-dlatypov@google.com> Subject: [PATCH v2 2/3] Documentation: KUnit: reword description of assertions From: Daniel Latypov To: brendanhiggins@google.com, davidgow@google.com Cc: rmoar@google.com, linux-kernel@vger.kernel.org, kunit-dev@googlegroups.com, linux-kselftest@vger.kernel.org, linux-doc@vger.kernel.org, skhan@linuxfoundation.org, Daniel Latypov X-Spam-Status: No, score=-9.6 required=5.0 tests=BAYES_00,DKIMWL_WL_MED, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE, SPF_HELO_NONE,SPF_PASS,USER_IN_DEF_DKIM_WL autolearn=unavailable autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1748977062123396707?= X-GMAIL-MSGID: =?utf-8?q?1748977062123396707?= The existing wording implies that kunit_kmalloc_array() is "the method under test". We're actually testing the sort() function in that example. This is because the example was changed in commit 953574390634 ("Documentation: KUnit: Rework writing page to focus on writing tests"), but the wording was not. Also add a `note` telling people they can use the KUNIT_ASSERT_EQ() macros from any function. Some users might be coming from a framework like gUnit where that'll compile but silently do the wrong thing. Signed-off-by: Daniel Latypov Reviewed-by: Sadiya Kazi Reviewed-by: David Gow --- Documentation/dev-tools/kunit/usage.rst | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst index b0a6c3bc0eeb..8060114e3aa6 100644 --- a/Documentation/dev-tools/kunit/usage.rst +++ b/Documentation/dev-tools/kunit/usage.rst @@ -112,11 +112,14 @@ terminates the test case if the condition is not satisfied. For example: KUNIT_EXPECT_LE(test, a[i], a[i + 1]); } -In this example, the method under test should return pointer to a value. If the -pointer returns null or an errno, we want to stop the test since the following -expectation could crash the test case. `ASSERT_NOT_ERR_OR_NULL(...)` allows us -to bail out of the test case if the appropriate conditions are not satisfied to -complete the test. +In this example, we need to be able to allocate an array to test the ``sort()`` +function. So we use ``KUNIT_ASSERT_NOT_ERR_OR_NULL()`` to abort the test if +we there's an allocation error. + +.. note:: + In other test frameworks, ``ASSERT`` macros are often implemented by calling + ``return`` so they only work from the test function. In KUnit, we stop the + current kthread on failure, so you can call them from anywhere. Customizing error messages -------------------------- From patchwork Wed Nov 9 00:36:18 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Latypov X-Patchwork-Id: 17294 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:6687:0:0:0:0:0 with SMTP id l7csp60460wru; Tue, 8 Nov 2022 16:42:16 -0800 (PST) X-Google-Smtp-Source: AMsMyM5KlzR5w51U67etjRd7ljoVeyBryHcw0AJ+KZw7WEXEUT8QiDxzwnOmFfsW/53wVS0uRiGs X-Received: by 2002:aa7:d6d1:0:b0:463:ba50:e574 with SMTP id x17-20020aa7d6d1000000b00463ba50e574mr40149048edr.158.1667954536329; Tue, 08 Nov 2022 16:42:16 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1667954536; cv=none; d=google.com; s=arc-20160816; b=Mtoq2z0DIf7+TRdbOASEJB5JkPxacSMC5E0m6tOlsEAOVQEdlVX6kOZ6JoaxzFq6Xp WZWyf3mrdfgkYr3slTQzxVfT7up+RycMKXDSSN1oH2wUQlUDPj+bQW0wl/MLP8QUUTXy 3YvOsZimJFJX3PEqhYxE59rt7DaFVeY9szm0ObDPuA50dE6tquGfAGmFzyAM1Eizab3D cydE5YJe8hixv7M/XocwlnDqHn+7S3H7izC4DlM5pcm2Ftx60nbMMXia0aErVyCmf25c lqWt2narDcJyoHQOvek56kd+g0dWTshfeH0xCp/NZYHM3MS7R1fxThTP8fwS+a6g/WX2 Z7PQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:cc:to:from:subject:message-id:references :mime-version:in-reply-to:date:dkim-signature; bh=HRpeAbE4kg4ytKwLuX0U3bbW7BL+7KJFVYe6N59c5wQ=; b=wkuMJcVjQrEhwHMaNIMnjZMli4wumlVTghpuVGRzYsYvZnXU4kNysUW5bnWmf9xfBi X7o9AN+H5DahOV9T+9Xvm3Sd83/rMKa4KjN5B6x2ypHkZpzn+5ypsBsfYE45S6+1Bmvq xUPsLvjQ/4x6JwHoKwVttrug6VzNdNObyXO+r/Q72YRgIa/zFibFG+3UbEV/A2u+tfph F17bqGgEoPOq3r9nTLwzrU5TV4jy779Kjog/VS3sAIBTd2DvdrNaE4AdSFqsXVl4AIKu LiVoMhc4msFj8iGUKcNrEANJ3ceWE17/NU5T0WD2Gd8ZahlI/U/P/AB3BKizRXayV1Lw 1edA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@google.com header.s=20210112 header.b=eYBlaZZd; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=google.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id c11-20020a05640227cb00b0045c3f5b458fsi17392145ede.397.2022.11.08.16.41.53; Tue, 08 Nov 2022 16:42:16 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; dkim=pass header.i=@google.com header.s=20210112 header.b=eYBlaZZd; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=REJECT sp=REJECT dis=NONE) header.from=google.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229917AbiKIAgj (ORCPT + 99 others); Tue, 8 Nov 2022 19:36:39 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37854 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229719AbiKIAgb (ORCPT ); Tue, 8 Nov 2022 19:36:31 -0500 Received: from mail-yw1-x114a.google.com (mail-yw1-x114a.google.com [IPv6:2607:f8b0:4864:20::114a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 2A668627D1 for ; Tue, 8 Nov 2022 16:36:30 -0800 (PST) Received: by mail-yw1-x114a.google.com with SMTP id 00721157ae682-352e29ff8c2so151268097b3.21 for ; Tue, 08 Nov 2022 16:36:30 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20210112; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:from:to:cc:subject:date:message-id:reply-to; bh=HRpeAbE4kg4ytKwLuX0U3bbW7BL+7KJFVYe6N59c5wQ=; b=eYBlaZZdnhKMf9c7h7BMTcyzAqd2R7kggGDvkeaEUPZm9F+2bTPLZVUpkrbhMiW/Xq iXqr170uBbJzFPegUMTV9y1VU1XHGTIh6LEi51SR+K+jgTS2iNPW98vZ45iOYXD0xKro nhgpk9XnCn4/XUxICCVwyyriUpEqe4zskFFcPRGPm1ikMgO2VpQjaJkQc6E+2DL6zeV5 Cu8/6F2+YcZhvRor9YRKsYU0F45JTi52UyBq+0I5GfmEF1uLSKGiS40VrWyvKfLKBjzm BJzuEYxxTFmpYTFp3UJQUyJg1c8dkuyQ6LnKzdniqttuH3ULLUVdjBNZ7FMNjgTi40/a ejAw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=HRpeAbE4kg4ytKwLuX0U3bbW7BL+7KJFVYe6N59c5wQ=; b=Ra/5/Bol5bK156HnrJq9x6kmfTRIeujHCLlkJjk4qPSd96Bw0cltZxyPVrJg18V1vu DJiJE/38GjZY5Jm4Io1+gIdIECNBhVFEn5i+YAwNRKJh7yIL1FmvXrRIoRPcCm+TPjSb STCF91+RCKQcPaLUcEOxxF5476v3Ep9rSnpwwBTrePgTMGjEllq7v+1iHt8UWMaGa3lW YtSqwLAxZcPV6kX+w5JgdYx+EKUVCyOWHhFZDaY50TiaRBCLtPkRsXawkSNT+0fcbnLW Er4VTBDlWzs5zP6Nuor3mCH4OCsQcO8yv5V2j4Dtd5i2TImoV/+04ZkyN/irZ/HEH/sw +5CQ== X-Gm-Message-State: ACrzQf0C/10yJbSFsSSdIxus4G9qNV40t8DTqCAKCbgzxOSnS43/PybC BDEKVLu5XlEgI9zSqKQWGKxYU22lpNCaJw== X-Received: from dlatypov-spec.c.googlers.com ([fda3:e722:ac3:cc00:24:72f4:c0a8:3f35]) (user=dlatypov job=sendgmr) by 2002:a81:80c3:0:b0:349:8498:a05b with SMTP id q186-20020a8180c3000000b003498498a05bmr55480921ywf.403.1667954189465; Tue, 08 Nov 2022 16:36:29 -0800 (PST) Date: Tue, 8 Nov 2022 16:36:18 -0800 In-Reply-To: <20221109003618.3784591-1-dlatypov@google.com> Mime-Version: 1.0 References: <20221109003618.3784591-1-dlatypov@google.com> X-Mailer: git-send-email 2.38.1.431.g37b22c650d-goog Message-ID: <20221109003618.3784591-3-dlatypov@google.com> Subject: [PATCH v2 3/3] Documentation: kunit: Remove redundant 'tips.rst' page From: Daniel Latypov To: brendanhiggins@google.com, davidgow@google.com Cc: rmoar@google.com, linux-kernel@vger.kernel.org, kunit-dev@googlegroups.com, linux-kselftest@vger.kernel.org, linux-doc@vger.kernel.org, skhan@linuxfoundation.org, Daniel Latypov X-Spam-Status: No, score=-9.6 required=5.0 tests=BAYES_00,DKIMWL_WL_MED, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_NONE, SPF_HELO_NONE,SPF_PASS,USER_IN_DEF_DKIM_WL autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1748977095610982684?= X-GMAIL-MSGID: =?utf-8?q?1748977095610982684?= From: David Gow The contents of 'tips.rst' was mostly included in 'usage.rst' way back in commit 953574390634 ("Documentation: KUnit: Rework writing page to focus on writing tests"), but the tips page remained behind as well. The parent patches in this series fill in the gaps, so now 'tips.rst' is redundant. Therefore, delete 'tips.rst'. While I regret breaking any links to 'tips' which might exist externally, it's confusing to have two subtly different versions of the same content around. Signed-off-by: David Gow Signed-off-by: Daniel Latypov Reviewed-by: Sadiya Kazi --- v1 -> v2: rebased onto some parent patches to fix the missing sections in usage.rst and tweaked the commit message to reflect that. --- Documentation/dev-tools/kunit/index.rst | 1 - Documentation/dev-tools/kunit/tips.rst | 190 ------------------------ 2 files changed, 191 deletions(-) delete mode 100644 Documentation/dev-tools/kunit/tips.rst diff --git a/Documentation/dev-tools/kunit/index.rst b/Documentation/dev-tools/kunit/index.rst index f5d13f1d37be..d5629817cd72 100644 --- a/Documentation/dev-tools/kunit/index.rst +++ b/Documentation/dev-tools/kunit/index.rst @@ -16,7 +16,6 @@ KUnit - Linux Kernel Unit Testing api/index style faq - tips running_tips This section details the kernel unit testing framework. diff --git a/Documentation/dev-tools/kunit/tips.rst b/Documentation/dev-tools/kunit/tips.rst deleted file mode 100644 index 492d2ded2f5a..000000000000 --- a/Documentation/dev-tools/kunit/tips.rst +++ /dev/null @@ -1,190 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -============================ -Tips For Writing KUnit Tests -============================ - -Exiting early on failed expectations ------------------------------------- - -``KUNIT_EXPECT_EQ`` and friends will mark the test as failed and continue -execution. In some cases, it's unsafe to continue and you can use the -``KUNIT_ASSERT`` variant to exit on failure. - -.. code-block:: c - - void example_test_user_alloc_function(struct kunit *test) - { - void *object = alloc_some_object_for_me(); - - /* Make sure we got a valid pointer back. */ - KUNIT_ASSERT_NOT_ERR_OR_NULL(test, object); - do_something_with_object(object); - } - -Allocating memory ------------------ - -Where you would use ``kzalloc``, you should prefer ``kunit_kzalloc`` instead. -KUnit will ensure the memory is freed once the test completes. - -This is particularly useful since it lets you use the ``KUNIT_ASSERT_EQ`` -macros to exit early from a test without having to worry about remembering to -call ``kfree``. - -Example: - -.. code-block:: c - - void example_test_allocation(struct kunit *test) - { - char *buffer = kunit_kzalloc(test, 16, GFP_KERNEL); - /* Ensure allocation succeeded. */ - KUNIT_ASSERT_NOT_ERR_OR_NULL(test, buffer); - - KUNIT_ASSERT_STREQ(test, buffer, ""); - } - - -Testing static functions ------------------------- - -If you don't want to expose functions or variables just for testing, one option -is to conditionally ``#include`` the test file at the end of your .c file, e.g. - -.. code-block:: c - - /* In my_file.c */ - - static int do_interesting_thing(); - - #ifdef CONFIG_MY_KUNIT_TEST - #include "my_kunit_test.c" - #endif - -Injecting test-only code ------------------------- - -Similarly to the above, it can be useful to add test-specific logic. - -.. code-block:: c - - /* In my_file.h */ - - #ifdef CONFIG_MY_KUNIT_TEST - /* Defined in my_kunit_test.c */ - void test_only_hook(void); - #else - void test_only_hook(void) { } - #endif - -This test-only code can be made more useful by accessing the current kunit -test, see below. - -Accessing the current test --------------------------- - -In some cases, you need to call test-only code from outside the test file, e.g. -like in the example above or if you're providing a fake implementation of an -ops struct. -There is a ``kunit_test`` field in ``task_struct``, so you can access it via -``current->kunit_test``. - -Here's a slightly in-depth example of how one could implement "mocking": - -.. code-block:: c - - #include /* for current */ - - struct test_data { - int foo_result; - int want_foo_called_with; - }; - - static int fake_foo(int arg) - { - struct kunit *test = current->kunit_test; - struct test_data *test_data = test->priv; - - KUNIT_EXPECT_EQ(test, test_data->want_foo_called_with, arg); - return test_data->foo_result; - } - - static void example_simple_test(struct kunit *test) - { - /* Assume priv is allocated in the suite's .init */ - struct test_data *test_data = test->priv; - - test_data->foo_result = 42; - test_data->want_foo_called_with = 1; - - /* In a real test, we'd probably pass a pointer to fake_foo somewhere - * like an ops struct, etc. instead of calling it directly. */ - KUNIT_EXPECT_EQ(test, fake_foo(1), 42); - } - - -Note: here we're able to get away with using ``test->priv``, but if you wanted -something more flexible you could use a named ``kunit_resource``, see -Documentation/dev-tools/kunit/api/test.rst. - -Failing the current test ------------------------- - -But sometimes, you might just want to fail the current test. In that case, we -have ``kunit_fail_current_test(fmt, args...)`` which is defined in ```` and -doesn't require pulling in ````. - -E.g. say we had an option to enable some extra debug checks on some data structure: - -.. code-block:: c - - #include - - #ifdef CONFIG_EXTRA_DEBUG_CHECKS - static void validate_my_data(struct data *data) - { - if (is_valid(data)) - return; - - kunit_fail_current_test("data %p is invalid", data); - - /* Normal, non-KUnit, error reporting code here. */ - } - #else - static void my_debug_function(void) { } - #endif - - -Customizing error messages --------------------------- - -Each of the ``KUNIT_EXPECT`` and ``KUNIT_ASSERT`` macros have a ``_MSG`` variant. -These take a format string and arguments to provide additional context to the automatically generated error messages. - -.. code-block:: c - - char some_str[41]; - generate_sha1_hex_string(some_str); - - /* Before. Not easy to tell why the test failed. */ - KUNIT_EXPECT_EQ(test, strlen(some_str), 40); - - /* After. Now we see the offending string. */ - KUNIT_EXPECT_EQ_MSG(test, strlen(some_str), 40, "some_str='%s'", some_str); - -Alternatively, one can take full control over the error message by using ``KUNIT_FAIL()``, e.g. - -.. code-block:: c - - /* Before */ - KUNIT_EXPECT_EQ(test, some_setup_function(), 0); - - /* After: full control over the failure message. */ - if (some_setup_function()) - KUNIT_FAIL(test, "Failed to setup thing for testing"); - -Next Steps -========== -* Optional: see the Documentation/dev-tools/kunit/usage.rst page for a more - in-depth explanation of KUnit.