tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

tools: unittests: add tests for CMatch

The CMatch logic is complex enough to justify tests to ensure
that it is doing its job.

Add unittests to check the functionality provided by CMatch
by replicating expected patterns.

The CMatch class handles with complex macros. Add an unittest
to check if its doing the right thing and detect eventual regressions
as we improve its code.

The initial version was generated using gpt-oss:latest LLM
on my local GPU, as LLMs aren't bad transforming patterns
into unittests.

Yet, the curent version contains only the skeleton of what
LLM produced, as I ended higly changing its content to be
more representative and to have real case scenarios.

The kdoc_xforms test suite contains 3 test groups. Two of
them tests the basic functionality of CMatch to
replace patterns.

The last one (TestRealUsecases) contains real code snippets
from the Kernel with some cleanups to better fit in 80 columns
and uses the same transforms as kernel-doc, thus allowing
to test the logic used inside kdoc_parser to transform
functions, structs and variable patterns.

Its output is like this:

$ tools/unittests/kdoc_xforms.py
Ran 25 tests in 0.003s

OK
test_cmatch:
TestSearch:
test_search_acquires_multiple: OK
test_search_acquires_nested_paren: OK
test_search_acquires_simple: OK
test_search_must_hold: OK
test_search_must_hold_shared: OK
test_search_no_false_positive: OK
test_search_no_function: OK
test_search_no_macro_remains: OK

Ran 8 tests

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <119712b5bc53b4c6dda6a81b4a783dcbfd1d970d.1773770483.git.mchehab+huawei@kernel.org>

authored by

Mauro Carvalho Chehab and committed by
Jonathan Corbet 50b87bb4 f1cf9f7c

+95
+95
tools/unittests/test_cmatch.py
··· 1 + #!/usr/bin/env python3 2 + # SPDX-License-Identifier: GPL-2.0 3 + # Copyright(c) 2026: Mauro Carvalho Chehab <mchehab@kernel.org>. 4 + # 5 + # pylint: disable=C0413,R0904 6 + 7 + 8 + """ 9 + Unit tests for kernel-doc CMatch. 10 + """ 11 + 12 + import os 13 + import re 14 + import sys 15 + import unittest 16 + 17 + 18 + # Import Python modules 19 + 20 + SRC_DIR = os.path.dirname(os.path.realpath(__file__)) 21 + sys.path.insert(0, os.path.join(SRC_DIR, "../lib/python")) 22 + 23 + from kdoc.c_lex import CMatch 24 + from kdoc.xforms_lists import CTransforms 25 + from unittest_helper import run_unittest 26 + 27 + # 28 + # Override unittest.TestCase to better compare diffs ignoring whitespaces 29 + # 30 + class TestCaseDiff(unittest.TestCase): 31 + """ 32 + Disable maximum limit on diffs and add a method to better 33 + handle diffs with whitespace differences. 34 + """ 35 + 36 + @classmethod 37 + def setUpClass(cls): 38 + """Ensure that there won't be limit for diffs""" 39 + cls.maxDiff = None 40 + 41 + 42 + # 43 + # Tests doing with different macros 44 + # 45 + 46 + class TestSearch(TestCaseDiff): 47 + """ 48 + Test search mechanism 49 + """ 50 + 51 + def test_search_acquires_simple(self): 52 + line = "__acquires(ctx) foo();" 53 + result = ", ".join(CMatch("__acquires").search(line)) 54 + self.assertEqual(result, "__acquires(ctx)") 55 + 56 + def test_search_acquires_multiple(self): 57 + line = "__acquires(ctx) __acquires(other) bar();" 58 + result = ", ".join(CMatch("__acquires").search(line)) 59 + self.assertEqual(result, "__acquires(ctx), __acquires(other)") 60 + 61 + def test_search_acquires_nested_paren(self): 62 + line = "__acquires((ctx1, ctx2)) baz();" 63 + result = ", ".join(CMatch("__acquires").search(line)) 64 + self.assertEqual(result, "__acquires((ctx1, ctx2))") 65 + 66 + def test_search_must_hold(self): 67 + line = "__must_hold(&lock) do_something();" 68 + result = ", ".join(CMatch("__must_hold").search(line)) 69 + self.assertEqual(result, "__must_hold(&lock)") 70 + 71 + def test_search_must_hold_shared(self): 72 + line = "__must_hold_shared(RCU) other();" 73 + result = ", ".join(CMatch("__must_hold_shared").search(line)) 74 + self.assertEqual(result, "__must_hold_shared(RCU)") 75 + 76 + def test_search_no_false_positive(self): 77 + line = "call__acquires(foo); // should stay intact" 78 + result = ", ".join(CMatch(r"\b__acquires").search(line)) 79 + self.assertEqual(result, "") 80 + 81 + def test_search_no_macro_remains(self): 82 + line = "do_something_else();" 83 + result = ", ".join(CMatch("__acquires").search(line)) 84 + self.assertEqual(result, "") 85 + 86 + def test_search_no_function(self): 87 + line = "something" 88 + result = ", ".join(CMatch(line).search(line)) 89 + self.assertEqual(result, "") 90 + 91 + # 92 + # Run all tests 93 + # 94 + if __name__ == "__main__": 95 + run_unittest(__file__)