[v3,1/3] Documentation: KUnit: make usage.rst a superset of tips.rst, remove duplication

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>
Reviewed-by: Sadiya Kazi <sadiyakazi@google.com>
---
 Documentation/dev-tools/kunit/usage.rst | 49 ++++++++++++++++---------
 1 file changed, 31 insertions(+), 18 deletions(-)


base-commit: 870f63b7cd78d0055902d839a60408f7428b4e84

On Sat, Nov 12, 2022 at 2:29 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>
> Reviewed-by: Sadiya Kazi <sadiyakazi@google.com>
> ---

Looks good to me, thanks!

Reviewed-by: David Gow <davidgow@google.com>

Cheers,
-- David

>  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: 870f63b7cd78d0055902d839a60408f7428b4e84
> --
> 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/20221111182906.1377191-1-dlatypov%40google.com.