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 -----------------