From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 7E12B426A2; Mon, 2 Oct 2023 14:45:10 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 5556440294; Mon, 2 Oct 2023 14:45:10 +0200 (CEST) Received: from mgamail.intel.com (mgamail.intel.com [134.134.136.65]) by mails.dpdk.org (Postfix) with ESMTP id 2B5164003C for ; Mon, 2 Oct 2023 14:45:09 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1696250709; x=1727786709; h=from:to:cc:subject:date:message-id:mime-version: content-transfer-encoding; bh=pIjWbabt3dx9jdNMfGBtjBhFqjiJBZ++fRsTr9I+I2E=; b=J6/mTDpgs37I54eVrcYJFvfdxNaaVLby4TA8ujQSW3Ga/020/VjqYMq4 iQ4/DdnKbUVBMRR8Rl60VcqNeMYMWRB+t46kgNxW3h/X/urmRVEWrBy8E kOz0Xs1LYcF4ZIOmQNHNUQLEmkA/vmmTkby225yWcoM6JM+bRLKbGbKf2 xYriLjKcLDG+1w8ZRnd7C1aReTVcnwWSVyIe5bvo2/k1FTU6ERl0XM2dt bOiYiE2iJoE4sw6+y1yNVcXhs5MtYaxEO5kSoODDdHKbvubDZk1jyz4cA EiB0owPN2fAwXO+dLiQr9elIHr6a0BgoPalJJnVOnVikGD+Bs1rxwrSMU w==; X-IronPort-AV: E=McAfee;i="6600,9927,10851"; a="386505094" X-IronPort-AV: E=Sophos;i="6.03,194,1694761200"; d="scan'208";a="386505094" Received: from orsmga008.jf.intel.com ([10.7.209.65]) by orsmga103.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Oct 2023 05:45:07 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=McAfee;i="6600,9927,10851"; a="779920902" X-IronPort-AV: E=Sophos;i="6.03,194,1694761200"; d="scan'208";a="779920902" Received: from silpixa00401385.ir.intel.com ([10.237.214.41]) by orsmga008.jf.intel.com with ESMTP; 02 Oct 2023 05:45:06 -0700 From: Bruce Richardson To: dev@dpdk.org Cc: aconole@redhat.com, Bruce Richardson Subject: [PATCH] doc/contributing: update test guidelines for meson changes Date: Mon, 2 Oct 2023 13:44:59 +0100 Message-Id: <20231002124459.452527-1-bruce.richardson@intel.com> X-Mailer: git-send-email 2.39.2 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org With the meson test suites being reworked to be automatically generated, rather than having to be hard-coded in the meson.build file, we need to update our contributing guidelines to take account of this change. Signed-off-by: Bruce Richardson --- NOTE: this patch contains only changes needed to bring the doc up-to-date with the meson suite registration changes. I believe the doc needs further general updates beyond this, but that is out of scope for this patch. --- doc/guides/contributing/unit_test.rst | 34 +++++++++++++++------------ 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/doc/guides/contributing/unit_test.rst b/doc/guides/contributing/unit_test.rst index 1b2eb0da03..382eaf9667 100644 --- a/doc/guides/contributing/unit_test.rst +++ b/doc/guides/contributing/unit_test.rst @@ -126,16 +126,15 @@ the build system includes a standard way of executing the Meson test suites. After building via ``ninja``, the ``meson test`` command with no arguments will execute the Meson test suites. -There are five pre-configured Meson test suites. +There are a number of pre-configured Meson test suites. The first is the **fast** test suite, which is the largest group of test cases. These are the bulk of the unit tests to validate functional blocks. The second is the **perf** tests. These test suites can take longer to run and do performance evaluations. The third is the **driver** test suite, which is mostly for special hardware related testing (such as `cryptodev`). -The fourth suite is the **debug** suite. +The fourth, and currently the last, suite is the **debug** suite. These tests mostly are used to dump system information. -The last suite is the **extra** suite for tests having some known issues. The Meson test suites can be selected by adding the ``--suite`` option to the ``meson test`` command. @@ -184,10 +183,15 @@ create a new test file for that suite (ex: see *app/test/test_version.c* for the ``version_autotest`` test suite). There are two important functions for interacting with the test harness: - ``REGISTER_TEST_COMMAND(command_name, function_to_execute)`` + ``REGISTER__TEST(command_name, function_to_execute)`` Registers a test command with the name `command_name` - and which runs the function `function_to_execute` - when `command_name` is invoked. + and which runs the function `function_to_execute` when `command_name` is invoked. + The test is automatically added to the meson test suite `` by this macro. + Examples would be ``REGISTER_DRIVER_TEST``, or ``REGISTER_PERF_TEST``. + **NOTE:** The ``REGISTER_FAST_TEST`` macro is slightly different, + in that it takes two additional parameters, + specifying whether the test can be run using ``--no-huge``, + and whether the test can be run using Address Sanitization (ASAN) ``unit_test_suite_runner(struct unit_test_suite *)`` Returns a runner for a full test suite object, @@ -248,7 +252,7 @@ An example of both a test suite and a case: return unit_test_suite_runner(&example_testsuite); } - REGISTER_TEST_COMMAND(example_autotest, example_tests); + REGISTER_PERF_TEST(example_autotest, example_tests); The above code block is a small example that can be used to create a complete test suite with test case. @@ -315,7 +319,7 @@ of the unit test suite structure, for example: return ret; } - REGISTER_TEST_COMMAND(example_autotest, example_tests); + REGISTER_FAST_TEST(example_autotest, true /*no-huge*/, false /*ASan*/, example_tests); Designing a test @@ -392,9 +396,10 @@ This can be used to assist in test development. Adding a suite or test case to Meson ------------------------------------ -Adding to one of the Meson test suites involves -editing the appropriate Meson build file `app/test/meson.build` -and adding the command to the correct test suite class. +Adding to one of the Meson test suites involves using the appropriate macro to register the test in dpdk-test, +as described above. +For example, +defining the test command using ``REGISTER_PERF_TEST`` automatically adds the test to the perf-test meson suite. Once added, the new test will be run as part of the appropriate class (fast, perf, driver, etc.). @@ -409,11 +414,10 @@ by using the ``--list`` option:: Some of these test suites are run during continuous integration tests, making regression checking automatic for new patches submitted to the project. -In general, when a test is added to the `dpdk-test` application, -it probably should be added to a Meson test suite, -but the choice is left to maintainers and individual developers. -Preference is to add tests to the Meson test suites. +.. note:: + The use of the old ``REGISTER_TEST_COMMAND`` macro to add a command without adding it to a meson test suite is deprecated. + All new tests must be added to a test suite using the appropriate ``REGISTER__TEST`` macro Running cryptodev tests ----------------------- -- 2.39.2