| Message ID | 20221109003618.3784591-1-dlatypov@google.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | 65c48a48ead042856525b92cedf673d2bf5bdfc9 |
| Delegated to: | Brendan Higgins |
| Headers | show |
| Series | [v2,1/3] Documentation: KUnit: make usage.rst a superset of tips.rst, remove duplication | expand |
On Wed, Nov 9, 2022 at 6:06 AM 'Daniel Latypov' via KUnit Development <kunit-dev@googlegroups.com> wrote: > > 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 <dlatypov@google.com> > --- Thanks Daniel. This looks fine to me. Reviewed-by: Sadiya Kazi <sadiyakazi@google.com> Best Regards, Sadiya > Documentation/dev-tools/kunit/usage.rst | 49 ++++++++++++++++--------- > 1 file changed, 31 insertions(+), 18 deletions(-) > > 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 > ----------------- > > > base-commit: 6fe1ad4a156095859721fef85073df3ed43081d4 > -- > 2.38.1.431.g37b22c650d-goog > > -- > You received this message because you are subscribed to the Google Groups "KUnit Development" group. > To unsubscribe from this group and stop receiving emails from it, send an email to kunit-dev+unsubscribe@googlegroups.com. > To view this discussion on the web visit https://groups.google.com/d/msgid/kunit-dev/20221109003618.3784591-1-dlatypov%40google.com.
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 -----------------
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 <dlatypov@google.com> --- Documentation/dev-tools/kunit/usage.rst | 49 ++++++++++++++++--------- 1 file changed, 31 insertions(+), 18 deletions(-) base-commit: 6fe1ad4a156095859721fef85073df3ed43081d4