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-…
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(a)google.com>
---
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
On Tue, 15 Nov 2022 at 13:36, Björn Töpel <bjorn(a)kernel.org> wrote:
>
Hi,
Adding the kselftest list
> I ran into build issues when building selftests/net on Ubuntu/Debian,
> which is related to that BPF program builds usually needs libc (and the
> corresponding target host configuration/defines).
>
> When I try to build selftests/net, on my Debian host I get:
I've ran into this issue too building with tuxmake [1] that uses
debian containers.
>
> clang -O2 -target bpf -c bpf/nat6to4.c -I../../bpf -I../../../../lib -I../../../../../usr/include/ -o /home/bjorn/src/linux/linux/tools/testing/selftests/net/bpf/nat6to4.o
> In file included from bpf/nat6to4.c:27:
> In file included from /usr/include/linux/bpf.h:11:
> /usr/include/linux/types.h:5:10: fatal error: 'asm/types.h' file not found
> #include <asm/types.h>
> ^~~~~~~~~~~~~
> 1 error generated.
>
> asm/types.h lives in /usr/include/"TRIPLE" on Debian, say
> /usr/include/x86_64-linux-gnu. Target BPF does not (obviously) add the
> x86-64 search path. These kind of problems have been worked around in,
> e.g., commit 167381f3eac0 ("selftests/bpf: Makefile fix "missing"
> headers on build with -idirafter").
>
> However, just adding the host specific path is not enough. Typically,
> when you start to include libc files, like "sys/socket.h" it's
> expected that host specific defines are set. On my x86-64 host:
>
> $ clang -dM -E - < /dev/null|grep x86_
> #define __x86_64 1
> #define __x86_64__ 1
>
> $ clang -target riscv64-linux-gnu -dM -E - < /dev/null|grep xlen
> #define __riscv_xlen 64
>
> otherwise you end up with errors like the one below.
>
> Missing __x86_64__:
> #if !defined __x86_64__
> # include <gnu/stubs-32.h>
> #endif
>
> clang -O2 -target bpf -c bpf/nat6to4.c -idirafter /usr/lib/llvm-16/lib/clang/16.0.0/include -idirafter /usr/local/include -idirafter /usr/include/x86_64-linux-gnu -idirafter /usr/include -Wno-compare-distinct-pointer-types -I../../bpf -I../../../../lib -I../../../../../usr/include/ -o /home/bjorn/src/linux/linux/tools/testing/selftests/net/bpf/nat6to4.o
> In file included from bpf/nat6to4.c:28:
> In file included from /usr/include/linux/if.h:28:
> In file included from /usr/include/x86_64-linux-gnu/sys/socket.h:22:
> In file included from /usr/include/features.h:510:
> /usr/include/x86_64-linux-gnu/gnu/stubs.h:7:11: fatal error: 'gnu/stubs-32.h' file not found
> # include <gnu/stubs-32.h>
> ^~~~~~~~~~~~~~~~
> 1 error generated.
>
> Now, say that we'd like to cross-compile for a platform. Should I make
> sure that all the target compiler's "default defines" are exported to
> the BPF-program build step? I did a hack for RISC-V a while back in
> commit 6016df8fe874 ("selftests/bpf: Fix broken riscv build"). Not
> super robust, and not something I'd like to see for all supported
> platforms.
>
> Any ideas? Maybe a convenience switch to Clang/target bpf? :-)
I added the same thing selftests/bpf have in their Makefile [2] and that
highlighted another issue which is that selftests/net/bpf depends on
bpf_helpers.h
which in turn depends on the generated file bpf_helper_defs.h...
Cheers,
Anders
[1] https://tuxmake.org/
[2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/too…