Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/133909/?format=api
{ "id": 133909, "url": "http://patches.dpdk.org/api/patches/133909/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/patch/20231106171601.160749-9-juraj.linkes@pantheon.tech/", "project": { "id": 1, "url": "http://patches.dpdk.org/api/projects/1/?format=api", "name": "DPDK", "link_name": "dpdk", "list_id": "dev.dpdk.org", "list_email": "dev@dpdk.org", "web_url": "http://core.dpdk.org", "scm_url": "git://dpdk.org/dpdk", "webscm_url": "http://git.dpdk.org/dpdk", "list_archive_url": "https://inbox.dpdk.org/dev", "list_archive_url_format": "https://inbox.dpdk.org/dev/{}", "commit_url_format": "" }, "msgid": "<20231106171601.160749-9-juraj.linkes@pantheon.tech>", "list_archive_url": "https://inbox.dpdk.org/dev/20231106171601.160749-9-juraj.linkes@pantheon.tech", "date": "2023-11-06T17:15:46", "name": "[v5,08/23] dts: test suite docstring update", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": true, "hash": "c9e9daf111f0ea5459cc5fbda11ecf6928a2681e", "submitter": { "id": 1626, "url": "http://patches.dpdk.org/api/people/1626/?format=api", "name": "Juraj Linkeš", "email": "juraj.linkes@pantheon.tech" }, "delegate": { "id": 2642, "url": "http://patches.dpdk.org/api/users/2642/?format=api", "username": "mcoquelin", "first_name": "Maxime", "last_name": "Coquelin", "email": "maxime.coquelin@redhat.com" }, "mbox": "http://patches.dpdk.org/project/dpdk/patch/20231106171601.160749-9-juraj.linkes@pantheon.tech/mbox/", "series": [ { "id": 30173, "url": "http://patches.dpdk.org/api/series/30173/?format=api", "web_url": "http://patches.dpdk.org/project/dpdk/list/?series=30173", "date": "2023-11-06T17:15:38", "name": "dts: add dts api docs", "version": 5, "mbox": "http://patches.dpdk.org/series/30173/mbox/" } ], "comments": "http://patches.dpdk.org/api/patches/133909/comments/", "check": "success", "checks": "http://patches.dpdk.org/api/patches/133909/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<dev-bounces@dpdk.org>", "X-Original-To": "patchwork@inbox.dpdk.org", "Delivered-To": "patchwork@inbox.dpdk.org", "Received": [ "from mails.dpdk.org (mails.dpdk.org [217.70.189.124])\n\tby inbox.dpdk.org (Postfix) with ESMTP id 88C1A432BB;\n\tMon, 6 Nov 2023 18:17:13 +0100 (CET)", "from mails.dpdk.org (localhost [127.0.0.1])\n\tby mails.dpdk.org (Postfix) with ESMTP id 49EFD40EDC;\n\tMon, 6 Nov 2023 18:16:18 +0100 (CET)", "from mail-ej1-f52.google.com (mail-ej1-f52.google.com\n [209.85.218.52]) by mails.dpdk.org (Postfix) with ESMTP id B0C6A40E2D\n for <dev@dpdk.org>; Mon, 6 Nov 2023 18:16:16 +0100 (CET)", "by mail-ej1-f52.google.com with SMTP id\n a640c23a62f3a-9dbb3d12aefso676763866b.0\n for <dev@dpdk.org>; Mon, 06 Nov 2023 09:16:16 -0800 (PST)", "from jlinkes-PT-Latitude-5530.. (ip-46.34.243.197.o2inet.sk.\n [46.34.243.197]) by smtp.gmail.com with ESMTPSA id\n s10-20020a170906354a00b009b947aacb4bsm47016eja.191.2023.11.06.09.16.15\n (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n Mon, 06 Nov 2023 09:16:16 -0800 (PST)" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=pantheon.tech; s=google; t=1699290976; x=1699895776; darn=dpdk.org;\n h=content-transfer-encoding:mime-version:references:in-reply-to\n :message-id:date:subject:cc:to:from:from:to:cc:subject:date\n :message-id:reply-to;\n bh=G6YPFi+z5sN9CIKgDbzi+2+pExm1ffPsLTIbtsOXKR0=;\n b=bjuQvevIzwXMKoovEwOGS2DyDKboOBh2DuWGd7EzYZECMS2KEQHgZoivF26vsJYkKF\n dzK8nvUkmAAqJssTANGi6SVqiOZoxNaL/eDx8Il12VTjm14OspwRvXB+KMMCfTJDmJNI\n CUPRUUWonWasIuyje5FDao4NiLtoHNpIDBqQYp1/XUkYfHPXBkp5JmIK8JFBjfaJPkUa\n bPzBrJ/W6f54s9HmEKUNe1ILfnJS8nLkPeuwlCsvIwezTwhAlpks67wFx6RSD73MHbha\n sgfgxtPl1YxeMnaWSfDzR6r4kdGi4tzY/3yTNBXc3h7QNkol9hKpCunvtrDEeOu3ORDw\n dJJw==", "X-Google-DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=1e100.net; s=20230601; t=1699290976; x=1699895776;\n h=content-transfer-encoding:mime-version:references:in-reply-to\n :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc\n :subject:date:message-id:reply-to;\n bh=G6YPFi+z5sN9CIKgDbzi+2+pExm1ffPsLTIbtsOXKR0=;\n b=urXih7kUWM1UnQ966OR8Ghb61bvvTu9RabGt5LoAUGpzHALInRBIDMH1OJ/d7/VMRk\n dXd+p/FdoiOnG3+Z+oXzKL0oUSu2DtyrBOqGQf07xEEI+X7Nt7Ngb8FGn87QOS7SUa+s\n w54zBHPT7JA98rToigq8p2MRoycupg6jlfKE+xWrIPRNhgq78+wnVkZGAn6nNEmYdijb\n Cen66xkAX2QY8nyy0GmcZGIAwObxNMPpCYC5arKIQXf1FQ7vpJgPZIZm2Y0ypd/BzofQ\n jQOIot2zkwtuyJkz10O9ek5q8XCLyd+Z2y1ZHCTwq4H2vR0C5OssUSuwpdrxigvtIoOx\n euTw==", "X-Gm-Message-State": "AOJu0YxomHuiEi+y852mxrAImsi9JIDn9yyDV6aseop+rNNFDEakqPpu\n NiVmJhGQxeprW622xCobuxeeXOI2pWztr31945MJNg==", "X-Google-Smtp-Source": "\n AGHT+IH8/Cekyrm83ureGznASUOvQS8yTQZlE0gnpO5KgmkQySH5OmcYwtka/5V2BA3jYaX9EoYIdw==", "X-Received": "by 2002:a17:907:934d:b0:9af:4561:591d with SMTP id\n bv13-20020a170907934d00b009af4561591dmr14508870ejc.18.1699290976271;\n Mon, 06 Nov 2023 09:16:16 -0800 (PST)", "From": "=?utf-8?q?Juraj_Linke=C5=A1?= <juraj.linkes@pantheon.tech>", "To": "thomas@monjalon.net, Honnappa.Nagarahalli@arm.com,\n bruce.richardson@intel.com, jspewock@iol.unh.edu, probb@iol.unh.edu,\n paul.szczepanek@arm.com, yoan.picchi@foss.arm.com", "Cc": "dev@dpdk.org, =?utf-8?q?Juraj_Linke=C5=A1?= <juraj.linkes@pantheon.tech>", "Subject": "[PATCH v5 08/23] dts: test suite docstring update", "Date": "Mon, 6 Nov 2023 18:15:46 +0100", "Message-Id": "<20231106171601.160749-9-juraj.linkes@pantheon.tech>", "X-Mailer": "git-send-email 2.34.1", "In-Reply-To": "<20231106171601.160749-1-juraj.linkes@pantheon.tech>", "References": "<20230831100407.59865-1-juraj.linkes@pantheon.tech>\n <20231106171601.160749-1-juraj.linkes@pantheon.tech>", "MIME-Version": "1.0", "Content-Type": "text/plain; charset=UTF-8", "Content-Transfer-Encoding": "8bit", "X-BeenThere": "dev@dpdk.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "DPDK patches and discussions <dev.dpdk.org>", "List-Unsubscribe": "<https://mails.dpdk.org/options/dev>,\n <mailto:dev-request@dpdk.org?subject=unsubscribe>", "List-Archive": "<http://mails.dpdk.org/archives/dev/>", "List-Post": "<mailto:dev@dpdk.org>", "List-Help": "<mailto:dev-request@dpdk.org?subject=help>", "List-Subscribe": "<https://mails.dpdk.org/listinfo/dev>,\n <mailto:dev-request@dpdk.org?subject=subscribe>", "Errors-To": "dev-bounces@dpdk.org" }, "content": "Format according to the Google format and PEP257, with slight\ndeviations.\n\nSigned-off-by: Juraj Linkeš <juraj.linkes@pantheon.tech>\n---\n dts/framework/test_suite.py | 223 +++++++++++++++++++++++++++---------\n 1 file changed, 168 insertions(+), 55 deletions(-)", "diff": "diff --git a/dts/framework/test_suite.py b/dts/framework/test_suite.py\nindex d53553bf34..8daac35818 100644\n--- a/dts/framework/test_suite.py\n+++ b/dts/framework/test_suite.py\n@@ -2,8 +2,19 @@\n # Copyright(c) 2010-2014 Intel Corporation\n # Copyright(c) 2023 PANTHEON.tech s.r.o.\n \n-\"\"\"\n-Base class for creating DTS test cases.\n+\"\"\"Features common to all test suites.\n+\n+The module defines the :class:`TestSuite` class which doesn't contain any test cases, and as such\n+must be extended by subclasses which add test cases. The :class:`TestSuite` contains the basics\n+needed by subclasses:\n+\n+ * Test suite and test case execution flow,\n+ * Testbed (SUT, TG) configuration,\n+ * Packet sending and verification,\n+ * Test case verification.\n+\n+The module also defines a function, :func:`get_test_suites`,\n+for gathering test suites from a Python module.\n \"\"\"\n \n import importlib\n@@ -31,25 +42,44 @@\n \n \n class TestSuite(object):\n- \"\"\"\n- The base TestSuite class provides methods for handling basic flow of a test suite:\n- * test case filtering and collection\n- * test suite setup/cleanup\n- * test setup/cleanup\n- * test case execution\n- * error handling and results storage\n- Test cases are implemented by derived classes. Test cases are all methods\n- starting with test_, further divided into performance test cases\n- (starting with test_perf_) and functional test cases (all other test cases).\n- By default, all test cases will be executed. A list of testcase str names\n- may be specified in conf.yaml or on the command line\n- to filter which test cases to run.\n- The methods named [set_up|tear_down]_[suite|test_case] should be overridden\n- in derived classes if the appropriate suite/test case fixtures are needed.\n+ \"\"\"The base class with methods for handling the basic flow of a test suite.\n+\n+ * Test case filtering and collection,\n+ * Test suite setup/cleanup,\n+ * Test setup/cleanup,\n+ * Test case execution,\n+ * Error handling and results storage.\n+\n+ Test cases are implemented by subclasses. Test cases are all methods starting with ``test_``,\n+ further divided into performance test cases (starting with ``test_perf_``)\n+ and functional test cases (all other test cases).\n+\n+ By default, all test cases will be executed. A list of testcase names may be specified\n+ in the YAML test run configuration file and in the :option:`--test-cases` command line argument\n+ or in the :envvar:`DTS_TESTCASES` environment variable to filter which test cases to run.\n+ The union of both lists will be used. Any unknown test cases from the latter lists\n+ will be silently ignored.\n+\n+ If the :option:`--re-run` command line argument or the :envvar:`DTS_RERUN` environment variable\n+ is set, in case of a test case failure, the test case will be executed again until it passes\n+ or it fails that many times in addition of the first failure.\n+\n+ The methods named ``[set_up|tear_down]_[suite|test_case]`` should be overridden in subclasses\n+ if the appropriate test suite/test case fixtures are needed.\n+\n+ The test suite is aware of the testbed (the SUT and TG) it's running on. From this, it can\n+ properly choose the IP addresses and other configuration that must be tailored to the testbed.\n+\n+ Attributes:\n+ sut_node: The SUT node where the test suite is running.\n+ tg_node: The TG node where the test suite is running.\n+ is_blocking: Whether the test suite is blocking. A failure of a blocking test suite\n+ will block the execution of all subsequent test suites in the current build target.\n \"\"\"\n \n sut_node: SutNode\n- is_blocking = False\n+ tg_node: TGNode\n+ is_blocking: bool = False\n _logger: DTSLOG\n _test_cases_to_run: list[str]\n _func: bool\n@@ -72,6 +102,19 @@ def __init__(\n func: bool,\n build_target_result: BuildTargetResult,\n ):\n+ \"\"\"Initialize the test suite testbed information and basic configuration.\n+\n+ Process what test cases to run, create the associated :class:`TestSuiteResult`,\n+ find links between ports and set up default IP addresses to be used when configuring them.\n+\n+ Args:\n+ sut_node: The SUT node where the test suite will run.\n+ tg_node: The TG node where the test suite will run.\n+ test_cases: The list of test cases to execute.\n+ If empty, all test cases will be executed.\n+ func: Whether to run functional tests.\n+ build_target_result: The build target result this test suite is run in.\n+ \"\"\"\n self.sut_node = sut_node\n self.tg_node = tg_node\n self._logger = getLogger(self.__class__.__name__)\n@@ -95,6 +138,7 @@ def __init__(\n self._tg_ip_address_ingress = ip_interface(\"192.168.101.3/24\")\n \n def _process_links(self) -> None:\n+ \"\"\"Construct links between SUT and TG ports.\"\"\"\n for sut_port in self.sut_node.ports:\n for tg_port in self.tg_node.ports:\n if (sut_port.identifier, sut_port.peer) == (\n@@ -106,27 +150,42 @@ def _process_links(self) -> None:\n )\n \n def set_up_suite(self) -> None:\n- \"\"\"\n- Set up test fixtures common to all test cases; this is done before\n- any test case is run.\n+ \"\"\"Set up test fixtures common to all test cases.\n+\n+ This is done before any test case has been run.\n \"\"\"\n \n def tear_down_suite(self) -> None:\n- \"\"\"\n- Tear down the previously created test fixtures common to all test cases.\n+ \"\"\"Tear down the previously created test fixtures common to all test cases.\n+\n+ This is done after all test have been run.\n \"\"\"\n \n def set_up_test_case(self) -> None:\n- \"\"\"\n- Set up test fixtures before each test case.\n+ \"\"\"Set up test fixtures before each test case.\n+\n+ This is done before *each* test case.\n \"\"\"\n \n def tear_down_test_case(self) -> None:\n- \"\"\"\n- Tear down the previously created test fixtures after each test case.\n+ \"\"\"Tear down the previously created test fixtures after each test case.\n+\n+ This is done after *each* test case.\n \"\"\"\n \n def configure_testbed_ipv4(self, restore: bool = False) -> None:\n+ \"\"\"Configure IPv4 addresses on all testbed ports.\n+\n+ The configured ports are:\n+\n+ * SUT ingress port,\n+ * SUT egress port,\n+ * TG ingress port,\n+ * TG egress port.\n+\n+ Args:\n+ restore: If :data:`True`, will remove the configuration instead.\n+ \"\"\"\n delete = True if restore else False\n enable = False if restore else True\n self._configure_ipv4_forwarding(enable)\n@@ -153,11 +212,13 @@ def _configure_ipv4_forwarding(self, enable: bool) -> None:\n def send_packet_and_capture(\n self, packet: Packet, duration: float = 1\n ) -> list[Packet]:\n- \"\"\"\n- Send a packet through the appropriate interface and\n- receive on the appropriate interface.\n- Modify the packet with l3/l2 addresses corresponding\n- to the testbed and desired traffic.\n+ \"\"\"Send and receive `packet` using the associated TG.\n+\n+ Send `packet` through the appropriate interface and receive on the appropriate interface.\n+ Modify the packet with l3/l2 addresses corresponding to the testbed and desired traffic.\n+\n+ Returns:\n+ A list of received packets.\n \"\"\"\n packet = self._adjust_addresses(packet)\n return self.tg_node.send_packet_and_capture(\n@@ -165,13 +226,25 @@ def send_packet_and_capture(\n )\n \n def get_expected_packet(self, packet: Packet) -> Packet:\n+ \"\"\"Inject the proper L2/L3 addresses into `packet`.\n+\n+ Args:\n+ packet: The packet to modify.\n+\n+ Returns:\n+ `packet` with injected L2/L3 addresses.\n+ \"\"\"\n return self._adjust_addresses(packet, expected=True)\n \n def _adjust_addresses(self, packet: Packet, expected: bool = False) -> Packet:\n- \"\"\"\n+ \"\"\"L2 and L3 address additions in both directions.\n+\n Assumptions:\n- Two links between SUT and TG, one link is TG -> SUT,\n- the other SUT -> TG.\n+ Two links between SUT and TG, one link is TG -> SUT, the other SUT -> TG.\n+\n+ Args:\n+ packet: The packet to modify.\n+ expected: If True, the direction is SUT -> TG, otherwise the direction is TG -> SUT.\n \"\"\"\n if expected:\n # The packet enters the TG from SUT\n@@ -197,6 +270,19 @@ def _adjust_addresses(self, packet: Packet, expected: bool = False) -> Packet:\n return Ether(packet.build())\n \n def verify(self, condition: bool, failure_description: str) -> None:\n+ \"\"\"Verify `condition` and handle failures.\n+\n+ When `condition` is :data:`False`, raise an exception and log the last 10 commands\n+ executed on both the SUT and TG.\n+\n+ Args:\n+ condition: The condition to check.\n+ failure_description: A short description of the failure\n+ that will be stored in the raised exception.\n+\n+ Raises:\n+ TestCaseVerifyError: `condition` is :data:`False`.\n+ \"\"\"\n if not condition:\n self._fail_test_case_verify(failure_description)\n \n@@ -216,6 +302,19 @@ def _fail_test_case_verify(self, failure_description: str) -> None:\n def verify_packets(\n self, expected_packet: Packet, received_packets: list[Packet]\n ) -> None:\n+ \"\"\"Verify that `expected_packet` has been received.\n+\n+ Go through `received_packets` and check that `expected_packet` is among them.\n+ If not, raise an exception and log the last 10 commands\n+ executed on both the SUT and TG.\n+\n+ Args:\n+ expected_packet: The packet we're expecting to receive.\n+ received_packets: The packets where we're looking for `expected_packet`.\n+\n+ Raises:\n+ TestCaseVerifyError: `expected_packet` is not among `received_packets`.\n+ \"\"\"\n for received_packet in received_packets:\n if self._compare_packets(expected_packet, received_packet):\n break\n@@ -303,10 +402,14 @@ def _verify_l3_packet(self, received_packet: IP, expected_packet: IP) -> bool:\n return True\n \n def run(self) -> None:\n- \"\"\"\n- Setup, execute and teardown the whole suite.\n- Suite execution consists of running all test cases scheduled to be executed.\n- A test cast run consists of setup, execution and teardown of said test case.\n+ \"\"\"Set up, execute and tear down the whole suite.\n+\n+ Test suite execution consists of running all test cases scheduled to be executed.\n+ A test case run consists of setup, execution and teardown of said test case.\n+\n+ Record the setup and the teardown and handle failures.\n+\n+ The list of scheduled test cases is constructed when creating the :class:`TestSuite` object.\n \"\"\"\n test_suite_name = self.__class__.__name__\n \n@@ -338,9 +441,7 @@ def run(self) -> None:\n raise BlockingTestSuiteError(test_suite_name)\n \n def _execute_test_suite(self) -> None:\n- \"\"\"\n- Execute all test cases scheduled to be executed in this suite.\n- \"\"\"\n+ \"\"\"Execute all test cases scheduled to be executed in this suite.\"\"\"\n if self._func:\n for test_case_method in self._get_functional_test_cases():\n test_case_name = test_case_method.__name__\n@@ -357,14 +458,18 @@ def _execute_test_suite(self) -> None:\n self._run_test_case(test_case_method, test_case_result)\n \n def _get_functional_test_cases(self) -> list[MethodType]:\n- \"\"\"\n- Get all functional test cases.\n+ \"\"\"Get all functional test cases defined in this TestSuite.\n+\n+ Returns:\n+ The list of functional test cases of this TestSuite.\n \"\"\"\n return self._get_test_cases(r\"test_(?!perf_)\")\n \n def _get_test_cases(self, test_case_regex: str) -> list[MethodType]:\n- \"\"\"\n- Return a list of test cases matching test_case_regex.\n+ \"\"\"Return a list of test cases matching test_case_regex.\n+\n+ Returns:\n+ The list of test cases matching test_case_regex of this TestSuite.\n \"\"\"\n self._logger.debug(f\"Searching for test cases in {self.__class__.__name__}.\")\n filtered_test_cases = []\n@@ -378,9 +483,7 @@ def _get_test_cases(self, test_case_regex: str) -> list[MethodType]:\n return filtered_test_cases\n \n def _should_be_executed(self, test_case_name: str, test_case_regex: str) -> bool:\n- \"\"\"\n- Check whether the test case should be executed.\n- \"\"\"\n+ \"\"\"Check whether the test case should be scheduled to be executed.\"\"\"\n match = bool(re.match(test_case_regex, test_case_name))\n if self._test_cases_to_run:\n return match and test_case_name in self._test_cases_to_run\n@@ -390,9 +493,9 @@ def _should_be_executed(self, test_case_name: str, test_case_regex: str) -> bool\n def _run_test_case(\n self, test_case_method: MethodType, test_case_result: TestCaseResult\n ) -> None:\n- \"\"\"\n- Setup, execute and teardown a test case in this suite.\n- Exceptions are caught and recorded in logs and results.\n+ \"\"\"Setup, execute and teardown a test case in this suite.\n+\n+ Record the result of the setup and the teardown and handle failures.\n \"\"\"\n test_case_name = test_case_method.__name__\n \n@@ -427,9 +530,7 @@ def _run_test_case(\n def _execute_test_case(\n self, test_case_method: MethodType, test_case_result: TestCaseResult\n ) -> None:\n- \"\"\"\n- Execute one test case and handle failures.\n- \"\"\"\n+ \"\"\"Execute one test case, record the result and handle failures.\"\"\"\n test_case_name = test_case_method.__name__\n try:\n self._logger.info(f\"Starting test case execution: {test_case_name}\")\n@@ -452,6 +553,18 @@ def _execute_test_case(\n \n \n def get_test_suites(testsuite_module_path: str) -> list[type[TestSuite]]:\n+ r\"\"\"Find all :class:`TestSuite`\\s in a Python module.\n+\n+ Args:\n+ testsuite_module_path: The path to the Python module.\n+\n+ Returns:\n+ The list of :class:`TestSuite`\\s found within the Python module.\n+\n+ Raises:\n+ ConfigurationError: The test suite module was not found.\n+ \"\"\"\n+\n def is_test_suite(object: Any) -> bool:\n try:\n if issubclass(object, TestSuite) and object is not TestSuite:\n", "prefixes": [ "v5", "08/23" ] }