From patchwork Fri Nov 11 18:29:04 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Latypov X-Patchwork-Id: 18938 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:6687:0:0:0:0:0 with SMTP id l7csp904326wru; Fri, 11 Nov 2022 10:35:40 -0800 (PST) X-Google-Smtp-Source: AA0mqf7JoFhTRBHXzvCxDO9QXKh9N5RltIYimFtKkMWNa+lYPLsMX/pSZVtzZZ8/t3moTTHiAnJ9 X-Received: by 2002:a50:fb0b:0:b0:461:91e1:368 with SMTP id d11-20020a50fb0b000000b0046191e10368mr2595692edq.327.1668191740583; Fri, 11 Nov 2022 10:35:40 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1668191740; cv=none; d=google.com; s=arc-20160816; b=eTUB7yu8VmAp5RKOjzvu7on9T7bOgsOwdseKWd9Hq0Q0DYc+vgx9XMpuw7ibkMVyrQ DfWY2CwQM5F3ywkP2xSXyJYA7LzJinJsL7T9tdh++dHwnhS4F+MNSJOI7DKREV+IuIn8 cAqtZFItXYXnRGdbC+ruZFwAHw9ikzutVS+vBX6qFy5CnDFMqlDsV1GpCpihkuqkOPAj pZfvZnOFCyoBjWo2jOo3PjCfDJdNRFiuQx6r1GuEowP1kmNgkc5Is0xdp624EFD/YYUV McEultu+gu9MXBWhchv4Mi+3ruSW4dlV67vCOhLZneBU8hAix4aEArA7SX0hnLcuxKOO aQrA== 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=/XHe3/zCTpZWNceRA9RtU7Jdjy85jUuF1PtTziDeOJ4=; b=PMaXDYodxStoGh5UVqyRBCyUr6+zxuKNKSZMjXQAZj06XbBcbC/mR7CjLd6jkn9P39 +CrFFfE6iZTDa7aIqGlxSsXsFpD8VunF38RwC8gpQ93wL/0e/0hkQtTRHnCzfUnV56pp B10SKt4jPFylcfjzl4xXjTpwDUA37QP8iJ/xBIN4fdT63e9j6QwuuYhbLrLBslQaY2dx oLIMfmOhkGmZW4ge94kztdQL+SaA+h9LzayYa3Sxcf47Ta17/yJZy/5kOm6GpP30U+Yr MkngubHpO47iATuB+SsnQz3dRU/6SN8THG27Ac74zhUOAKp8msIyYXEkBDzsERqPcbJB LNjg== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@google.com header.s=20210112 header.b=SHWYMQw6; 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 ho16-20020a1709070e9000b0073ffabc3352si2804573ejc.836.2022.11.11.10.35.16; Fri, 11 Nov 2022 10:35:40 -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=SHWYMQw6; 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 S234224AbiKKS3m (ORCPT + 99 others); Fri, 11 Nov 2022 13:29:42 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:33400 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234146AbiKKS30 (ORCPT ); Fri, 11 Nov 2022 13:29:26 -0500 Received: from mail-pf1-x44a.google.com (mail-pf1-x44a.google.com [IPv6:2607:f8b0:4864:20::44a]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 554AF5CD15 for ; Fri, 11 Nov 2022 10:29:25 -0800 (PST) Received: by mail-pf1-x44a.google.com with SMTP id cj8-20020a056a00298800b0056cee8a0cf8so3083030pfb.9 for ; Fri, 11 Nov 2022 10:29:25 -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=/XHe3/zCTpZWNceRA9RtU7Jdjy85jUuF1PtTziDeOJ4=; b=SHWYMQw6kstMFCPeHdhZKyPK3U1w2EOYu+EfQeWTuTi4NJieEMZil99CRywaRL3QXr M7ApzG4XLCYAg0PetxNjHSfwNLA3LxmKu8LWDFygNY1lctOOSshYpwuhWdWdEPG4cj6h QWqck+Cp18gxDExvnjGBgUh7CGuL123P/8Sic7xH/4xHFrfRq9PyO6QZDjJ4xQ81rw8G Mj7r+mHBVner9YkXBqCGbX7sD3i/SJKHNJEtf9od3zBTOZpkh1OElZCPLXu9Kh0yHr+g 5EMsCruUmvhnGFsKUm63rt7fbbaTOV3YvxO7RSu0ufBKSPyJZYCW9ZnNfdCPxDuX08e5 qhGA== 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=/XHe3/zCTpZWNceRA9RtU7Jdjy85jUuF1PtTziDeOJ4=; b=dSlMUvG+plkJLVcXNRjJV25SO3vZ7w/o/ngtytVF2HPDPGBawbQuCGhdkuBZ4T19AY DiKX9dQM4BLe1vr25onEtfwNiP9eFFKAAcqx9cVZ4jXt6C26dHRQEUthPsxYrQsP8vZL qrNWRm65LvC70TvFHynILfEmfB/pqpKzV8vwau3UTrmAQc11NgwjhI9aw6rtcp1MUq8m ZlmM1rQzylYZjDltj/Jd7kz1jib+sgNgJYpuEJcVJ6tzi6aSe6Hxb99C0ytSnuQljATv 82K0sJzv1Mh6E/coR4ozSq4diZyiYh2laDLTnuVilELb1uhjs/Q+O9O8xj5HsgEWPyCB hpUw== X-Gm-Message-State: ANoB5pmRIJcoH9mlSEepGxAcm85bPYxkb+zNIitXCXDahLNKgV2wh7K2 L6VjJsnTZ785EHRbmaZhYaSuJZ0fL0ecGQ== X-Received: from dlatypov-spec.c.googlers.com ([fda3:e722:ac3:cc00:24:72f4:c0a8:3f35]) (user=dlatypov job=sendgmr) by 2002:a17:90a:d01:b0:20a:fee1:8f69 with SMTP id t1-20020a17090a0d0100b0020afee18f69mr7707pja.0.1668191364606; Fri, 11 Nov 2022 10:29:24 -0800 (PST) Date: Fri, 11 Nov 2022 10:29:04 -0800 Mime-Version: 1.0 X-Mailer: git-send-email 2.38.1.431.g37b22c650d-goog Message-ID: <20221111182906.1377191-1-dlatypov@google.com> Subject: [PATCH v3 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 , Sadiya Kazi 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?1749225822522334011?= X-GMAIL-MSGID: =?utf-8?q?1749225822522334011?= 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 Reviewed-by: David Gow --- Documentation/dev-tools/kunit/usage.rst | 49 ++++++++++++++++--------- 1 file changed, 31 insertions(+), 18 deletions(-) base-commit: 870f63b7cd78d0055902d839a60408f7428b4e84 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 Fri Nov 11 18:29:05 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Latypov X-Patchwork-Id: 18940 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:6687:0:0:0:0:0 with SMTP id l7csp904379wru; Fri, 11 Nov 2022 10:35:47 -0800 (PST) X-Google-Smtp-Source: AA0mqf5OLx36f/qXbZYstyjTJgRsn0UKNkD2KmmtcWmX4AG1GyxMzM1HrBgGw+VVMALz44s3Ijk4 X-Received: by 2002:a05:6402:2b89:b0:45f:c7f2:297d with SMTP id fj9-20020a0564022b8900b0045fc7f2297dmr2677519edb.266.1668191747350; Fri, 11 Nov 2022 10:35:47 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1668191747; cv=none; d=google.com; s=arc-20160816; b=s/S4HjPyyIYjgVDw73AfFFCm51YmrstaC9B87Vz5IMwMbegvb6x/ykCd0vKHf5D7zd u1AYuHRwoow8HB23jdiYBE4bJovzV8xBKQscwoXz0XdKqsJeWqugPsU6uC9dubKjKEgS E3R9badeSnZer2HceltAC3r4CdGwsEpxHMVOBVggVRKKfIQ0PyXeYPEurab+MMiRQd2J etAqyox9dKl4QBeNCwfTG/wtupPRSbkN4CY14IfsquZxs5CrqudKqIassLDA3hST8Qdx JxDOQ04aTbX/jmFABeo7LwuB/4bWqKTgqfvkQvALCzFzA9/gDQw3CuHFFwDB2IT3wW2K IG0Q== 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=KcgFgh+nSA6rGpYyKLAuOEZq9MjORsirblL9B+ChLi0=; b=AB927oHC3+mB4lplikZrYACsIgxh75nj4WdWwVlm2Wcbx8j5+xb/gQNwlBFTUqiRV8 t/QOYqpchIUMGBxxqN8JizGBERGQopYl/okAgm5bBcZLlu1SQYuE6z5qayISFdv/ZdiY DNadBgG5Bkgit3HQRikMiFPqdhx5GVF/qekvI+37yeYswF1O/0ONnwBwmO0A/4Gg0H2s 2MtRRub7K55B643pqt3myu15Zbfc0S1Aov+y2z8AGKoYHmH5O+3NteZIHT+Tg0Ug+vzq fkkcdogqLpseaoNpMZcYhqYSndwXuVFUGFuS5JPXwsTdXgFtDzr+cq4bHLIPZ6kI4/TE Vsvw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@google.com header.s=20210112 header.b="GN/K8Lkz"; 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 qw18-20020a1709066a1200b007ae98ea45e0si2785916ejc.751.2022.11.11.10.35.23; Fri, 11 Nov 2022 10:35:47 -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="GN/K8Lkz"; 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 S234253AbiKKS3p (ORCPT + 99 others); Fri, 11 Nov 2022 13:29:45 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:33416 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234157AbiKKS31 (ORCPT ); Fri, 11 Nov 2022 13:29:27 -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 111565CD05 for ; Fri, 11 Nov 2022 10:29:27 -0800 (PST) Received: by mail-pj1-x1049.google.com with SMTP id c10-20020a17090aa60a00b00212e91df6acso3082412pjq.5 for ; Fri, 11 Nov 2022 10:29:27 -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=KcgFgh+nSA6rGpYyKLAuOEZq9MjORsirblL9B+ChLi0=; b=GN/K8LkzrC3Xi5m04YE/88CUGXGI57CIBf0CroPXanf1c2e6S7KaF1zLqjHRHaJxTx GjvPAk0vMcz6bA+Z4e5AcNtwS8mrZeHu5LV1+rn9AUJ2buoMWZLYzv9ZOeqx8p90AClW d6tTK9BSyqanwQ7lWbOgSTQgzJu5hJc6k6RH4Umsl2iyoKEsZeEo3LWxKjJAeFlbRGdn t2T0hO+T2pQQWkpLB6mpYhu5eIgLgYbYKfQyVBtJ2LKCmwARyFYbzrW+mPnt/8U1HCuE vfvziKXdQL3Iy3zXYcXgXULs2DiskUzS69Uezt504J3TOKAHeIuvc8XiNQcxhonzGESx 1eoQ== 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=KcgFgh+nSA6rGpYyKLAuOEZq9MjORsirblL9B+ChLi0=; b=Qxx3+yQeYDDqu1JpuZIn2mF8cVFz1jcpSRcac6Uaqeb0IjgQmSxNkvjRRSV7yPEIau KJRwQfEmyr1SIhX91NCABkylmok0f82VUG9h6m/43CW2hXAcVNG4pMJGt6lYIi72y+FC i5LIKvCVjkiimOKnvJPDEkejUjn3UzfXPDPWHS1yQcXjEjvS3Dr+6lU2zWr4mYsql/HT 4NhgaAQlSBhztYpiGzMdEz8LC+71MAo09Cx8B73sIQB8+A0mHae9wsl2VjnPCEOW1euU y7dKt+qw1Ii5teVWMF3Pd3EeztGl0OB6t+NSRnDOUqPNfnBMMtX2uasbcP2NOizbsJ8P MwFA== X-Gm-Message-State: ANoB5plN+2C8+tomvvklw4sVl+yK3CNTA49xkGhR4EhpXWp4G+ewfyWI 3HxVGFXqtUpZW3uaqI/qeKONHDpCvlFLeg== X-Received: from dlatypov-spec.c.googlers.com ([fda3:e722:ac3:cc00:24:72f4:c0a8:3f35]) (user=dlatypov job=sendgmr) by 2002:a17:902:9302:b0:187:3a43:3a9d with SMTP id bc2-20020a170902930200b001873a433a9dmr3593182plb.152.1668191366583; Fri, 11 Nov 2022 10:29:26 -0800 (PST) Date: Fri, 11 Nov 2022 10:29:05 -0800 In-Reply-To: <20221111182906.1377191-1-dlatypov@google.com> Mime-Version: 1.0 References: <20221111182906.1377191-1-dlatypov@google.com> X-Mailer: git-send-email 2.38.1.431.g37b22c650d-goog Message-ID: <20221111182906.1377191-2-dlatypov@google.com> Subject: [PATCH v3 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 , Sadiya Kazi 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?1749225829781747497?= X-GMAIL-MSGID: =?utf-8?q?1749225829781747497?= 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..22416ebb94ab 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 +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 Fri Nov 11 18:29:06 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Latypov X-Patchwork-Id: 18939 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a5d:6687:0:0:0:0:0 with SMTP id l7csp904375wru; Fri, 11 Nov 2022 10:35:47 -0800 (PST) X-Google-Smtp-Source: AA0mqf7tIzM0IncgbZPT99GVm0ODtrOD1i3yinmoyfyPjHt8B7+5sNXRHpbcPTKWrpdvwuSxWini X-Received: by 2002:a17:906:ad82:b0:7ae:415:3fb5 with SMTP id la2-20020a170906ad8200b007ae04153fb5mr2778562ejb.255.1668191746873; Fri, 11 Nov 2022 10:35:46 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1668191746; cv=none; d=google.com; s=arc-20160816; b=ryWS7bqlhwQG1iw/NPzn13JqWqPe9ipQdOVPQSDV3rReaVNPpuSss0QAWQIfnujW7a biJuv3mVY5Cuado9C/ztKCkTxjcAxMCSl+y70Zv5BKAXQ5u9iCxzam1lSjW0GqFquCzG oYSX9Z2kdEiaozxLiV3MljvEKBdTTPAMS9nGAUsa2DUJ2huMOBNDRvXfma858RGy7d51 ssTLciYulrfGNwmqcDM495WGcLu8kp39dSe5LLrQJtgxV9vWQ3WKPkXz89V2Crc129ZZ hfoy8N1fIz8h0zUkpzLtT22sQjBFBFYHPh4N//X3a1FfzeZXoqRbx755Wb4NyRYD8Aw8 47cA== 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=r84PG1jgHBipBYlbDtpXYn0KfCJQRPPV8o0t+BC7r80=; b=w/qSKi+cnS2rs4xdshj23F9wgxRrUOn6CVS/DGiCViLn+Mx6iJFHkAvouIcUkSlO58 dr2/Iz1xnLIJ+gpF24Xg2ojfw2VyE6c0IPaB6LsGegJ6Zi1EIT+GbQ2VazsTVm0ahP7e H++5hbfe4vsHn/h4My+/CFIdzmCPuPsBgrlryX2Lm+pBFVGpJxlrWhIelwIVFeWGLaMm wTQc8XpzNd6iqm7eEf0eX+vEqA5soZvXkdkO+jyTml4hQsLCNRpG0j3p0HTygjTj0raz UBEqpw8IWKvkMRq9aPqGGs76v18ECaNlnGmgtuVmH/vaNsEO/TtaNYQxi83Y4u3wzj3B g1ww== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@google.com header.s=20210112 header.b=RTy2mC0L; 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 h4-20020a0564020e0400b0046155426889si2846402edh.272.2022.11.11.10.35.23; Fri, 11 Nov 2022 10:35:46 -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=RTy2mC0L; 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 S234289AbiKKS3q (ORCPT + 99 others); Fri, 11 Nov 2022 13:29:46 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:33434 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234167AbiKKS3a (ORCPT ); Fri, 11 Nov 2022 13:29:30 -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 737B95B5A7 for ; Fri, 11 Nov 2022 10:29:29 -0800 (PST) Received: by mail-yw1-x114a.google.com with SMTP id 00721157ae682-37010fefe48so50819147b3.19 for ; Fri, 11 Nov 2022 10:29:29 -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=r84PG1jgHBipBYlbDtpXYn0KfCJQRPPV8o0t+BC7r80=; b=RTy2mC0LwDZH56aX/w5OhguMBUe0+J5NWLoqXauoT3IvbjP/GZvP1lp3Ift6APPArw S0endsxM2v7avWGZ+xCuwXUGDN1LUVmi91L7dhjt+htx7KxAGxyNOFM7nD2b5cV9Gjet buNVVDzwkcV0nD4TURr1q/Yb95l5qlwiHrXiN1Wa5ZSlFNtuhxnJZ+it6EZo//YgJeik FE+LS07QdGQf7NGbEIgl3UI5l28xphpdu91FyM0N5oN+V6awlfOCHo16TYQtqzA0GQ7I yz623pljBCpZ0pOe/hhh3r7I+V3xhKWBdS4NYzn+am8dRY/ZDPkW2jqT444VqZ7G5oFX 0AUw== 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=r84PG1jgHBipBYlbDtpXYn0KfCJQRPPV8o0t+BC7r80=; b=gkc61cO6U+X58y4WFaP4c7DqSELolj92HG7ZAF5bpiPMa95+9DhFo4rAUGotcx31vi BUdh4T0RH7QA7Yvq/UhbiKYoL49AgslYqGSccCLOHZGvkDefLhTEzNJZAoll9bP3zAak kjP+8GdQPakXbG3vabKDJe5zDFGSOqasSd1ouXFkbz+shFbhoV5rp6287FJJfrQeL1OF dignWSCE+9HSibP2uq7rpzy2TyfPlyO+MhaEA9/YgEkou02Sq2k43h1L6NefZnHnEQ10 BgOAspNCsGoDTUCkANy46YGP+LctmN/8VzNkLBVgbb5UejbY4gsyvDBnHrqhUE4yMEMz vOOw== X-Gm-Message-State: ACrzQf1f9goEJe1qkR31/libBChdcExyN1DRdA2qGz1W0fmUDQAC+AJZ 07FQ6SoL44nWUnhW4HYkZ+30I55My37I8w== X-Received: from dlatypov-spec.c.googlers.com ([fda3:e722:ac3:cc00:24:72f4:c0a8:3f35]) (user=dlatypov job=sendgmr) by 2002:a81:5d7:0:b0:367:300a:b24a with SMTP id 206-20020a8105d7000000b00367300ab24amr65639713ywf.128.1668191368372; Fri, 11 Nov 2022 10:29:28 -0800 (PST) Date: Fri, 11 Nov 2022 10:29:06 -0800 In-Reply-To: <20221111182906.1377191-1-dlatypov@google.com> Mime-Version: 1.0 References: <20221111182906.1377191-1-dlatypov@google.com> X-Mailer: git-send-email 2.38.1.431.g37b22c650d-goog Message-ID: <20221111182906.1377191-3-dlatypov@google.com> Subject: [PATCH v3 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 , Sadiya Kazi 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?1749225829116738252?= X-GMAIL-MSGID: =?utf-8?q?1749225829116738252?= 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.