Re: [PATCH v2 6/6] Documentation/dev-tools: Add kselftest_harness documentation
On Tue, May 2, 2017 at 3:26 PM, Mickaël Salaün wrote: > Add metadata to kselftest_harness.h to be able to include the comments > in the Sphinx documentation. > > Signed-off-by: Mickaël Salaün > Cc: Andy Lutomirski > Cc: Jonathan Corbet > Cc: Kees Cook > Cc: Shuah Khan > Cc: Will Drewry > --- > Documentation/dev-tools/kselftest.rst | 57 ++ > tools/testing/selftests/kselftest_harness.h | 259 > > 2 files changed, 243 insertions(+), 73 deletions(-) > > diff --git a/Documentation/dev-tools/kselftest.rst > b/Documentation/dev-tools/kselftest.rst > index 39af2cb3d248..cf1e1f262c44 100644 > --- a/Documentation/dev-tools/kselftest.rst > +++ b/Documentation/dev-tools/kselftest.rst > @@ -138,3 +138,60 @@ Contributing new tests (details) > executable which is not tested by default. > TEST_FILES, TEST_GEN_FILES mean it is the file which is used by > test. > + > +Test Harness > + > + > +The *kselftest_harness.h* file contains useful helpers to build tests. The > +tests from seccomp/seccomp_bpf.c can be used as examples. > + > +Example > +~~~ > + > +.. code-block:: c > + > +#include "../kselftest_harness.h" > + > +TEST(standalone_test) { > + do_some_stuff; > + EXPECT_GT(10, stuff) { > + stuff_state_t state; > + enumerate_stuff_state(&state); > + TH_LOG("expectation failed with state: %s", state.msg); > + } > + more_stuff; > + ASSERT_NE(some_stuff, NULL) TH_LOG("how did it happen?!"); > + last_stuff; > + EXPECT_EQ(0, last_stuff); > +} > + > +FIXTURE(my_fixture) { > + mytype_t *data; > + int awesomeness_level; > +}; > +FIXTURE_SETUP(my_fixture) { > + self->data = mytype_new(); > + ASSERT_NE(NULL, self->data); > +} > +FIXTURE_TEARDOWN(my_fixture) { > + mytype_free(self->data); > +} > +TEST_F(my_fixture, data_is_good) { > + EXPECT_EQ(1, is_my_data_good(self->data)); > +} > + > +TEST_HARNESS_MAIN > + > + > +Helpers > +~ > + > +.. kernel-doc:: tools/testing/selftests/kselftest_harness.h > +:doc: helpers > + > + > +Operators > +~ > + > +.. kernel-doc:: tools/testing/selftests/kselftest_harness.h > +:doc: operators Awesome! Yay docs! > diff --git a/tools/testing/selftests/kselftest_harness.h > b/tools/testing/selftests/kselftest_harness.h > index 8ba227db46aa..efe50c80 100644 > --- a/tools/testing/selftests/kselftest_harness.h > +++ b/tools/testing/selftests/kselftest_harness.h > @@ -4,38 +4,6 @@ > * > * kselftest_harness.h: simple C unit test helper. > * > - * Usage: Can you add a pointer to the .rst file so someone looking at the header file will find out where to get an example? Otherwise, looks great! -Kees > - * #include "../kselftest_harness.h" > - * TEST(standalone_test) { > - * do_some_stuff; > - * EXPECT_GT(10, stuff) { > - *stuff_state_t state; > - *enumerate_stuff_state(&state); > - *TH_LOG("expectation failed with state: %s", state.msg); > - * } > - * more_stuff; > - * ASSERT_NE(some_stuff, NULL) TH_LOG("how did it happen?!"); > - * last_stuff; > - * EXPECT_EQ(0, last_stuff); > - * } > - * > - * FIXTURE(my_fixture) { > - * mytype_t *data; > - * int awesomeness_level; > - * }; > - * FIXTURE_SETUP(my_fixture) { > - * self->data = mytype_new(); > - * ASSERT_NE(NULL, self->data); > - * } > - * FIXTURE_TEARDOWN(my_fixture) { > - * mytype_free(self->data); > - * } > - * TEST_F(my_fixture, data_is_good) { > - * EXPECT_EQ(1, is_my_data_good(self->data)); > - * } > - * > - * TEST_HARNESS_MAIN > - * > * API inspired by code.google.com/p/googletest > */ > > @@ -58,7 +26,13 @@ > * Exported APIs > */ > > -/* TEST(name) { implementation } > +/** > + * DOC: helpers > + * > + * .. code-block:: c > + * > + * TEST(name) { implementation } > + * > * Defines a test by name. > * Names must be unique and tests must not be run in parallel. The > * implementation containing block is a function and scoping should be > treated > @@ -68,7 +42,13 @@ > */ > #define TEST TEST_API(TEST) > > -/* TEST_SIGNAL(name, signal) { implementation } > +/** > + * DOC: helpers > + * > + * .. code-block:: c > + * > + * TEST_SIGNAL(name, signal) { implementation } > + * > * Defines a test by name and the expected term signal. > * Names must be unique and tests must not be run in parallel. The > * implementation containing block is a function and scoping should be > treated > @@ -78,25 +58,43 @@ > */ > #define TEST_SIGNAL TEST_API(TEST_SIGNAL) > > -/* FIXTURE(datatype name) { > - * type property1; > - * ... > - * }; > - * Defines the data provided to TEST_F()-defined tests as |self|. It should > be > +/** > + * DOC: helpers > + * > + * .. code-block:: c > + * > + * FIXTURE(datatype name) { > + * type property1; > + * ... > + * }; > + * > + * Defines
[PATCH v2 6/6] Documentation/dev-tools: Add kselftest_harness documentation
Add metadata to kselftest_harness.h to be able to include the comments in the Sphinx documentation. Signed-off-by: Mickaël Salaün Cc: Andy Lutomirski Cc: Jonathan Corbet Cc: Kees Cook Cc: Shuah Khan Cc: Will Drewry --- Documentation/dev-tools/kselftest.rst | 57 ++ tools/testing/selftests/kselftest_harness.h | 259 2 files changed, 243 insertions(+), 73 deletions(-) diff --git a/Documentation/dev-tools/kselftest.rst b/Documentation/dev-tools/kselftest.rst index 39af2cb3d248..cf1e1f262c44 100644 --- a/Documentation/dev-tools/kselftest.rst +++ b/Documentation/dev-tools/kselftest.rst @@ -138,3 +138,60 @@ Contributing new tests (details) executable which is not tested by default. TEST_FILES, TEST_GEN_FILES mean it is the file which is used by test. + +Test Harness + + +The *kselftest_harness.h* file contains useful helpers to build tests. The +tests from seccomp/seccomp_bpf.c can be used as examples. + +Example +~~~ + +.. code-block:: c + +#include "../kselftest_harness.h" + +TEST(standalone_test) { + do_some_stuff; + EXPECT_GT(10, stuff) { + stuff_state_t state; + enumerate_stuff_state(&state); + TH_LOG("expectation failed with state: %s", state.msg); + } + more_stuff; + ASSERT_NE(some_stuff, NULL) TH_LOG("how did it happen?!"); + last_stuff; + EXPECT_EQ(0, last_stuff); +} + +FIXTURE(my_fixture) { + mytype_t *data; + int awesomeness_level; +}; +FIXTURE_SETUP(my_fixture) { + self->data = mytype_new(); + ASSERT_NE(NULL, self->data); +} +FIXTURE_TEARDOWN(my_fixture) { + mytype_free(self->data); +} +TEST_F(my_fixture, data_is_good) { + EXPECT_EQ(1, is_my_data_good(self->data)); +} + +TEST_HARNESS_MAIN + + +Helpers +~ + +.. kernel-doc:: tools/testing/selftests/kselftest_harness.h +:doc: helpers + + +Operators +~ + +.. kernel-doc:: tools/testing/selftests/kselftest_harness.h +:doc: operators diff --git a/tools/testing/selftests/kselftest_harness.h b/tools/testing/selftests/kselftest_harness.h index 8ba227db46aa..efe50c80 100644 --- a/tools/testing/selftests/kselftest_harness.h +++ b/tools/testing/selftests/kselftest_harness.h @@ -4,38 +4,6 @@ * * kselftest_harness.h: simple C unit test helper. * - * Usage: - * #include "../kselftest_harness.h" - * TEST(standalone_test) { - * do_some_stuff; - * EXPECT_GT(10, stuff) { - *stuff_state_t state; - *enumerate_stuff_state(&state); - *TH_LOG("expectation failed with state: %s", state.msg); - * } - * more_stuff; - * ASSERT_NE(some_stuff, NULL) TH_LOG("how did it happen?!"); - * last_stuff; - * EXPECT_EQ(0, last_stuff); - * } - * - * FIXTURE(my_fixture) { - * mytype_t *data; - * int awesomeness_level; - * }; - * FIXTURE_SETUP(my_fixture) { - * self->data = mytype_new(); - * ASSERT_NE(NULL, self->data); - * } - * FIXTURE_TEARDOWN(my_fixture) { - * mytype_free(self->data); - * } - * TEST_F(my_fixture, data_is_good) { - * EXPECT_EQ(1, is_my_data_good(self->data)); - * } - * - * TEST_HARNESS_MAIN - * * API inspired by code.google.com/p/googletest */ @@ -58,7 +26,13 @@ * Exported APIs */ -/* TEST(name) { implementation } +/** + * DOC: helpers + * + * .. code-block:: c + * + * TEST(name) { implementation } + * * Defines a test by name. * Names must be unique and tests must not be run in parallel. The * implementation containing block is a function and scoping should be treated @@ -68,7 +42,13 @@ */ #define TEST TEST_API(TEST) -/* TEST_SIGNAL(name, signal) { implementation } +/** + * DOC: helpers + * + * .. code-block:: c + * + * TEST_SIGNAL(name, signal) { implementation } + * * Defines a test by name and the expected term signal. * Names must be unique and tests must not be run in parallel. The * implementation containing block is a function and scoping should be treated @@ -78,25 +58,43 @@ */ #define TEST_SIGNAL TEST_API(TEST_SIGNAL) -/* FIXTURE(datatype name) { - * type property1; - * ... - * }; - * Defines the data provided to TEST_F()-defined tests as |self|. It should be +/** + * DOC: helpers + * + * .. code-block:: c + * + * FIXTURE(datatype name) { + * type property1; + * ... + * }; + * + * Defines the data provided to TEST_F()-defined tests as \|self\|. It should be * populated and cleaned up using FIXTURE_SETUP and FIXTURE_TEARDOWN. */ #define FIXTURE TEST_API(FIXTURE) -/* FIXTURE_DATA(datatype name) +/** + * DOC: helpers + * + * .. code-block:: c + * + * FIXTURE_DATA(datatype name) + * * This call may be used when the type of the fixture data * is needed. In general, this should not be needed unless - * the |self| is being passed to a helper directly. + * the \|self\| is being passed to a helper directly. */ #define FIXTURE_DATA TEST_API(F